English

Google App Engine

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: The New Web Application Project button. 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 {
    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 named web.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"?>
<!DOCTYPE web-app PUBLIC
 "-//Oracle Corporation//DTD Web Application 2.3//EN"
 "http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app xmlns="http://java.sun.com/xml/ns/javaee" version="2.5">
    <servlet>
        <servlet-name>guestbook</servlet-name>
        <servlet-class>guestbook.GuestbookServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>guestbook</servlet-name>
        <url-pattern>/guestbook</url-pattern>
    </servlet-mapping>
    <welcome-file-list>
        <welcome-file>index.html</welcome-file>
    </welcome-file-list>
</web-app>

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"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
    <application></application>
    <version>1</version>
</appengine-web-app>

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 the appengine-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:

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

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.

Continue to Using the Users Service.