com.google.appengine.api.taskqueue

## Class TaskOptions

- java.lang.Object
- - com.google.appengine.api.taskqueue.TaskOptions

- All Implemented Interfaces:
    java.io.Serializable

      public final class TaskOptions
      extends java.lang.Object
      implements java.io.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.*;

       ...
       QueueFactory.getDefaultQueue().add(header("X-HEADER", "value"));

  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `TaskOptions.Builder` Provides static creation methods for `TaskOptions`.
    `static class` | `TaskOptions.Method` Methods supported by `Queue`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TaskOptions(TaskOptions options)` A copy constructor for `TaskOptions`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `TaskOptions` | `clearParams()` Clears the parameters.
    `TaskOptions` | `countdownMillis(long countdownMillis)` Set the number of milliseconds delay before execution of the task.
    `boolean` | `equals(java.lang.Object obj)`
    `TaskOptions` | `etaMillis(long etaMillis)` Sets the approximate absolute time to execute.
    `java.lang.Long` | `getEtaMillis()` Returns the specified ETA for a task.
    `java.lang.String` | `getTag()` Returns the tag for a task.
    `byte[]` | `getTagAsBytes()` Returns the tag for a task.
    `java.lang.String` | `getUrl()`
    `int` | `hashCode()`
    `TaskOptions` | `header(java.lang.String headerName, java.lang.String value)` Adds a header `name/value` pair.
    `TaskOptions` | `headers(java.util.Map<java.lang.String,java.lang.String> headers)` Replaces the existing headers with the provided header `name/value` mapping.
    `TaskOptions` | `method(TaskOptions.Method method)` Set the method used for this task.
    `TaskOptions` | `param(java.lang.String name, byte[] value)` Add a named `byte` array parameter.
    `TaskOptions` | `param(java.lang.String name, java.lang.String value)` Add a named `String` parameter.
    `TaskOptions` | `payload(byte[] payload)` Sets the payload directly without specifying the content-type.
    `TaskOptions` | `payload(byte[] payload, java.lang.String contentType)` Set the payload with the given content type.
    `TaskOptions` | `payload(DeferredTask deferredTask)` Sets the payload to the serialized form of the deferredTask object.
    `TaskOptions` | `payload(java.lang.String payload)` Set the payload by `String`.
    `TaskOptions` | `payload(java.lang.String payload, java.lang.String charset)` Sets the payload from a `String` given a specific character set.
    `TaskOptions` | `removeHeader(java.lang.String headerName)` Remove all headers with the given name.
    `TaskOptions` | `removeParam(java.lang.String paramName)` Remove all parameters with the given name.
    `TaskOptions` | `retryOptions(RetryOptions retryOptions)` Sets retry options for this task.
    `TaskOptions` | `tag(byte[] tag)` Sets the tag for a task.
    `TaskOptions` | `tag(java.lang.String tag)` Sets the tag for a task.
    `TaskOptions` | `taskName(java.lang.String taskName)` Sets the task name.
    `java.lang.String` | `toString()`
    `TaskOptions` | `url(java.lang.String url)` Set the URL.

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### TaskOptions

          public TaskOptions(TaskOptions options)

      A copy constructor for `TaskOptions`.

  - ### Method Detail

    - #### taskName

          public TaskOptions taskName(java.lang.String taskName)

      Sets the task name.
      Throws:
        `java.lang.IllegalArgumentException` - The provided name is null, empty or doesn't match the regular expression `QueueConstants.TASK_NAME_REGEX`

    - #### 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(java.lang.String payload,
                            java.lang.String charset)

      Sets the payload from a `String` given a specific character set.
      Throws:
        `UnsupportedTranslationException`

    - #### payload

          public TaskOptions payload(byte[] payload,
                            java.lang.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(java.lang.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.

    - #### headers

          public TaskOptions headers(java.util.Map<java.lang.String,java.lang.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(java.lang.String headerName,
                           java.lang.String value)

      Adds a header `name/value` pair.
      Throws:
        `java.lang.IllegalArgumentException`

    - #### removeHeader

          public TaskOptions removeHeader(java.lang.String headerName)

      Remove all headers with the given name.

    - #### method

          public TaskOptions method(TaskOptions.Method method)

      Set the method used for this task. Defaults to `TaskOptions.Method.POST`.

    - #### clearParams

          public TaskOptions clearParams()

      Clears the parameters.

    - #### param

          public TaskOptions param(java.lang.String name,
                          java.lang.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:
        `java.lang.IllegalArgumentException`

    - #### param

          public TaskOptions param(java.lang.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:
        `java.lang.IllegalArgumentException`

    - #### removeParam

          public TaskOptions removeParam(java.lang.String paramName)

      Remove all parameters with the given name.
      Parameters:
        `paramName` - Name of the parameter. Must not be null or empty.

    - #### getUrl

          public java.lang.String getUrl()

    - #### url

          public TaskOptions url(java.lang.String url)

      Set the URL.

      Default value is `null`.

      Parameters:
        `url` - String containing URL.

    - #### countdownMillis

          public TaskOptions countdownMillis(long countdownMillis)

      Set the number of milliseconds delay before execution of the task.

    - #### getEtaMillis

          public java.lang.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()`).

    - #### 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 tag for a task. May be `null` if tag is not specified.

    - #### getTag

          public java.lang.String getTag()
                                  throws java.io.UnsupportedEncodingException

      Returns the tag for a task. May be `null` if tag is not specified.
      Throws:
        `java.io.UnsupportedEncodingException`

    - #### tag

          public TaskOptions tag(byte[] tag)

      Sets the tag for a task. Ignores null or zero-length tags.

    - #### tag

          public TaskOptions tag(java.lang.String tag)

      Sets the tag for a task. Ignores null or empty tags.

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          public boolean equals(java.lang.Object obj)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`