Creating a Guestbook Application

This tutorial shows the code you need to implement a simple Java application for Google App Engine--a simple guestbook that lets users post messages to a public message board. It uses javax.servlet and JavaServer Pages (JSP).

In this code walkthrough, you:

  • Clone the tutorial project.
  • Learn about core features of App Engine called out in key parts of the project.
  • Run, test, and deploy the project.

The tutorial assumes that you are familiar with Java.

The UI for the application looks like this:



  • Walk through an Apache Maven project to view an App Engine project with the required layout and files.
  • Understand the servlet code and JSP templates that respond to user requests.
  • Understand the integration with Google Accounts for user authentication.
  • Understand how to use Objectify to save data to Google Cloud Datastore.
  • Build and test your app in the local development server.
  • Deploy the app to production Google App Engine.


App Engine has free a 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 might be different from the project name. The project ID is used in commands and in configurations.
  4. You should have the Java 7 SDK installed, preferably the Enterprise Edition. For more information, see these download and installation instructions.
  5. You should have Maven 3.3.9 or greater installed. See Setting up Maven.

Cloning the tutorial project

If you haven't already, clone the Guestbook app repository to your local machine and change directory to its final subdirectory:

git clone
cd appengine-java-guestbook-multiphase/final

Alternatively, you can download the sample as a zip file and extract it.

The cloned project (or download) contains two sub-projects: final and phase1. In this tutorial we will only cover the project named final.

Viewing the project layout and files

If you execute a tree command or equivalent on the final subdirectory, this is what the structure of the final project looks like:.

Maven Project Layout

We'll cover the contents of some of these files in detail during the tutorial. To give you a quick synopsis of these files for now, here's a brief inventory:

File Description
pom.xml Project settings and dependencies used by Maven.
appengine-web.xml Used to specify the project ID this application is deployed to, the application version, and the location of the file used for application logging. Used to set the default log level (Error, Warning, Info, and so on).
web.xml Does all the mappings required for the servlet. Defines the entity that is posted by the user, saved to Google Cloud Datastore, and displayed on the message board. Registers the Greeting entity with Objectify. A listener that registers the Objectify service with the servlet The servlet that handles the user's request to POST a message to the message board and saves the message.

Note that you can use the Maven App Engine artifact appengine-skeleton-archetype to create an empty App Engine project later on. This artifact provides the same directory structure, the required pom.xml settings and the same WEB-INF files listed in the table, but you won't get the Java files mentioned in the table.

Building and running locally

To build and run the sample locally:

  1. From the project subdirectory appengine-java-guestbook-multiphase-master/final, run:

    mvn clean package
  2. Wait for the project to build. When the project successfully finishes, you'll see a message similar to this one:

    [INFO] --------------------------------------------------
    [INFO] --------------------------------------------------
    [INFO] Total time: 1:16.656s
    [INFO] Finished at: Mon Apr 5 11:42:22 PDT 2016
    [INFO] Final Memory: 16M/228M
    [INFO] --------------------------------------------------
  3. Run the following Maven command to start the application locally:

     mvn appengine:devserver
  4. 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
  5. Visit this URL in your browser:


    If you get a runtime error when you first visit localhost:8080, referring to a restricted class, for example, java.lang.NoClassDefFoundError: java.nio.charset.StandardCharsets is a restricted class., check the settings in final/pom.xml. You must set the App Engine version to the most recent App Engine SDK version: 1.9.42.

  6. The app serves a page inviting you to sign in. 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.

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