Getting started with Java

This tutorial is intended for those new to building apps in the cloud, such as engineers and web developers, who want to learn key app development concepts as they apply to Google Cloud.

Objectives

• Learn basic Google Cloud tools, such as the Google Cloud Console and gcloud.
• Deploy your app to Cloud Run.
• Persist your data with Firestore.
• Store file uploads in Cloud Storage.
• Monitor your app using Google Cloud's operations suite.

For other language-specific tutorials for building your apps, see the following guides:

• Deploying an app to Google Kubernetes Engine.

Costs

This tutorial uses the following billable components of Google Cloud:

• Cloud Run
• Cloud Storage
• Firestore
• Google Cloud's operations suite

The tutorial is designed to keep your resource usage within the limits of Google Cloud's Always Free tier. To generate a cost estimate based on your projected usage, use the pricing calculator. New Google Cloud users might be eligible for a free trial.

When you finish this tutorial, you can avoid continued billing by deleting the resources you created. For more information, see Cleaning up.

Before you begin

1. Sign in to your Google Account.

   If you don't already have one, sign up for a new account.

2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to the project selector page

3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

4. To create a Firestore database in Native mode, complete the following steps:
   1. In the Cloud Console, go to the Firestore viewer page.
      Go to the Firestore viewer
   2. From the Select a Cloud Firestore mode screen, click Select Native Mode.
   3. Select a location for your Firestore database. This location setting is the default Google Cloud resource location for your Cloud project . This location is used for Google Cloud services in your Cloud project that require a location setting, specifically, your default Cloud Storage bucket and your Cloud Run app.
      Warning: After you set the default resource location for your Cloud project, you cannot change it.
   4. Click Create Database.
5. Enable the Cloud Run Admin, Cloud Storage, Cloud Logging, and Error Reporting APIs.

   Enable the APIs

6. In Cloud Shell, open the app's source code.
   Go to Cloud Shell

   Cloud Shell provides command-line access to your Google Cloud resources directly from the browser.

7. To download the sample code and change into the app directory, click Proceed.

8. In Cloud Shell, configure the gcloud tool to use your new Google Cloud project:

   # Configure gcloud for your project
   gcloud config set project PROJECT_ID
   

   Replace PROJECT_ID with the Google Cloud project ID that you created using the Cloud Console.

   The gcloud command-line tool is the primary way you interact with your Google Cloud resources from the command line. In this tutorial, you use the gcloud tool to deploy and monitor your app.

Running your app

1. If you already use Cloud Shell and have configured it to use Java 11, update the shell's Java alternatives, JAVA_HOME, and PATH environment variables to specify Java 8.
2. Change into the bookshelf/1-cloud-run directory and run the app:

   GOOGLE_CLOUD_PROJECT=PROJECT_ID mvn -Plocal clean jetty:run-exploded
   

   Replace PROJECT_ID with the Google Cloud project ID that you created.
3. In Cloud Shell, click Web preview , and select Preview on port 8080. This opens a new window with your running app.

Deploying your app to Cloud Run

Google Cloud offers several options for running your code. For this example, you use Cloud Run to deploy a scalable app to Google Cloud. With zero server management, Cloud Run lets you focus on writing code. Plus, Cloud Run automatically scales to support sudden traffic spikes.

1. Build the image using Jib:
   mvn package jib:build -Dimage=gcr.io/PROJECT_ID/bookshelf

   Replace PROJECT_ID with the Google Cloud project ID that you created.

2. Then deploy the image:

   gcloud run deploy bookshelf --image gcr.io/PROJECT_ID/bookshelf \
   --platform managed --region us-central1 --allow-unauthenticated

   Replace PROJECT_ID with the Google Cloud project ID that you created.

When the deployment succeeds, it will output an endpoint to the app running in Cloud Run, in the format:

https://bookshelf-abcdefghij-uc.a.run.app

Your app is now viewable at this link, hereafter called YOUR_CODE_RUN_URL. In your web browser, enter the URL to view the app.

Persisting your data with Firestore

You cannot store information on your Cloud Run instances, because it is lost if the instance is restarted, and doesn't exist when new instances are created. Instead, you use a database that all your instances read from and write to.

Google Cloud offers several options for storing your data. In this example, you use Firestore to store the data for each book. Firestore is a fully managed, serverless, NoSQL document database that lets you store and query data. Firestore auto scales to meet your app needs, and scales to zero when you're not using it. Add your first book now.

1. In your web browser, go to your YOUR_CODE_RUN_URL.

2. To create a book for your deployed app, click Add book.

   
3. In the Title field, enter Moby Dick.
4. In the Author field, enter Herman Melville.

5. Click Save. There is now an entry to your Bookshelf app.

   
6. In the Cloud Console, to refresh the Firestore page, click Refresh . The data appears in Firestore. The Bookshelf app stores each book as a Firestore document with a unique ID, and all these documents are stored in a Firestore collection. For the purposes of this tutorial, the collection is called books.

Firestore stores the books by using the Firestore Client Library. Here is an example of fetching a Firestore document:

bookshelf/1-cloud-run/src/main/java/com/example/getstarted/daos/FirestoreDao.java

View on GitHub

public class FirestoreDao implements BookDao {
  private CollectionReference booksCollection;

  public FirestoreDao() {
    Firestore firestore = FirestoreOptions.getDefaultInstance().getService();
    booksCollection = firestore.collection("books");
  }

  private Book documentToBook(DocumentSnapshot document) {
    Map<String, Object> data = document.getData();
    if (data == null) {
      System.out.println("No data in document " + document.getId());
      return null;
    }

    return new Book.Builder()
        .author((String) data.get(Book.AUTHOR))
        .description((String) data.get(Book.DESCRIPTION))
        .publishedDate((String) data.get(Book.PUBLISHED_DATE))
        .imageUrl((String) data.get(Book.IMAGE_URL))
        .createdBy((String) data.get(Book.CREATED_BY))
        .createdById((String) data.get(Book.CREATED_BY_ID))
        .title((String) data.get(Book.TITLE))
        .id(document.getId())
        .build();
  }

  @Override
  public String createBook(Book book) {
    String id = UUID.randomUUID().toString();
    DocumentReference document = booksCollection.document(id);
    Map<String, Object> data = Maps.newHashMap();

    data.put(Book.AUTHOR, book.getAuthor());
    data.put(Book.DESCRIPTION, book.getDescription());
    data.put(Book.PUBLISHED_DATE, book.getPublishedDate());
    data.put(Book.TITLE, book.getTitle());
    data.put(Book.IMAGE_URL, book.getImageUrl());
    data.put(Book.CREATED_BY, book.getCreatedBy());
    data.put(Book.CREATED_BY_ID, book.getCreatedById());
    try {
      document.set(data).get();
    } catch (InterruptedException | ExecutionException e) {
      e.printStackTrace();
    }

    return id;
  }

  @Override
  public Book readBook(String bookId) {
    try {
      DocumentSnapshot document = booksCollection.document(bookId).get().get();

      return documentToBook(document);
    } catch (InterruptedException | ExecutionException e) {
      e.printStackTrace();
    }
    return null;
  }

  @Override
  public void updateBook(Book book) {
    DocumentReference document = booksCollection.document(book.getId());
    Map<String, Object> data = Maps.newHashMap();

    data.put(Book.AUTHOR, book.getAuthor());
    data.put(Book.DESCRIPTION, book.getDescription());
    data.put(Book.PUBLISHED_DATE, book.getPublishedDate());
    data.put(Book.TITLE, book.getTitle());
    data.put(Book.IMAGE_URL, book.getImageUrl());
    data.put(Book.CREATED_BY, book.getCreatedBy());
    data.put(Book.CREATED_BY_ID, book.getCreatedById());
    try {
      document.set(data).get();
    } catch (InterruptedException | ExecutionException e) {
      e.printStackTrace();
    }
  }

  @Override
  public void deleteBook(String bookId) {
    try {
      booksCollection.document(bookId).delete().get();
    } catch (InterruptedException | ExecutionException e) {
      e.printStackTrace();
    }
  }

  private List<Book> documentsToBooks(List<QueryDocumentSnapshot> documents) {
    List<Book> resultBooks = new ArrayList<>();
    for (QueryDocumentSnapshot snapshot : documents) {
      resultBooks.add(documentToBook(snapshot));
    }
    return resultBooks;
  }

  @Override
  public Result<Book> listBooks(String startTitle) {
    Query booksQuery = booksCollection.orderBy("title").limit(10);
    if (startTitle != null) {
      booksQuery = booksQuery.startAfter(startTitle);
    }
    try {
      QuerySnapshot snapshot = booksQuery.get().get();
      List<Book> results = documentsToBooks(snapshot.getDocuments());
      String newCursor = null;
      if (results.size() > 0) {
        newCursor = results.get(results.size() - 1).getTitle();
      }
      return new Result<>(results, newCursor);
    } catch (InterruptedException | ExecutionException e) {
      e.printStackTrace();
    }
    return new Result<>(Lists.newArrayList(), null);
  }

  @Override
  public Result<Book> listBooksByUser(String userId, String startTitle) {
    Query booksQuery =
        booksCollection.orderBy("title").whereEqualTo(Book.CREATED_BY_ID, userId).limit(10);
    if (startTitle != null) {
      booksQuery = booksQuery.startAfter(startTitle);
    }
    try {
      QuerySnapshot snapshot = booksQuery.get().get();
      List<Book> results = documentsToBooks(snapshot.getDocuments());
      String newCursor = null;
      if (results.size() > 0) {
        newCursor = results.get(results.size() - 1).getTitle();
      }
      return new Result<>(results, newCursor);
    } catch (InterruptedException | ExecutionException e) {
      e.printStackTrace();
    }
    return new Result<>(Lists.newArrayList(), null);
  }
}

For more information on using Firestore, see Adding data to Firestore.

Storing file uploads in Cloud Storage

Now that you've added a book, it's time to add the book cover image. You cannot store files on your instances. A database isn't the right choice for image files. Instead, you use Cloud Storage.

Cloud Storage is the primary blob store for Google Cloud. You can use Cloud Storage to host app assets that you want to share across Google Cloud. To use Cloud Storage, you need to create a Cloud Storage bucket, a basic container to hold your data.

1. In the Cloud Console, go to the Cloud Storage Browser page.

   Go to the Cloud Storage Browser page

2. Click Create bucket.
3. In the Create bucket dialog, enter a name for your bucket by appending your Google Cloud project ID to the string _bucket so the name looks like YOUR_PROJECT_ID_bucket. This name is subject to the bucket name requirements. All other fields can remain at their default values.
4. Click Create.
5. After your bucket is created, objects must be made publicly accessible to be viewed by users. To make your objects publicly accessible see Making Data Public.
6. Click Edit book, and select an image to upload as your book's cover. For example, you can use this public domain image:
   
7. Click Save. You're redirected to the homepage, where there is an entry to your Bookshelf app.
   

The bookshelf app sends uploaded files to Cloud Storage by using the Cloud Storage Client Library.

bookshelf/1-cloud-run/src/main/java/com/example/getstarted/util/CloudStorageHelper.java

View on GitHub

public class CloudStorageHelper {

  private final Logger logger = Logger.getLogger(CloudStorageHelper.class.getName());
  private static Storage storage = null;

  static {
    storage = StorageOptions.getDefaultInstance().getService();
  }


  /**
   * Uploads a file to Google Cloud Storage to the bucket specified in the BUCKET_NAME environment
   * variable, appending a timestamp to end of the uploaded filename.
   */
  public String uploadFile(FileItemStream fileStream, final String bucketName)
      throws IOException, ServletException {
    checkFileExtension(fileStream.getName());

    System.out.println("FileStream name: " + fileStream.getName() + "\nBucket name: " + bucketName);

    DateTimeFormatter dtf = DateTimeFormat.forPattern("-YYYY-MM-dd-HHmmssSSS");
    DateTime dt = DateTime.now(DateTimeZone.UTC);
    String dtString = dt.toString(dtf);
    final String fileName = fileStream.getName() + dtString;

    // the inputstream is closed by default, so we don't need to close it here
    @SuppressWarnings("deprecation")
    BlobInfo blobInfo =
        storage.create(
            BlobInfo.newBuilder(bucketName, fileName)
                // Modify access list to allow all users with link to read file
                .setAcl(new ArrayList<>(Arrays.asList(Acl.of(User.ofAllUsers(), Role.READER))))
                .build(),
            fileStream.openStream());
    logger.log(
        Level.INFO, "Uploaded file {0} as {1}", new Object[] {fileStream.getName(), fileName});
    // return the public download link
    return blobInfo.getMediaLink();
  }


  /** Checks that the file extension is supported. */
  private void checkFileExtension(String fileName) throws ServletException {
    if (fileName != null && !fileName.isEmpty() && fileName.contains(".")) {
      String[] allowedExt = {".jpg", ".jpeg", ".png", ".gif"};
      for (String ext : allowedExt) {
        if (fileName.endsWith(ext)) {
          return;
        }
      }
      throw new ServletException("file must be an image");
    }
  }
}

Note: You can change the bucket name at any time by setting the bucketName variable in the preceding code to a different name and redeploying your app by using gcloud app deploy.

For more information on using Cloud Storage, see the list of how-to guides.

Monitoring your app using Google Cloud's operations suite

You've deployed your app and created and modified books. To monitor these events for your users, use Application Performance Management.

Monitor logs with Cloud Logging

1. In the Google Cloud, go to the Logs Viewer

   Go to Logs Viewer

   You can monitor your app in real time. If you have any issues with your app, this is one of the first places to look.

   
2. In the Resource drop-down list, select Cloud Run Revision, bookshelf.

Monitor errors with Error Reporting

1. In the Cloud Console, go to the Error Reporting page.
   Go to Error Reporting page
   Error Reporting highlights errors and exceptions in your app and lets you set up alerting around them.
2. In your browser, go to the /errors URL in your app.
   

   YOUR_CODE_RUN_URL/errors

   This generates a new test exception and sends it to Google Cloud's operations suite.

3. In the Cloud Console, return to the Error Reporting page, and in a few moments the new error is visible. Click Auto Reload so you don't need to manually refresh the page.

   

Note: Application Performance Management contains many tools to help debug and monitor your apps. For more information, see the tutorials.

Cleaning up

To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, either delete the project that contains the resources, or keep the project and delete the individual resources.

Delete the project

Caution: Deleting a project has the following effects:

• Everything in the project is deleted. If you used an existing project for this tutorial, when you delete it, you also delete any other work you've done in the project.
• Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as an appspot.com URL, delete selected resources inside the project instead of deleting the whole project.

If you plan to explore multiple tutorials and quickstarts, reusing projects can help you avoid exceeding project quota limits.

1. In the Cloud Console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

What's next

• Deploying an app to Google Kubernetes Engine
• Deploying an app to Compute Engine
• Handling sessions with Firestore