Provides a mechanism to perform work initiated by a user request, outside of that request. See Also: com.google.appengine.api.taskqueue.Queue, The Task Queue Java API in the Google App Engine Developer's Guide.
Classes
DeferredTaskContext
Resources for managing DeferredTask.
IQueueFactoryProvider
Factory provider for IQueueFactory.
Note: This class is not intended for end users.
LeaseOptions
Contains various options for lease requests following the builder pattern. Calls to LeaseOptions methods may be chained to specify multiple options in the one LeaseOptions object.
Notes on usage:
The recommended way to instantiate a LeaseOptions object is to statically import Builder.* and invoke a static creation method followed by instance mutators:
import static com.google.appengine.api.taskqueue.LeaseOptions.Builder.*;
...
tasks = pullQueue.leaseTasks(withLeasePeriod(2, TimeUnit.HOURS).countLimit(1000));
LeaseOptions.Builder
Provides static creation methods for LeaseOptions.
QueueConstants
Describes various taskqueue limits.
QueueFactory
Creates Queue objects. QueueFactory is thread safe.
QueueStatistics
QueueStatistics allow observation of the rate that tasks on a given queue are being executed. Note that statistics provided are only approximate, and some statistics may be delayed or transiently unavailable.
RetryOptions
Contains various options for a task's retry strategy. Calls to RetryOptions methods may be chained to specify multiple options in the one RetryOptions object.
Notes on usage:
The recommended way to instantiate a RetryOptions object is to statically import Builder.* and invoke a static creation method followed by an instance mutator (if needed):
import static com.google.appengine.api.taskqueue.RetryOptions.Builder.*;
...
RetryOptions retry = withTaskRetryLimit(10).taskAgeLimitSeconds("4d")
.minBackoffSeconds(120).maxBackoffSeconds(3600).maxDoublings(5);
QueueFactory#getDefaultQueue().add(retryOptions(retry));
RetryOptions.Builder
Provides static creation methods for RetryOptions.
TaskHandle
Created from Queue#add(TaskOptions). Contains the task name (generated if otherwise unspecified), task ETA (computed if not specified) and queue name. The queue name and task name uniquely identify the task for an application.
TaskOptions
Contains various options for a task following the builder pattern. Calls to TaskOptions methods may be chained to specify multiple options in the one TaskOptions object.
taskOptions can have either TaskOptions.Method PULL or a PUSH-related method, e.g. POST, GET, ... Tasks with PULL method can only be added into a PULL queue and PUSH tasks can only be added into a PUSH queue.
Notes on usage:
The recommended way to instantiate a TaskOptions object is to statically import Builder.* and invoke a static creation method followed by an instance mutator (if needed):
import static com.google.appengine.api.taskqueue.TaskOptions.Builder.*;
...
QueueFactory#getDefaultQueue().add(withUrl(url).etaMillis(eta));
TaskOptions.Builder
Provides static creation methods for TaskOptions.
Interfaces
DeferredTask
Interface for deferred tasks. Classes implementing this interface may use TaskOptions#payload(DeferredTask) to serialize the DeferredTask into the payload of the task definition. The DeferredTask#run() method will be called when the task is received by the built in DeferredTask servlet.
Normal return from this method is considered success and will not retry unless DeferredTaskContext#markForRetry is called. Exceptions thrown from this method will indicate a
failure and will be processed as a retry attempt unless DeferredTaskContext#setDoNotRetry(boolean) was set to true.
IQueueFactory
Creates Queue objects. QueueFactory is thread safe.
Queue
Queue is used to manage a task queue.
Implementations of this interface must be threadsafe.
Queues are transactional. If a datastore transaction is in progress when #add() or
#add(TaskOptions) is invoked, the task will only be added to the queue if the datastore
transaction successfully commits. If you want to add a task to a queue and have that operation
succeed or fail independently of an existing datastore transaction you can invoke #add(Transaction, TaskOptions) with a null transaction argument. Note that while the
addition of the task to the queue can participate in an existing transaction, the execution of
the task cannot participate in this transaction. In other words, when the transaction commits you
are guaranteed that your task will be added and run, not that your task executed successfully.
Queues may be configured in either push or pull mode, but they share the same interface. However, only tasks with TaskOptions.Method#PULL may be added to pull queues. The tasks in push queues must be added with one of the other available methods.
Pull mode queues do not automatically deliver tasks to the application. The application is required to call leaseTasks to acquire a lease on the task and process them explicitly. Attempting to call leaseTasks on a push queue causes a InvalidQueueModeException to be thrown. When the task processing has finished processing a task that is leased, it should call #deleteTask(String). If deleteTask is not called before the lease expires, the task will again be available for lease.
Queue mode can be switched between push and pull. When switching from push to pull, tasks will stay in the task queue and are available for lease, but url and headers information will be ignored when returning the tasks. When switching from pull to push, existing tasks will remain in the queue but will fail on auto-execution because they lack a url. If the queue mode is once again changed to pull, these tasks will eventually be available for lease.
Enums
TaskOptions.Method
Methods supported by Queue. Tasks added to pull queues must have the #Method PULL. All other methods are appropriate for push queues. See Queue for more detail on pull and push mode queues.
Exceptions
DeferredTaskCreationException
Indicates a failure to create a task payload. This is most likely an issue with serialization.
InternalFailureException
Internal task queue error.
InvalidQueueModeException
Mismatch of task method and queue mode. e.g. Queue#leaseTasks(long, java.util.concurrent.TimeUnit, long) called on a push queue, Queue#add(TaskOptions) with method TaskOptions.Method PULL to a push queue, or with TaskOptions.Method not equal to PULL to a pull queue.
QueueFailureException
Unspecified queue failure.
QueueNameMismatchException
Queue name mismatch failure.
TaskAlreadyExistsException
One or more task names already exists in the queue.
TransactionalTaskException
Queue operation failure caused by Datastore exception
TransientFailureException
Intermittent failure.
The requested operation may succeed if attempted again.
UnsupportedTranslationException
Attempt to convert String to an unsupported charset.