English

Uploading and Managing a Java App

The App Engine Java SDK includes a command for interacting with App Engine. You can use this command to upload new versions of the code, configuration and static files for your app to App Engine. You can also use the command to manage datastore indexes and download log data.

Uploading the App

If you are using Eclipse and the Google Plugin, you can upload your application directly from within Eclipse. To upload the app, click the App Engine deploy button in the toolbar: The App Engine deploy button. For more information, see Google Eclipse Plugin.

You can also upload your application from a command prompt. To use other features of the command, such as downloading logs, you must run the command from the command prompt. The command to run is in the SDK's appengine-java-sdk/bin/ directory.

If you are using Windows, the command is as follows:

appengine-java-sdk\bin\appcfg.cmd [options] <action> <war-location>

If you are using Mac OS X or Linux, the command is as follows:

./appengine-java-sdk/bin/appcfg.sh [options] <action> <war-location>

The command takes the name of an action to perform and the location of your application's WAR directory as arguments.

To upload an application, use the update action, as follows:

./appengine-java-sdk/bin/appcfg.sh update myapp/war

These commands are OS-specific wrapper scripts that run the Java class com.google.appengine.tools.admin.AppCfg in appengine-java-sdk/lib/appengine-tools-api.jar.

Updating Indexes

When you upload an application using the update action, the update includes the app's index configuration (the datastore-indexes.xml and generated/datastore-indexes-auto.xml files). If the index configuration defines an index that doesn't exist yet on App Engine, App Engine creates the new index. Depending on how much data is already in the datastore that needs to be mentioned in the new index, the process of creating the index may take a while. If the app performs a query that requires an index that hasn't finished building yet, the query will raise an exception.

To prevent this, you must ensure that the new version of the app that requires a new index is not the live version of the application until the indexes finish building. One way to do this is to give the app a new version number in appengine-web.xml whenever you add or change an index in the configuration. The app is uploaded as a new version, and does not become the default version automatically. When your indexes have finished building, you change the default version to the new one using the "Versions" section of the Admin Console.

Another way to ensure that new indexes are built before the new app goes live is to upload the index configuration separately before uploading the app. To upload only the index configuration for an app, use the update_indexes action:

./appengine-java-sdk/bin/appcfg.sh update_indexes myapp/war

You can check the status of the app's indexes from the "Indexes" section of the Admin Console.

Managing Scheduled Tasks

App Engine supports scheduled tasks (known as cron jobs). You specify these in a file called cron.xml, and upload them using the update_cron command:

./appengine-java-sdk/bin/appcfg.sh update_cron myapp/war

appcfg update will also upload cron job specifications if the file exists. For more on cron jobs, see the Cron Jobs documentation.

Downloading Logs

App Engine maintains a log of messages that your application emits. App Engine also records each request in the log. You can browse your app's logs from the "Logs" section of the Admin Console.

If you wish to perform more detailed analysis of your application's logs, you can download the log data to a file on your computer. To download logs to a file named mylogs.txt, use the request_logs action, as follows:

./appengine-java-sdk/bin/appcfg.sh request_logs myapp/war mylogs.txt

By default, the command downloads log messages from the current calendar day (since midnight Pacific Time) with a log level of INFO or higher (omitting DEBUG level messages). The command overwrites the local log file. You can adjust the number of days, the minimum log level, and whether to overwrite or append to the local log file using command-line options. See below for more information on these options.

Command-Line Arguments

The AppCfg command takes a set of options, an action, and arguments for the action.

The following actions are available:

appcfg.sh [options] update <war-location>

Uploads files for an application given the application's root directory. The application ID and version are taken from the appengine-web.xml file.

appcfg.sh [options] rollback <war-location>

Undo a partially completed update for the given application. You can use this if an update was interrupted, and the command is reporting that the application cannot be updated due to a lock.

appcfg.sh [options] update_indexes <war-location>

Updates datastore indexes in App Engine to include newly added indexes. If a new version of your application requires an additional index definition that was added to the index configuration, you can update your index configuration in App Engine prior to uploading the new version of your application. Running this action a few hours prior to uploading your new application version will give the indexes time to build and be serving when the application is deployed.

appcfg.sh [options] request_logs <war-location> <output-file>

Retrieve log data for the application running on App Engine. output-file is the name of the file to create or replace. If output-file is a hyphen (-), the log data is printed to the console. The following options apply to request_logs:

--num_days=...

The number of days of log data to retrieve, ending on the current date at midnight UTC. A value of 0 retrieves all available logs. If --append is given, then the default is 0, otherwise the default is 1.

--severity=...

The minimum log level for the log messages to retrieve. The value is a number corresponding to the log level: 4 for CRITICAL, 3 for ERROR, 2 for WARNING, 1 for INFO, 0 for DEBUG. All messages at the given log level and above will be retrieved. Default is 1 (INFO).

appcfg.sh [options] help <war-location>

Print a help message about the given action, then quit.

The AppCfg command accepts the following options for all actions:

--email=...

The email address of the Google account of an administrator for the application, for actions that require signing in. If omitted and no cookie is stored from a previous use of the command, the command will prompt for this value.

--server=...

The App Engine server hostname. The default is appengine.google.com.

--host=...

The hostname of the local machine for use with remote procedure calls.

--sdk_root=...

A path to the App Engine Java SDK, if different from the location of the tool.

--passin

Do not store the administrator sign-in credentials as a cookie; prompt for a password every time.