Storing Data in Datastore

In this section, you'll extend the simple application created earlier by adding the ability to post greetings and display previously posted greetings. You'll add a new servlet that handles the form submission and save the data.

The database we are using is Google Cloud Datastore, a scalable, highly reliable data storage service that's easy to use from App Engine. Unlike a relational database, the Datastore is a schemaless object store, with an index-based query engine and transactional capabilities.

This tutorial uses the Objectify library, a Java data modeling library for the Datastore. There are several alternative APIs you can use: a simple low-level API, implementations of the Java Data Objects (JDO) and Java Persistence API (JPA) interfaces, or the Slim3 library.

This is what the app will look like after you add the message submission form:

You'll make these changes to your existing application:

• Set up Objectify, and create data model classes for the guestbook.
• Edit the JSP page to allow users to post greetings to the datastore, and to display all the greetings currently stored.
• Create a new servlet named SignGuestbookServlet that handles the form submission.
• Add entries in web.xml so requests can be routed to the new servlet.

Setting up Objectify

To use the Objectify library, you must declare the dependency in the pom.xml file, so Maven can install it. In the application root directory (guestbook/), edit pom.xml, locate the <dependencies> section, then add the following:

<dependency>
    <groupId>com.googlecode.objectify</groupId>
    <artifactId>objectify</artifactId>
    <version>4.0.1</version>
</dependency>

Maven will install the library the next time you run a target that needs it (such as the development server).

In order to use Objectify in a JSP, we need a helper class that registers the model classes in the JSP servlet context. In guestbook/src/main/java/com/example/guestbook/, create a file named OfyHelper.java with the following contents:

package com.example.guestbook;

import com.googlecode.objectify.Objectify;
import com.googlecode.objectify.ObjectifyFactory;
import com.googlecode.objectify.ObjectifyService;

import javax.servlet.ServletContextListener;
import javax.servlet.ServletContextEvent;

/**
 * OfyHelper, a ServletContextListener, is setup in web.xml to run before a JSP is run.  This is
 * required to let JSP's access Ofy.
 **/
public class OfyHelper implements ServletContextListener {
  public void contextInitialized(ServletContextEvent event) {
    // This will be invoked as part of a warmup request, or the first user request if no warmup
    // request.
    ObjectifyService.register(Guestbook.class);
    ObjectifyService.register(Greeting.class);
  }

  public void contextDestroyed(ServletContextEvent event) {
    // App Engine does not currently invoke this method.
  }
}

This file refers to the Greeting and Guestbook model classes that you'll create in the next section.

Finally, in guestbook/src/main/webapp/WEB-INF/, edit web.xml, and add the following lines inside <web-app> to set up the JSP helper:

<filter>
  <filter-name>ObjectifyFilter</filter-name>
  <filter-class>com.googlecode.objectify.ObjectifyFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>ObjectifyFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>
<listener>
  <listener-class>com.example.guestbook.OfyHelper</listener-class>
</listener>

Creating the data model classes

With Objectify, you create classes whose instances will represent datastore entities in your code. Objectify does the work of translating these Java objects to datastore entities.

Create a Greeting class to represent a message posted by a user. In guestbook/src/main/java/com/example/guestbook/, create a file named Greeting.java with the following contents:

package com.example.guestbook;

import com.googlecode.objectify.annotation.Entity;
import com.googlecode.objectify.annotation.Id;
import com.googlecode.objectify.annotation.Index;
import com.googlecode.objectify.annotation.Parent;
import com.googlecode.objectify.Key;

import java.lang.String;
import java.util.Date;
import java.util.List;

/**
 * The @Entity tells Objectify about our entity.  We also register it in {@link OfyHelper}
 * Our primary key @Id is set automatically by the Google Datastore for us.
 *
 * We add a @Parent to tell the object about its ancestor. We are doing this to support many
 * guestbooks.  Objectify, unlike the AppEngine library requires that you specify the fields you
 * want to index using @Index.  Only indexing the fields you need can lead to substantial gains in
 * performance -- though if not indexing your data from the start will require indexing it later.
 *
 * NOTE - all the properties are PUBLIC so that can keep the code simple.
 **/
@Entity
public class Greeting {
  @Parent Key<Guestbook> theBook;
  @Id public Long id;

  public String author_email;
  public String author_id;
  public String content;
  @Index public Date date;

  /**
   * Simple constructor just sets the date
   **/
  public Greeting() {
    date = new Date();
  }

  /**
   * A connivence constructor
   **/
  public Greeting(String book, String content) {
    this();
    if( book != null ) {
      theBook = Key.create(Guestbook.class, book);  // Creating the Ancestor key
    } else {
      theBook = Key.create(Guestbook.class, "default");
    }
    this.content = content;
  }

  /**
   * Takes all important fields
   **/
  public Greeting(String book, String content, String id, String email) {
    this(book, content);
    author_email = email;
    author_id = id;
  }

}

We also need a Guestbook class to represent an entire guestbook. While this example doesn't explicitly create a Guestbook object in the datastore, it uses this class as part of the datastore key for the Greeting objects. This demonstrates how you might define keys so that all of the greetings in a guestbook could be updated in a single datastore transaction.

Create a file named Guestbook.java with the following contents:

package com.example.guestbook;

import com.googlecode.objectify.annotation.Entity;
import com.googlecode.objectify.annotation.Id;

/**
 * The @Entity tells Objectify about our entity.  We also register it in
 * OfyHelper.java -- very important.
 *
 * This is never actually created, but gives a hint to Objectify about our Ancestor key.
 */
@Entity
public class Guestbook {
  @Id public String book;
}

Adding the greetings and the form to the JSP template

In guestbook/src/main/webapp, edit guestbook.jsp. Add the following lines to the imports at the top:

<%@ page import="com.example.guestbook.Greeting" %>
<%@ page import="com.example.guestbook.Guestbook" %>
<%@ page import="com.googlecode.objectify.Key" %>
<%@ page import="com.googlecode.objectify.ObjectifyService" %>

Just above the line <form action="/guestbook.jsp" method="get">, add the following code:

<%
    // Create the correct Ancestor key
      Key<Guestbook> theBook = Key.create(Guestbook.class, guestbookName);

    // Run an ancestor query to ensure we see the most up-to-date
    // view of the Greetings belonging to the selected Guestbook.
      List<Greeting> greetings = ObjectifyService.ofy()
          .load()
          .type(Greeting.class) // We want only Greetings
          .ancestor(theBook)    // Anyone in this book
          .order("-date")       // Most recent first - date is indexed.
          .limit(5)             // Only show 5 of them.
          .list();

    if (greetings.isEmpty()) {
%>
<p>Guestbook '${fn:escapeXml(guestbookName)}' has no messages.</p>
<%
    } else {
%>
<p>Messages in Guestbook '${fn:escapeXml(guestbookName)}'.</p>
<%
      // Look at all of our greetings
        for (Greeting greeting : greetings) {
            pageContext.setAttribute("greeting_content", greeting.content);
            String author;
            if (greeting.author_email == null) {
                author = "An anonymous person";
            } else {
                author = greeting.author_email;
                String author_id = greeting.author_id;
                if (user != null && user.getUserId().equals(author_id)) {
                    author += " (You)";
                }
            }
            pageContext.setAttribute("greeting_user", author);
%>
<p><b>${fn:escapeXml(greeting_user)}</b> wrote:</p>
<blockquote>${fn:escapeXml(greeting_content)}</blockquote>
<%
        }
    }
%>

<form action="/sign" method="post">
    <div><textarea name="content" rows="3" cols="60"></textarea></div>
    <div><input type="submit" value="Post Greeting"/></div>
    <input type="hidden" name="guestbookName" value="${fn:escapeXml(guestbookName)}"/>
</form>

When the user loads the page, the template performs a datastore query for all Greeting entities that use the same Guestbook in their key. The query is sorted by date in reverse chronological order ("-date"), and results are limited to the five most recent greetings. The rest of the template displays the results as HTML, and also renders the form that the user can use to post a new greeting.

See Datastore Queries to learn more about queries.

Creating the form handling servlet

The web form sends an HTTP POST request to the /sign URL. Let's create a servlet to handle these requests.

In guestbook/src/main/java/com/example/guestbook, create a file named SignGuestbookServlet.java, and give it the following contents:

package com.example.guestbook;

import com.google.appengine.api.datastore.DatastoreService;
import com.google.appengine.api.datastore.DatastoreServiceFactory;
import com.google.appengine.api.datastore.Entity;
import com.google.appengine.api.datastore.Key;
import com.google.appengine.api.datastore.KeyFactory;
import com.google.appengine.api.users.User;
import com.google.appengine.api.users.UserService;
import com.google.appengine.api.users.UserServiceFactory;

import java.io.IOException;
import java.util.Date;

import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.googlecode.objectify.ObjectifyService;

/**
 * Form Handling Servlet
 * Most of the action for this sample is in webapp/guestbook.jsp, which displays the
 * {@link Greeting}'s. This servlet has one method
 * {@link #doPost(<#HttpServletRequest req#>, <#HttpServletResponse resp#>)} which takes the form
 * data and saves it.
 */
public class SignGuestbookServlet extends HttpServlet {

  // Process the http POST of the form
  @Override
  public void doPost(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    Greeting greeting;

    UserService userService = UserServiceFactory.getUserService();
    User user = userService.getCurrentUser();  // Find out who the user is.

    String guestbookName = req.getParameter("guestbookName");
    String content = req.getParameter("content");
    if (user != null) {
      greeting = new Greeting(guestbookName, content, user.getUserId(), user.getEmail());
    } else {
      greeting = new Greeting(guestbookName, content);
    }

    // Use Objectify to save the greeting and now() is used to make the call synchronously as we
    // will immediately get a new page using redirect and we want the data to be present.
    ObjectifyService.ofy().save().entity(greeting).now();

    resp.sendRedirect("/guestbook.jsp?guestbookName=" + guestbookName);
  }
}

This servlet is the POST handler for the greetings posted by users. It takes the the greeting (content) from the incoming request and stores it in Datastore as a Greeting entity. Its properties include the content of the post, the date the post was created, and, if the user is signed in, the author's ID and email address. For more information about entities in App Engine, see Entities, Properties, and Keys.

Finally, in guestbook/src/main/webapp/WEB-INF/, edit web.xml and ensure the new servlets have URLs mapped. The final version should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

    <servlet>
      <servlet-name>sign</servlet-name>
      <servlet-class>com.example.guestbook.SignGuestbookServlet</servlet-class>
    </servlet>

    <servlet-mapping>
      <servlet-name>sign</servlet-name>
      <url-pattern>/sign</url-pattern>
    </servlet-mapping>

    <welcome-file-list>
        <welcome-file>guestbook.jsp</welcome-file>
    </welcome-file-list>

    <filter>
      <filter-name>ObjectifyFilter</filter-name>
      <filter-class>com.googlecode.objectify.ObjectifyFilter</filter-class>
    </filter>
    <filter-mapping>
      <filter-name>ObjectifyFilter</filter-name>
      <url-pattern>/*</url-pattern>
    </filter-mapping>
    <listener>
      <listener-class>com.example.guestbook.OfyHelper</listener-class>
    </listener>
</web-app>

Testing the app

Restart the development server to build and run the app:

mvn appengine:devserver

Visit the app in a browser:

localhost:8080

Try posting a greeting. Also try posting a greeting while signed in, and while not signed in.

Creating required indexes

If your app uses the Datastore, when you run your app on the development server, the development server automatically creates any Datastore indexes required to run in production App Engine. These indexes are generated in guestbook/target/guestbook-1.0-SNAPSHOT/WEB-INF/appengine-generated/datastore-indexes-auto.xml. You'll also notice the file local_db.bin at that same location: this is local storage for the development server to persist your app data between development server sessions. The file datastore-indexes-auto.xml is automatically uploaded along with your app. local_db.bin is not uploaded.

For complete information about indexes, see Datastore Indexes.

We now have a working guest book application that authenticates users using Google accounts, lets them submit messages, and displays messages other users have left.

The only thing left to do is upload our application...

Uploading Your Application >>