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. Note that EAR is supported for the
Java 7 runtime only, not for the Java 8 runtime.
The 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.
META-INF directory has two configuration files:
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:
The WAR directory file
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
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
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
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. You can define the default
appengine-web.xml file with the
<service>default</service>, but it isn't necessary to do this. 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
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:
If you use any of these files, put them in the default service's WEB-INF directory.
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
Assuming that the top-level EAR directory is "my-application," define the file
<?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:
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
parameter or leave it out of the file. Here is the file
my-application/default/WEB-INF/appengine-web.xml that defines the default
<?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>
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
enumerates the services. Note that the default service should be the first
<?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.