io.machinecode.then.api

Interface Promise<T,F extends Throwable>

All Superinterfaces:

Future<T>, OnCancel, OnReject<F>, OnResolve<T>

public interface Promise<T,F extends Throwable>
extends OnResolve<T>, OnReject<F>, OnCancel, Future<T>

A representation of a computation allowing listeners to be notified of state changes. This representation allows for four main states: PENDING, RESOLVED, REJECTED and CANCELLED. Of these RESOLVED, REJECTED and CANCELLED will be referred to as 'terminal states', that is a state when the isDone() method will return true. A promise reaches one of these states by a call to a 'terminal method', one of resolve(Object), reject(Throwable) and cancel(boolean) respectively.

The javadoc here only considers these three terminal states however this definition does not preclude inheritors from adding further terminal states and associated methods.

Since:

1.0

Author:

Brent Douglas (brent.n.douglas@gmail.com)

Field Summary

Fields

Modifier and Type	Field and Description
static byte	CANCELLED
static byte	PENDING
static byte	REJECTED
static byte	RESOLVED

Method Summary

Modifier and Type	Method and Description
boolean	cancel(boolean interrupt) Called to attempt to stop the computation.
boolean	isCancelled()
boolean	isDone()
boolean	isRejected()
boolean	isResolved()
Promise<T,F>	onCancel(OnCancel then) Triggered on any event after which isCancelled() will return true.
Promise<T,F>	onComplete(OnComplete then) Triggered on any event after which isDone() will return true; Will be fired in addition to the callback for the specific event.
Promise<T,F>	onGet(Future<?> then) Triggered when Future.get(long, TimeUnit) or Future.get() is called.
Promise<T,F>	onReject(OnReject<F> then) Triggered on any event after which isRejected() will return true.
Promise<T,F>	onResolve(OnResolve<T> then) Triggered on any event after which isResolved() will return true.
void	reject(F that) Called to indicate the failure of the computation this promise represents.
void	resolve(T that) Called to indicate the successful completion of the computation this promise represents.

Methods inherited from interface java.util.concurrent.Future

get, get

Field Detail

PENDING

static final byte PENDING

See Also:

Constant Field Values

RESOLVED

static final byte RESOLVED

See Also:

Constant Field Values

REJECTED

static final byte REJECTED

See Also:

Constant Field Values

CANCELLED

static final byte CANCELLED

See Also:

Constant Field Values

Method Detail

resolve

void resolve(T that)
      throws ListenerException,
             ResolvedException,
             RejectedException,
             CancelledException

Called to indicate the successful completion of the computation this promise represents. After this method has been called isDone() will return true. If this was the first terminal method to be called isResolved() will also return true.

Specified by:

resolve in interface OnResolve<T>

Parameters:

that - The result of the computation.

Throws:

ListenerException - MAY be thrown if a listener throws an exception.

ResolvedException - MAY be thrown by an implementation if resolve has previously called.

RejectedException - MAY be thrown by an implementation if reject(Throwable) has previously called.

CancelledException - MAY be thrown by an implementation if cancel(boolean) has previously called.

reject

void reject(F that)
     throws ListenerException,
            ResolvedException,
            RejectedException,
            CancelledException

Called to indicate the failure of the computation this promise represents. After this method has been called isDone() will return true. If this was the first terminal method to be called isRejected() will also return true.

Specified by:

reject in interface OnReject<F extends Throwable>

Parameters:

that - The exception that caused the computation to terminate.

Throws:

ListenerException - MAY be thrown if a listener throws an exception.

ResolvedException - MAY be thrown by an implementation if resolve(Object) has previously called.

RejectedException - MAY be thrown by an implementation if reject has previously called.

CancelledException - MAY be thrown by an implementation if cancel(boolean) has previously called.

cancel

boolean cancel(boolean interrupt)
        throws ListenerException

Called to attempt to stop the computation. Calling this method does not guarantee that the computation will cease however if this method is the first terminal method called, an implementation must guarantee that any listeners will not by notified of calls to any other terminal methods. After this method has been called isDone() will return true. If this was the first terminal method to be called isCancelled() will also return true.

Specified by:

cancel in interface Future<T>

Specified by:

cancel in interface OnCancel

Parameters:

interrupt - true If the computation should be interrupted in the case that it has already commenced.

Returns:

true If the promise was cancelled, false if it had already reached another terminal state.

Throws:

ListenerException - MAY be thrown if a listener throws an exception.

See Also:

Future.cancel(boolean)

isDone

boolean isDone()

Specified by:

isDone in interface Future<T>

Returns:

true if any terminal method has been called.

isResolved

boolean isResolved()

Returns:

true if resolve(Object) was the first terminal method called.

isRejected

boolean isRejected()

Returns:

true if reject(Throwable) was the first terminal method called.

isCancelled

boolean isCancelled()

Specified by:

isCancelled in interface Future<T>

Returns:

true if cancel(boolean) was the first terminal method called.

onResolve

Promise<T,F> onResolve(OnResolve<T> then)

Triggered on any event after which isResolved() will return true.

Parameters:

then - Callback to be executed

Returns:

This instance for method chaining.

onReject

Promise<T,F> onReject(OnReject<F> then)

Triggered on any event after which isRejected() will return true.

Parameters:

then - Callback to be executed

Returns:

This instance for method chaining.

onCancel

Promise<T,F> onCancel(OnCancel then)

Triggered on any event after which isCancelled() will return true.

Parameters:

then - Callback to be executed

Returns:

This instance for method chaining.

onComplete

Promise<T,F> onComplete(OnComplete then)

Triggered on any event after which isDone() will return true; Will be fired in addition to the callback for the specific event.

Parameters:

then - Callback to be executed

Returns:

This instance for method chaining.

onGet

Promise<T,F> onGet(Future<?> then)

Triggered when Future.get(long, TimeUnit) or Future.get() is called. It will be called after this promise has transitioned into a state where isDone() will return true. Each get method will call the corresponding get method on the Future in the thread that called either Future.get() or Future.get(long, TimeUnit).

Parameters:

then - Callback to be executed

Returns:

This instance for method chaining.