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.
Note: If you created your project using the Google Developers Console , your project has a title and an ID. In the instructions that follow, the project title and ID can be used wherever an application title and ID are mentioned. They are the same thing.
-
About
appengine-web.xml
- Static files and resource files
- System properties and environment variables
- Configuring Secure URLs (SSL)
- Enabling sessions
- Reserved URLs
- Inbound services
- Warmup requests
- Disabling precompilation
- Administration console custom pages
- Custom error responses
- Using concurrent requests
- Custom PageSpeed configuration
- Auto ID policy
About
appengine-web.xml
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>
. A minimal file that specifies the application ID, a version identifier, and no static files or resource files looks like this:
<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<application>_your_app_id_</application>
<version>1</version>
<threadsafe>true</threadsafe>
</appengine-web-app>
The
<application>
element contains the application's ID. This is the application ID you register when you create your application in the
Google Developers Console
. When you upload your app, AppCfg gets the application ID from this file.
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. AppCfg 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, e.g.,
http://_version_id_-dot-_your_app_id_.appspot.com
. Using the
Google Developers Console
, you can select the default version of your app. The default version is loaded when no version, or an invalid version, is specified.
The
<threadsafe>
element defines whether App Engine can send multiple requests at the same time to a given web server. It is further described in the section
Using concurrent requests
.
The
<static-files>
and
<resource-files>
elements are described in the next section.
You can find the DTD and schema specifications for this file in the SDK's
docs/
directory.
Static files and resource files
Many web applications have files that are served directly to the user's browser, such as images, CSS style sheets, or browser JavaScript code. These are known as static files because they do not change, and can benefit from web servers dedicated just to static content. App Engine serves static files from dedicated servers and caches that are separate from the application servers.
Files that are accessible by the application code using the filesystem are called resource files . These files are stored on the application servers with the app.
By default, all files in the WAR are treated as both static files and resource files, except for JSP files, which are compiled into servlet classes and mapped to URL paths, and files in the
WEB-INF/
directory, which are never served as static files and always available to the app as resource files.
You can adjust which files are considered static files and which are considered resource files using elements in the
appengine-web.xml
file. 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. Similarly, the
<resource-files>
element specifies which files are considered resource files.
Including and excluding files
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" />
Similarly, the following sample demonstrates how to designate all
.xml
files as resource files (except those in the
feeds/
directory and all of its subdirectories):
<resource-files>
<include path="/**.xml" />
<exclude path="/feeds/**.xml" />
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>
Changing the MIME type 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.
Changing the root directory
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
:
<public-root>/static</public-root>
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.
(Script handlers can set cache durations by returning the appropriate HTTP headers to the browser.)
For example:
<static-files>
<include path="/**.png" expiration="4d 5h" />
</static-files>