Task

All Superinterfaces:

Cancellable, Promise<T>

All Known Subinterfaces:

ParTask<T>, Tuple2Task<T1,T2>, Tuple3Task<T1,T2,T3>, Tuple4Task<T1,T2,T3,T4>, Tuple5Task<T1,T2,T3,T4,T5>, Tuple6Task<T1,T2,T3,T4,T5,T6>, Tuple7Task<T1,T2,T3,T4,T5,T6,T7>, Tuple8Task<T1,T2,T3,T4,T5,T6,T7,T8>, Tuple9Task<T1,T2,T3,T4,T5,T6,T7,T8,T9>

All Known Implementing Classes:

ActionTask, AsyncCallableTask, BaseTask, CallableTask, Par2Task, Par3Task, Par4Task, Par5Task, Par6Task, Par7Task, Par8Task, Par9Task, Tuple2TaskDelegate, Tuple3TaskDelegate, Tuple4TaskDelegate, Tuple5TaskDelegate, Tuple6TaskDelegate, Tuple7TaskDelegate, Tuple8TaskDelegate, Tuple9TaskDelegate
```
public interface Task<T>
extends Promise<T>, Cancellable
```
A task represents a deferred execution that also contains its resulting value. In addition, tasks include tracing information that can be used with various trace printers.
Tasks should be run using an Engine. They should not be run directly.

Author:

Chris Pettitt (cpettitt@linkedin.com), Jaroslaw Odzga (jodzga@linkedin.com)

Field Summary

Fields
Modifier and Type Field and Description

static org.slf4j.Logger LOGGER

Fields
Modifier and Type	Field and Description
`static org.slf4j.Logger`	`LOGGER`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`static Task<java.lang.Void>`	`action(Action action)` Equivalent to `action("action", action)`.
`static Task<java.lang.Void>`	`action(java.lang.String desc, Action action)` Creates a new task that have a value of type `Void`.
`default Task<T>`	`andThen(Consumer1<? super T> consumer)` Equivalent to `andThen("andThen", consumer)`.
`default Task<T>`	`andThen(java.lang.String desc, Consumer1<? super T> consumer)` Creates a new task which applies a consumer to the result of this task and completes with a result of this task.
`default <R> Task<R>`	`andThen(java.lang.String desc, Task<R> task)` Creates a new task which runs given task after completion of this task and completes with a result of that task.
`default <R> Task<R>`	`andThen(Task<R> task)` Equivalent to `andThen("andThen", task)`.
`default <R> Task<R>`	`apply(java.lang.String desc, PromisePropagator<T,R> propagator)`
`static <T> Task<T>`	`async(java.util.concurrent.Callable<Promise<? extends T>> callable)` Equivalent to `async("async", callable)`.
`static <T> Task<T>`	`async(Function1<Context,Promise<? extends T>> func)` Equivalent to `async("async", func)`.
`static <T> Task<T>`	`async(java.lang.String name, java.util.concurrent.Callable<Promise<? extends T>> callable)` Creates a new task from a callable that returns a `Promise`.
`static <T> Task<T>`	`async(java.lang.String name, Function1<Context,Promise<? extends T>> func)` Creates a new task from a callable that returns a `Promise`.
`static <T> Task<T>`	`blocking(java.util.concurrent.Callable<? extends T> callable, java.util.concurrent.Executor executor)` Equivalent to `blocking("blocking", callable, executor)`.
`static <T> Task<T>`	`blocking(java.lang.String name, java.util.concurrent.Callable<? extends T> callable, java.util.concurrent.Executor executor)` This method provides a way to create an asynchronous task from a blocking or long running callables like JDBC requests.
`static <T> Task<T>`	`callable(java.util.concurrent.Callable<? extends T> callable)` Equivalent to `callable("callable", callable)`.
`static <T> Task<T>`	`callable(java.lang.String name, java.util.concurrent.Callable<? extends T> callable)` Creates a new task that's value will be set to the value returned from the supplied callable.
`void`	`contextRun(Context context, Task<?> parent, java.util.Collection<Task<?>> predecessors)` Attempts to run the task with the given context.
`static <T> Task<T>`	`failure(java.lang.String desc, java.lang.Throwable failure)` Creates a new task that will be fail with given exception when it is executed.
`static <T> Task<T>`	`failure(java.lang.Throwable failure)` Equivalent to `failure("failure", failure)`.
`default <R> Task<R>`	`flatMap(Function1<? super T,Task<R>> func)` Equivalent to `flatMap("flatMap", func)`.
`default <R> Task<R>`	`flatMap(java.lang.String desc, Function1<? super T,Task<R>> func)` Creates a new task by applying a function to the successful result of this task and returns the result of a function as the new task.
`static <R> Task<R>`	`flatten(java.lang.String desc, Task<Task<R>> task)` Converts `Task<Task<R>>` into `Task<R>`.
`static <R> Task<R>`	`flatten(Task<Task<R>> task)` Equivalent to `flatten("flatten", task)`.
`java.lang.Long`	`getId()` Unique identifier of the task.
`java.lang.String`	`getName()` Returns the name of this task.
`int`	`getPriority()` Returns the priority for this task.
`ShallowTrace`	`getShallowTrace()` Returns the ShallowTrace for this task.
`ShallowTraceBuilder`	`getShallowTraceBuilder()`
`Trace`	`getTrace()` Returns the Trace for this task.
`TraceBuilder`	`getTraceBuilder()`
`default <R> Task<R>`	`map(Function1<? super T,? extends R> func)` Equivalent to `map("map", func)`.
`default <R> Task<R>`	`map(java.lang.String desc, Function1<? super T,? extends R> func)` Creates a new task by applying a function to the successful result of this task.
`default Task<T>`	`onFailure(Consumer1<java.lang.Throwable> consumer)` Equivalent to `onFailure("onFailure", consumer)`.
`default Task<T>`	`onFailure(java.lang.String desc, Consumer1<java.lang.Throwable> consumer)` Creates a new task which applies a consumer to the exception this task may fail with.
`static <T1,T2> Tuple2Task<T1,T2>`	`par(Task<T1> task1, Task<T2> task2)` Creates a new task that will run given tasks in parallel.
`static <T1,T2,T3> Tuple3Task<T1,T2,T3>`	`par(Task<T1> task1, Task<T2> task2, Task<T3> task3)` Creates a new task that will run given tasks in parallel.
`static <T1,T2,T3,T4> Tuple4Task<T1,T2,T3,T4>`	`par(Task<T1> task1, Task<T2> task2, Task<T3> task3, Task<T4> task4)` Creates a new task that will run given tasks in parallel.
`static <T1,T2,T3,T4,T5> Tuple5Task<T1,T2,T3,T4,T5>`	`par(Task<T1> task1, Task<T2> task2, Task<T3> task3, Task<T4> task4, Task<T5> task5)` Creates a new task that will run given tasks in parallel.
`static <T1,T2,T3,T4,T5,T6> Tuple6Task<T1,T2,T3,T4,T5,T6>`	`par(Task<T1> task1, Task<T2> task2, Task<T3> task3, Task<T4> task4, Task<T5> task5, Task<T6> task6)` Creates a new task that will run given tasks in parallel.
`static <T1,T2,T3,T4,T5,T6,T7> Tuple7Task<T1,T2,T3,T4,T5,T6,T7>`	`par(Task<T1> task1, Task<T2> task2, Task<T3> task3, Task<T4> task4, Task<T5> task5, Task<T6> task6, Task<T7> task7)` Creates a new task that will run given tasks in parallel.
`static <T1,T2,T3,T4,T5,T6,T7,T8> Tuple8Task<T1,T2,T3,T4,T5,T6,T7,T8>`	`par(Task<T1> task1, Task<T2> task2, Task<T3> task3, Task<T4> task4, Task<T5> task5, Task<T6> task6, Task<T7> task7, Task<T8> task8)` Creates a new task that will run given tasks in parallel.
`static <T1,T2,T3,T4,T5,T6,T7,T8,T9> Tuple9Task<T1,T2,T3,T4,T5,T6,T7,T8,T9>`	`par(Task<T1> task1, Task<T2> task2, Task<T3> task3, Task<T4> task4, Task<T5> task5, Task<T6> task6, Task<T7> task7, Task<T8> task8, Task<T9> task9)` Creates a new task that will run given tasks in parallel.
`default Task<T>`	`recover(Function1<java.lang.Throwable,T> func)` Equivalent to `recover("recover", func)`.
`default Task<T>`	`recover(java.lang.String desc, Function1<java.lang.Throwable,T> func)` Creates a new task that will handle failure of this task.
`default Task<T>`	`recoverWith(Function1<java.lang.Throwable,Task<T>> func)` Equivalent to `recoverWith("recoverWith", func)`.
`default Task<T>`	`recoverWith(java.lang.String desc, Function1<java.lang.Throwable,Task<T>> func)` Creates a new task that will handle failure of this task.
`boolean`	`setPriority(int priority)` Overrides the priority for this task.
`void`	`setTraceValueSerializer(java.util.function.Function<T,java.lang.String> serializer)` Allows adding `String` representation of value computed by this task to trace.
`default Task<T>`	`shareable()` Creates a new task that can be safely shared within a plan or between multiple plans.
`default Task<Try<T>>`	`toTry()` Equivalent to `toTry("toTry")`.
`default Task<Try<T>>`	`toTry(java.lang.String desc)` This method transforms `Task<T>` into `Task<Try<T>>`.
`default <R> Task<R>`	`transform(Function1<Try<T>,Try<R>> func)` Equivalent to `transform("transform", func)`.
`default <R> Task<R>`	`transform(java.lang.String desc, Function1<Try<T>,Try<R>> func)` Creates a new task that applies a transformation to the result of this task.
`static <T> Task<T>`	`value(java.lang.String desc, T value)` Creates a new task that will be resolved with given value when it is executed.
`static <T> Task<T>`	`value(T value)` Equivalent to `value("value", value)`.
`default Task<T>`	`withSideEffect(Function1<? super T,Task<?>> func)` Equivalent to `withSideEffect("sideEffect", func)`.
`default Task<T>`	`withSideEffect(java.lang.String desc, Function1<? super T,Task<?>> func)` Creates a new task that will run another task as a side effect once the primary task completes successfully.
`default Task<T>`	`withTimeout(long time, java.util.concurrent.TimeUnit unit)` Creates a new task that has a timeout associated with it.

Methods inherited from interface com.linkedin.parseq.promise.Promise
addListener, await, await, get, getError, getOrDefault, isDone, isFailed

Methods inherited from interface com.linkedin.parseq.Cancellable
cancel

Field Detail
- LOGGER
```
static final org.slf4j.Logger LOGGER
```

Method Detail

getName
```
java.lang.String getName()
```
Returns the name of this task.

Returns:

the name of this task

getPriority
```
int getPriority()
```
Returns the priority for this task.

Returns:

the priority for this task.

setPriority
```
boolean setPriority(int priority)
```
Overrides the priority for this task. Higher priority tasks will be executed before lower priority tasks in the same context. In most cases, the default priority is sufficient.
The default priority is 0. Use priority < 0 to make a task lower priority and priority > 0 to make a task higher priority.
If the task has already started execution the priority cannot be changed.

Parameters:

priority - the new priority for the task.

Returns:

true if the priority was set; otherwise false.

Throws:

java.lang.IllegalArgumentException - if the priority is out of range

See Also:

Priority

setTraceValueSerializer
```
void setTraceValueSerializer(java.util.function.Function<T,java.lang.String> serializer)
```
Allows adding String representation of value computed by this task to trace. When this task is finished successfully, value will be converted to String using given serializer and it will be included in this task's trace.
Failures are automatically included in a trace.

Parameters:

serializer - serialized used for converting result of this task to String that will be included in this task's trace.

contextRun
```
void contextRun(Context context,
                Task<?> parent,
                java.util.Collection<Task<?>> predecessors)
```
Attempts to run the task with the given context. This method is reserved for use by Engine and Context.

Parameters:

context - the context to use while running this step

parent - the parent of this task

predecessors - that lead to the execution of this task

getShallowTrace
```
ShallowTrace getShallowTrace()
```
Returns the ShallowTrace for this task. The ShallowTrace will be a point-in-time snapshot and may change over time until the task is completed.

Returns:

the ShallowTrace related to this task

getTrace
```
Trace getTrace()
```
Returns the Trace for this task. The Trace will be a point-in-time snapshot and may change over time until the task is completed.

Returns:

the Trace related to this task

getId
```
java.lang.Long getId()
```
Unique identifier of the task.

Returns:

unique identifier of the task.

getShallowTraceBuilder

ShallowTraceBuilder getShallowTraceBuilder()

getTraceBuilder
```
TraceBuilder getTraceBuilder()
```

apply

default <R> Task<R> apply(java.lang.String desc,
                          PromisePropagator<T,R> propagator)

map

default <R> Task<R> map(java.lang.String desc,
                        Function1<? super T,? extends R> func)

Creates a new task by applying a function to the successful result of this task. Returned task will complete with value calculated by a function.

 Task <String> hello = Task.value("Hello World");

 // this task will complete with value 11
 Task <Integer> length = hello.map("length", s  -> s.length());

If this task is completed with an exception then the new task will also complete with that exception.

  Task <String> failing = Task.callable("hello", ()  -> {
    return "Hello World".substring(100);
  });

  // this task will fail with java.lang.StringIndexOutOfBoundsException
  Task <Integer> length = failing.map("length", s  -> s.length());

Type Parameters:: R - return type of function func
Parameters:: desc - description of a mapping function, it will show up in a trace; func - function to be applied to successful result of this task.
Returns:: a new task which will apply given function on result of successful completion of this task

map

default <R> Task<R> map(Function1<? super T,? extends R> func)

Equivalent to map("map", func).

See Also:: map(String, Function1)

flatMap
```
default <R> Task<R> flatMap(java.lang.String desc,
                            Function1<? super T,Task<R>> func)
```
Creates a new task by applying a function to the successful result of this task and returns the result of a function as the new task. Returned task will complete with value calculated by a task returned by the function.
```
  Task <URI> url = Task.value("uri", URI.create("http://linkedin.com"));

  // this task will complete with contents of a LinkedIn homepage
  // assuming fetch(u) fetches contents given by a URI
  Task <String> homepage = url.flatMap("fetch", u  -> fetch(u));
 
```
If this task is completed with an exception then the new task will also contain that exception.
```
  Task <URI> url = Task.callable("uri", ()  -> URI.create("not a URI"));

  // this task will fail with java.lang.IllegalArgumentException
  Task <String> homepage = url.flatMap("fetch", u  -> fetch(u));
 
```
Type Parameters:

R - return type of function func

Parameters:

desc - description of a mapping function, it will show up in a trace

func - function to be applied to successful result of this task which returns new task to be executed

Returns:

a new task which will apply given function on result of successful completion of this task to get instance of a task which will be executed next

flatMap
```
default <R> Task<R> flatMap(Function1<? super T,Task<R>> func)
```
Equivalent to flatMap("flatMap", func).

See Also:

flatMap(String, Function1)

withSideEffect
```
default Task<T> withSideEffect(java.lang.String desc,
                               Function1<? super T,Task<?>> func)
```
Creates a new task that will run another task as a side effect once the primary task completes successfully. The properties of side effect task are:
- The side effect task will not be run if the primary task has not run e.g. due to failure or cancellation.
- The side effect does not affect returned task. It means that failure of side effect task is not propagated to returned task.
- The returned task is marked done once this task completes, even if the side effect has not been run yet.
The side effect task is useful in situations where operation (side effect) should continue to run in the background but it's execution is not required for the main computation. An example might be updating cache once data has been retrieved from the main source.
```
  Task <Long> id = Task.value("id", 1223L);

  // this task will be completed as soon as user name is fetched
  // by fetch() method and will not fail even if updateMemcache() fails
  Task <String> userName = id.flatMap("fetch", u  -> fetch(u))
      .withSideEffect("update memcache", u  -> updateMemcache(u));
 
```
Parameters:

desc - description of a side effect, it will show up in a trace

func - function to be applied on result of successful completion of this task to get side effect task

Returns:

a new task that will run side effect task specified by given function upon succesful completion of this task

withSideEffect
```
default Task<T> withSideEffect(Function1<? super T,Task<?>> func)
```
Equivalent to withSideEffect("sideEffect", func).

See Also:

withSideEffect(String, Function1)

shareable
```
default Task<T> shareable()
```
Creates a new task that can be safely shared within a plan or between multiple plans. Cancellation of returned task will not cause cancellation of the original task.
Sharing tasks within a plan or among different plans is generally not safe because task can be cancelled if it's parent has been resolved. Imagine situation where fetch task that fetches data from a remote server is shared among few plans. If one of those plans times out then all started tasks that belong to it will be automatically cancelled. This means that fetch may also be cancelled and this can affect other plans that are still running. Similar situation can happen even within one plan if task is used multiple times.
In example below google task has timeout 10ms what causes entire plan to fail and as a consequence all tasks that belong to it that have been started - in this case bing task. This may be problematic if bing task is used somewhere else.
```
 final Task <Response> google = HttpClient.get("http://google.com").task();
 final Task <Response> bing = HttpClient.get("http://bing.com").task();

 // this task will fail because google task will timeout after 10ms
 // as a consequence bing task will be cancelled
 final Task both = Task.par(google.withTimeout(10, TimeUnit.MILLISECONDS), bing);
 
```
shareable method solves above problem. Task returned by shareable() can be can be cancelled without affecting original task.
```
 final Task <Response> google = HttpClient.get("http://google.com").task();
 final Task <Response> bing = HttpClient.get("http://bing.com").task();

 // this task will fail because wrapped google task will timeout after 10ms
 // notice however that original googel and bing tasks were not cancelled
   final Task both =
       Task.par(google.shareable().withTimeout(10, TimeUnit.MILLISECONDS), bing.shareable());
 
```
Returns:

new task that can be safely shared within a plan or between multiple plans. Cancellation of returned task will not cause cancellation of the original task.

andThen

default Task<T> andThen(java.lang.String desc,
                        Consumer1<? super T> consumer)

Creates a new task which applies a consumer to the result of this task and completes with a result of this task. It is used in situations where consumer needs to be called after successful completion of this task.

  Task <String> hello = Task.value("greeting", "Hello World");

  // this task will print "Hello World"
  Task <String> sayHello = hello.andThen("say", System.out::println);

If this task fails then consumer will not be called and failure will be propagated to task returned by this method.

  Task <String> failing = Task.callable("greeting", ()  -> {
    return "Hello World".substring(100);
  });

  // this task will fail with java.lang.StringIndexOutOfBoundsException
  Task <String> sayHello = failing.andThen("say", System.out::println);

Parameters:: desc - description of a consumer, it will show up in a trace; consumer - consumer of a value returned by this task
Returns:: a new task which will complete with result of this task

andThen
```
default Task<T> andThen(Consumer1<? super T> consumer)
```
Equivalent to andThen("andThen", consumer).

See Also:

andThen(String, Consumer1)

andThen
```
default <R> Task<R> andThen(java.lang.String desc,
                            Task<R> task)
```
Creates a new task which runs given task after completion of this task and completes with a result of that task. Task passed in as a parameter will run even if this task completes fails.
```
  // task that processes payment
  Task <PaymentStatus> processPayment = processPayment(...);

  // task that ships product
  Task <ShipmentInfo> shipProduct = shipProduct(...);

  Task <ShipmentInfo> shipAfterPayment =
      processPayment.andThen("shipProductAterPayment", shipProduct);
 
```
Type Parameters:

R - return type of the task

Parameters:

desc - description of a task, it will show up in a trace

task - task which will be executed after completion of this task

Returns:

a new task which will run given task after completion of this task

andThen
```
default <R> Task<R> andThen(Task<R> task)
```
Equivalent to andThen("andThen", task).

See Also:

andThen(String, Task)

recover
```
default Task<T> recover(java.lang.String desc,
                        Function1<java.lang.Throwable,T> func)
```
Creates a new task that will handle failure of this task. Early completion due to cancellation is not considered to be a failure. If this task completes successfully, then recovery function is not called.
```
 // this method return task which asynchronously retrieves Person by id
 Task <Person> fetchPerson(Long id) {
 (...)
 }

 // this task will fetch Person object and transform it into  "<first name> <last name>"
 // if fetching Person failed then form  "Member <id>" will be return
 Task <String> userName = fetchPerson(id)
      .map("toSignature", p  -> p.getFirstName() + " " + p.getLastName())
      .recover(e  -> "Member " + id);
 
```
Note that task cancellation is not considered to be a failure. If this task has been cancelled then task returned by this method will also be cancelled and recovery function will not be applied.
Parameters:

desc - description of a recovery function, it will show up in a trace

func - recovery function which can complete task with a value depending on failure of this task

Returns:

a new task which can recover from failure of this task

recover
```
default Task<T> recover(Function1<java.lang.Throwable,T> func)
```
Equivalent to recover("recover", func).

See Also:

recover(String, Function1)

onFailure
```
default Task<T> onFailure(java.lang.String desc,
                          Consumer1<java.lang.Throwable> consumer)
```
Creates a new task which applies a consumer to the exception this task may fail with. It is used in situations where consumer needs to be called after failure of this task. Result of task returned by this method will be exactly the same as result of this task.
```
  Task <String> failing = Task.callable("greeting", ()  -> {
    return "Hello World".substring(100);
  });

  // this task will print out java.lang.StringIndexOutOfBoundsException
  // and complete with that exception as a reason for failure
  Task <String> sayHello = failing.onFailure("printFailure", System.out::println);
 
```
If this task completes successfully then consumer will not be called.
```
  Task <String> hello = Task.value("greeting", "Hello World");

  // this task will return "Hello World"
  Task <String> sayHello = hello.onFailure(System.out::println);
 
```
Exceptions thrown by a consumer will be ignored.
Note that task cancellation is not considered to be a failure. If this task has been cancelled then task returned by this method will also be cancelled and consumer will not be called.
Parameters:

desc - description of a consumer, it will show up in a trace

consumer - consumer of an exception this task failed with

Returns:

a new task which will complete with result of this task

onFailure
```
default Task<T> onFailure(Consumer1<java.lang.Throwable> consumer)
```
Equivalent to onFailure("onFailure", consumer).

See Also:

onFailure(String, Consumer1)

toTry
```
default Task<Try<T>> toTry(java.lang.String desc)
```
This method transforms Task<T> into Task<Try<T>>. It allows explicit handling of failures by returning potential exceptions as a result of task execution. Task returned by this method will always complete successfully unless it has been cancelled. If this task completes successfully then return task will be completed with result value wrapped with Success.
```
  Task <String> hello = Task.value("greeting", "Hello World");

  // this task will complete with Success("Hello World")
  Task <Try<String>> helloTry = hello.toTry("try");
 
```
If this task is completed with an exception then the returned task will be completed with an exception wrapped with Failure.
```
  Task <String> failing = Task.callable("greeting", ()  -> {
      return "Hello World".substring(100);
  });

  // this task will complete successfully with Failure(java.lang.StringIndexOutOfBoundsException)
  Task <Try<String>> failingTry = failing.toTry("try");
 
```
All failures are automatically propagated and it is usually enough to use recover or recoverWith.
Note that task cancellation is not considered to be a failure. If this task has been cancelled then task returned by this method will also be cancelled.
Parameters:

desc - description of a consumer, it will show up in a trace

Returns:

a new task that will complete successfully with the result of this task

See Also:

Try, recover, recoverWith, CancellationException

toTry
```
default Task<Try<T>> toTry()
```
Equivalent to toTry("toTry").

See Also:

toTry(String)

transform
```
default <R> Task<R> transform(java.lang.String desc,
                              Function1<Try<T>,Try<R>> func)
```
Creates a new task that applies a transformation to the result of this task. This method allows handling both successful completion and failure at the same time.
```
 Task <Integer> num = ...

 // this task will complete with either complete successfully
 // with String representation of num or fail with  MyLibException
 Task <String> text = num.transform("toString", t  -> {
   if (t.isFailed()) {
     return Failure.of(new MyLibException(t.getError()));
   } else {
     return Success.of(String.valueOf(t.get()));
   }
 });
 
```
Note that task cancellation is not considered to be a failure. If this task has been cancelled then task returned by this method will also be cancelled and transformation will not be applied.
Type Parameters:

R - type parameter of function func return Try

Parameters:

desc - description of a consumer, it will show up in a trace

func - a transformation to be applied to the result of this task

Returns:

a new task that will apply a transformation to the result of this task

See Also:

Try

transform
```
default <R> Task<R> transform(Function1<Try<T>,Try<R>> func)
```
Equivalent to transform("transform", func).

See Also:

transform(String, Function1)

recoverWith
```
default Task<T> recoverWith(java.lang.String desc,
                            Function1<java.lang.Throwable,Task<T>> func)
```
Creates a new task that will handle failure of this task. Early completion due to cancellation is not considered to be a failure. If this task completes successfully, then recovery function is not called.
```
 // this method return task which asynchronously retrieves Person by id from cache
 Task <Person> fetchFromCache(Long id) {
 (...)
 }

 // this method return task which asynchronously retrieves Person by id from DB
 Task <Person> fetchFromDB(Long id) {
 (...)
 }

 // this task will try to fetch Person from cache and
 // if it fails for any reason it will attempt to fetch from DB
 Task <Person> user = fetchFromCache(id).recoverWith(e  -> fetchFromDB(id));
 
```
If recovery task fails then returned task is completed with that failure.
Note that task cancellation is not considered to be a failure. If this task has been cancelled then task returned by this method will also be cancelled and recovery function will not be applied.
Parameters:

desc - description of a recovery function, it will show up in a trace

func - recovery function provides task which will be used to recover from failure of this task

Returns:

a new task which can recover from failure of this task

recoverWith
```
default Task<T> recoverWith(Function1<java.lang.Throwable,Task<T>> func)
```
Equivalent to recoverWith("recoverWith", func).

See Also:

recoverWith(String, Function1)

withTimeout
```
default Task<T> withTimeout(long time,
                            java.util.concurrent.TimeUnit unit)
```
Creates a new task that has a timeout associated with it. If this task finishes before the timeout occurs then returned task will be completed with the value of this task. If this task does not complete in the given time then returned task will fail with a TimeoutException as a reason of failure and this task will be cancelled.
```
 final Task google = HttpClient.get("http://google.com").task()
     .withTimeout(10, TimeUnit.MILLISECONDS);
 
```
Parameters:

time - the time to wait before timing out

unit - the units for the time

Returns:

the new task with a timeout

flatten
```
static <R> Task<R> flatten(java.lang.String desc,
                           Task<Task<R>> task)
```
Converts Task<Task<R>> into Task<R>.

Type Parameters:

R - return type of nested task

Parameters:

desc - description that will show up in a trace

task - task to be flattened

Returns:

flattened task

flatten
```
static <R> Task<R> flatten(Task<Task<R>> task)
```
Equivalent to flatten("flatten", task).

See Also:

flatten(String, Task)

action
```
static Task<java.lang.Void> action(java.lang.String desc,
                                   Action action)
```
Creates a new task that have a value of type Void. Because the returned task returns no value, it is typically used to produce side effects. It is not appropriate for long running or blocking actions. If action is long running or blocking use blocking method.
```
 // this task will print "Hello" on standard output
 Task <Void> task = Task.action("greeting", ()  -> System.out.println("Hello"));
 
```
Returned task will fail if Action passed in as a parameter throws an exception.
```
 // this task will fail with java.lang.ArithmeticException
 Task <Void> task = Task.action("division", ()  -> System.out.println(2 / 0));
 
```
Parameters:

desc - a description the action, it will show up in a trace

action - the action that will be executed when the task is run

Returns:

the new task that will execute the action

action
```
static Task<java.lang.Void> action(Action action)
```
Equivalent to action("action", action).

See Also:

action(String, Action)

value
```
static <T> Task<T> value(java.lang.String desc,
                         T value)
```
Creates a new task that will be resolved with given value when it is executed. Note that this task is not initially completed.

Type Parameters:

T - type of the value

Parameters:

desc - a description of the value, it will show up in a trace

value - a value the task will be resolved with

Returns:

new task that will be resolved with given value when it is executed

value
```
static <T> Task<T> value(T value)
```
Equivalent to value("value", value).

See Also:

value(String, Object)

failure
```
static <T> Task<T> failure(java.lang.String desc,
                           java.lang.Throwable failure)
```
Creates a new task that will be fail with given exception when it is executed. Note that this task is not initially completed.

Type Parameters:

T - type parameter of the returned task

Parameters:

desc - a description of the failure, it will show up in a trace

failure - a failure the task will fail with

Returns:

new task that will fail with given failure when it is executed

failure
```
static <T> Task<T> failure(java.lang.Throwable failure)
```
Equivalent to failure("failure", failure).

See Also:

failure(String, Throwable)

callable
```
static <T> Task<T> callable(java.lang.String name,
                            java.util.concurrent.Callable<? extends T> callable)
```
Creates a new task that's value will be set to the value returned from the supplied callable. This task is useful when doing basic computation that does not require asynchrony. It is not appropriate for long running or blocking callables. If callable is long running or blocking use blocking method.
```
 // this task will complete with  String representing current time
 Task <String> task = Task.callable("current time", ()  -> new Date().toString());
 
```
Returned task will fail if callable passed in as a parameter throws an exception.
```
 // this task will fail with java.lang.ArithmeticException
 Task <Integer> task = Task.callable("division", ()  -> 2 / 0);
 
```
Type Parameters:

T - the type of the return value for this task

Parameters:

name - a name that describes the task, it will show up in a trace

callable - the callable to execute when this task is run

Returns:

the new task that will invoke the callable and complete with it's result

callable
```
static <T> Task<T> callable(java.util.concurrent.Callable<? extends T> callable)
```
Equivalent to callable("callable", callable).

See Also:

callable(String, Callable)

async

static <T> Task<T> async(java.lang.String name,
                         java.util.concurrent.Callable<Promise<? extends T>> callable)

Creates a new task from a callable that returns a Promise. This method is mainly used to integrate ParSeq with 3rd party asynchronous libraries. It should not be used in order to compose or manipulate existing tasks. The following example shows how to integrate AsyncHttpClient with ParSeq.

  // Creates a task that asynchronouslyexecutes given HTTP request
  // and will complete with HTTP response. It uses asyncHttpRequest()
  // method as a lambda of shape: ThrowableCallable <Promise<Response>>.
  Task <Response> httpTask(final Request request) {
    return Task.async(()  -> asyncHttpRequest(request), false);
  }

  // This method uses HTTP_CLIENT to make asynchronous
  // request and returns a Promise that will be resolved once
  // the HTTP request is completed.
  Promise <Response> asyncHttpRequest(final Request request) {

    // Create a settable promise. We'll use this to signal completion of this
    // task once the response is received from the HTTP client.
    final SettablePromise <Response> promise = Promises.settable();

    // Send the request and register a callback with the client that will
    // set the response on our promise.
    HTTP_CLIENT.prepareRequest(request).execute(new AsyncCompletionHandler <Response>() {

       @Override
      public Response onCompleted(final Response response) throws Exception {
        // At this point the HTTP client has given us the HTTP response
        // asynchronously. We set the response value on our promise to indicate
        // that the task is complete.
        promise.done(response);
        return response;
      }

       @Override
      public void onThrowable(final Throwable t) {
        // If there was an error then we should set it on the promise.
        promise.fail(t);
      }
    });

    // Return the promise. It may or may not be
    // resolved by the time we return this promise.
    return promise;
  }

This method is not appropriate for long running or blocking callables. If callable is long running or blocking use blocking method.

Type Parameters:: T - the type of the return value for this task
Parameters:: name - a name that describes the task, it will show up in a trace; callable - a callable to execute when this task is run, it must return a Promise<T>
Returns:: a new task that will invoke the callable and complete with result returned by a Promise returned by it
See Also:: Promise

async

static <T> Task<T> async(java.util.concurrent.Callable<Promise<? extends T>> callable)

Equivalent to async("async", callable).

See Also:: async(String, Callable)

async
```
static <T> Task<T> async(java.lang.String name,
                         Function1<Context,Promise<? extends T>> func)
```
Creates a new task from a callable that returns a Promise. This method is mainly used to build functionality that has not been provided by ParSeq API. It gives access to Context which allows scheduling tasks in current plan. This method almost never should be necessary. If you feel the need to use this method, please contact ParSeq team to help us improve our API.

Type Parameters:

T - the type of the return value for this task

Parameters:

name - a name that describes the task, it will show up in a trace

func - a function to execute when this task is run, it must return a Promise<T>

Returns:

a new task that will invoke the function and complete with result returned by a Promise returned by it

See Also:

Context, Promise

async

static <T> Task<T> async(Function1<Context,Promise<? extends T>> func)

Equivalent to async("async", func).

See Also:: async(String, Function1)

blocking
```
static <T> Task<T> blocking(java.lang.String name,
                            java.util.concurrent.Callable<? extends T> callable,
                            java.util.concurrent.Executor executor)
```
This method provides a way to create an asynchronous task from a blocking or long running callables like JDBC requests. Unlike with tasks created with all other methods a callable passed as a parameter is not executed on ParSeq's thread but instead it is executed on specified Executor. It means that callable does not get any special memory consistency guarantees and should not attempt to use shared state.

Type Parameters:

T - the type of the return value for this task

Parameters:

name - a name that describes the task, it will show up in a trace

callable - a callable that will provide result

executor - Executor that will be used to run the callable

Returns:

a new task that will submit the callable to given executor and complete with result returned by that callable

blocking

static <T> Task<T> blocking(java.util.concurrent.Callable<? extends T> callable,
                            java.util.concurrent.Executor executor)

Equivalent to blocking("blocking", callable, executor).

See Also:: blocking(String, Callable, Executor)

par

static <T1,T2> Tuple2Task<T1,T2> par(Task<T1> task1,
                                     Task<T2> task2)

Creates a new task that will run given tasks in parallel. Returned task will be resolved with results of all tasks as soon as all of them has been completed successfully.

  // this task will asynchronously fetch user and company in parallel
  // and create signature in a form  "<first name> <last name> working for <company>"
  Task <String> signature =
      Task.par(fetchUser(userId), fetchCompany(companyId))
        .map((user, company)  ->
          user.getFirstName() + user.getLastName() + " working for " + company.getName());