io.temporal.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 Temporal 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 canceled operation completes its Promise with CanceledFailure when canceled.
• handle(Functions.Func2) and similar callback operations do not allow blocking calls inside functions

Method Summary

Modifier and Type	Method and Description
static <V> Promise<java.lang.Void>	allOf(java.lang.Iterable<Promise<V>> 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 <V> Promise<V>	anyOf(java.lang.Iterable<Promise<V>> 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.
V	cancellableGet() Waits if necessary for the computation to complete or fail, and then returns its result.
V	cancellableGet(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.
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.
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.

cancellableGet

V cancellableGet()

Waits if necessary for the computation to complete or fail, and then returns its result. This call is going to throw CanceledFailure without waiting for this Promise to become ready. Note that in the most situations it is better to let the operation that returned a Promise to perform cleanup and then complete the promise with CanceledException. So calling get() on an asynchronous activity or child workflow invocation result is preferable.

Returns:

the computed result

Throws:

java.lang.RuntimeException - if the computation failed.

CanceledFailure - if surrounding @CancellationScope is canceled.

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

cancellableGet

V cancellableGet(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. This call is going to throw CanceledFailure without waiting for this Promise to become ready. Note that in the most situations it is better to let the operation that returned a Promise to perform cleanup and then complete the promise with CanceledException. So calling get(long, TimeUnit) on an asynchronous activity or child workflow invocation result is preferable.

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

CanceledFailure - if surrounding @CancellationScope is canceled.

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 <V> Promise<java.lang.Void> allOf(java.lang.Iterable<Promise<V>> 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 is completed with null when all the argument promises become completed.

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 <V> Promise<V> anyOf(java.lang.Iterable<Promise<V>> 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.