io.machinecode.then.api

Interface Deferred<T,F,P>

All Superinterfaces:

Future<T>, OnCancel, OnProgress<P>, OnReject<F>, OnResolve<T>, Promise<T,F,P>

public interface Deferred<T,F,P>
extends OnResolve<T>, OnReject<F>, OnProgress<P>, Promise<T,F,P>

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 Promise.isDone() method will return true. A promise reaches one of these states by a call to a 'terminal method', one of resolve(Object), reject(Object) and Promise.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

Field Summary

Fields

Modifier and Type	Field and Description
static byte	CANCELLED This is a terminal state indicating Promise.cancel(boolean) was the first terminal method called.
static byte	PENDING This is a transient state indicating no terminal method has yet been called.
static byte	REJECTED This is a terminal state indicating reject(Object) was the first terminal method called.
static byte	RESOLVED This is a terminal state indicating resolve(Object) was the first terminal method called.

Method Summary

Modifier and Type	Method and Description
Deferred<T,F,P>	onCancel(OnCancel then) Triggered when Promise.cancel(boolean) is the first terminal method called.
Deferred<T,F,P>	onComplete(OnComplete then) Triggered on any event after which Promise.isDone() will return true.
Deferred<T,F,P>	onGet(Future<?> then) Triggered when Future.get(long, java.util.concurrent.TimeUnit) or Future.get() is called.
Deferred<T,F,P>	onProgress(OnProgress<P> then) Triggered when progress(Object) is called.
Deferred<T,F,P>	onReject(OnReject<F> then) Triggered when reject(Object) is the first terminal method called.
Deferred<T,F,P>	onResolve(OnResolve<T> then) Triggered when resolve(Object) is the first terminal method called.
void	progress(P that) Called to notify listeners that the some work has been done in the computation.
Promise<T,F,P>	promise() Produces a readonly view of this Deferred.
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 deferred represents.

Methods inherited from interface io.machinecode.then.api.Promise

cancel, isCancelled, isDone, isRejected, isResolved

Methods inherited from interface java.util.concurrent.Future

get, get

Field Detail

PENDING

static final byte PENDING

This is a transient state indicating no terminal method has yet been called.

See Also:

Constant Field Values

RESOLVED

static final byte RESOLVED

This is a terminal state indicating resolve(Object) was the first terminal method called.

See Also:

Constant Field Values

REJECTED

static final byte REJECTED

This is a terminal state indicating reject(Object) was the first terminal method called.

See Also:

Constant Field Values

CANCELLED

static final byte CANCELLED

This is a terminal state indicating Promise.cancel(boolean) was the first terminal method called.

See Also:

Constant Field Values

Method Detail

promise

Promise<T,F,P> promise()

Produces a readonly view of this Deferred.

Returns:

A promise which will have it's listeners invoked when this Deferred reaches a terminal state.

resolve

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

Called to indicate the successful completion of the computation this deferred represents. After this method has been called Promise.isDone() will return true. If this was the first terminal method to be called Promise.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(Object) has previously called.

CancelledException - MAY be thrown by an implementation if Promise.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 Promise.isDone() will return true. If this was the first terminal method to be called Promise.isRejected() will also return true.

Specified by:

reject in interface OnReject<F>

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 Promise.cancel(boolean) has previously called.

progress

void progress(P that)
       throws ListenerException

Called to notify listeners that the some work has been done in the computation.

Specified by:

progress in interface OnProgress<P>

Parameters:

that - The value to notify listeners with.

Throws:

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

onResolve

Deferred<T,F,P> onResolve(OnResolve<T> then)

Triggered when resolve(Object) is the first terminal method called.

Specified by:

onResolve in interface Promise<T,F,P>

Parameters:

then - Callback to be executed

Returns:

This instance for method chaining.

onReject

Deferred<T,F,P> onReject(OnReject<F> then)

Triggered when reject(Object) is the first terminal method called.

Specified by:

onReject in interface Promise<T,F,P>

Parameters:

then - Callback to be executed

Returns:

This instance for method chaining.

onCancel

Deferred<T,F,P> onCancel(OnCancel then)

Triggered when Promise.cancel(boolean) is the first terminal method called.

Specified by:

onCancel in interface Promise<T,F,P>

Parameters:

then - Callback to be executed

Returns:

This instance for method chaining.

onComplete

Deferred<T,F,P> onComplete(OnComplete then)

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

Will be fired in addition to the callback for the specific event.

Specified by:

onComplete in interface Promise<T,F,P>

Parameters:

then - Callback to be executed

Returns:

This instance for method chaining.

onProgress

Deferred<T,F,P> onProgress(OnProgress<P> then)

Triggered when progress(Object) is called.

An implementation MUST ensure that the value from a call to progress(Object) is reported to every listener that is registered prior to that call. Values from calls to progress(Object) before this method was called MAY be sent to the listener. If they are they MUST be sent in the same order they were received by progress(Object);

Specified by:

onProgress in interface Promise<T,F,P>

Parameters:

then - Callback to be executed

Returns:

This instance for method chaining.

onGet

Deferred<T,F,P> onGet(Future<?> then)

Triggered when Future.get(long, java.util.concurrent.TimeUnit) or Future.get() is called. It will be called after this promise has transitioned into a state where Promise.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, java.util.concurrent.TimeUnit).

Specified by:

onGet in interface Promise<T,F,P>

Parameters:

then - Callback to be executed

Returns:

This instance for method chaining.