App Engine and Google Cloud Storage Sample

This tutorial shows how to enable your App Engine Java app to access Cloud Storage. This non-interactive sample show to create, write, read, and list files in the Cloud Storage bucket.

The UI for the application looks like this:

Hello Cloud Storage


  • Build and run the sample app locally.
  • Deploy and run the sample app on Google App Engine.
  • Create a file with text content and write the file to a Google Cloud Storage bucket.
  • Read the file from the bucket.


App Engine has a free level of usage. If your total usage of App Engine is less than the limits specified in the App Engine free quota, there is no charge for doing this tutorial.

Before you begin

  1. Sign in to your Google account.

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

  2. Select or create a Cloud Platform Console project.

    Go to the Projects page

  3. Make a note of the project ID, which is used in commands and in the appengine-web.xml
  4. Complete the Quickstart for Java App Engine standard environment.
  5. Download and install the App Engine SDK for Java.
  6. [Download and install](/appengine/docs/java/tools/maven#installing_maven_339 Maven 3.3.9 or greater.
  7. Activate the default Cloud Storage bucket
  8. Use the git clone method to Download and install the Google Cloud Storage Client Library using Git. This downloads the library and sample code.

Viewing the project layout and files

To view the project layout:

  1. Change directory to the directory where you downloaded or cloned the Cloud Storage client library: appengine-gcs-client.

  2. Execute a tree command or equivalent on the java subdirectory:

    Cloud Storage Project Layout

You'll learn about these files during the walkthrough:

File Description
index.html The sample user interface: this accepts user supplied bucket and filename and issues the appropriate POST or GET to the servlet. The sample servlet that handles the user POST by writing to the Cloud Storage bucket and the user GET by reading from the Cloud Storage bucket.

Specify the project ID in the sample

The deployment utility deploys the app to the project ID specified in the appengine-web.xml file.

To specify the project ID in the sample code:

  1. Change directory to appengine-gcs-client/java/example/.

  2. Edit pom.xml replacing the properties <> value with the project ID you obtained when you created the project.

  3. Save your changes.

Building and running locally

To build and run the sample locally:

  1. From the project subdirectory appengine-gcs-client/java/example, build:

    mvn clean package

    Wait for the project to build. It may take a few minutes to download dependencies the first time you build.

  2. Start the application locally in the development server:

     mvn appengine:devserver
  3. Wait for the success message, which looks something like this:

     [INFO] INFO: Module instance default is running at http://localhost:8080/
     [INFO] Apr 5, 2016 3:28:38 PM startup
     [INFO] INFO: The admin console is running at http://localhost:8080/_ah/admin
     [INFO] Apr 5, 2016 3:28:38 PM doStart
     [INFO] INFO: Dev App Server is now running
  4. Visit this URL in your browser:


  5. The app serves a page inviting you to sign in. Make sure you log in as admin by checking the login as Admin checkbox.

    Try clicking the Sign in link, then sign in with any email address. The development server has only a very basic emulation of the Google Account sign-in process for testing purposes, so this accepts whatever email you supply, valid or not, and generates a fake user object based on that supplied value. When deployed to production, this same code requires a valid Google Account and email address, and generates a valid user object.

  6. Supply the name of the default bucket in Bucket, any file name you wish in File Name, type in some text in File Contents, then click Upload Content.

  7. In the Download area, notice that the Bucket and File Name values are automatically filled in: click Download Content.

  8. Stop the development server by pressing Control-C.

Deploying and running the sample

To deploy the sample app to App Engine and run it:

  1. In the subdirectory appengine-gcs-client/java/example, invoke the command:

    mvn appengine:update
  2. Follow the prompts to authorize the app deployment. Typically, you only need to supply these the first time you deploy an app to a project.

  3. Wait for the app to deploy.

  4. In your browser, visit https://<your-project-id>; and exercise the application in the same way as you did when running locally. Only this time, the reads and writes are to the default Cloud Storage bucket for your app.

index.html walkthrough

The index.html file handles the user interaction and responds by issuing the POST for file writes to the bucket, or GET for file downloads from the bucket:

    <form action="/index.html" enctype="text/plain" method="get" name="putFile" id="putFile">
        Bucket: <input type="text" name="bucket" />
        File Name: <input type="text" name="fileName" />
        <br /> File Contents: <br />
        <textarea name="content" id="content" rows="3" cols="60"></textarea>
        <br />
        <input type="submit" onclick='uploadFile(this)' value="Upload Content" />
  <td style="font-weight: bold;">Download a file from Google Cloud Storage:</td>
    <form name="getFile">
        Bucket: <input type="text" name="bucket" id="bucket" />
        File Name: <input type="text" name="fileName" id="fileName" />
    <form action="/index.html" method="get" name="submitGet">
        <input type="submit" onclick='changeGetPath(this)' value="Download Content" />

Notice that the expected /gcs/ is prepended to the user-supplied bucket name in the POST request. imports walkthrough

The file contains the following imports you need to access Cloud Storage via the client library:


Writing a file to Cloud Storage

To write a file to Cloud Storage:

public void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException {
  GcsFileOptions instance = GcsFileOptions.getDefaultInstance();
  GcsFilename fileName = getFileName(req);
  GcsOutputChannel outputChannel;
  outputChannel = gcsService.createOrReplace(fileName, instance);
  copy(req.getInputStream(), Channels.newOutputStream(outputChannel));

This sample writes a new file to Cloud Storage, or, if a file with the same name already exists, it overwrites it. This is useful because once you write a file to Cloud Storage, you cannot modify it. To change the file, you must make your modifications to a copy of the file, then overwrite the old file.

Reading a file from Cloud Storage

To read a file from Cloud Storage:

public void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
  GcsFilename fileName = getFileName(req);
    BlobstoreService blobstoreService = BlobstoreServiceFactory.getBlobstoreService();
    BlobKey blobKey = blobstoreService.createGsBlobKey(
        "/gs/" + fileName.getBucketName() + "/" + fileName.getObjectName());
    blobstoreService.serve(blobKey, resp);
  } else {
    GcsInputChannel readChannel = gcsService.openPrefetchingReadChannel(fileName, 0, BUFFER_SIZE);
    copy(Channels.newInputStream(readChannel), resp.getOutputStream());

In the line containing gcsService.openPrefetchingReadChannel, notice the use of prefetching. This buffers data in memory and prefetches it before it is required to avoid blocking on the read call.

What's next