Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)



Java Backends Configuration

The Backend API is deprecated as of March 13, 2014. Although Google will continue to support the Backend API in accordance with our terms of service , it is strongly recommended that all new applications use the Modules API instead.

For information on converting existing apps using the Backend API to the Modules API, see Converting Apps to Modules

You can add backends to your application in a configuration file called backends.yaml , which declares the name and desired properties of each backend server. The backends.yaml file is stored in the application's WEB-INF directory.

  1. About backends.yaml
  2. Types of backends
  3. Request handling
  4. Defining handlers
  5. Instance classes
  6. Backends definitions

About backends.yaml

Backends have several unique and important differences from default App Engine instances; for more information about how backends work, please see the Backends documentation . The following code sample shows a sample backends.yaml file. This configuration file defines four separate backends:

  1. A backend named memdb . This backend has five instances of the instance class B8.
  2. A backend named crawler uses the default class and options, but with ten instances.
  3. A backend named worker using the default class with one instance, and configured with failfast to disable pending queue behavior.
  4. A backend named cmdline , used to execute long-running commands issued by admins of the application. 
backends:
- name: memdb
  class: B8
  instances: 5
- name: crawler
  instances: 10
- name: worker
  options: failfast
- name: cmdline
  options: dynamic

Types of backends

App Engine supports two backend types: resident and dynamic. Resident backends are the default type of backend; they use resident instances, which remain in memory, even when idle, and are restarted automatically. This allows you to perform larger tasks or tasks requiring continuous processing. By default, a backend is configured with one instance, but you can add more in the configuration file.

The following table compares the major features of resident and dynamic backends:

Resident Backends Dynamic Backends Other Notes
Instance type Resident
Dynamic Both resident and dynamic backends have one instance by default. You can configure the number of instances using the optional instances element. Startup Manual, via the Admin Console or command-line tool Upon receipt of an HTTP request Shutdown Usually manual, via the Admin Console or command-line tool After sitting idle for a few minutes. Other factors can affect shutdown. See Shutdown for more information. State Preserved until manually shut down, or until an unexpected shutdown event takes place. See Shutdown for more details on shutdown events. Erased when the backend is shutdown after sitting idle for a few minutes. Type of Processing Continuous or driven by requests Driven by requests Cost Relatively more, because resident backends run continuously. Relatively less, because dynamic backends terminate when idle. Billed by the hour , even if idle Uses Any work that requires continuous processing or preserved state, such as: Any request-based work, such as: Both resident and dynamic backends allow you to address tasks to a specific instance of a backend. You can obtain the instance and backend names programmatically; the endpoint takes the form http://[instance].[backend_name].[your_app_id].appspot.com . Load Balancing Requests are evenly balanced across all instances of the backend. Requests are concentrated on the lowest-numbered instances first, and are served by additional instances as traffic increases.

Request handling

Resident and dynamic backends both use pending queues to handle incoming traffic. Requests to a backend that is busy handling other requests wait in a pending queue for a short period of time (10 seconds) before being aborted.

You can disable the backend's pending queue using the failfast feature. You can configure failfast either on a per-request basis or on an entire backend (though the backend option is currently experimental). To use failfast for a single request, add the following header to the task request: 

X-AppEngine-FailFast

To make a backend failfast, add the failfast option to the backend definition in backends.yaml .

Defining handlers

Backends share the request handlers defined in app.yaml with your main application version. It is not possible to configure a separate set of handlers for each backend, so mark any handlers that you wish to restrict to admins with login: admin . This login declaration blocks external requests, while allowing internal requests (for example, from another instance of your application, or a Task Queue) to access a handler without additional configuration.

The start directive allows each backend to define a separate handler for /_ah/start .

Instance classes

App Engine provides four different classes of backend instances, each with different memory and CPU limits. These classes allow you to configure your backend with the processing capacity you need to perform your work. Each class has a specific hourly billing rate. See Pricing for more information.

The default class for backends is B2 , which gives you 256MB of memory and 1200MHz of CPU capacity.

You can change the class of a backend using the class directive in backends.yaml : 

backends:
- name: cmdline
  class: B4

The class directive has the following values:

Class configuration Memory limit CPU limit Cost per hour*
B1 128MB 600MHz $0.05
B2 (default) 256MB 1.2GHz $0.10
B4 512MB 2.4GHz $0.20
B4_1G 1024MB 2.4GHz $0.30
B8 1024MB 4.8GHz $0.40

*See Billing, Quotas, and Limits for more information about Backends Billing.

Backends definitions

The backends.yaml file has a single list element called backends . Each element in the list represents a backend for the application. Backends are subject to Billing, Quotas, and Limits .

A backends directive can have the following directives:

name (required)
The server name, composed of letters, digits, and hyphens. The name "default" is reserved and cannot be used. You also cannot use a name that is already used as an application version. This name is also referred to as the BACKEND_ID .
class
Determines the backend's instance class , which determines the memory and CPU limits for each instance. The default class is B2 .
instances

An integer between 1 and 20 indicating the number of instances to assign to the given backend. Defaults to 1 if unspecified. The instance number is also referred to as the INSTANCE_ID .

Each instance can handle multiple requests if your application is marked as threadsafe in appengine-web.xml . You can also configure the maximum number of concurrent requests . This feature is experimental. Backends have pending queues; requests to a busy instance retry for 10 seconds before aborting.

max_concurrent_requests
Specifies the maximum number of requests that each instance can handle simultaneously. If unset, App Engine determines the concurrent request limit dynamically.
options

A list of settings, which can include one or more of the following options.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.