com.uber.cadence.workflow

Interface Promise<V>

All Known Subinterfaces:

CompletablePromise<V>

public interface Promise<V>

Contains result of an asynchronous computation. Similar to Future with the following differences:

• Can be used only inside a Cadence workflow code. Use Future and its derivatives to implement activities and workflow starting and querying code.
• get() doesn't throw InterruptedException. The only way to unblock get() is to complete the Promise
• Exceptions passed to CompletablePromise.completeExceptionally(RuntimeException) are not wrapped. It is possible as CompletablePromise.completeExceptionally(RuntimeException) accepts only runtime exceptions. So wrapping must be done by the caller of that method.
• Promise doesn't directly supports cancellation. Use CancellationScope to cancel and handle cancellations. The pattern is that a cancelled operation completes its Promise with CancellationException when cancelled.
• #handle(Func2) and similar callback operations do not allow blocking calls inside functions

Method Summary

Modifier and Type	Method and Description
static <U> Promise<java.util.List<U>>	allOf(java.util.Collection<Promise<U>> promises) Returns Promise that becomes completed when all promises in the collection are completed.
static Promise<java.lang.Void>	allOf(Promise<?>... promises) Returns Promise that becomes completed when all arguments are completed.
static Promise<java.lang.Object>	anyOf(java.lang.Iterable<Promise<?>> promises) Returns Promise that becomes completed when any of the arguments is completed.
static Promise<java.lang.Object>	anyOf(Promise<?>... promises) Returns Promise that becomes completed when any of the arguments is completed.
Promise<V>	exceptionally(Functions.Func1<java.lang.Throwable,? extends V> fn) Returns a new Promise that, when this promise completes exceptionally, is executed with this promise's exception as the argument to the supplied function.
V	get() Waits if necessary for the computation to complete or fail, and then returns its result.
V	get(long timeout, java.util.concurrent.TimeUnit unit) Waits if necessary for at most the given time for the computation to complete, and then returns its result, if available.
V	get(long timeout, java.util.concurrent.TimeUnit unit, V defaultValue) Waits if necessary for at most the given time for the computation to complete, and then retrieves its result, if available.
V	get(V defaultValue) Waits if necessary for the computation to complete or fail, and then returns its result or defaultValue in case of failure.
java.lang.RuntimeException	getFailure() Waits if necessary for the computation to complete or fail, and then returns the failure or null.
<U> Promise<U>	handle(Functions.Func2<? super V,java.lang.RuntimeException,? extends U> fn) Returns Promise that contains a result of a function.
boolean	isCompleted() Returns true if this promise is completed.
<U> Promise<U>	thenApply(Functions.Func1<? super V,? extends U> fn) Returns Promise that contains a result of a function.
<U> Promise<U>	thenCompose(Functions.Func1<? super V,? extends Promise<U>> fn) Returns a new Promise that, when this promise completes normally, is executed with this promise as the argument to the supplied function.

Method Detail

isCompleted

boolean isCompleted()

Returns true if this promise is completed.

Completion may be due to normal termination, an exception, or cancellation -- in all of these cases, this method will return true.

Returns:

true if this promise completed

get

V get()

Waits if necessary for the computation to complete or fail, and then returns its result.

Returns:

the computed result

Throws:

java.lang.RuntimeException - if the computation failed.

get

V get(V defaultValue)

Waits if necessary for the computation to complete or fail, and then returns its result or defaultValue in case of failure.

Parameters:

defaultValue - value to return in case of failure

Returns:

the computed result

Throws:

java.lang.RuntimeException - if the computation failed.

get

V get(long timeout,
      java.util.concurrent.TimeUnit unit)
throws java.util.concurrent.TimeoutException

Waits if necessary for at most the given time for the computation to complete, and then returns its result, if available.

Parameters:

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

the computed result

Throws:

java.lang.RuntimeException - if the computation failed.

java.util.concurrent.TimeoutException - if the wait timed out

get

V get(long timeout,
      java.util.concurrent.TimeUnit unit,
      V defaultValue)

Waits if necessary for at most the given time for the computation to complete, and then retrieves its result, if available.

Parameters:

timeout - the maximum time to wait

unit - the time unit of the timeout argument

defaultValue - value to return in case of timeout or failure

Returns:

the computed result or default value in case of any failure including timeout.

getFailure

java.lang.RuntimeException getFailure()

Waits if necessary for the computation to complete or fail, and then returns the failure or null.

thenApply

<U> Promise<U> thenApply(Functions.Func1<? super V,? extends U> fn)

Returns Promise that contains a result of a function. The function is called with the value of this Promise when it is ready. #completeExceptionally is propagated directly to the returned Promise skipping the function.

Note that no blocking calls are allowed inside of the function.

handle

<U> Promise<U> handle(Functions.Func2<? super V,java.lang.RuntimeException,? extends U> fn)

Returns Promise that contains a result of a function. The function is called with the value of this Promise or with an exception when it is completed. If the function throws a RuntimeException it fails the resulting promise.

Note that no blocking calls are allowed inside of the function.

thenCompose

<U> Promise<U> thenCompose(Functions.Func1<? super V,? extends Promise<U>> fn)

Returns a new Promise that, when this promise completes normally, is executed with this promise as the argument to the supplied function.

Type Parameters:

U - the type of the returned CompletionStage's result

Parameters:

fn - the function returning a new Promise

Returns:

the Promise that completes when fn returned Promise completes.

exceptionally

Promise<V> exceptionally(Functions.Func1<java.lang.Throwable,? extends V> fn)

Returns a new Promise that, when this promise completes exceptionally, is executed with this promise's exception as the argument to the supplied function. Otherwise, if this promise completes normally, then the returned promise also completes normally with the same value.

Parameters:

fn - the function to use to compute the value of the returned CompletionPromise if this CompletionPromise completed exceptionally

Returns:

the new Promise

allOf

static <U> Promise<java.util.List<U>> allOf(java.util.Collection<Promise<U>> promises)

Returns Promise that becomes completed when all promises in the collection are completed. A single promise failure causes resulting promise to deliver the failure immediately.

Parameters:

promises - promises to wait for.

Returns:

Promise that contains a list of results of all promises in the same order.

allOf

static Promise<java.lang.Void> allOf(Promise<?>... promises)

Returns Promise that becomes completed when all arguments are completed. A single promise failure causes resulting promise to deliver the failure immediately.

anyOf

static Promise<java.lang.Object> anyOf(java.lang.Iterable<Promise<?>> promises)

Returns Promise that becomes completed when any of the arguments is completed. If it completes exceptionally then result is also completes exceptionally.

anyOf

static Promise<java.lang.Object> anyOf(Promise<?>... promises)

Returns Promise that becomes completed when any of the arguments is completed. If it completes exceptionally then result is also completes exceptionally.