com.dxfeed.promise

Class Promise<T>

java.lang.Object

com.dxfeed.promise.Promise<T>

public class Promise<T>
extends Object

Result of a computation that will be completed normally or exceptionally in the future.

Usage in API

This class is designed to represent a promise to deliver certain result. If there is a service with a synchronous method like this:

     public T findSomething(Args args);

then this method should be represented in promise-oriented way like this:

     public Promise<T> findSomethingPromise(Args args);

In this case, the call to findSomething(args) is semantically equivalent to findSomethingPromise(args).await(). There may be service-specific difference between those two forms of invocation. If findSomething throws exception, then await wraps them into PromiseException. If findSomething consults some kind of local cache with subscription, then it may be defined by the service to return immediately and only retrieve the result from the cache, while findSomethingPromise is a proper form that makes potentially time-consuming call to a back end data provider.

Usage in service implementations

The basic implementation of findSomethingPromise via findSomething using an Executor for background computation looks like this:

     public Promise<T> findSomethingPromise(Args args) {
         Promise<T> promise = new Promise<T>();
         executor.execute(() -> {
             try {
                 T result = findSomething(args);
                 promise.complete(result);
             } catch (Throwable t) {
                 promise.completeExceptionally(t);
             }
         });
         return promise;
     }

A more advanced implementation may also cancel pending and/or ongoing computation when client cancels the promise or times out waiting for a promise to be completed. The sketch of such implementation using an ExecutorService is:

     public Promise<T> findSomethingPromise(Args args) {
         Promise<T> promise = new Promise<T>();
         Future<?> future = executor.submit(() -> {
             try {
                 T result = findSomething(args);
                 promise.complete(result);
             } catch (Throwable t) {
                 promise.completeExceptionally(t);
             }
         });
         promise.whenDone(p -> future.cancel(true)); // true to interrupt running task
         return promise;
     }

Usage in service clients

The basic usage of a promise that is returned by some service is to wait for result like this:

     try {
         findSomething(args).await();
         handleResult(result);
     } catch (Throwable t) {
         handleException(t);
     }

Waiting with timeout is performed by replacing await call with await(timeout, unit). The same handling can be performed in the service provider thread like this:

     findSomething(args).whenDone(promise -> {
         if (promise.hasResult())
            handleResult(promise.getResult());
         else
            handleException(promise.getException());
     });

Promise state

Internally, promise can be in one the four states: initial, result, exception, and cancelled. A freshly created promise is in initial state. Every other state if final and is transitioned to by a dedicated transition method as shown in the below table.

What \ State	Initial	Result	Exception	Cancelled
Transition method	constructor	complete	completeExceptionally	cancel
isDone	false	true	true	true
hasResult	false	true	false	false
hasException	false	false	true	true
isCancelled	false	false	false	true
getResult	null	result	null	null
getException	null	null	exception	CancellationException

Threads and locks

This class is thread-safe and can be used concurrently from multiple threads without external synchronization.

By default, whenDone notifications are performed in the same thread that invoked the state-changing method like complete, completeExceptionally, or cancel. Promise class can be extended to override protected handleDone method to move notification to other threads, for example, or to do other kind of processing.

Performance considerations

This class is optimized for a case of a single attached PromiseHandler, while at the same time supporting multiple invocations of whenDone at the cost of extra memory consumption. Performance-sensitive service implementations that need to cancel their internal computation on the promise cancel are encouraged to extend Promise class and override handleDone for this purpose instead of using whenDone.

Working with multiple promises

See Promises class for utility methods that combine multiple Promise instances to facilitate batch processing and concurrent invocations.

Design note

This class is based on the Future and CompletableFuture. However, the methods in this class are carefully selected to minimize the interface weight and the preference is given to methods that do no throw checked exceptions. All the names of the methods are picked to avoid conflicts with CompletionStage, so this class can be potentially enhanced to implement CompletionStage while maintaining backwards compatibility.

Constructor Summary

Constructors

Constructor and Description
Promise() Creates promise in the initial state and without an executor for notifications.

Method Summary

Modifier and Type	Method and Description
T	await() Wait for computation to complete and return its result or throw an exception in case of exceptional completion.
T	await(long timeout, TimeUnit unit) Wait for computation to complete or timeout and return its result or throw an exception in case of exceptional completion or timeout.
boolean	awaitWithoutException(long timeout, TimeUnit unit) Wait for computation to complete or timeout or throw an exception in case of exceptional completion.
void	cancel() Cancels computation.
void	complete(T result) Completes computation normally with a specified result.
static <T> Promise<T>	completed(T result) Returns new promise that is completed with a specified result.
void	completeExceptionally(Throwable exception) Completes computation exceptionally with a specified exception.
static <T> Promise<T>	failed(Throwable exception) Returns new promise that is completed exceptionally with a specified exception.
Throwable	getException() Returns exceptional outcome of computation.
T	getResult() Returns result of computation.
protected void	handleDone(PromiseHandler<? super T> handler) Invoked when promise is done.
boolean	hasException() Returns true when computation has completed exceptionally or was cancelled.
boolean	hasResult() Returns true when computation has completed normally.
boolean	isCancelled() Returns true when computation was cancelled.
boolean	isDone() Returns true when computation has completed normally, or exceptionally, or was cancelled.
void	whenDone(PromiseHandler<? super T> handler) Registers a handler to be invoked exactly once when computation completes.
void	whenDoneAsync(PromiseHandler<? super T> handler, Executor executor) Registers a handler to be invoked asynchronously exactly once when computation completes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Promise

public Promise()

Creates promise in the initial state and without an executor for notifications.

Method Detail

isDone

public final boolean isDone()

Returns true when computation has completed normally, or exceptionally, or was cancelled.

Returns:

true when computation has completed.

hasResult

public final boolean hasResult()

Returns true when computation has completed normally. Use getResult() method to get the result of the computation.

Returns:

true when computation has completed normally.

See Also:

getResult()

hasException

public final boolean hasException()

Returns true when computation has completed exceptionally or was cancelled. Use getException() method to get the exceptional outcome of the computation.

Returns:

true when computation has completed exceptionally or was cancelled.

isCancelled

public final boolean isCancelled()

Returns true when computation was cancelled. Use getException() method to get the corresponding CancellationException.

Returns:

true when computation was cancelled.

See Also:

cancel(), getException()

getResult

public final T getResult()

Returns result of computation. If computation has no result, then this method returns null.

Returns:

result of computation.

See Also:

hasResult()

getException

public final Throwable getException()

Returns exceptional outcome of computation. If computation has no exception, then this method returns null. If computation has completed exceptionally or was cancelled, then the result of this method is not null. If computation was cancelled, then this method returns an instance of CancellationException.

Returns:

exceptional outcome of computation.

See Also:

hasException()

await

public final T await()

Wait for computation to complete and return its result or throw an exception in case of exceptional completion. If the wait is interrupted, then the computation is cancelled, the interruption flag on the current thread is set, and CancellationException is thrown.

This method waits forever. See await(timeout, unit) for a timed wait when the result of this promise is required to proceed or awaitWithoutException(timeout, unit) when the result is not required and the normal execution shall continue on timeout.

Returns:

result of computation.

Throws:

CancellationException - if computation was cancelled.

PromiseException - if computation has completed exceptionally.

await

public final T await(long timeout,
                     TimeUnit unit)

Wait for computation to complete or timeout and return its result or throw an exception in case of exceptional completion or timeout. If the wait is interrupted, then the computation is cancelled, the interruption flag on the current thread is set, and CancellationException is thrown.

If the wait times out, then the computation is cancelled and CancellationException is thrown. Use this method in the code that must get and process the result of this promise, which is returned by this method when it completes normally. When the result is not required and the normal execution shall continue on timeout use awaitWithoutException.

Returns:

result of computation.

Throws:

CancellationException - if computation was cancelled or timed out.

PromiseException - if computation has completed exceptionally.

awaitWithoutException

public final boolean awaitWithoutException(long timeout,
                                           TimeUnit unit)

Wait for computation to complete or timeout or throw an exception in case of exceptional completion. If the wait is interrupted, then the computation is cancelled, the interruption flag on the current thread is set, and CancellationException is thrown.

If the wait times out, then the computation is cancelled and this method returns false. Use this method in the code that shall continue normal execution in case of timeout.

Returns:

true if the computation has completed normally; false when wait timed out.

Throws:

CancellationException - if computation was cancelled.

PromiseException - if computation has completed exceptionally.

cancel

public final void cancel()

Cancels computation. This method does nothing if computation has already completed.

If cancelled, then getException will return CancellationException, isDone, isCancelled, and hasException will return true, all handlers that were installed with whenDone method are notified by invoking their promiseDone method, and all waiters on join method throw CancellationException.

complete

public final void complete(T result)

Completes computation normally with a specified result. This method does nothing if computation has already completed (normally, exceptionally, or was cancelled),

If completed, then getResult will return the specified result, isDone and hasResult will return true, all handlers that were installed with whenDone method are notified by invoking their promiseDone method, and all waiters on join method return the result.

Parameters:

result - the result of computation.

See Also:

getResult()

completeExceptionally

public final void completeExceptionally(Throwable exception)

Completes computation exceptionally with a specified exception. This method does nothing if computation has already completed, otherwise getException() will return the specified exception.

If completed exceptionally, then getException will return the specified exception, isDone and hasException will return true, all handlers that were installed with whenDone method are notified by invoking their promiseDone method, and all waiters on join method throw PromiseException wrapping this exception.

Parameters:

exception - the exception.

Throws:

NullPointerException - if exception is null.

See Also:

getException()

whenDone

public final void whenDone(PromiseHandler<? super T> handler)

Registers a handler to be invoked exactly once when computation completes. The handler's promiseDone method is invoked immediately when this computation has already completed, otherwise it will be invoked synchronously in the future when computation completes normally, or exceptionally, or is cancelled from the same thread that had invoked one of the completion methods. Exceptions that are produced by the invocation of PromiseHandler.promiseDone method are caught and logged.

Parameters:

handler - the handler.

Throws:

NullPointerException - if handler is null.

whenDoneAsync

public final void whenDoneAsync(PromiseHandler<? super T> handler,
                                Executor executor)

Registers a handler to be invoked asynchronously exactly once when computation completes.

This method is a shortcut for the following code:

 whenDone(new PromiseHandler<T>() {
     public void promiseDone(Promise<? extends T> promise) {
         executor.execute(new Runnable() {
             public void run() {
                 handler.promiseDone(Promise.this);
             }
         });
     }
 });
 

Parameters:

handler - the handler.

executor - the executor.

Throws:

NullPointerException - if handler or executor is null.

completed

public static <T> Promise<T> completed(T result)

Returns new promise that is completed with a specified result.

Type Parameters:

T - the result type.

Parameters:

result - the result of computation.

Returns:

new promise that is completed with a specified result.

failed

public static <T> Promise<T> failed(Throwable exception)

Returns new promise that is completed exceptionally with a specified exception.

Type Parameters:

T - the result type.

Parameters:

exception - the exception.

Returns:

new promise that is completed exceptionally with a specified exception.

Throws:

NullPointerException - if exception is null.

handleDone

protected void handleDone(PromiseHandler<? super T> handler)

Invoked when promise is done. This implementation invokes PromiseHandler.promiseDone on all handlers.

Parameters:

handler - reference to installed handlers list or null when no handlers were set.