-
Notifications
You must be signed in to change notification settings - Fork 64
appref xml
ludoch edited this page Apr 15, 2026
·
2 revisions
Note: If you use legacy bundled services and want to upgrade to Java 25, you can
choose to continue using javax.servlet.* APIs only if your apps run on Java
Enterprise Edition 8 (EE 8). You must update your appengine-web.xml file if
you choose to remain on EE 8. To learn more about your configuration options,
see Upgrade an existing application.
You should use the appengine-web.xml file for configuring your app only if you
are migrating an existing app from the App Engine Java 8 runtime to the latest
supported Java version and you want to use the legacy bundled
services. If you are using an appengine-web.xml in
your project, the app.yaml is automatically generated for you at deployment.
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.
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.
Note: The standard appengine-web.xml file defines the default service. You
will need to specify additional configuration parameters for each non-default
service, which were formerly known as modules. These are described in the
overview of App Engine. You
can also apply these configuration parameters to the default service.
<tr id="automatic_scaling">
<td>`<automatic-scaling>`</td>
<td>
Optional. For a full explanation, see the <a
href="#scaling_elements_automatic_scaling">automatic scaling</a>
section.
</td>
</tr>
<tr id="basic_scaling">
<td>`<basic-scaling>`</td>
<td>
Optional. For a full explanation, see the <a
href="#scaling_elements_basic_scaling">basic scaling</a> section.
</td>
</tr>
<tr id="environment_variables">
<td>`<env-variables>`</td>
<td>
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.
To determine how long a connection remains inactive without any data
transmission before the client closes it, configure an idle timeout using
the following syntax:
<env-variables>
<env-var name="APPENGINE_API_CALLS_IDLE_TIMEOUT_MS" value="TIMEOUT_IN_MS" />
</env-variables> Replace `TIMEOUT_IN_MS` with the required timeout in
milliseconds.
To match a 60-second overall request/URL Fetch deadline,
set it to `60000`. Alternatively, setting it slightly less
than the server-side timeout (often 60 seconds) might be beneficial, for
example, `59000`. The current default is `58000`
milliseconds.
This idle timeout configuration isn't the same as the overall request
deadline for scaling, or the URL Fetch API deadline that you configure using
<code><a href="#url-fetch-timeout">appengine.api.urlfetch.defaultDeadline</a></code>.
</td>
</tr>
<tr id="inbound_services">
<td>`<inbound-services>`</td>
<td>
Optional.
Before an application can receive email, 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 service is available:
<dl>
<dt id="inbound_services_mail">`mail`</dt>
<dd>
Allows your application to <a
href="/appengine/docs/standard/services/mail/receiving-mail-with-mail-api?tab=java">receive mail</a>.
</dd>
<tr id="url-stream-handler">
<td>`<url-stream-handler>`</td>
<td>
Optional. Possible values, `native` or `urlfetch`.
The default value is `native`, which means that standard
Java network classes use the standard Java HTTP(S) transport.
To use this setting, you must enable billing for your app, or you
will get exceptions, which are documented in
<a href="/appengine/docs/standard/services/urlfetch/issue-requests">Issue requests</a>.
If you set `url-stream-handler` to
`urlfetch`,
<a href="https://docs.oracle.com/javase/8/docs/api/java/net/URL.html#openConnection--">`URL.openConnection`</a>
and related methods will use URL Fetch for `http` and `https` transport.
<url-stream-handler>urlfetch</url-stream-handler> </td>
</tr>
<tr id="version">
<td>`<version>`</td>
<td>
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.uc.r.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.
</td>
</tr>
<tr id="warmup_requests_enabled">
<td>`<warmup-requests-enabled>`</td>
<td>
Optional. Default: true. Warmup requests are enabled by default for
Java applications.
With <href="/appengine/docs/standard/configuring-warmup-requests">warmup requests</a>
enabled, the App Engine infrastructure issues `GET`
requests to `/_ah/warmup`, initializing
`<load-on-startup>` servlets,
`ServletContextListeners`</a>, 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:
<warmup-requests-enabled>false</warmup-requests-enabled> </td>
</tr>
<tr id="vpc_access_connector">
<td>`<vpc-access-connector>`</td>
<td>
Optional.
Configures your application to use a Serverless VPC Access
connector, enabling the application to send requests to internal
resources in your VPC network. Specify the fully-qualified name of a
connector in the `<name>` element:
<vpc-access-connector>
<name>projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]</name>
</vpc-access-connector> For more information, see
<a href="/appengine/docs/standard/connecting-vpc">Connecting to internal resources in a VPC network</a>.
</td>
</tr>
| Element | Description |
|---|---|
| `<application>` |
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<entrypoint>
java
-showversion -Xms32M -Xmx819M -XX:+UseG1GC -XX:+ParallelRefProcEnabled
-XX:+PrintCommandLineFlags
--add-opens java.base/java.lang=ALL-UNNAMED
--add-opens java.base/java.nio.charset=ALL-UNNAMED
--add-opens java.logging/java.util.logging=ALL-UNNAMED
--add-opens java.base/java.util.concurrent=ALL-UNNAMED
-Dclasspath.runtimebase=/base/java_runtime
-Djava.class.path=/base/java_runtime/runtime-main.jar
-Djava.library.path=/base/java_runtime:
com/google/apphosting/runtime/JavaRuntimeMainWithDefaults
--fixed_application_path=/workspace
/base/java_runtime
</entrypoint>
</appengine-web-app><async-session-persistence enabled="true" /><async-session-persistence enabled="true" queue-name="myqueue"/>href="http://googlecloudplatform.blogspot.com/2013/05/update-on-datastore-auto-ids.html" target="_blank">blog post announcing this change. |
| `<instance-class>` |
<precompilation-enabled>false</precompilation-enabled><public-root>/static</public-root><runtime>java25</runtime><service-account>[SERVICE_ACCOUNT_NAME]@[PROJECT_ID].</service-account>href="https://docs.oracle.com/javaee/7/api/javax/servlet/http/HttpSession.html"
target="_blank">the servlet session interface.
The implementation stores session data in Cloud Datastore for
persistence, and also uses memcache for speed. As with most other servlet
containers, the session attributes that are set with <sessions-enabled>true</sessions-enabled><ssl-enabled>false</ssl-enabled>be Optional. You can configure an HTTP connector for improving CPU and memory utilization. If your application interacts with Cloud Datastore or Task Queues operations, set up monitoring to monitor performance and behavior impacts after enabling this feature. <system-properties>
<property name="appengine.use.httpconnector" value="true"/>
</system-properties><system-properties>
<property name="appengine.use.EE11" value="true"/><!--only for Java 25-->
</system-properties><system-properties>
<property name="appengine.use.virtualthreads" value="true"/>
</system-properties>For more information regarding thread support, see Jetty 12 – Virtual Threads Support. |
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>` |
|
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 in the following table.
| Element | Description |
|---|---|
| `<staging>` |
|
The defaults for staging options are different depending on whether you use gcloud CLI-based tooling, such as the gcloud CLI, or the gcloud CLI-based Maven, Gradle, or IntelliJ plugins.
Staging element | App Engine SDK-based defaults -| gcloud CLI-based
defaults --------------- | ----------------------------- |
------------------------ enable-jar-splitting | false
| true jar-splitting-excludes | N/A | N/A
disable-jar-jsps | false | false
enable-jar-classes | false | true. This can
impact class loading order, so if your app depends on a certain order using the
former false default, you can set this to false. delete-jsps |
false | true compile-encoding | utf-8
| utf-8
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
won't 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):
You can also set HTTP headers to use when responding to requests to these static resources.
Note: If the path string doesn't start with a slash, then the HTTP headers, if
any, work on App Engine but do not work on the Development Server.
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.
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>