Class TaskOptions (2.0.0)

public final class TaskOptions 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 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(withUrl(url).etaMillis(eta));
 

Inheritance

Object > TaskOptions

Implements

Serializable

Constructors

TaskOptions(TaskOptions options)

public TaskOptions(TaskOptions options)

A copy constructor for TaskOptions.

Parameter
NameDescription
optionsTaskOptions

Methods

clearParams()

public TaskOptions clearParams()

Clears the parameters.

Returns
TypeDescription
TaskOptions

countdownMillis(long countdownMillis)

public TaskOptions countdownMillis(long countdownMillis)

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

Parameter
NameDescription
countdownMillislong
Returns
TypeDescription
TaskOptions

dispatchDeadline(Duration 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.

Parameter
NameDescription
dispatchDeadlineDuration
Returns
TypeDescription
TaskOptions

equals(Object obj)

public boolean equals(Object obj)
Parameter
NameDescription
objObject
Returns
TypeDescription
boolean
Overrides

etaMillis(long etaMillis)

public TaskOptions etaMillis(long etaMillis)

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

Parameter
NameDescription
etaMillislong
Returns
TypeDescription
TaskOptions

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.

Returns
TypeDescription
Map<String,List<byte[]>>

getCountdownMillis()

public Long getCountdownMillis()

Returns the delay to apply to the submitted time. May be null.

Returns
TypeDescription
Long

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.

Returns
TypeDescription
@org.checkerframework.checker.nullness.qual.Nullable java.time.Duration

getEtaMillis()

public Long getEtaMillis()

Returns the specified ETA for a task. May be null if not specified.

Returns
TypeDescription
Long

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.

Returns
TypeDescription
Map<String,List<String>>

getMethod()

public TaskOptions.Method getMethod()

Returns the method used for this task.

Returns
TypeDescription
TaskOptions.Method

getPayload()

public byte[] getPayload()

Returns the live payload for the task, not a copy. May be null.

Returns
TypeDescription
byte[]

getRetryOptions()

public RetryOptions getRetryOptions()

Returns a copy of the retry options for a task. May be null if not specified.

Returns
TypeDescription
RetryOptions

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.

Returns
TypeDescription
Map<String,List<String>>

getTag()

public String getTag()

Returns the tag for a task. May be null if tag is not specified.

Returns
TypeDescription
String
Exceptions
TypeDescription
UnsupportedEncodingException

getTagAsBytes()

public byte[] getTagAsBytes()

Returns the live tag bytes for a task, not a copy. May be null if tag is not specified.

Returns
TypeDescription
byte[]

getTaskName()

public String getTaskName()

Returns the task name.

Returns
TypeDescription
String

getUrl()

public String getUrl()
Returns
TypeDescription
String

hashCode()

public int hashCode()
Returns
TypeDescription
int
Overrides

header(String headerName, String value)

public TaskOptions header(String headerName, String value)

Adds a header name/value pair.

Parameters
NameDescription
headerNameString
valueString
Returns
TypeDescription
TaskOptions

headers(Map<String,String> headers)

public TaskOptions headers(Map<String,String> headers)

Replaces the existing headers with the provided header name/value mapping.

Parameter
NameDescription
headersMap<String,String>

The headers to copy.

Returns
TypeDescription
TaskOptions

TaskOptions object for chaining.

method(TaskOptions.Method method)

public TaskOptions method(TaskOptions.Method method)

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

Parameter
NameDescription
methodTaskOptions.Method
Returns
TypeDescription
TaskOptions

param(String name, byte[] value)

public TaskOptions param(String name, byte[] value)

Add a named byte array parameter.

Parameters
NameDescription
nameString

Name of the parameter. Must not be null or empty.

valuebyte[]

A byte array and encoded as-is (i.e. without character encoding transformations). value must not be null.

Returns
TypeDescription
TaskOptions

param(String name, String value)

public TaskOptions param(String name, String value)

Add a named String parameter.

Parameters
NameDescription
nameString

Name of the parameter. Must not be null or empty.

valueString

The value of the parameter will undergo a "UTF-8" character encoding transformation upon being added to the queue. value must not be null.

Returns
TypeDescription
TaskOptions

payload(byte[] 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.

Parameter
NameDescription
payloadbyte[]

The bytes representing the paylaod.

Returns
TypeDescription
TaskOptions

TaskOptions object for chaining.

payload(byte[] payload, String contentType)

public TaskOptions payload(byte[] payload, String contentType)

Set the payload with the given content type.

Parameters
NameDescription
payloadbyte[]

The bytes representing the paylaod.

contentTypeString

The content-type of the bytes.

Returns
TypeDescription
TaskOptions

TaskOptions object for chaining.

payload(DeferredTask deferredTask)

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 Method is not PULL, the content type will be set to DeferredTaskContext#RUNNABLE_TASK_CONTENT_TYPE, the method will be forced to 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.

Parameter
NameDescription
deferredTaskDeferredTask

The object to serialize into the payload.

Returns
TypeDescription
TaskOptions

payload(String 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.

Parameter
NameDescription
payloadString

The String to be used.

Returns
TypeDescription
TaskOptions

TaskOptions object for chaining.

payload(String payload, String charset)

public TaskOptions payload(String payload, String charset)

Sets the payload from a String given a specific character set.

Parameters
NameDescription
payloadString
charsetString
Returns
TypeDescription
TaskOptions

removeHeader(String headerName)

public TaskOptions removeHeader(String headerName)

Remove all headers with the given name.

Parameter
NameDescription
headerNameString
Returns
TypeDescription
TaskOptions

removeParam(String paramName)

public TaskOptions removeParam(String paramName)

Remove all parameters with the given name.

Parameter
NameDescription
paramNameString

Name of the parameter. Must not be null or empty.

Returns
TypeDescription
TaskOptions

retryOptions(RetryOptions retryOptions)

public TaskOptions retryOptions(RetryOptions retryOptions)

Sets retry options for this task. Retry Options must be built with RetryOptions.Builder.

Parameter
NameDescription
retryOptionsRetryOptions
Returns
TypeDescription
TaskOptions

tag(byte[] tag)

public TaskOptions tag(byte[] tag)

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

Parameter
NameDescription
tagbyte[]
Returns
TypeDescription
TaskOptions

tag(String tag)

public TaskOptions tag(String tag)

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

Parameter
NameDescription
tagString
Returns
TypeDescription
TaskOptions

taskName(String taskName)

public TaskOptions taskName(String taskName)

Sets the task name.

Parameter
NameDescription
taskNameString
Returns
TypeDescription
TaskOptions

toString()

public String toString()
Returns
TypeDescription
String
Overrides

url(String url)

public TaskOptions url(String url)

Set the URL.

Default value is null.

Parameter
NameDescription
urlString

String containing URL.

Returns
TypeDescription
TaskOptions