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.
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>application-id</application> <version>1</version> </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 Admin 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 letters, digits, and hyphens. 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 using a URL such as http://version-id.latest.application-id.appspot.com. You can select which version of the app your users see, the "default" version, using the Admin Console.
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.
Many web applications have files that are served directly to the user's browser, such as images, CSS stylesheets, 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.
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, amending the default behavior. Similarly, the <resource-files> element specifies which files are considered resource 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.
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).
For example, to specify that all files whose names end in .png are static files (but never those in WEB-INF/) except those in the data/ directory and all subdirectories:
|
<static-files>
<include path="/**.png" />
<exclude path="/data/**.png" />
</static-files>
Similarly, to specify that all files whose names end in .xml are resource files (including those outside of WEB-INF/) except those in the feeds/ directory and all subdirectories:
<resource-files>
<include path="/**.xml" />
<exclude path="/feeds/**.xml" />
</resource-files>
You can specify a browser cache expiration time for static files. To do so, provide 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 loaded by the browser.
<static-files>
<include path="/**.png" expiration="4d 5h" />
</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.
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>
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:
<ssl-enabled>false</ssl-enabled>
There is no way to disallow HTTPS for some URL paths and not others in the Java runtime environment.
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 saved to the datastore at the end of the request.
This feature is off by default. To turn it on, add the following to appengine-web.xml:
<sessions-enabled>true</sessions-enabled>
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.
Before an application can receive XMPP messages, the application must be configured to enable those services. You enable these services for a Python app by including an <inbound-services> element in the appengine-web.xml file.
To enable incoming XMPP messages, add the following to appengine-web.xml:
<inbound-services>
<service>xmpp_message</service>
</inbound-services>