English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# 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 {
        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:

- 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.

Continue to Using the Users Service.