Google App Engine - Java Application Development - Introduction

Welcome to Google App Engine! Creating an App Engine application is easy, and only takes a few minutes. And it's free to start: upload your app and share it with users right away, at no charge and with no commitment required.

Google App Engine applications can be written in the Java, Python, Go or PHP programming languages. This tutorial covers Java. If you would prefer to use Python, Go or PHP to build your applications, see the Python 2.7, Go or PHP guides.

In this tutorial, you will learn how to:

build an App Engine application using standard Java web technologies, such as servlets and JSPs
create an App Engine Java project with Eclipse, and without
use the Google Plugin for Eclipse for App Engine development
use the App Engine datastore with the Datastore API
integrate an App Engine application with Google Accounts for user authentication
upload your app to App Engine

By the end of the tutorial, you will have implemented a working application, a simple guest book that lets users post messages to a public message board.

Installing the Java SDK

You develop and upload Java applications for Google App Engine using the App Engine Java software development kit (SDK).

The SDK includes software for a web server that you can run on your own computer to test your Java applications. The server simulates all of the App Engine services, including a local version of the datastore, Google Accounts, and the ability to fetch URLs and send email from your computer using the App Engine APIs.

Getting Java

When App Engine runs your Java application, it uses the Java 7 virtual machine (JVM) and standard libraries. You should use Java 7 for compiling and testing your application to ensure that the local server behaves similarly to App Engine.

Warning: The App Engine SDK no longer supports Java 6. Applications that use Java 6 need to be migrated to Java 7. Existing applications that use the Java 6 runtime are still supported, but this support will be removed in a future release.

If necessary, download and install the Java SE Development Kit (JDK) for your platform. Mac users, see Apple's Java developer site to download and install the latest version of the Java Developer Kit available for Mac OS X.

Once the JDK is installed, run the following commands from a command prompt (for Windows, Command Prompt; for Mac OS X, Terminal) to determine which version is installed. If you have Java 7 installed, these commands will report a version number similar to 1.7.0.

java -version

javac -version

Using Eclipse and the Google Plugin for Eclipse

If you are using the Eclipse development environment, the easiest way to develop, test and upload App Engine apps is to use the Google Plugin for Eclipse. The plugin includes everything you need to build, test and deploy your app, entirely within Eclipse.

Using Apache Ant

If you want to compile and run your application using the command line, or an IDE other than Eclipse, you will need to install something to manage this process. Apache Ant is one such solution. Full directions on installing and setting up Apache Ant to work with App Engine can be found at Using Apache Ant.

Getting the SDK

If you are using Eclipse and the Google Plugin, you can install the App Engine SDK from Eclipse using Software Update. If you haven't already, install the "Google App Engine Java SDK" component using the locations above.

If you are not using Eclipse or the Google Plugin, you can download the App Engine Java SDK as a Zip archive.

Download the App Engine Java SDK. Unpack the archive in a convenient location on your hard drive.

Note: Unpacking the archive creates a directory whose name is something like appengine-java-sdk-X.X.X, where X.X.X is the SDK version number. Throughout this documentation, this directory will be referred to as appengine-java-sdk/. You may want to rename the directory after unpacking.

Trying a Demo Application

The App Engine Java SDK includes several demo applications in the demos/ directory. The final version of the guest book application you will create in this tutorial is included under the directory guestbook/. This demo has been precompiled for you so you can try it right away.

If you are using Eclipse, the SDK is located in your Eclipse installation directory, under plugins/com.google.appengine.eclipse.sdkbundle_VERSION/, whereVERSION is a version identifier for the SDK. From the command line, change the current working directory to this directory to run the following command. If you're using Mac OS X or Linux, you may need to give the command files executable permissions before you can run them (such as with the command chmod u+x dev_appserver.sh).

If you are using Windows, start the guest book demo in the development server by running the following command at a command prompt:

appengine-java-sdk\bin\dev_appserver.cmd appengine-java-sdk\demos\guestbook\war

If you are using Mac OS X or Linux, run the following command:

./appengine-java-sdk/bin/dev_appserver.sh appengine-java-sdk/demos/guestbook/war

The development server starts, and listens for requests on port 8080. Visit the following URL in your browser:

http://localhost:8080/

Note: When you start the development server from within Eclipse using the Google Plugin for Eclipse (discussed later), the server uses the port 8888 by default:http://localhost:8888/

For more information about running the development web server from the command line, including how to change which port it uses, see the Dev Web Server reference.

To stop the server, make sure the command prompt window is active, then press Control-C.

Creating a Project

App Engine Java applications use the Java Servlet standard for interacting with the web server environment. An application's files, including compiled classes, JARs, static files and configuration files, are arranged in a directory structure using the WAR standard layout for Java web applications. You can use any development process you like to develop web servlets and produce a WAR directory. (WAR archive files are not yet supported by the SDK.)

The Project Directory

For this tutorial, we will use a single directory named Guestbook/ for all project files. A subdirectory named src/ contains the Java source code, and a subdirectory named war/contains the complete application arranged in the WAR format. Our build process compiles the Java source files and puts the compiled classes in the appropriate location in war/.

The complete project directory looks like this:

Guestbook/
  src/
    ...Java source code...
    META-INF/
      ...other configuration...
  war/
    ...JSPs, images, data files...
    WEB-INF/
      ...app configuration...
      lib/
        ...JARs for libraries...
      classes/
        ...compiled classes...

If you are using Eclipse, create a new project by clicking the New Web Application Project button in the toolbar:

Give the project a "Project name" of Guestbook and a "Package" of guestbook. Uncheck "Use Google Web Toolkit," and ensure "Use Google App Engine" is checked. See Using the Google Plugin for Eclipse for more information. The wizard creates the directory structure, and the files described below.

If you are not using Eclipse, create the directory structure described above. As you read each of the files described in this section, create the files using the given locations and names.

You can also copy the new project template included with the SDK, in the appengine-java-sdk/demos/new_project_template/ directory.

The Servlet Class

App Engine Java applications use the Java Servlet API to interact with the web server. An HTTP servlet is an application class that can process and respond to web requests. This class extends either the javax.servlet.GenericServlet class or the javax.servlet.http.HttpServlet class.

Our guest book project begins with one servlet class, a simple servlet that displays a message.

If you are not using the Eclipse plugin, create the directories for the path src/guestbook/, then create the servlet class file described below.

In the directory src/guestbook/, make a file named GuestbookServlet.java with the following contents:

package guestbook;
import java.io.IOException;
import javax.servlet.http.*;
public class GuestbookServlet extends HttpServlet {
    @Override
    public void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws IOException {
        resp.setContentType("text/plain");
        resp.getWriter().println("Hello, world");
    }
}

The web.xml File

When the web server receives a request, it determines which servlet class to call using a configuration file known as the "web application deployment descriptor." This file is namedweb.xml, and resides in the war/WEB-INF/ directory in the WAR. WEB-INF/ and web.xml are part of the servlet specification.

In the directory war/WEB-INF/, a file named web.xml has the following contents:

xml version="1.0" encoding="utf-8"?>
 "-//Oracle Corporation//DTD Web Application 2.3//EN"
 "http://java.sun.com/dtd/web-app_2_3.dtd">
 xmlns="http://java.sun.com/xml/ns/javaee" version="2.5">
    
        guestbook

guestbook.GuestbookServlet

guestbook

/guestbook

index.html

This web.xml file declares a servlet named guestbook, and maps it to the URL path /guestbook. It also says that, whenever the user fetches a URL path that is not already mapped to a servlet and represents a directory path inside the application's WAR, the server should check for a file named index.html in that directory and serve it if found.

The appengine-web.xml File

App Engine needs one additional configuration file to figure out how to deploy and run the application. This file is named appengine-web.xml, and resides in WEB-INF/alongside web.xml. It includes the registered ID of your application (Eclipse creates this with an empty ID for you to fill in later), the version number of your application, and lists of files that ought to be treated as static files (such as images and CSS) and resource files (such as JSPs and other application data).

In the directory war/WEB-INF/, a file named appengine-web.xml has the following contents:

xml version="1.0" encoding="utf-8"?>
 xmlns="http://appengine.google.com/ns/1.0">
    
    1

true

appengine-web.xml is specific to App Engine, and is not part of the servlet standard. You can find XML schema files describing the format of this file in the SDK, in theappengine-java-sdk/docs/ directory. See Configuring an App for more information about this file.

Running the Project

The App Engine SDK includes a web server application you can use to test your application. The server simulates the App Engine environment and services, including sandbox restrictions, the datastore, and the services.

If you are using Eclipse, you can start the development server within the Eclipse debugger. Make sure the project ("Guestbook") is selected, then in the Run menu, select Debug As > Web Application. See Using the Google Plugin for Eclipse for details on creating the debug configuration.

If you are not using Eclipse, see Using Apache Ant for a build script that can build the project and start the development server. To start the server with this build script, enter the following command: ant runserver To stop the server, hit Control-C.

Testing the Application

Start the server, then visit the server's URL in your browser. If you're using Eclipse and the Google Eclipse plugin, the server runs using port 8888 by default:

http://localhost:8888/guestbook

If you're using the dev_appserver command to start the server, the default port is 8080:

http://localhost:8080/guestbook

For the rest of this tutorial, we'll assume the server is using port 8888.

The server calls the servlet, and displays the message in the browser.

Next...

You now have a complete App Engine application! You could deploy this simple greeting right now and share it with users worldwide.

This app displays a generic greeting to all users. Let's add a feature to customize the greeting for each visitor using Google Accounts.

Kumar's Blog

Sunday, November 17, 2013