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
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.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
DEFAULT_QUEUE
The default queue name.
|
static java.lang.String |
DEFAULT_QUEUE_PATH
The default queue path.
|
Modifier and Type | Method and Description |
---|---|
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.
|
java.util.concurrent.Future<TaskHandle> |
addAsync()
Asynchronously submits a task to this queue with an auto generated name with default
options.
|
java.util.concurrent.Future<java.util.List<TaskHandle>> |
addAsync(java.lang.Iterable<TaskOptions> taskOptions)
Asynchronously submits tasks to this queue.
|
java.util.concurrent.Future<TaskHandle> |
addAsync(TaskOptions taskOptions)
Asynchronously submits a task to this queue.
|
java.util.concurrent.Future<java.util.List<TaskHandle>> |
addAsync(Transaction txn,
java.lang.Iterable<TaskOptions> taskOptions)
Asynchronously submits tasks to this queue in the provided Transaction.
|
java.util.concurrent.Future<TaskHandle> |
addAsync(Transaction txn,
TaskOptions taskOptions)
Asynchronously submits a task to this queue in the provided Transaction.
|
java.util.List<java.lang.Boolean> |
deleteTask(java.util.List<TaskHandle> taskHandles)
Deletes a list of tasks from this
Queue . |
boolean |
deleteTask(java.lang.String taskName)
Deletes a task from this
Queue . |
boolean |
deleteTask(TaskHandle taskHandle)
Deletes a task from this
Queue . |
java.util.concurrent.Future<java.util.List<java.lang.Boolean>> |
deleteTaskAsync(java.util.List<TaskHandle> taskHandles)
Asynchronously deletes a list of tasks from this
Queue . |
java.util.concurrent.Future<java.lang.Boolean> |
deleteTaskAsync(java.lang.String taskName)
Asynchronously deletes a task from this
Queue . |
java.util.concurrent.Future<java.lang.Boolean> |
deleteTaskAsync(TaskHandle taskHandle)
Asynchronously deletes a task from this
Queue . |
QueueStatistics |
fetchStatistics()
Obtain statistics for this
Queue . |
java.util.concurrent.Future<QueueStatistics> |
fetchStatisticsAsync(java.lang.Double deadlineInSeconds)
Asynchronously obtains statistics for this
Queue . |
java.lang.String |
getQueueName()
Returns the queue name.
|
java.util.List<TaskHandle> |
leaseTasks(LeaseOptions options)
Leases tasks from this queue, with lease period and other options specified by
options . |
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 . |
java.util.concurrent.Future<java.util.List<TaskHandle>> |
leaseTasksAsync(LeaseOptions options)
Asynchronously leases tasks from this queue, with lease period and other options specified by
options . |
java.util.concurrent.Future<java.util.List<TaskHandle>> |
leaseTasksAsync(long lease,
java.util.concurrent.TimeUnit unit,
long countLimit)
Asynchronously leases up to
countLimit tasks from this queue for a period specified by
lease and unit . |
java.util.List<TaskHandle> |
leaseTasksByTag(long lease,
java.util.concurrent.TimeUnit unit,
long countLimit,
java.lang.String tag)
Leases up to
countLimit tasks from this queue for a period specified by
lease and unit , having tag tag . |
java.util.concurrent.Future<java.util.List<TaskHandle>> |
leaseTasksByTagAsync(long lease,
java.util.concurrent.TimeUnit unit,
long countLimit,
java.lang.String tag)
Asynchronously leases up to
countLimit tasks from this queue for a period specified by
lease and unit , having tag tag . |
java.util.List<TaskHandle> |
leaseTasksByTagBytes(long lease,
java.util.concurrent.TimeUnit unit,
long countLimit,
byte[] tag)
Leases up to
countLimit tasks from this queue for a period specified by
lease and unit , having tag tag . |
java.util.concurrent.Future<java.util.List<TaskHandle>> |
leaseTasksByTagBytesAsync(long lease,
java.util.concurrent.TimeUnit unit,
long countLimit,
byte[] tag)
Asynchronously leases up to
countLimit tasks from this queue for a period specified by
lease and unit , having tag tag . |
TaskHandle |
modifyTaskLease(TaskHandle taskHandle,
long lease,
java.util.concurrent.TimeUnit unit)
Modify the lease of the specified task in this
Queue for a period of time specified
by lease and unit . |
void |
purge()
Clears all the tasks in this
Queue . |
static final java.lang.String DEFAULT_QUEUE
static final java.lang.String DEFAULT_QUEUE_PATH
java.lang.String getQueueName()
TaskHandle add()
This method is similar to calling add(TaskOptions)
with
a TaskOptions
object returned by
TaskOptions.Builder.withDefaults()
.
TaskHandle
.InternalFailureException
java.lang.IllegalStateException
- If the queue does not exist. (see queue.xml)TransientFailureException
- Attempting the request after this exception may succeed.InvalidQueueModeException
- task method is TaskOptions.Method.PULL
and queue is
push queue or vice versa.TaskHandle add(TaskOptions taskOptions)
taskOptions
- The definition of the task.TaskHandle
.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
- task method is TaskOptions.Method.PULL
and queue is
push queue or vice versa.java.util.List<TaskHandle> add(java.lang.Iterable<TaskOptions> taskOptions)
Submission is not atomic i.e. if this method throws then some tasks may have been added to the queue.
taskOptions
- An iterable over task definitions.TaskHandle
for each added task.InternalFailureException
java.lang.IllegalStateException
- If the queue does not exist. (see queue.xml)TaskAlreadyExistsException
- If any of the provided TaskOptions
contained a name
of a task that was previously created, and if no other Exception
would be thrown. Note
that if a TaskAlreadyExistsException
is caught, the caller can be guaranteed that for
each one of the provided TaskOptions
, either the corresponding task was successfully
added, or a task with the given name was successfully added in the past.TransientFailureException
- Attempting the request after this exception may succeed.UnsupportedTranslationException
- If chosen character encoding is unsupported.InvalidQueueModeException
- task method is TaskOptions.Method.PULL
and queue is
push queue or vice versa.TaskHandle add(Transaction txn, TaskOptions taskOptions)
A task is added if and only if the transaction is applied successfully.
txn
- an enclosing Transaction
or null, if not null a task cannot be named.taskOptions
- The definition of the task.TaskHandle
.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
- task method is TaskOptions.Method.PULL
and queue is
push queue or vice versa.java.util.List<TaskHandle> add(Transaction txn, java.lang.Iterable<TaskOptions> taskOptions)
The tasks are added if and only if the transaction is applied successfully.
txn
- an enclosing Transaction
or null, if not null a task cannot be named.taskOptions
- An iterable over task definitions.TaskHandle
for each added task.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
- task method is TaskOptions.Method.PULL
and queue is
push queue or vice versa.java.util.concurrent.Future<TaskHandle> addAsync()
This method is similar to calling addAsync(TaskOptions)
with
a TaskOptions
object returned by
TaskOptions.Builder.withDefaults()
.
Future
with a result type of TaskHandle
.java.util.concurrent.Future<TaskHandle> addAsync(TaskOptions taskOptions)
taskOptions
- The definition of the task.Future
with a result type of TaskHandle
.UnsupportedTranslationException
- If chosen character encoding is unsupported.java.util.concurrent.Future<java.util.List<TaskHandle>> addAsync(java.lang.Iterable<TaskOptions> taskOptions)
Submission is not atomic i.e. if this method fails then some tasks may have been added to the queue.
taskOptions
- An iterable over task definitions.Future
whose result is a list containing a TaskHandle
for each added
task.UnsupportedTranslationException
- If chosen character encoding is unsupported.java.util.concurrent.Future<TaskHandle> addAsync(Transaction txn, TaskOptions taskOptions)
A task is added if and only if the transaction is applied successfully.
txn
- an enclosing Transaction
or null, if not null a task cannot be named.taskOptions
- The definition of the task.Future
with a result type of TaskHandle
.UnsupportedTranslationException
- If chosen character encoding is unsupported.java.util.concurrent.Future<java.util.List<TaskHandle>> addAsync(Transaction txn, java.lang.Iterable<TaskOptions> taskOptions)
The tasks are added if and only if the transaction is applied successfully.
txn
- an enclosing Transaction
or null, if not null a task cannot be named.taskOptions
- An iterable over task definitions.Future
whose result is a list containing a TaskHandle
for each added
task.UnsupportedTranslationException
- If chosen character encoding is unsupported.boolean deleteTask(java.lang.String taskName)
Queue
. Task is identified by taskName.taskName
- name of the task to delete.java.lang.IllegalArgumentException
- if 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.boolean deleteTask(TaskHandle taskHandle)
Queue
. Task is identified by a TaskHandle.taskHandle
- handle of the task to delete.java.lang.IllegalArgumentException
- if 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)QueueNameMismatchException
- if the task handle refers to a different named queue.TransientFailureException
- Attempting the request after this exception may succeed.java.util.List<java.lang.Boolean> deleteTask(java.util.List<TaskHandle> taskHandles)
Queue
. The tasks are identified
by a list of TaskHandles.taskHandles
- list of handles of tasks to delete.java.lang.IllegalArgumentException
- if 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)QueueNameMismatchException
- if the task handle refers to a different named queue.TransientFailureException
- Attempting the request after this exception may succeed.java.util.concurrent.Future<java.lang.Boolean> deleteTaskAsync(java.lang.String taskName)
Queue
. Task is identified by taskName.taskName
- name of the task to delete.Future
whose result is True if the task was sucessfully deleted, False if the
task was not found or was previously deleted.java.lang.IllegalArgumentException
- if the provided name is null, empty or doesn't match the
expected pattern.java.util.concurrent.Future<java.lang.Boolean> deleteTaskAsync(TaskHandle taskHandle)
Queue
. Task is identified by a TaskHandle.taskHandle
- handle of the task to delete.Future
whose result is True if the task was sucessfully deleted, False if the
task was not found or was previously deleted.java.lang.IllegalArgumentException
- if the provided name is null, empty or doesn't match the
expected pattern.QueueNameMismatchException
- if the task handle refers to a different named queue.java.util.concurrent.Future<java.util.List<java.lang.Boolean>> deleteTaskAsync(java.util.List<TaskHandle> taskHandles)
Queue
. The tasks are identified
by a list of TaskHandles.taskHandles
- list of handles of tasks to delete.Future
whose result is a Listjava.lang.IllegalArgumentException
- if the provided name is null, empty or doesn't match the
expected pattern.QueueNameMismatchException
- if the task handle refers to a different named queue.java.util.List<TaskHandle> leaseTasks(long lease, java.util.concurrent.TimeUnit unit, long countLimit)
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.lease
- Number of unit
s in the lease periodunit
- Time unit of the lease periodcountLimit
- maximum number of tasks to leaseTaskHandle
for each leased task.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.java.util.List<TaskHandle> leaseTasksByTagBytes(long lease, java.util.concurrent.TimeUnit unit, long countLimit, byte[] tag)
countLimit
tasks from this queue for a period specified by
lease
and unit
, having tag tag
. If tag
is null
, tasks
having the same tag as the task with earliest eta will be returned. If fewer such tasks than
countLimit
are available, all available such 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.lease
- Number of unit
s in the lease periodunit
- Time unit of the lease periodcountLimit
- maximum number of tasks to leasetag
- User defined tag required for returned tasks. If null
, the tag of the task
with earliest eta will be used.TaskHandle
for each leased task.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.java.util.List<TaskHandle> leaseTasksByTag(long lease, java.util.concurrent.TimeUnit unit, long countLimit, java.lang.String tag)
countLimit
tasks from this queue for a period specified by
lease
and unit
, having tag tag
. If tag
is null
, tasks
having the same tag as the task with earliest eta will be returned. If fewer such tasks than
countLimit
are available, all available such 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.
lease
- Number of unit
s in the lease periodunit
- Time unit of the lease periodcountLimit
- maximum number of tasks to leasetag
- User defined String
tag required for returned tasks. If null
, the
tag of the task with earliest eta will be used.TaskHandle
for each leased task.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.java.util.List<TaskHandle> leaseTasks(LeaseOptions options)
options
. 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.
If options
specifies a tag, only tasks having that tag will be returned.
If options
specifies no tag, but does specify groupByTag
, only tasks
having the same tag as the task with earliest eta will be returned.
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.
options
- Specific options for this lease requestTaskHandle
for each leased task.InvalidQueueModeException
- if the target queue is not in pull mode.java.lang.IllegalArgumentException
- if lease period or countLimit is null 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.java.util.concurrent.Future<java.util.List<TaskHandle>> leaseTasksAsync(long lease, java.util.concurrent.TimeUnit unit, long countLimit)
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.lease
- Number of unit
s in the lease periodunit
- Time unit of the lease periodcountLimit
- maximum number of tasks to leaseFuture
whose result is a list of TaskHandle
for each leased task.java.lang.IllegalArgumentException
- if lease < 0, countLimit <= 0 or either is too large.java.util.concurrent.Future<java.util.List<TaskHandle>> leaseTasksByTagBytesAsync(long lease, java.util.concurrent.TimeUnit unit, long countLimit, byte[] tag)
countLimit
tasks from this queue for a period specified by
lease
and unit
, having tag tag
. If tag
is null
, tasks
having the same tag as the task with earliest eta will be returned. If fewer such tasks than
countLimit
are available, all available such 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.lease
- Number of unit
s in the lease periodunit
- Time unit of the lease periodcountLimit
- maximum number of tasks to leasetag
- User defined tag required for returned tasks. If null
, the tag of the task
with earliest eta will be used.Future
whose result is a list of TaskHandle
for each leased task.java.lang.IllegalArgumentException
- if lease < 0, countLimit <= 0 or either is too large.java.util.concurrent.Future<java.util.List<TaskHandle>> leaseTasksByTagAsync(long lease, java.util.concurrent.TimeUnit unit, long countLimit, java.lang.String tag)
countLimit
tasks from this queue for a period specified by
lease
and unit
, having tag tag
. If tag
is null
, tasks
having the same tag as the task with earliest eta will be returned. If fewer such tasks than
countLimit
are available, all available such 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.
lease
- Number of unit
s in the lease periodunit
- Time unit of the lease periodcountLimit
- maximum number of tasks to leasetag
- User defined String
tag required for returned tasks. If null
, the
tag of the task with earliest eta will be used.Future
whose result is a list of TaskHandle
for each leased task.java.lang.IllegalArgumentException
- if lease < 0, countLimit <= 0 or either is too large.java.util.concurrent.Future<java.util.List<TaskHandle>> leaseTasksAsync(LeaseOptions options)
options
. 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.
If options
specifies a tag, only tasks having that tag will be returned.
If options
specifies no tag, but does specify groupByTag
, only tasks
having the same tag as the task with earliest eta will be returned.
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.
options
- Specific options for this lease requestFuture
whose result is a list of TaskHandle
for each leased task.java.lang.IllegalArgumentException
- if lease period or countLimit is null or either is too large.void purge()
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.java.lang.IllegalStateException
- If the Queue does not exist. (see queue.xml)TransientFailureException
- Attempting the request after this exception may succeed.InternalFailureException
TaskHandle modifyTaskLease(TaskHandle taskHandle, long lease, java.util.concurrent.TimeUnit unit)
Queue
for a period of time specified
by lease
and unit
. A lease time of 0 will relinquish the lease on the
task and make it avaible to be leased by calling leaseTasks
.taskHandle
- handle of the task that is having its lease modified.lease
- Number of unit
s in the lease period.unit
- Time unit of the lease period.TaskHandle
with the new lease period.InvalidQueueModeException
- if the target queue is not in pull mode.java.lang.IllegalArgumentException
- if lease < 0 or too large.InternalFailureException
java.lang.IllegalStateException
- If the queue does not exist, or the task lease has expired
or the queue has been paused.TransientFailureException
- Attempting the request after this exception may succeed.QueueStatistics fetchStatistics()
Queue
.QueueStatistics
for this queue.java.lang.IllegalStateException
- If the Queue does not exist. (see queue.xml)TransientFailureException
- Attempting the request after this exception may succeed.InternalFailureException
java.util.concurrent.Future<QueueStatistics> fetchStatisticsAsync(java.lang.Double deadlineInSeconds)
Queue
.deadlineInSeconds
- the maximum duration, in seconds, that the fetch statistics
request can run. A default deadline will be used if null
is supplied.Future
with a result type of QueueStatistics
.java.lang.IllegalArgumentException
- if deadlineInSeconds <= 0.