Package com.google.appengine.api.taskqueue

Class TaskOptions

java.lang.Object
com.google.appengine.api.taskqueue.TaskOptions
All Implemented Interfaces:
Serializable
public final class TaskOptions extends Object implements Serializable
Contains various options for a task following the builder pattern. Calls to TaskOptions methods may be chained to specify multiple options in the one TaskOptions object.

taskOptions can have either TaskOptions.Method PULL or a PUSH-related method, e.g. POST, GET, ... Tasks with PULL method can only be added into a PULL queue and PUSH tasks can only be added into a PUSH queue.

Notes on usage:
The recommended way to instantiate a TaskOptions object is to statically import TaskOptions.Builder.* and invoke a static creation method followed by an instance mutator (if needed): 


 import static com.google.appengine.api.taskqueue.TaskOptions.Builder.*;

 ...
 {@link QueueFactory#getDefaultQueue()}.add(withUrl(url).etaMillis(eta));
See Also:

  • Constructor Details

  • Method Details

    • taskName

      public TaskOptions taskName(String taskName)
      Sets the task name.
      Throws:
      IllegalArgumentException - The provided name is null, empty or doesn't match the regular expression QueueConstants.TASK_NAME_REGEX

    • getTaskName

      public String getTaskName()
      Returns the task name.

    • getPayload

      public byte[] getPayload()
      Returns the live payload for the task, not a copy. May be null.

    • payload

      public TaskOptions payload(byte[] payload)
      Sets the payload directly without specifying the content-type. If this task is added to a push queue, the content-type will be set to 'application/octet-stream' by default.
      Parameters:
      payload - The bytes representing the paylaod.
      Returns:
      TaskOptions object for chaining.

    • payload

      public TaskOptions payload(DeferredTask deferredTask)
      Sets the payload to the serialized form of the deferredTask object. The payload will be generated by serializing the deferredTask object using ObjectOutputStream.writeObject(Object). If the deferredTask's TaskOptions.Method is not PULL, the content type will be set to DeferredTaskContext.RUNNABLE_TASK_CONTENT_TYPE, the method will be forced to TaskOptions.Method.POST and if otherwise not specified, the url will be set to DeferredTaskContext.DEFAULT_DEFERRED_URL; the DeferredTask servlet is, by default, mapped to this url.

      Note: While this may be a convenient API, it requires careful control of the serialization compatibility of objects passed into payload(DeferredTask) method as objects placed in the task queue will survive revision updates of the application and hence may fail deserialization when the task is decoded with new revisions of the application. In particular, Java anonymous classes are convenient but may be particularly difficult to control or test for serialization compatibility.

      Parameters:
      deferredTask - The object to serialize into the payload.
      Throws:
      DeferredTaskCreationException - if there was an IOException serializing object.

    • payload

      public TaskOptions payload(String payload, String charset)
      Sets the payload from a String given a specific character set.
      Throws:
      UnsupportedTranslationException

    • payload

      public TaskOptions payload(byte[] payload, String contentType)
      Set the payload with the given content type.
      Parameters:
      payload - The bytes representing the paylaod.
      contentType - The content-type of the bytes.
      Returns:
      TaskOptions object for chaining.

    • payload

      public TaskOptions payload(String payload)
      Set the payload by String. The charset to convert the String to will be UTF-8 unless the method is PULL, in which case the String's bytes will be used directly.
      Parameters:
      payload - The String to be used.
      Returns:
      TaskOptions object for chaining.

    • getHeaders

      public Map<String,List<String>> getHeaders()
      Returns a copy of the task's headers as a map from each header name to a list of values for that header name.

    • headers

      public TaskOptions headers(Map<String,String> headers)
      Replaces the existing headers with the provided header name/value mapping.
      Parameters:
      headers - The headers to copy.
      Returns:
      TaskOptions object for chaining.

    • header

      public TaskOptions header(String headerName, String value)
      Adds a header name/value pair.
      Throws:
      IllegalArgumentException

    • removeHeader

      public TaskOptions removeHeader(String headerName)
      Remove all headers with the given name.

    • getMethod

      public TaskOptions.Method getMethod()
      Returns the method used for this task.

    • method

      public TaskOptions method(TaskOptions.Method method)
      Set the method used for this task. Defaults to TaskOptions.Method.POST.

    • getStringParams

      public Map<String,List<String>> getStringParams()
      Returns a copy of the task's string-valued parameters as a map from each parameter name to a list of values for that name.

    • getByteArrayParams

      public Map<String,List<byte[]>> getByteArrayParams()
      Returns a copy of the task's byte-array-valued parameters as a map from each parameter name to a list of values for that name.

    • clearParams

      public TaskOptions clearParams()
      Clears the parameters.

    • param

      public TaskOptions param(String name, String value)
      Add a named String parameter.
      Parameters:
      name - Name of the parameter. Must not be null or empty.
      value - The value of the parameter will undergo a "UTF-8" character encoding transformation upon being added to the queue. value must not be null.
      Throws:
      IllegalArgumentException

    • param

      public TaskOptions param(String name, byte[] value)
      Add a named byte array parameter.
      Parameters:
      name - Name of the parameter. Must not be null or empty.
      value - A byte array and encoded as-is (i.e. without character encoding transformations). value must not be null.
      Throws:
      IllegalArgumentException

    • removeParam

      public TaskOptions removeParam(String paramName)
      Remove all parameters with the given name.
      Parameters:
      paramName - Name of the parameter. Must not be null or empty.

    • getUrl

      public String getUrl()

    • url

      public TaskOptions url(String url)
      Set the URL.

      Default value is null.

      Parameters:
      url - String containing URL.

    • getCountdownMillis

      public Long getCountdownMillis()
      Returns the delay to apply to the submitted time. May be null.

    • countdownMillis

      public TaskOptions countdownMillis(long countdownMillis)
      Set the number of milliseconds delay before execution of the task.

    • getEtaMillis

      public Long getEtaMillis()
      Returns the specified ETA for a task. May be null if not specified.

    • etaMillis

      public TaskOptions etaMillis(long etaMillis)
      Sets the approximate absolute time to execute. (i.e. etaMillis is comparable with System.currentTimeMillis()).

    • getRetryOptions

      public RetryOptions getRetryOptions()
      Returns a copy of the retry options for a task. May be null if not specified.

    • retryOptions

      public TaskOptions retryOptions(RetryOptions retryOptions)
      Sets retry options for this task. Retry Options must be built with RetryOptions.Builder.

    • getTagAsBytes

      public byte[] getTagAsBytes()
      Returns the live tag bytes for a task, not a copy. May be null if tag is not specified.

    • getTag

      public String getTag() throws UnsupportedEncodingException
      Returns the tag for a task. May be null if tag is not specified.
      Throws:
      UnsupportedEncodingException

    • getDispatchDeadline

      public @Nullable Duration getDispatchDeadline()
      Returns the dispatch deadline for a task. The dispatch deadline determines how long the of a task should take. If a task exceeds its deadline, it will be canceled and retried based on retry configurations of the task and/or queue.

    • tag

      public TaskOptions tag(byte[] tag)
      Sets the tag for a task. Ignores null or zero-length tags.

    • tag

      public TaskOptions tag(String tag)
      Sets the tag for a task. Ignores null or empty tags.

    • dispatchDeadline

      public TaskOptions dispatchDeadline(Duration dispatchDeadline)
      Sets the dispatch deadline for a task. The dispatch deadline should be no smaller than TaskOptions#MIN_DISPATCH_DEADLINE and no larger than TaskOptions#MAX_DISPATCH_DEADLINE.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object