Configuration Files

Note: Services were previously called "modules", and services are still declared in appengine-web.xml files as modules, for example: <module>service_name</module>.

An App Engine application that uses services is organized as an unpacked Java Enterprise Archive (EAR) directory structure. The top-level EAR directory contains a single META-INF subdirectory, and a separate directory for each service in the app. These service directories are organized as unpacked Java Web Application Archives (WAR). Each WAR directory usually has the same name as the service it defines, but this is not required. Although Java EE supports WAR files, service configuration uses unpacked WAR directories only. The App Engine Maven plugin includes archetypes that you can use to build a skeletal EAR structure.

Hierarchy graph of EAR directories

The META-INF directory has two configuration files: appengine-application.xml and application.xml. The appengine-application.xml file contains general information used by App Engine tools when your app is deployed. The application.xml file declares the list of services and their WAR directories that comprise the application. The WAR directory for each service contains two configuration files: appengine-web.xml, and web.xml.

The WAR directory file appengine-web.xml defines the configuration of services. Each service has its own file, which defines the scaling type and instance class for a specific service/version. Different scaling parameters are used depending on which type of scaling you specify. If you do not specify scaling, automatic scaling is the default.

Note that while every appengine-web.xml file must contain the <application> tag, the name you supply there is ignored. The name of the application is taken from the <application> tag in the appengine-application.xml file.

For each service you can also specify settings that map URL requests to specific Java servlets and identify static files for better server efficiency. These settings are included in the web.xml and appengine-web.xml files and are described in the web.xml Deployment Descriptor and appengine-web.xml reference sections.

The default service

Every application has a single default service. The default service is defined by the standard appengine-web.xml file or by an appengine-web.xml with the setting <service>default</service>. All configuration parameters relevant to services can apply to the default service.

Also be sure to list the default service as the first service in the EAR directory's META-INF/application.xml file, as shown in the example below.

Optional configuration files

These configuration files control optional features that apply to all the services in an app:

  • dispatch.xml
  • queue.xml
  • datastore-indexes.xml
  • cron.xml
  • dos.xml

If you use any of these files, put them in the default service's WEB-INF directory.

An example

Here is an example of how you would configure the various files in an EAR directory structure for an application that has two services: a default service that handles web requests, plus another service (named my-service) for backend processing.

Assuming that the top-level EAR directory is "my-application," define the file my-application/META-INF/appengine-application.xml:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<appengine-application xmlns="http://appengine.google.com/ns/1.0">
  <application>my-application</application>
</appengine-application>

Create WAR directories for the two services: my-application/default and my-application/my-service.

Now create an appengine-web.xml file in each WAR that specifies the parameters for the service. The file must include a version name for the service. To define the default service, you can explicitly include the <service>default</service> parameter or leave it out of the file. Here is the file my-application/default/WEB-INF/appengine-web.xml that defines the default service:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>my-application</application>
  <module>default</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
</appengine-web-app>

The file my-application/my-service/WEB-INF/appengine-web.xml defines the service that will handle background requests:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>my-application</application>
  <module>my-service</module>
  <version>uno</version>
  <threadsafe>true</threadsafe>
  <manual-scaling>
    <instances>5</instances>
  </manual-scaling>
</appengine-web-app>

Finally, define the file my-application/META-INF/application.xml that enumerates the services. Note that the default service should be the first service listed.

<?xml version="1.0"
encoding="UTF-8"?>

<application
  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/application_5.xsd"
  version="5">

  <description>GAE Java SuperFun app</description>
  <display-name>SuperFun</display-name>

  <!-- Services -->
  <!-- The default service should be listed first -->
  <module>
    <web>
      <web-uri>default</web-uri>
      <context-root>default</context-root>
    </web>
  </module>
  <module>
    <web>
      <web-uri>my-service</web-uri>
      <context-root>my-service</context-root>
    </web>
  </module>

</application>

App Engine will ignore the <context-root> elements, so HTTP clients need not prepend it to the URL path when addressing a service.