java/src/main/com/google/appengine/api/taskqueue/Queue.java

   1 // Copyright 2010 Google Inc. All rights reserved.
   2 package com.google.appengine.api.taskqueue;
   3
   4 import com.google.appengine.api.datastore.Transaction;
   5
   6 import java.util.List;
   7 import java.util.concurrent.Future;
   8 import java.util.concurrent.TimeUnit;
   9
  10 /**
  11  * {@link Queue} is used to manage a task queue.
  12  * <p>Implementations of this interface must be threadsafe.
  13  *
  14  * <p>Queues are transactional.  If a datastore transaction is in progress when
  15  * {@link #add()} or {@link #add(TaskOptions)} is invoked, the task will only
  16  * be added to the queue if the datastore transaction successfully commits.  If
  17  * you want to add a task to a queue and have that operation succeed or fail
  18  * independently of an existing datastore transaction you can invoke
  19  * {@link #add(Transaction, TaskOptions)} with a {@code null} transaction
  20  * argument.  Note that while the addition of the task to the queue can
  21  * participate in an existing transaction, the execution of the task cannot
  22  * participate in this transaction.  In other words, when the transaction
  23  * commits you are guaranteed that your task will be added and run, not that
  24  * your task executed successfully.
  25  * <p> Queues may be configured in either push or pull mode, but they share the
  26  * same interface. However, only tasks with {@link TaskOptions.Method#PULL} may
  27  * be added to pull queues. The tasks in push queues must be added with one of
  28  * the other available methods.
  29  * <p>Pull mode queues do not automatically deliver tasks to the application.
  30  * The application is required to call
  31  * {@link #leaseTasks(long, TimeUnit, long) leaseTasks} to acquire a lease on
  32  * the task and process them explicitly.  Attempting to call
  33  * {@link #leaseTasks(long, TimeUnit, long) leaseTasks} on a push queue causes
  34  * a {@link InvalidQueueModeException} to be thrown. When the task processing
  35  * has finished processing a task that is leased, it should call
  36  * {@link #deleteTask(String)}. If deleteTask is not called before the lease
  37  * expires, the task will again be available for lease.
  38  *
  39  * <p> Queue mode can be switched between push and pull. When switching from
  40  * push to pull, tasks will stay in the task queue and are available for lease,
  41  * but url and headers information will be ignored when returning the tasks.
  42  * When switching from pull to push, existing tasks will remain in the queue but
  43  * will fail on auto-execution because they lack a url. If the queue mode is
  44  * once again changed to pull, these tasks will eventually be available for
  45  * lease.
  46  *
  47  */
  48 public interface Queue {
  49   /**
  50    * The default queue name.
  51    */
  52   String DEFAULT_QUEUE = "default";
  53
  54   /**
  55    * The default queue path.
  56    */
  57   String DEFAULT_QUEUE_PATH = "/_ah/queue";
  58
  59   /**
  60    * Returns the queue name.
  61    */
  62   String getQueueName();
  63
  64   /**
  65    * Submits a task to this queue with an auto generated name with default
  66    * options.
  67    * <p>This method is similar to calling {@link #add(TaskOptions)} with
  68    * a {@link TaskOptions} object returned by
  69    * {@link TaskOptions.Builder#withDefaults()}.
  70    * @return A {@link TaskHandle}.
  71    * @throws InternalFailureException
  72    * @throws IllegalStateException If the queue does not exist. (see queue.xml)
  73    * @throws TransientFailureException Attempting the request after this exception may succeed.
  74    * @throws InvalidQueueModeException task method is {@link TaskOptions.Method#PULL} and queue is
  75    * push queue or vice versa.
  76    */
  77   TaskHandle add();
  78
  79   /**
  80    * Submits a task to this queue.
  81    * @param taskOptions The definition of the task.
  82    * @return A {@link TaskHandle}.
  83    * @throws InternalFailureException
  84    * @throws IllegalStateException If the queue does not exist. (see queue.xml)
  85    * @throws TaskAlreadyExistsException
  86    * @throws TransientFailureException Attempting the request after this exception may succeed.
  87    * @throws UnsupportedTranslationException If chosen character encoding is unsupported.
  88    * @throws InvalidQueueModeException task method is {@link TaskOptions.Method#PULL} and queue is
  89    * push queue or vice versa.
  90    */
  91   TaskHandle add(TaskOptions taskOptions);
  92
  93   /**
  94    * Submits tasks to this queue.
  95    * <p>Submission is not atomic i.e. if this method throws then some tasks may have been added to
  96    * the queue.
  97    * @param taskOptions An iterable over task definitions.
  98    * @return A list containing a {@link TaskHandle} for each added task.
  99    * @throws InternalFailureException
 100    * @throws IllegalStateException If the queue does not exist. (see queue.xml)
 101    * @throws TaskAlreadyExistsException If any of the provided {@code TaskOptions} contained a name
 102    * of a task that was previously created, and if no other {@code Exception} would be thrown. Note
 103    * that if a {@code TaskAlreadyExistsException} is caught, the caller can be guaranteed that for
 104    * each one of the provided {@code TaskOptions}, either the corresponding task was successfully
 105    * added, or a task with the given name was successfully added in the past.
 106    * @throws TransientFailureException Attempting the request after this exception may succeed.
 107    * @throws UnsupportedTranslationException If chosen character encoding is unsupported.
 108    * @throws InvalidQueueModeException task method is {@link TaskOptions.Method#PULL} and queue is
 109    * push queue or vice versa.
 110    */
 111   List<TaskHandle> add(Iterable<TaskOptions> taskOptions);
 112
 113   /**
 114    * Submits a task to this queue in the provided Transaction.
 115    * <p>A task is added if and only if the transaction is applied successfully.
 116    * @param txn an enclosing {@link Transaction} or null, if not null a task cannot be named.
 117    * @param taskOptions The definition of the task.
 118    * @return A {@link TaskHandle}.
 119    * @throws InternalFailureException
 120    * @throws IllegalStateException If the queue does not exist. (see queue.xml)
 121    * @throws TaskAlreadyExistsException if a task with the same name was previously created.
 122    * @throws TransientFailureException Attempting the request after this exception may succeed.
 123    * @throws UnsupportedTranslationException If chosen character encoding is unsupported.
 124    * @throws InvalidQueueModeException task method is {@link TaskOptions.Method#PULL} and queue is
 125    * push queue or vice versa.
 126    */
 127   TaskHandle add(Transaction txn, TaskOptions taskOptions);
 128
 129   /**
 130    * Submits tasks to this queue in the provided Transaction.
 131    * <p>The tasks are added if and only if the transaction is applied successfully.
 132    * @param txn an enclosing {@link Transaction} or null, if not null a task cannot be named.
 133    * @param taskOptions An iterable over task definitions.
 134    * @return A list containing a {@link TaskHandle} for each added task.
 135    * @throws InternalFailureException
 136    * @throws IllegalStateException If the queue does not exist. (see queue.xml)
 137    * @throws TaskAlreadyExistsException if a task with the same name was previously created.
 138    * @throws TransientFailureException Attempting the request after this exception may succeed.
 139    * @throws UnsupportedTranslationException If chosen character encoding is unsupported.
 140    * @throws InvalidQueueModeException task method is {@link TaskOptions.Method#PULL} and queue is
 141    * push queue or vice versa.
 142    */
 143   List<TaskHandle> add(Transaction txn, Iterable<TaskOptions> taskOptions);
 144
 145   /**
 146    * Asynchronously submits a task to this queue with an auto generated name with default
 147    * options.
 148    * <p>This method is similar to calling {@link #addAsync(TaskOptions)} with
 149    * a {@link TaskOptions} object returned by
 150    * {@link TaskOptions.Builder#withDefaults()}.
 151    * @return A {@code Future} with a result type of {@link TaskHandle}.
 152    */
 153   Future<TaskHandle> addAsync();
 154
 155   /**
 156    * Asynchronously submits a task to this queue.
 157    * @param taskOptions The definition of the task.
 158    * @return A {@code Future} with a result type of {@link TaskHandle}.
 159    * @throws UnsupportedTranslationException If chosen character encoding is unsupported.
 160    */
 161   Future<TaskHandle> addAsync(TaskOptions taskOptions);
 162
 163   /**
 164    * Asynchronously submits tasks to this queue.
 165    * <p>Submission is not atomic i.e. if this method fails then some tasks may have been added to
 166    * the queue.
 167    * @param taskOptions An iterable over task definitions.
 168    * @return A {@code Future} whose result is a list containing a {@link TaskHandle} for each added
 169    * task.
 170    * @throws UnsupportedTranslationException If chosen character encoding is unsupported.
 171    */
 172   Future<List<TaskHandle>> addAsync(Iterable<TaskOptions> taskOptions);
 173
 174   /**
 175    * Asynchronously submits a task to this queue in the provided Transaction.
 176    * <p>A task is added if and only if the transaction is applied successfully.
 177    * @param txn an enclosing {@link Transaction} or null, if not null a task cannot be named.
 178    * @param taskOptions The definition of the task.
 179    * @return A {@code Future} with a result type of {@link TaskHandle}.
 180    * @throws UnsupportedTranslationException If chosen character encoding is unsupported.
 181    */
 182   Future<TaskHandle> addAsync(Transaction txn, TaskOptions taskOptions);
 183
 184   /**
 185    * Asynchronously submits tasks to this queue in the provided Transaction.
 186    * <p>The tasks are added if and only if the transaction is applied successfully.
 187    * @param txn an enclosing {@link Transaction} or null, if not null a task cannot be named.
 188    * @param taskOptions An iterable over task definitions.
 189    * @return A {@code Future} whose result is a list containing a {@link TaskHandle} for each added
 190    * task.
 191    * @throws UnsupportedTranslationException If chosen character encoding is unsupported.
 192    */
 193   Future<List<TaskHandle>> addAsync(
 194       Transaction txn, Iterable<TaskOptions> taskOptions);
 195
 196   /**
 197    * Deletes a task from this {@link Queue}. Task is identified by taskName.
 198    * @param taskName name of the task to delete.
 199    * @return True if the task was successfully deleted. False if the task was not found or was
 200    * previously deleted.
 201    * @throws IllegalArgumentException if the provided name is null, empty or doesn't match the
 202    *         expected pattern.
 203    * @throws InternalFailureException
 204    * @throws IllegalStateException If the queue does not exist. (see queue.xml)
 205    * @throws TransientFailureException Attempting the request after this exception may succeed.
 206    */
 207   boolean deleteTask(String taskName);
 208
 209   /**
 210    * Deletes a task from this {@link Queue}. Task is identified by a TaskHandle.
 211    * @param taskHandle handle of the task to delete.
 212    * @return True if the task was successfully deleted. False if the task was not found or was
 213    * previously deleted.
 214    * @throws IllegalArgumentException if the provided name is null, empty or doesn't match the
 215    *         expected pattern.
 216    * @throws InternalFailureException
 217    * @throws IllegalStateException If the queue does not exist. (see queue.xml)
 218    * @throws QueueNameMismatchException if the task handle refers to a different named queue.
 219    * @throws TransientFailureException Attempting the request after this exception may succeed.
 220    */
 221   boolean deleteTask(TaskHandle taskHandle);
 222
 223   /**
 224    * Deletes a list of tasks from this {@link Queue}. The tasks are identified
 225    *        by a list of TaskHandles.
 226    * @param taskHandles list of handles of tasks to delete.
 227    * @return {@code List<Boolean>} that represents the result of deleting each task in
 228    *         the same order as the input handles. True if a task was successfully deleted.
 229    *         False if the task was not found or was previously deleted.
 230    * @throws IllegalArgumentException if the provided name is null, empty or doesn't match the
 231    *         expected pattern.
 232    * @throws InternalFailureException
 233    * @throws IllegalStateException If the queue does not exist. (see queue.xml)
 234    * @throws QueueNameMismatchException if the task handle refers to a different named queue.
 235    * @throws TransientFailureException Attempting the request after this exception may succeed.
 236    */
 237   List<Boolean> deleteTask(List<TaskHandle> taskHandles);
 238
 239   /**
 240    * Asynchronously deletes a task from this {@link Queue}. Task is identified by taskName.
 241    * @param taskName name of the task to delete.
 242    * @return A {@code Future} whose result is True if the task was successfully deleted,
 243    * False if the task was not found or was previously deleted.
 244    * @throws IllegalArgumentException if the provided name is null, empty or doesn't match the
 245    *         expected pattern.
 246    */
 247   Future<Boolean> deleteTaskAsync(String taskName);
 248
 249   /**
 250    * Asynchronously deletes a task from this {@link Queue}. Task is identified by a TaskHandle.
 251    * @param taskHandle handle of the task to delete.
 252    * @return A {@code Future} whose result is True if the task was successfully deleted,
 253    * False if the task was not found or was previously deleted.
 254    * @throws IllegalArgumentException if the provided name is null, empty or doesn't match the
 255    *         expected pattern.
 256    * @throws QueueNameMismatchException if the task handle refers to a different named queue.
 257    */
 258   Future<Boolean> deleteTaskAsync(TaskHandle taskHandle);
 259
 260   /**
 261    * Asynchronously deletes a list of tasks from this {@link Queue}. The tasks are identified
 262    *        by a list of TaskHandles.
 263    * @param taskHandles list of handles of tasks to delete.
 264    * @return A {@code Future} whose result is a {@code List<Boolean>} that represents the result of
 265    *         deleting each task in the same order as the input handles. True if a task was
 266    *         successfully deleted. False if the task was not found or was previously deleted.
 267    * @throws IllegalArgumentException if the provided name is null, empty or doesn't match the
 268    *         expected pattern.
 269    * @throws QueueNameMismatchException if the task handle refers to a different named queue.
 270    */
 271   Future<List<Boolean>> deleteTaskAsync(List<TaskHandle> taskHandles);
 272
 273   /**
 274    * Leases up to {@code countLimit} tasks from this queue for a period specified by
 275    * {@code lease} and {@code unit}. If fewer tasks than {@code countLimit} are available, all
 276    * available tasks in this {@link Queue} will be returned. The available tasks are those in the
 277    * queue having the earliest eta such that eta is prior to the time at which the lease is
 278    * requested. It is guaranteed that the leased tasks will be unavailable for lease to others in
 279    * the lease period. You must call deleteTask to prevent the task from being leased again after
 280    * the lease period. This method supports leasing a maximum of 1000 tasks for no more than one
 281    * week. If you generate more than 10 LeaseTasks requests per second, only the first 10 requests
 282    * will return results. The others will return no results.
 283    * @param lease Number of {@code unit}s in the lease period
 284    * @param unit Time unit of the lease period
 285    * @param countLimit maximum number of tasks to lease
 286    * @return A list of {@link TaskHandle} for each leased task.
 287    * @throws InvalidQueueModeException if the target queue is not in pull mode.
 288    * @throws IllegalArgumentException if {@literal lease < 0}, {@literal countLimit <= 0},
 289    * or either is too large.
 290    * @throws InternalFailureException
 291    * @throws IllegalStateException If the queue does not exist. (see queue.xml)
 292    * @throws TransientFailureException Attempting the request after this exception may succeed.
 293    */
 294   List<TaskHandle> leaseTasks(long lease, TimeUnit unit, long countLimit);
 295
 296   /**
 297    * Leases up to {@code countLimit} tasks from this queue for a period specified by
 298    * {@code lease} and {@code unit}, having tag {@code tag}. If {@code tag} is {@code null}, tasks
 299    * having the same tag as the task with earliest eta will be returned. If fewer such tasks than
 300    * {@code countLimit} are available, all available such tasks in this {@link Queue} will be
 301    * returned. The available tasks are those in the queue having the earliest eta such that eta is
 302    * prior to the time at which the lease is requested.
 303    * It is guaranteed that the leased tasks will be unavailable for lease to others in the
 304    * lease period. You must call deleteTask to prevent the task from being leased again after
 305    * the lease period. This method supports leasing a maximum of 1000 tasks for no more than one
 306    * week.
 307    * @param lease Number of {@code unit}s in the lease period
 308    * @param unit Time unit of the lease period
 309    * @param countLimit maximum number of tasks to lease
 310    * @param tag User defined tag required for returned tasks. If {@code null}, the tag of the task
 311    *        with earliest eta will be used.
 312    * @return A list of {@link TaskHandle} for each leased task.
 313    * @throws InvalidQueueModeException if the target queue is not in pull mode.
 314    * @throws IllegalArgumentException if {@literal lease < 0}, {@literal countLimit <= 0},
 315    * or either is too large.
 316    * @throws InternalFailureException
 317    * @throws IllegalStateException If the queue does not exist. (see queue.xml)
 318    * @throws TransientFailureException Attempting the request after this exception may succeed.
 319    */
 320   List<TaskHandle> leaseTasksByTagBytes(long lease, TimeUnit unit, long countLimit, byte[] tag);
 321
 322   /**
 323    * Leases up to {@code countLimit} tasks from this queue for a period specified by
 324    * {@code lease} and {@code unit}, having tag {@code tag}. If {@code tag} is {@code null}, tasks
 325    * having the same tag as the task with earliest eta will be returned. If fewer such tasks than
 326    * {@code countLimit} are available, all available such tasks in this {@link Queue} will be
 327    * returned. The available tasks are those in the queue having the earliest eta such that eta is
 328    * prior to the time at which the lease is requested.
 329    * <p>It is guaranteed that the leased tasks will be unavailable for lease to others in the
 330    * lease period. You must call deleteTask to prevent the task from being leased again after
 331    * the lease period. This method supports leasing a maximum of 1000 tasks for no more than one
 332    * week.
 333    * @param lease Number of {@code unit}s in the lease period
 334    * @param unit Time unit of the lease period
 335    * @param countLimit maximum number of tasks to lease
 336    * @param tag User defined {@code String} tag required for returned tasks. If {@code null}, the
 337    *        tag of the task with earliest eta will be used.
 338    * @return A list of {@link TaskHandle} for each leased task.
 339    * @throws InvalidQueueModeException if the target queue is not in pull mode.
 340    * @throws IllegalArgumentException if {@literal lease < 0}, {@literal countLimit <= 0},
 341    * or either is too large.
 342    * @throws InternalFailureException
 343    * @throws IllegalStateException If the queue does not exist. (see queue.xml)
 344    * @throws TransientFailureException Attempting the request after this exception may succeed.
 345    */
 346   List<TaskHandle> leaseTasksByTag(long lease, TimeUnit unit, long countLimit, String tag);
 347
 348   /**
 349    * Leases tasks from this queue, with lease period and other options specified by
 350    * {@code options}. The available tasks are those in the queue having the earliest eta such that
 351    * eta is prior to the time at which the lease is requested.
 352    * <p> If {@code options} specifies a tag, only tasks having that tag will be returned.
 353    * If {@code options} specifies no tag, but does specify {@code groupByTag}, only tasks
 354    * having the same tag as the task with earliest eta will be returned.
 355    * <p> It is guaranteed that the leased tasks will be unavailable for lease to others in
 356    * the lease period. You must call deleteTask to prevent the task from being leased again after
 357    * the lease period. This method supports leasing a maximum of 1000 tasks for no more than one
 358    * week.
 359    * @param options Specific options for this lease request
 360    * @return A list of {@link TaskHandle} for each leased task.
 361    * @throws InvalidQueueModeException if the target queue is not in pull mode.
 362    * @throws IllegalArgumentException if lease period or countLimit is null or either is too large.
 363    * @throws InternalFailureException
 364    * @throws IllegalStateException If the queue does not exist. (see queue.xml)
 365    * @throws TransientFailureException Attempting the request after this exception may succeed.
 366    */
 367   List<TaskHandle> leaseTasks(LeaseOptions options);
 368
 369   /**
 370    * Asynchronously leases up to {@code countLimit} tasks from this queue for a period specified by
 371    * {@code lease} and {@code unit}. If fewer tasks than {@code countLimit} are available, all
 372    * available tasks in this {@link Queue} will be returned. The available tasks are those in the
 373    * queue having the earliest eta such that eta is prior to the time at which the lease is
 374    * requested. It is guaranteed that the leased tasks will be unavailable for lease to others in
 375    * the lease period. You must call deleteTask to prevent the task from being leased again after
 376    * the lease period. This method supports leasing a maximum of 1000 tasks for no more than one
 377    * week.
 378    * @param lease Number of {@code unit}s in the lease period
 379    * @param unit Time unit of the lease period
 380    * @param countLimit maximum number of tasks to lease
 381    * @return A {@code Future} whose result is a list of {@link TaskHandle} for each leased task.
 382    * @throws IllegalArgumentException if {@literal lease < 0}, {@literal countLimit <= 0},
 383    * or either is too large.
 384    */
 385   Future<List<TaskHandle>> leaseTasksAsync(
 386       long lease, TimeUnit unit, long countLimit);
 387
 388   /**
 389    * Asynchronously leases up to {@code countLimit} tasks from this queue for a period specified by
 390    * {@code lease} and {@code unit}, having tag {@code tag}. If {@code tag} is {@code null}, tasks
 391    * having the same tag as the task with earliest eta will be returned. If fewer such tasks than
 392    * {@code countLimit} are available, all available such tasks in this {@link Queue} will be
 393    * returned. The available tasks are those in the queue having the earliest eta such that eta is
 394    * prior to the time at which the lease is requested.
 395    * It is guaranteed that the leased tasks will be unavailable for lease to others in the
 396    * lease period. You must call deleteTask to prevent the task from being leased again after
 397    * the lease period. This method supports leasing a maximum of 1000 tasks for no more than one
 398    * week.
 399    * @param lease Number of {@code unit}s in the lease period
 400    * @param unit Time unit of the lease period
 401    * @param countLimit maximum number of tasks to lease
 402    * @param tag User defined tag required for returned tasks. If {@code null}, the tag of the task
 403    *        with earliest eta will be used.
 404    * @return A {@code Future} whose result is a list of {@link TaskHandle} for each leased task.
 405    * @throws IllegalArgumentException if {@literal lease < 0}, {@literal countLimit <= 0},
 406    * or either is too large.
 407    */
 408   Future<List<TaskHandle>> leaseTasksByTagBytesAsync(
 409       long lease, TimeUnit unit, long countLimit, byte[] tag);
 410
 411   /**
 412    * Asynchronously leases up to {@code countLimit} tasks from this queue for a period specified by
 413    * {@code lease} and {@code unit}, having tag {@code tag}. If {@code tag} is {@code null}, tasks
 414    * having the same tag as the task with earliest eta will be returned. If fewer such tasks than
 415    * {@code countLimit} are available, all available such tasks in this {@link Queue} will be
 416    * returned. The available tasks are those in the queue having the earliest eta such that eta is
 417    * prior to the time at which the lease is requested.
 418    * <p>It is guaranteed that the leased tasks will be unavailable for lease to others in the
 419    * lease period. You must call deleteTask to prevent the task from being leased again after
 420    * the lease period. This method supports leasing a maximum of 1000 tasks for no more than one
 421    * week.
 422    * @param lease Number of {@code unit}s in the lease period
 423    * @param unit Time unit of the lease period
 424    * @param countLimit maximum number of tasks to lease
 425    * @param tag User defined {@code String} tag required for returned tasks. If {@code null}, the
 426    *        tag of the task with earliest eta will be used.
 427    * @return A {@code Future} whose result is a list of {@link TaskHandle} for each leased task.
 428    * @throws IllegalArgumentException if {@literal lease < 0}, {@literal countLimit <= 0},
 429    * or either is too large.
 430    */
 431   Future<List<TaskHandle>> leaseTasksByTagAsync(
 432       long lease, TimeUnit unit, long countLimit, String tag);
 433
 434   /**
 435    * Asynchronously leases tasks from this queue, with lease period and other options specified by
 436    * {@code options}. The available tasks are those in the queue having the earliest eta such that
 437    * eta is prior to the time at which the lease is requested.
 438    * <p> If {@code options} specifies a tag, only tasks having that tag will be returned.
 439    * If {@code options} specifies no tag, but does specify {@code groupByTag}, only tasks
 440    * having the same tag as the task with earliest eta will be returned.
 441    * <p> It is guaranteed that the leased tasks will be unavailable for lease to others in
 442    * the lease period. You must call deleteTask to prevent the task from being leased again after
 443    * the lease period. This method supports leasing a maximum of 1000 tasks for no more than one
 444    * week.
 445    * @param options Specific options for this lease request
 446    * @return A {@code Future} whose result is a list of {@link TaskHandle} for each leased task.
 447    * @throws IllegalArgumentException if lease period or countLimit is null or either is too large.
 448    */
 449   Future<List<TaskHandle>> leaseTasksAsync(LeaseOptions options);
 450
 451   /**
 452    * Clears all the tasks in this {@link Queue}. This function returns
 453    * immediately. Some delay may apply on the server before the Queue is
 454    * actually purged. Tasks being executed at the time the purge call is
 455    * made will continue executing, other tasks in this Queue will continue
 456    * being dispatched and executed before the purge call takes effect.
 457    * @throws IllegalStateException If the Queue does not exist. (see queue.xml)
 458    * @throws TransientFailureException Attempting the request after this exception may succeed.
 459    * @throws InternalFailureException
 460    */
 461   void purge();
 462
 463   /**
 464    * Modify the lease of the specified task in this {@link Queue} for a period of time specified
 465    * by {@code lease} and {@code unit}. A lease time of 0 will relinquish the lease on the
 466    * task and make it available to be leased by calling
 467    * {@link #leaseTasks(LeaseOptions) leaseTasks}.
 468    * @param taskHandle handle of the task that is having its lease modified.
 469    * @param lease Number of {@code unit}s in the lease period.
 470    * @param unit Time unit of the lease period.
 471    * @return Updated {@link TaskHandle} with the new lease period.
 472    * @throws InvalidQueueModeException if the target queue is not in pull mode.
 473    * @throws IllegalArgumentException if {@literal lease < 0} or too large.
 474    * @throws InternalFailureException
 475    * @throws IllegalStateException If the queue does not exist, or the task lease has expired
 476    *         or the queue has been paused.
 477    * @throws TransientFailureException Attempting the request after this exception may succeed.
 478    */
 479   TaskHandle modifyTaskLease(TaskHandle taskHandle, long lease, TimeUnit unit);
 480
 481   /**
 482    * Obtain statistics for this {@link Queue}.
 483    * @return The current {@link QueueStatistics} for this queue.
 484    * @throws IllegalStateException If the Queue does not exist. (see queue.xml)
 485    * @throws TransientFailureException Attempting the request after this exception may succeed.
 486    * @throws InternalFailureException
 487    */
 488   QueueStatistics fetchStatistics();
 489
 490   /**
 491    * Asynchronously obtains statistics for this {@link Queue}.
 492    * @param deadlineInSeconds the maximum duration, in seconds, that the fetch statistics
 493    *        request can run. A default deadline will be used if {@code null} is supplied.
 494    * @throws IllegalArgumentException if {@literal deadlineInSeconds <= 0}.
 495    * @return A {@code Future} with a result type of {@link QueueStatistics}.
 496    */
 497   Future<QueueStatistics> fetchStatisticsAsync( Double deadlineInSeconds);
 498 }