Scheduling Tasks With Cron for Java

The App Engine Cron Service allows you to configure regularly scheduled tasks that operate at defined times or regular intervals. These tasks are commonly known as cron jobs. These cron jobs are automatically triggered by the App Engine Cron Service. For instance, you might use a cron job to send out an email report on a daily basis, or to update some cached data every 10 minutes, or refresh summary information once an hour.

A cron job invokes a URL, using an HTTP GET request, at a given time of day. An cron job request is subject to the same limits as those for push task queues.

Creating a cron job

  1. Create the cron.xml file in the WEB-INF/ directory of your application (alongside appengine-web.xml).
  2. Add one or more <cron> entries to your file and define the necessary elements for your job, including the required <url> and <schedule> elements.

    The following example creates a basic cron job that runs daily:

    <?xml version="1.0" encoding="UTF-8"?>
    <cronentries>
      <cron>
        <url>/tasks/summary</url>
        <target>v2.beta</target>
        <description>daily summary job</description>
        <schedule>every 24 hours</schedule>
      </cron>
    </cronentries>
    

    The target specification is optional and is the name of a service/version. If present, the target is prepended to your app's hostname, causing the job to be routed to that service/version. If no target is specified, the job will run in the default version of the default service.

  3. Create a handler for the cron job's URL. The handler should execute any tasks that you want scheduled. The handler should respond with an HTTP status code between 200 and 299 (inclusive) to indicate success. Other status codes can be returned and can be used to trigger retrying the job.

For more information about the syntax and parameters of the cron.xml, see the cron.xml reference.

Testing cron jobs in the development server

The development server doesn't automatically run your cron jobs. You can make requests directly to your cron job's URL to test your functionality. You can use your local cron or scheduled tasks interface to trigger the URLs of your jobs with curl or a similar tool.

Uploading cron jobs

You can use AppCfg to upload cron jobs.

Option 1: Upload your whole application

To upload your whole application, which also updates the Cron Service with the entries from your cron.xml file, run the following command:

./appengine-java-sdk/bin/appcfg.sh update <app-directory>
Option 2: Upload only your cron updates

To update just the cron configuration without uploading the rest of the application using AppCfg update_cron.

./appengine-java-sdk/bin/appcfg.sh update_cron <app-directory>

Deleting all cron jobs

To delete all cron jobs:

  1. Change the cron.xml file to just contain:

    <?xml version="1.0" encoding="UTF-8"?>
    <cronentries/>
    
  2. Upload your cron file.

Retrying cron jobs that fail

If a cron job's request handler returns a status code that is not in the range 200–299 (inclusive) App Engine considers the job to have failed. By default, failed jobs are not retried.

To set failed jobs to be retried:

  1. Include a retry-parameters block in your cron.xml file.
  2. Choose and set the retry parameters in the retry-parameters block.

    For example, this sample cron.xml file contains a single cron job that is configured to retry up to five times (the default) with a starting backoff of 2.5 seconds that doubles each time.

    <cronentries>
      <cron>
        <url>/retry</url>
        <description>Retry on jsdk</description>
        <schedule>every 10 minutes</schedule>
        <retry-parameters>
          <min-backoff-seconds>2.5</min-backoff-seconds>
          <max-doublings>5</max-doublings>
        </retry-parameters>
      </cron>
    </cronentries>
    

Learn more about the cron retry options

Securing URLs for cron

You can prevent users from accessing URLs used by scheduled tasks by restricting access to administrator accounts. Scheduled tasks can access admin-only URLs. You can read about restricting URLs at Security and Authentication. An example you would use in web.xml to restrict everything starting with /cron/ to admin-only is:

<security-constraint>
    <web-resource-collection>
        <web-resource-name>cron</web-resource-name>
        <url-pattern>/cron/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>admin</role-name>
    </auth-constraint>
</security-constraint>

For more on the format of web.xml, see the documentation on the deployment descriptor.

To test a cron job, sign in as an administrator and visit the URL of the handler in your browser.

Requests from the Cron Service will also contain a HTTP header:

X-Appengine-Cron: true

Requests from the Cron Service will also contain a HTTP header:

X-Appengine-Cron: true

The X-Appengine-Cron header is set internally by Google App Engine. If your request handler finds this header it can trust that the request is a cron request. If the header is present in an external user request to your app, it is stripped, except for requests from logged in administrators of the application, who are allowed to set the header for testing purposes.

Google App Engine issues Cron requests from the IP address 0.1.0.1.

Calling Google Cloud Endpoints

You cannot specify a Google Cloud Endpoint in the url field of a cron job. If you want your cron job to call a Google Cloud Endpoint, issue a request to a target that is served by a handler in your app, and call endpoint class and method from the handler code.

Viewing cron jobs in the Cloud Platform Console

The Cloud Platform Console Task queues page has a tab that shows the tasks that are running cron jobs.

You can also visit the Logs page see when cron jobs were added or removed.

Send feedback about...