English | Site Directory

Java Application Configuration

In addition to the web.xml deployment descriptor, an App Engine Java application uses a configuration file, named appengine-web.xml, to specify the app's registered application ID and the version identifier of the latest code, and to identify which files in the app's WAR are static files (like images) and which are resource files used by the application. The AppCfg command uses this information when you upload the app.

About appengine-web.xml

An App Engine Java app must have a file named appengine-web.xml in its WAR, in the directory WEB-INF/. This is an XML file whose root element is <appengine-web-app>. A minimal file that specifies the application ID, a version identifier, and no static files or resource files looks like this:

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

The <application> element contains the application's ID. This is the application ID you register when you create your application in the Admin Console. When you upload your app, AppCfg gets the application ID from this file.

The <version> element contains the version identifier for the latest version of the app's code. It can be any string. AppCfg uses this version identifier when it uploads the application, telling App Engine to either create a new version of the app with the given identifier, or replace the version of the app with the given identifier if one already exists. You can test new versions of your app using a URL such as http://version-id.latest.application-id.appspot.com. You can select which version of the app your users see, the "default" version, using the Admin Console.

The <static-files> and <resource-files> elements are described in the next section.

You can find the DTD and schema specifications for this file in the SDK's docs/ directory.

Static Files and Resource Files

Many web applications have files that are served directly to the user's browser, such as images, CSS stylesheets, or browser JavaScript code. These are known as static files because they do not change, and can benefit from web servers dedicated just to static content. App Engine serves static files from dedicated servers and caches.

Files that are accessible by the application code using the filesystem are called resource files. These files are stored on the application servers with the app.

By default, all files in the WAR are treated as both static files and resource files, except for JSP files, which are compiled into servlet classes and mapped to URL paths, and files in the WEB-INF/ directory, which are never served as static files and always available to the app as resource files.

You can adjust which files are considered static files and which are considered resource files using elements in the appengine-web.xml file. The <static-files> element specifies patterns that match file paths to include and exclude from the list of static files, amending the default behavior. Similarly, the <resource-files> element specifies which files are considered resource files.

Path patterns are specified using zero or more <include> and <exclude> elements. In a pattern, * represents zero or more of any character in a file or directory name, and ** represents zero or more directories in a path.

An <include> element overrides the default behavior of including all files. An <exclude> element applies after all <include> patterns (as well as the default if no explicit <include> is provided).

For example, to specify that all files whose names end in .png are static files (including those in WEB-INF/) except those in the data/ directory and all subdirectories:

    <static-files>
        <include path="/**.png" />
        <exclude path="/data/**.png" />
    </static-files>

Similarly, to specify that all files whose names end in .xml are resource files (including those outside of WEB-INF/) except those in the feeds/ directory and all subdirectories:

    <resource-files>
        <include path="/**.xml" />
        <exclude path="/feeds/**.xml" />
    </resource-files>

Static files are served using a MIME type selected based on the filename extension. To serve a file with a custom MIME type, make the file a resource file instead of a static file, and create a servlet that serves the data with the custom MIME type.

System Properties and Environment Variables

The appengine-web.xml file can define system properties and environment variables that are set when the application is running.

    <system-properties>
        <property name="myapp.maximum-message-length" value="140" />
        <property name="myapp.notify-every-n-signups" value="1000" />
        <property name="myapp.notify-url" value="http://www.example.com/signupnotify" />
    </system-properties>

    <env-variables>
        <env-var name="DEFAULT_ENCODING" value="UTF-8" />
    </env-variables>

Enabling Secure URLs (SSL)

If your application uses secure URLs (SSL, such as https://...), you must enable SSL for the application in the appengine-web.xml file. To enable SSL, add an <ssl-enabled> element to the file:

    <ssl-enabled>true</ssl-enabled>

See Deployment Descriptor: Secure URLs for more information about defining secure URLs.

Enabling Sessions

App Engine includes an implementation of sessions, using the servlet session interface. The implementation uses the App Engine datastore and memcache to store session data.

This feature is off by default. To turn it on, add the following to appengine-web.xml:

    <sessions-enabled>true</sessions-enabled>

The implementation creates datastore entities of the kind _ah_SESSION, and memcache entries using keys with a prefix of _ahs.