appengine-web.xml Reference

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.

Example

The following example is a minimal file that specifies the application ID, a version identifier, and no static files or resource files:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
  <application>_your_app_id_</application>
  <version>alpha-001</version>
  <threadsafe>true</threadsafe>
</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 DTD and schema specifications for this file in the SDK's docs/ directory.

Element Description
<application>

Not required if you deploy your app using the gcloud app deploy command. gcloud and gcloud tooling (Intellij, Gradle, and the new maven plug-ins) ignore this element and get the project ID from the gcloud config project property. The <application> element contains the application's project ID. This is the project ID you register when you create your project in the Google Cloud Platform Console. When you upload your app, appcfg gets the project ID from this file.

<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 the 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:
default
Default. Uses scattered auto IDs that are large well-distributed integeres that are small enough to be reperesented by 64-bit floats.
legacy
The legacy option will be deprecated in a future release and will eventually be removed. For more information, see the blog post announcing this change.
<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 appengine-web.xml file can define environment variables that are set when the application is running.

<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 or XMPP messages, the application must be configured to enable the service. You enable the service for a Java app by including an <inbound-services> section in the appengine-web.xml file.

The following inbound services are available:

channel_presence
Registers your application for notifications when a client connects or disconnects from a channel.
mail
Allows your application to receive mail.
xmpp_message
Allows your application to receive instant messages.
xmpp_presence
Allows your application to receive a user's chat presence.
xmpp_subscribe
Allows your application to receive user subscription POSTs.
warmup
Enables warmup requests.
Example:
<inbound-services>
  <service>mail</service>
  <service>warmup</service>
</inbound-services>
<instance-class>

Optional. The instance class size for this module.

The following instance classes are available when specifying different scaling options:

automatic_scaling
When using automatic scaling, the F1, F2, F4, and F4_1G instance classes are available.
Default: F1 is assigned if you do not specify an instance class along with the automatic_scaling element.
basic_scaling
When using basic scaling, the B1, B2, B4, B4_1G, and B8 instance classes are available.
Default: B2 is assigned if you do not specify a instance class along with the basic_scaling element.
manual_scaling
When using basic scaling, the B1, B2, B4, B4_1G, and B8 instance classes are available.
Default: B2 is assigned if you do not specify a instance class along with the manual_scaling element.
<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 appengine-web.xml file:

<?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 appengine-web.xml files as modules, for example: <module>service_name</module>.

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 and cannot start or end with a hyphen. 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 <public-root> is a directory in your application that contains the static files for your application. When a request for a static file is made, the <public-root> for your application is prepended to the request path. This gives the path of an application file containing the content that is being requested.

The default <public-root> is /.

For example, the following would map the URL path /index.html to the application file path /static/index.html:

<?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 that listed in the <resource-files> element are accessible by the application code using the filesystem. These files are stored on the application servers with the app as opposed to how static files are stored and served.

The <resource-files> element can contain the following elements:

<include>
An <include> element designates the files as resource files and available to your application code. These files are only available to your code on a read-only basis and not for traffic serving. Including and excluding files.
<exclude>

Files and directories matching <exclude> patterns will not be uploaded or available to your application code. However, these files and directories will still be accessible to your application when running on the local Development Server. For more information, see Including and excluding files.

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

This example demonstrates how to designate all .xml files as resource files except those in the feeds/ directory and all of its subdirectories.

App Engine resource files are read using java.io.File or javax.servlet.ServletContext.getResource/getResourceAsStream. They are not accessible via Class.getResourceAsStream().

service

Services were formerly known as modules.

Currently, defining a service as: <service>service_name</service > is supported only by gcloud app commands.

<sessions-enabled>

Optional. App Engine includes an implementation of sessions, using the servlet session interface. The implementation stores session data in the App Engine 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 appengine-web.xml:

Example:
<?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 _ah_SESSION, and memcache entries using keys with a prefix of _ahs.

Note: Because App Engine stores session data in the datastore and memcache, all values stored in the session must implement the java.io.Serializable interface.

See async-session-persistance element for reducing the latency of the storage of session data.

<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 appengine-web.xml file:

<?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 appengine-web.xml file. To serve custom error pages, add a <static-error-handlers> section to your appengine-web.xml, as ins this example:

<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 file entry indicates a static file that should be served in place of the generic error response. The error-code indicates which error code should cause the associated file to be served. Supported error codes are as follows:

over_quota
Indicates that the app has exceeded a resource quota.
dos_api_denial
This option serves this error page to any client blocked by your app's DoS Protection configuration.
timeout
Served if a deadline is reached before there is a response from your app.

The error-code is optional; if it's not specified, the given file is the default error response for your app.

You can optionally specify a mime-type to use when serving the custom error. See a complete list of MIME types.

<static-files>

Optional. The <static-files> element specifies patterns that match file paths to include and exclude from the list of static files, overriding or amending the default behavior. Static file are served from dedicated servers and caches that are separate from the application servers and are useful for serving static content such as images, CSS stylesheets or JavaScript files.

The <static-files> element can contain the following elements:

<include>

An <include> element overrides the default behavior of including all non-JSP files. The <include> element can specify HTTP headers to use when responding to request for the specified resources. For more information, see Including and excluding files.

You can specify the static cache expiration by specifying the expiration attribute on the include element. The value is a string of numbers and units, separated by spaces, where units can be d for days, h for hours, m for minutes, and s for seconds. For example, "4d 5h" sets cache expiration to 4 days and 5 hours after the file is first requested. If the expiration time is omitted, the production server defaults to 10 minutes. For more information, see Static cache expiration.

<exclude>
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. For more information, see Including and excluding files.
Example
<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 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>
<threadsafe>

Required. When the threadsafe element in appengine-web.xml is false, App Engine sends requests serially to a given web server. When the value is true, App Engine can send multiple requests in parallel:

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

<version>

The <version> element contains the version identifier for the latest version of the app's code. The version identifier can contain lowercase letters, digits, and hyphens. It cannot begin with the prefix "ah-" and the names "default" and "latest" are reserved and cannot be used.

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 123.my-module.appspot.com, which can be interpreted two ways: If version "123" exists, the target will be version "123" of the given module. If that version does not exist, the target will be instance number 123 of the default version of the module.

The appcfg command 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 with a URL using "-dot-" as a subdomain separator in the URL, such as, https://_version_id_-dot-_your_app_id_.appspot.com. Using the Google Cloud Platform Console, you can select the default version of your app. The default version is loaded when no version, or an invalid version, is specified.

<warmup-requests-enabled>

Optional. Default: true. Warmup requests are enabled by default for Java applications.

With warmup requests enabled, the App Engine infrastructure issues `GET` requests to /_ah/warmup, initializing <load-on-startup> servlets, ServletContextListeners, and custom warmup servlets, which allow you to initialize your application's code as it requires. You might need to implement your own handler for /_ah/warmup depending on which of these methods you choose.

To disable warmup requests, specify false for this element:

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

Scaling elements

To learn more about how Google App Engine application scale, see How Applications Scale. The following table lists the options for defining how you can specify that your application should scale.

Element Description
<automatic-scaling>

Optional. Automatic scaling is assumed by default with a default instance class of F1 unless specified otherwise.

The automatic_scaling element sets minimum and maximum levels for number of instances, latency, and concurrent connections for a module.

This element can contain the following elements:

<max-concurrent-requests>

Optional. The number of concurrent requests an automatic scaling instance can accept before the scheduler spawns a new instance (Default: 8, Maximum: 80).

You might experience increased API latency if this setting is too high. Note that the scheduler might spawn a new instance before the actual maximum number of requests is reached.

<max-idle-instances>

The maximum number of idle instances that App Engine should maintain for this version. The default value is "automatic." Keep the following in mind:

  • A high maximum reduces the number of idle instances more gradually when load levels return to normal after a spike. This helps your application maintain steady performance through fluctuations in request load, but also raises the number of idle instances (and consequent running costs) during such periods of heavy load.
  • A low maximum keeps running costs lower, but can degrade performance in the face of volatile load levels.

Note: When settling back to normal levels after a load spike, the number of idle instances can temporarily exceed your specified maximum. However, you will not be charged for more instances than the maximum number you've specified.

<max-pending-latency>

The maximum amount of time that App Engine should allow a request to wait in the pending queue before starting a new instance to handle it. Default: "30ms".

  • A low maximum means App Engine will start new instances sooner for pending requests, improving performance but raising running costs.
  • A high maximum means users might wait longer for their requests to be served, if there are pending requests and no idle instances to serve them, but your application will cost less to run.
<min-idle-instances>

The minimum number of idle instances that App Engine should maintain for this version. Only applies to the default version of a module, since other versions are not expected to receive significant traffic. Keep the following in mind:

  • A low minimum helps keep your running costs down during idle periods, but means that fewer instances might be immediately available to respond to a sudden load spike.
  • A high minimum allows you to prime the application for rapid spikes in request load. App Engine keeps the minimum number of “resident instances” running at all times, so an instance is always available to serve an incoming request. You are charged for resident instances, whether or not they are handling requests. For resident instances to function properly, you must be sure that warmup requests are enabled and your application handles warmup requests. The Availability column of the Cloud Platform Console Instance page indicates whether an instance is resident or dynamic.

    If you set a minimum number of idle instances, pending latency will have less effect on your application's performance. Because App Engine keeps idle instances in reserve, it is unlikely that requests will enter the pending queue except in exceptionally high load spikes. You will need to test your application and expected traffic volume to determine the ideal number of instances to keep in reserve.

<min-pending-latency>

The minimum amount of time that App Engine should allow a request to wait in the pending queue before starting a new instance to handle it.

  • A low minimum means requests must spend less time in the pending queue when all existing instances are active. This improves performance but increases the cost of running your application.
  • A high minimum means requests will remain pending longer if all existing instances are active. This lowers running costs but increases the time users must wait for their requests to be served.
Example
<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>
    <min-idle-instances>5</min-idle-instances>
    <!-- ‘automatic’ is the default value. -->
    <max-idle-instances>automatic</max-idle-instances>
    <!-- ‘automatic’ is the default value. -->
    <min-pending-latency>30ms</min-pending-latency>
    <max-pending-latency>automatic</max-pending-latency>
    <max-concurrent-requests>50</max-concurrent-requests>
  </automatic-scaling>
</appengine-web-app>
<basic-scaling>

Optional. The <basic-scaling> element sets the number of instances for a module.

This element can contain the following elements:

<idle-timeout>
Optional. The instance will be shut down this amount of time after receiving its last request. The default is 5 minutes.
<max-instances>
Required. The maximum number of instances for App Engine to create for this module version. This is useful to limit the costs of a module.
Example
<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 <manual-scaling> element enables manual scaling for a module and sets the number of instances for a module.

This element can contain the following elements:

<instances>
The number of instances to assign to the module at the start.
Example
<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>

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 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 in web.xml using <mime-mapping> elements.

Static cache expiration

Unless told otherwise, web proxies and browsers retain files they load from a website for a limited period of time.

You can configure a cache duration for specific static file handlers by providing an expiration attribute to <static-files><include ... >. The value is a string of numbers and units, separated by spaces, where units can be d for days, h for hours, m for minutes, and s for seconds. For example, "4d 5h" sets cache expiration to 4 days and 5 hours after the file is first requested. If the expiration time is omitted, the production server defaults to 10 minutes.

For example:

<static-files>
  <include path="/**.png" expiration="4d 5h" />
</static-files>

The expiration time will be sent in the Cache-Control and Expires HTTP response headers, and therefore, the files are likely to be cached by the user's browser, as well as by intermediate caching proxy servers such as Internet Service Providers. After a file is transmitted with a given expiration time, there is generally no way to clear it out of intermediate caches, even if the user clears their own browser cache. Re-deploying a new version of the app will not reset any caches. Therefore, if you ever plan to modify a static file, it should have a short (less than one hour) expiration time. In most cases, the default 10-minute expiration time is appropriate.

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>

Envoyer des commentaires concernant…

App Engine standard environment for Java