com.github.jparkie.promise

Interface Promise<T>

Type Parameters:

T - The type of the value promised to be available now, or in the future, or never.

public interface Promise<T>

A Promise is an object which can be completed with a value or failed with an exception. Furthermore, a promise can be cancelled, to prevent the propagation of its completion. The cancelling of a promise does not undo the propagation of a completion after the promise already completed. As well, it does not undo the completion. However, the cancelling of a promise prevents new propagation of completion. It is a unit of asynchronous computation; thus, Functions and Actions execute on a Scheduler. Accordingly, a promise is thread-safe.

Method Summary

Modifier and Type	Method and Description
void	await() Await the completion or the cancellation of the promise.
boolean	await(long timeout, java.util.concurrent.TimeUnit unit) Await the completion or the cancellation of the promise at most the time specified.
void	cancel() Cancels the propagation of completion of the promise.
T	get() Returns the value promised upon completion.
java.lang.Throwable	getError() Returns the error promised upon completion.
boolean	isCancelled() Returns whether the promise has been cancelled.
boolean	isDone() Returns whether the promise has been completed.
boolean	isSuccessful() Returns whether the promise has completed and has no errors .
void	set(T value) Completes the promise with a value.
void	setError(java.lang.Throwable error) Completes the promise with an error.
void	then(Scheduler scheduler, Action<T> action) Calls the action on the promise upon the completion of this promise.
<U> Promise<U>	then(Scheduler scheduler, Function<T,U> function) Returns a new transformed promise specified by the function upon the completion of this promise.

Method Detail

isCancelled

boolean isCancelled()

Returns whether the promise has been cancelled.

Returns:

If cancelled, true, else, false.

isDone

boolean isDone()

Returns whether the promise has been completed. A cancellation does not affect the status of completion.

Returns:

If set() or setError() has been called, true, else false.

isSuccessful

boolean isSuccessful()

Returns whether the promise has completed and has no errors .

Returns:

If isDone() and has no errors, true, else false.

cancel

void cancel()

Cancels the propagation of completion of the promise. This operation is idempotent. The propagation of cancelling will occur only once.

await

void await()
    throws java.lang.InterruptedException

Await the completion or the cancellation of the promise.

Throws:

java.lang.InterruptedException - If the thread awaiting on the promise is interrupted, an exception is thrown.

await

boolean await(long timeout,
              java.util.concurrent.TimeUnit unit)
       throws java.lang.InterruptedException

Await the completion or the cancellation of the promise at most the time specified.

Parameters:

timeout - The duration at most to await.

unit - The unit of duration to await.

Returns:

If the promise completed or cancelled under the timeout, true, else, false.

Throws:

java.lang.InterruptedException - If the thread awaiting on the promise is interrupted, an exception is thrown.

get

T get()
throws java.lang.IllegalStateException

Returns the value promised upon completion. If cancelled, returns the current view of the "value": null or otherwise.

Returns:

The value promised upon completion.

Throws:

java.lang.IllegalStateException - If this method is called before the completion of the promise, an exception is thrown.

getError

java.lang.Throwable getError()
                      throws java.lang.IllegalStateException

Returns the error promised upon completion. If cancelled, returns the current view of the "error": null or otherwise.

Returns:

The error promised upon completion.

Throws:

java.lang.IllegalStateException - If this method is called before the completion of the promise, an exception is thrown.

set

void set(T value)
  throws java.lang.IllegalStateException

Completes the promise with a value. Please avoid propagating nulls. Nulls are allowed due to the nature of cancelled promises.

Parameters:

value - The value to complete the promise.

Throws:

java.lang.IllegalStateException - If this method is called after the completion of the promise, an exception is thrown.

setError

void setError(java.lang.Throwable error)
       throws java.lang.IllegalStateException

Completes the promise with an error. Please avoid propagating nulls. Nulls are allowed due to the nature of cancelled promises.

Parameters:

error - The error to complete the promise.

Throws:

java.lang.IllegalStateException - If this method is called after the completion of the promise, an exception is thrown.

then

<U> Promise<U> then(Scheduler scheduler,
                    Function<T,U> function)

Returns a new transformed promise specified by the function upon the completion of this promise.

Type Parameters:

U - The new type of promise.

Parameters:

scheduler - The scheduler to call the function.

function - A function to transform the current promise into another promise.

Returns:

The transformed promise.

then

void then(Scheduler scheduler,
          Action<T> action)

Calls the action on the promise upon the completion of this promise.

Parameters:

scheduler - The scheduler to call the action.

action - The action to call on the current promise.