Region ID
The REGION_ID is an abbreviated code that Google assigns
based on the region you select when you create your app. The code does not
correspond to a country or province, even though some region IDs may appear
similar to commonly used country and province codes. For apps created after
February 2020, REGION_ID.r is included in
App Engine URLs. For existing apps created before this date, the
region ID is optional in the URL.
Learn more about region IDs.
In addition to the web.xml deployment
descriptor, App Engine Java
applications use a configuration file, named appengine-web.xml,
to specify information about your app and to identify which files in the app's
WAR file are static files (like images) and which are resource files used by
the application.
Example
The following example is a minimal file that specifies the Java 8 runtime with no static files or resource files:
<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<threadsafe>true</threadsafe>
<runtime>java8</runtime>
</appengine-web-app>
Syntax
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>.
You can find the Document Type Definition and schema specifications for the
appengine-web.xml in the SDK's docs/ directory.
| Element | Description |
|---|---|
<async-session-persistence> |
Optional. It's possible to reduce request latency by configuring your application to asynchronously write HTTP session data to the datastore: <?xml version="1.0" encoding="utf-8"?> <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <!-- ... --> <async-session-persistence enabled="true" /> <!-- ... --> </appengine-web-app> With async session persistence turned on, App Engine will submit a Task Queue task to write session data to the datastore before writing the data to memcache. By default the task will be submitted to the `default` queue. If you'd like to use a different queue, add the `queue-name` attribute: <?xml version="1.0" encoding="utf-8"?> <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <!-- ... --> <async-session-persistence enabled="true" queue-name="myqueue"/> <!-- ... --> </appengine-web-app> Session data is always written synchronously to memcache. If a request tries to read the session data when memcache is not available (or the session data has been flushed), it will fail over to Datastore, which might not yet have the most recent session data. This means that asynchronous session persistence can cause your application to see stale session data. However, for most applications the latency benefit far outweighs the risk. |
<auto-id-policy> |
Optional. If you are
setting entity identifiers automatically, you can change the method
employed by setting the auto ID policy. The following are valid options:
|
<automatic-scaling> |
Optional. For a full explanation, see the automatic scaling section. |
<basic-scaling> |
Optional. For a full explanation, see the basic scaling section. |
<env-variables> |
Optional.
The <env-variables> <env-var name="DEFAULT_ENCODING" value="UTF-8" /> </env-variables> To avoid conflicts with your local environment, the development server does not set environment variables based on this file, and requires that the local environment have these variables already set to matching values. export DEFAULT_ENCODING="UTF-8" dev_appserver war When deployed to App Engine, the environment is created with these variables already set. |
<inbound-services> |
Optional.
Before an application can receive email, the
application must be configured to enable the service.
You enable the service for a Java 8 app by including an
The following inbound service is available:
|
<instance-class> |
Optional. The instance class size for this module. The following instance classes are available when specifying different scaling options:
|
<manual-scaling> |
Optional. For a full explanation, see the manual scaling section. |
<precompilation-enabled> |
Optional. App Engine uses a "precompilation" process with the Java bytecode of an app to enhance the performance of the app in the Java runtime environment. Precompiled code functions identically to the original bytecode.
If for some reason you prefer that your app not use precompilation,
you can turn it off by adding the following to your
<?xml version="1.0" encoding="utf-8"?> <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <!-- ... --> <precompilation-enabled>false</precompilation-enabled> <!-- ... --> </appengine-web-app> |
module |
Note: Modules are now named
Services
and services are still declared in Required if creating a service. Optional for the default service. Each service and each version must have a name. A name can contain numbers, letters, and hyphens. It cannot be longer than 63 characters, start or end with a hyphen, and contain the string `-dot`. Choose a unique name for each service and each version. Don't reuse names between services and versions. Also see service. |
<public-root> |
Optional.
The
The default
For example, the following would map the URL path
<?xml version="1.0" encoding="utf-8"?> <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <!-- ... --> <public-root>/static</public-root> <!-- ... --> </appengine-web-app> |
<resource-files> |
Optional. The files listed in the
The
App Engine resource files are read using |
runtime |
To use the Java 8 runtime, you must specify this entry with the value
Example: <?xml version="1.0" encoding="utf-8"?> <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <!-- ... --> <runtime>java8</runtime> <!-- ... --> </appengine-web-app> |
service |
Services were formerly known as modules. Currently, defining a service as:
|
service-account |
Optional. The <?xml version="1.0" encoding="utf-8"?> <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <!-- ... --> <service-account>[SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com</service-account> <!-- ... --> </appengine-web-app> |
<sessions-enabled> |
Optional. App Engine includes an implementation of sessions, using the servlet session interface. The implementation stores session data in Datastore for persistence, and also uses memcache for speed. As with most other servlet containers, the session attributes that are set with `session.setAttribute()` during the request are persisted at the end of the request.
This feature is off by default. To turn it on, add the following to
<?xml version="1.0" encoding="utf-8"?> <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <!-- ... --> <sessions-enabled>true</sessions-enabled> <!-- ... --> </appengine-web-app>
The implementation creates Datastore entities of the kind
Note: Because App Engine stores session data in
Datastore and memcache, all values stored in the session must
implement the
See
|
<ssl-enabled> |
Optional. By default, any user can access any URL using either HTTP or HTTPS. You can configure an app to require HTTPS for certain URLs in the deployment descriptor. See Deployment Descriptor: Secure URLs.
If you want to disallow the use of HTTPS for the application, put the
following in the <?xml version="1.0" encoding="utf-8"?> <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <!-- ... --> <ssl-enabled>false</ssl-enabled> <!-- ... --> </appengine-web-app> There is no way to disallow HTTPS for some URL paths and not others in the Java runtime environment. |
<static-error-handlers> |
Optional.
When certain errors occur, App Engine serves a generic error
page. You can configure your app to serve a custom static file instead
of these generic error pages, so long as the custom error data is less
than 10 kilobytes. You can set up different static files to be served
for each supported error code by specifying the files in your app's
<static-error-handlers> <handler file="default_error.html" /> <handler file="over_quota.html" error-code="over_quota" /> </static-error-handlers> Warning: Make sure that the path to the error response file does not overlap with static file handler paths.
Each
The
You can optionally specify a |
<static-files> |
Optional.
The
The
<static-files> <include path="/my_static-files" > <http-header name="Access-Control-Allow-Origin" value="http://example.org" /> </include> </static-files> |
<system-properties> |
Optional. The <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> |
<threadsafe> |
Required.
When the <?xml version="1.0" encoding="utf-8"?> <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <!-- ... --> <threadsafe>true</threadsafe> <!-- ... --> </appengine-web-app>
If you wish to use concurrent requests, your application code needs to
use proper thread synchronization before you enable
This element is not supported in the Java 11+ runtimes. |
<url-stream-handler> |
Optional. Possible values, The default value is If you set <?xml version="1.0" encoding="utf-8"?> <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <!-- ... --> <url-stream-handler>urlfetch</url-stream-handler> <!-- ... --> </appengine-web-app> |
<version> |
The
Version names should begin with a letter, to distinguish them from
numeric instances which are always specified by a number. This avoids
the ambiguity with URLs like
App Engine uses this version identifier to determine whether
to 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 with a URL
using "-dot-" as a subdomain separator in the URL, such as,
|
<warmup-requests-enabled> |
Optional. Default: true. Warmup requests are enabled by default for Java 8 applications.
With warmup requests enabled, the App Engine infrastructure issues `GET`
requests to
To disable warmup requests, specify <?xml version="1.0" encoding="utf-8"?> <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <!-- ... --> <warmup-requests-enabled>false</warmup-requests-enabled> <!-- ... --> </appengine-web-app> |
<vpc-access-connector> |
Optional. Configures your application to use a Serverless VPC Access connector, enabling the application to send requests to internal resources in your VPC network. For more information, see Connecting to a VPC network.
<vpc-access-connector> <name>projects/PROJECT_ID/locations/REGION/connectors/CONNECTOR_NAME</name> <egress-setting>all-traffic</egress-setting> </vpc-access-connector> |
Scaling elements
The following table lists the options for defining how you can specify that your application should scale.
For a comparison of the performance features of the scaling types, see Scaling dynamic instances.
| Element | Description |
|---|---|
<automatic-scaling> |
Optional. Automatic scaling is assumed by default with a default
instance class of
The This element can contain the following elements:
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <application>simple-app</application> <module>default</module> <version>uno</version> <threadsafe>true</threadsafe> <instance-class>F2</instance-class> <automatic-scaling> <target-cpu-utilization>0.65</target-cpu-utilization> <min-instances>5</min-instances> <max-instances>100</max-instances> <max-concurrent-requests>50</max-concurrent-requests> </automatic-scaling> </appengine-web-app> |
<basic-scaling> |
Optional.
The This element can contain the following elements:
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <application>simple-app</application> <module>default</module> <version>uno</version> <threadsafe>true</threadsafe> <instance-class>B8</instance-class> <basic-scaling> <max-instances>11</max-instances> <idle-timeout>10m</idle-timeout> </basic-scaling> </appengine-web-app> |
<manual-scaling> |
Optional.
The This element can contain the following elements:
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <application>simple-app</application> <module>default</module> <version>uno</version> <threadsafe>true</threadsafe> <instance-class>B8</instance-class> <manual-scaling> <instances>5</instances> </manual-scaling> </appengine-web-app> |
Staging elements
Much of the work done during a deployment occurs locally in a preparation step called staging, where JAR files are assembled, JSPs are compiled, and so forth. You can optionally configure certain parts of the staging behavior using staging elements in the application configuration file. Most applications will deploy successfully without manually configuring staging behavior. If your app doesn't deploy, you may need to configure staging using the options shown below.
| Element | Description |
|---|---|
<staging> |
Optional. Most applications do not need to change default behavior. The staging element allows you to specify a particular staging configuration if needed for deployment. This element can contain the following elements:
For example:
<staging>
<delete-jsps>false</delete-jsps>
</staging>
|
Staging option defaults
The defaults for staging options are as follows:
| Staging element | Default value |
|---|---|
enable-jar-splitting |
true |
jar-splitting-excludes |
NA |
disable-jar-jsps |
false |
enable-jar-classes |
true. This can impact class loading order, so if your app depends on a certain order, set this to false. |
delete-jsps |
true |
compile-encoding |
utf-8 |
Include and exclude syntax
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. Files and directories matching <exclude>
patterns will not be uploaded when you deploy your app to App Engine. However,
these files and directories will still be accessible to your application when
running on the local Development Server.
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).
The following example demonstrates how to designate all .png files as static
files (except those in the data/ directory and all of its subdirectories):
<static-files>
<include path="/**.png" />
<exclude path="/data/**.png" />
</static-files>
You can also set HTTP headers to use when responding to requests to these static resources.
<static-files>
<include path="/my_static-files" >
<http-header name="Access-Control-Allow-Origin"
value="http://example.org" />
</include>
</static-files>
MIME types for static files
By default, static files are served using a MIME type selected based on the
filename extension. You can associate custom MIME types with filename
extensions for static files using <mime-mapping> elements in web.xml.
URLFetch timeout
You can set a deadline for each
URLFetch request. By default, the deadline for a fetch is 5 seconds.
You can change this default by including the following setting in your
appengine-web.xml configuration file. Specify the timeout in seconds:
<system-properties>
<property name="appengine.api.urlfetch.defaultDeadline" value="10"/>
</system-properties>