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` 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.

- - ### Field Summary

    Fields
    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.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    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`.

- - ### 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.
        `InvalidQueueModeException` - task method is `TaskOptions.Method.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` - task method is `TaskOptions.Method.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 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.

    - #### 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` - task method is `TaskOptions.Method.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` - task method is `TaskOptions.Method.PULL` and queue is push queue or vice versa.

    - #### addAsync

          java.util.concurrent.Future<TaskHandle> addAsync()

      Asynchronously submits a task to this queue with an auto generated name with default options.

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

      Returns:
        A `Future` with a result type of `TaskHandle`.

    - #### addAsync

          java.util.concurrent.Future<TaskHandle> addAsync(TaskOptions taskOptions)

      Asynchronously submits a task to this queue.
      Parameters:
        `taskOptions` - The definition of the task.
      Returns:
        A `Future` with a result type of `TaskHandle`.
      Throws:
        `UnsupportedTranslationException` - If chosen character encoding is unsupported.

    - #### addAsync

          java.util.concurrent.Future<java.util.List<TaskHandle>> addAsync(java.lang.Iterable<TaskOptions> taskOptions)

      Asynchronously submits tasks to this queue.

      Submission is not atomic i.e. if this method fails then some tasks may have been added to the queue.

      Parameters:
        `taskOptions` - An iterable over task definitions.
      Returns:
        A `Future` whose result is a list containing a `TaskHandle` for each added task.
      Throws:
        `UnsupportedTranslationException` - If chosen character encoding is unsupported.

    - #### addAsync

          java.util.concurrent.Future<TaskHandle> addAsync(Transaction txn,
                                                           TaskOptions taskOptions)

      Asynchronously 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 `Future` with a result type of `TaskHandle`.
      Throws:
        `UnsupportedTranslationException` - If chosen character encoding is unsupported.

    - #### addAsync

          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.

      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 `Future` whose result is a list containing a `TaskHandle` for each added task.
      Throws:
        `UnsupportedTranslationException` - If chosen character encoding is unsupported.

    - #### 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 successfully deleted. False if the task was not found or was previously deleted.
      Throws:
        `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.

    - #### deleteTask

          boolean deleteTask(TaskHandle taskHandle)

      Deletes a task from this `Queue`. Task is identified by a TaskHandle.
      Parameters:
        `taskHandle` - handle of the task to delete.
      Returns:
        True if the task was successfully deleted. False if the task was not found or was previously deleted.
      Throws:
        `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.

    - #### deleteTask

          java.util.List<java.lang.Boolean> deleteTask(java.util.List<TaskHandle> taskHandles)

      Deletes a list of tasks from this `Queue`. The tasks are identified by a list of TaskHandles. This method supports deleting up to 1000 tasks.
      Parameters:
        `taskHandles` - list of handles of tasks to delete.
      Returns:
        `List<Boolean>` that represents the result of deleting each task in the same order as the input handles. True if a task was successfully deleted. False if the task was not found or was previously deleted.
      Throws:
        `java.lang.IllegalArgumentException` - if the provided name is null, empty or doesn't match the expected pattern, or if the size of taskHandles is too large.
        `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.

    - #### deleteTaskAsync

          java.util.concurrent.Future<java.lang.Boolean> deleteTaskAsync(java.lang.String taskName)

      Asynchronously deletes a task from this `Queue`. Task is identified by taskName.
      Parameters:
        `taskName` - name of the task to delete.
      Returns:
        A `Future` whose result is True if the task was successfully deleted, False if the task was not found or was previously deleted.
      Throws:
        `java.lang.IllegalArgumentException` - if the provided name is null, empty or doesn't match the expected pattern.

    - #### deleteTaskAsync

          java.util.concurrent.Future<java.lang.Boolean> deleteTaskAsync(TaskHandle taskHandle)

      Asynchronously deletes a task from this `Queue`. Task is identified by a TaskHandle.
      Parameters:
        `taskHandle` - handle of the task to delete.
      Returns:
        A `Future` whose result is True if the task was successfully deleted, False if the task was not found or was previously deleted.
      Throws:
        `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.

    - #### deleteTaskAsync

          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`. The tasks are identified by a list of TaskHandles. This method supports deleting up to 1000 tasks.
      Parameters:
        `taskHandles` - list of handles of tasks to delete.
      Returns:
        A `Future` whose result is a `List<Boolean>` that represents the result of deleting each task in the same order as the input handles. True if a task was successfully deleted. False if the task was not found or was previously deleted.
      Throws:
        `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.

    - #### 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. If you generate more than 10 LeaseTasks requests per second, only the first 10 requests will return results. The others will return no results.
      Parameters:
        `lease` - Number of `unit`s 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.

    - #### leaseTasksByTagBytes

          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`. 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. If you generate more than 10 LeaseTasks requests per second, only the first 10 requests will return results. The others will return no results.
      Parameters:
        `lease` - Number of `unit`s in the lease period
        `unit` - Time unit of the lease period
        `countLimit` - maximum number of tasks to lease
        `tag` - User defined tag required for returned tasks. If `null`, the tag of the task with earliest eta will be used.
      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.

    - #### leaseTasksByTag

          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`. 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. If you generate more than 10 LeaseTasks requests per second, only the first 10 requests will return results. The others will return no results.

      Parameters:
        `lease` - Number of `unit`s in the lease period
        `unit` - Time unit of the lease period
        `countLimit` - maximum number of tasks to lease
        `tag` - User defined `String` tag required for returned tasks. If `null`, the tag of the task with earliest eta will be used.
      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.

    - #### leaseTasks

          java.util.List<TaskHandle> leaseTasks(LeaseOptions options)

      Leases tasks from this queue, with lease period and other options specified by `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. If you generate more than 10 LeaseTasks requests per second, only the first 10 requests will return results. The others will return no results.

      Parameters:
        `options` - Specific options for this lease request
      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 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.

    - #### leaseTasksAsync

          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`. 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. If you generate more than 10 LeaseTasks requests per second, only the first 10 requests will return results. The others will return no results.
      Parameters:
        `lease` - Number of `unit`s in the lease period
        `unit` - Time unit of the lease period
        `countLimit` - maximum number of tasks to lease
      Returns:
        A `Future` whose result is a list of `TaskHandle` for each leased task.
      Throws:
        `java.lang.IllegalArgumentException` - if lease < 0, countLimit <= 0, or either is too large.

    - #### leaseTasksAsync

          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`. 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. If you generate more than 10 LeaseTasks requests per second, only the first 10 requests will return results. The others will return no results.

      Parameters:
        `options` - Specific options for this lease request
      Returns:
        A `Future` whose result is a list of `TaskHandle` for each leased task.
      Throws:
        `java.lang.IllegalArgumentException` - if lease period or countLimit is null or either is too large.

    - #### leaseTasksByTagBytesAsync

          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`. 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. If you generate more than 10 LeaseTasks requests per second, only the first 10 requests will return results. The others will return no results.
      Parameters:
        `lease` - Number of `unit`s in the lease period
        `unit` - Time unit of the lease period
        `countLimit` - maximum number of tasks to lease
        `tag` - User defined tag required for returned tasks. If `null`, the tag of the task with earliest eta will be used.
      Returns:
        A `Future` whose result is a list of `TaskHandle` for each leased task.
      Throws:
        `java.lang.IllegalArgumentException` - if lease < 0, countLimit <= 0, or either is too large.

    - #### leaseTasksByTagAsync

          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`. 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. If you generate more than 10 LeaseTasks requests per second, only the first 10 requests will return results. The others will return no results.

      Parameters:
        `lease` - Number of `unit`s in the lease period
        `unit` - Time unit of the lease period
        `countLimit` - maximum number of tasks to lease
        `tag` - User defined `String` tag required for returned tasks. If `null`, the tag of the task with earliest eta will be used.
      Returns:
        A `Future` whose result is a list of `TaskHandle` for each leased task.
      Throws:
        `java.lang.IllegalArgumentException` - if lease < 0, countLimit <= 0, or either is too large.

    - #### 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`

    - #### modifyTaskLease

          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`. A lease time of 0 will relinquish the lease on the task and make it available to be leased by calling `leaseTasks`.
      Parameters:
        `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.
      Returns:
        Updated `TaskHandle` with the new lease period.
      Throws:
        `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.

    - #### fetchStatistics

          QueueStatistics fetchStatistics()

      Obtain statistics for this `Queue`.
      Returns:
        The current `QueueStatistics` for this queue.
      Throws:
        `java.lang.IllegalStateException` - If the Queue does not exist. (see queue.xml)
        `TransientFailureException` - Attempting the request after this exception may succeed.
        `InternalFailureException`

    - #### fetchStatisticsAsync

          java.util.concurrent.Future<QueueStatistics> fetchStatisticsAsync(java.lang.Double deadlineInSeconds)

      Asynchronously obtains statistics for this `Queue`.
      Parameters:
        `deadlineInSeconds` - the maximum duration, in seconds, that the fetch statistics request can run. A default deadline will be used if `null` is supplied.
      Returns:
        A `Future` with a result type of `QueueStatistics`.
      Throws:
        `java.lang.IllegalArgumentException` - if deadlineInSeconds <= 0.