com.google.appengine.api.taskqueue
Interface Queue


public interface 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(long, long) to acquire a lease on the task and process them explicitly. Attempting to call #leaseTasks(long, long) on a push queue causes a {


Field Summary
static java.lang.String DEFAULT_QUEUE
          The default queue name.
static java.lang.String DEFAULT_QUEUE_PATH
          The default queue path.
 
Method Summary
 TaskHandle add()
          Submits a task to this queue with an auto generated name with default options.
 java.util.List<TaskHandle> add(java.lang.Iterable<TaskOptions> taskOptions)
          Submits tasks to this queue.
 TaskHandle add(TaskOptions taskOptions)
          Submits a task to this queue.
 java.util.List<TaskHandle> add(Transaction txn, java.lang.Iterable<TaskOptions> taskOptions)
          Submits tasks to this queue in the provided Transaction.
 TaskHandle add(Transaction txn, TaskOptions taskOptions)
          Submits a task to this queue in the provided Transaction.
 boolean deleteTask(java.lang.String taskName)
          Deletes a task from this Queue.
 java.lang.String getQueueName()
          Returns the queue name.
 java.util.List<TaskHandle> leaseTasks(long lease, java.util.concurrent.TimeUnit unit, long countLimit)
          Leases up to countLimit tasks from this queue for a period specified by lease and unit.
 void purge()
          Clears all the tasks in this Queue.
 

Field Detail

DEFAULT_QUEUE

static final java.lang.String DEFAULT_QUEUE
The default queue name.

See Also:
Constant Field Values

DEFAULT_QUEUE_PATH

static final java.lang.String DEFAULT_QUEUE_PATH
The default queue path.

See Also:
Constant Field Values
Method Detail

getQueueName

java.lang.String getQueueName()
Returns the queue name.


add

TaskHandle add()
Submits a task to this queue with an auto generated name with default options.

This method is similar to calling add(TaskOptions) with a TaskOptions object returned by TaskOptions.Builder.withDefaults().

Returns:
A TaskHandle.
Throws:
InternalFailureException
java.lang.IllegalStateException - If the queue does not exist. (see queue.xml)
TransientFailureException - Attempting the request after this exception may succeed.
UnsupportedTranslationException - If chosen character encoding is unsupported.
InvalidQueueModeException - TaskOptions#Method is PULL and queue is push queue, or vice versa.

add

TaskHandle add(TaskOptions taskOptions)
Submits a task to this queue.

Parameters:
taskOptions - The definition of the task.
Returns:
A TaskHandle.
Throws:
InternalFailureException
java.lang.IllegalStateException - If the queue does not exist. (see queue.xml)
TaskAlreadyExistsException
TransientFailureException - Attempting the request after this exception may succeed.
UnsupportedTranslationException - If chosen character encoding is unsupported.
InvalidQueueModeException - TaskOptions#Method is PULL and queue is push queue, or vice versa.

add

java.util.List<TaskHandle> add(java.lang.Iterable<TaskOptions> taskOptions)
Submits tasks to this queue. Submission is not atomic i.e. if this method throws then some tasks may have been added to the queue.

Parameters:
taskOptions - An iterable over task definitions.
Returns:
A list containing a TaskHandle for each added task.
Throws:
InternalFailureException
java.lang.IllegalStateException - If the queue does not exist. (see queue.xml)
TaskAlreadyExistsException - if a task with the same name was previously created.
TransientFailureException - Attempting the request after this exception may succeed.
UnsupportedTranslationException - If chosen character encoding is unsupported.
InvalidQueueModeException - TaskOptions#Method is PULL and queue is push queue, or vice versa.

add

TaskHandle add(Transaction txn,
               TaskOptions taskOptions)
Submits a task to this queue in the provided Transaction. A task is added if and only if the transaction is applied successfully.

Parameters:
txn - an enclosing Transaction or null, if not null a task cannot be named.
taskOptions - The definition of the task.
Returns:
A TaskHandle.
Throws:
InternalFailureException
java.lang.IllegalStateException - If the queue does not exist. (see queue.xml)
TaskAlreadyExistsException - if a task with the same name was previously created.
TransientFailureException - Attempting the request after this exception may succeed.
UnsupportedTranslationException - If chosen character encoding is unsupported.
InvalidQueueModeException - TaskOptions#Method is PULL and queue is push queue, or vice versa.

add

java.util.List<TaskHandle> add(Transaction txn,
                               java.lang.Iterable<TaskOptions> taskOptions)
Submits tasks to this queue in the provided Transaction. The tasks are added if and only if the transaction is applied successfully.

Parameters:
txn - an enclosing Transaction or null, if not null a task cannot be named.
taskOptions - An iterable over task definitions.
Returns:
A list containing a TaskHandle for each added task.
Throws:
InternalFailureException
java.lang.IllegalStateException - If the queue does not exist. (see queue.xml)
TaskAlreadyExistsException - if a task with the same name was previously created.
TransientFailureException - Attempting the request after this exception may succeed.
UnsupportedTranslationException - If chosen character encoding is unsupported.
InvalidQueueModeException - TaskOptions#Method is PULL and queue is push queue, or vice versa.

deleteTask

boolean deleteTask(java.lang.String taskName)
Deletes a task from this Queue. Task is identified by taskName.

Parameters:
taskName - name of the task to delete.
Returns:
True if the task was sucessfully deleted. False if the task was not found or was previously deleted.
Throws:
java.lang.IllegalArgumentException - The provided name is null, empty or doesn't match the expected pattern.
InternalFailureException
java.lang.IllegalStateException - If the queue does not exist. (see queue.xml)
TransientFailureException - Attempting the request after this exception may succeed.

leaseTasks

java.util.List<TaskHandle> leaseTasks(long lease,
                                      java.util.concurrent.TimeUnit unit,
                                      long countLimit)
Leases up to countLimit tasks from this queue for a period specified by lease and unit. If fewer tasks than countLimit are available, all available tasks in this Queue will be returned. The available tasks are those in the queue having the earliest eta such that eta is prior to the time at which the lease is requested. It is guaranteed that the leased tasks will be unavailable for lease to others in the lease period. You must call deleteTask to prevent the task from being leased again after the lease period.. This method supports leasing a maximum of 1000 tasks for no more than one week.

Parameters:
lease - Number of units in the lease period
unit - Time unit of the lease period
countLimit - maximum number of tasks to lease
Returns:
A list of TaskHandle for each leased task.
Throws:
InvalidQueueModeException - if the target queue is not in pull mode.
java.lang.IllegalArgumentException - if lease < 0, countLimit <= 0 or either is too large.
InternalFailureException
java.lang.IllegalStateException - If the queue does not exist. (see queue.xml)
TransientFailureException - Attempting the request after this exception may succeed.

purge

void purge()
Clears all the tasks in this Queue. This function returns immediately. Some delay may apply on the server before the Queue is actually purged. Tasks being executed at the time the purge call is made will continue executing, other tasks in this Queue will continue being dispatched and executed before the purge call takes effect.

Throws:
java.lang.IllegalStateException - If the Queue does not exist. (see queue.xml)
TransientFailureException - Attempting the request after this exception may succeed.
InternalFailureException