io.machinecode.then.api

Interface Promise<T,F,P>

All Superinterfaces:

Future<T>, OnCancel

All Known Subinterfaces:

Deferred<T,F,P>

public interface Promise<T,F,P>
extends OnCancel, Future<T>

A read-only representation of a Deferred allowing listeners to be notified of state changes, though clients are allowed to attempt to stop the computation using cancel(boolean).

Since:

1.0

Author:

Brent Douglas

See Also:

Deferred

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,P>	onCancel(OnCancel then) Triggered when cancel(boolean) is the first terminal method called.
Promise<T,F,P>	onComplete(OnComplete then) Triggered on any event after which isDone() will return true.
Promise<T,F,P>	onGet(Future<?> then) Triggered when Future.get(long, java.util.concurrent.TimeUnit) or Future.get() is called.
Promise<T,F,P>	onProgress(OnProgress<? super P> then) Triggered when Deferred.progress(Object) is called.
Promise<T,F,P>	onReject(OnReject<? super F> then) Triggered when Deferred.reject(Object) is the first terminal method called.
Promise<T,F,P>	onResolve(OnResolve<? super T> then) Triggered when Deferred.resolve(Object) is the first terminal method called.
<Tx,Fx,Px> Promise<Tx,Fx,Px>	then(Progress<? super T,? super F,? super P,Tx,Fx,Px> then) Return a new promise that will have the resolved value of the original Promise converted to the new type using then.
<Tx,Fx> Promise<Tx,Fx,P>	then(Reject<? super T,? super F,Tx,Fx,P> then) Return a new promise that will have the resolved value of the original Promise converted to the new type using then.
<Tx> Promise<Tx,F,P>	then(Resolve<? super T,Tx,F,P> then) Return a new promise that will have the resolved value of the original Promise converted to the new type using the Resolve parameter.

Methods inherited from interface java.util.concurrent.Future

get, get

Method Detail

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 Deferred.resolve(Object) was the first terminal method called.

isRejected

boolean isRejected()

Returns:

true if Deferred.reject(Object) 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,P> onResolve(OnResolve<? super T> then)

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

Parameters:

then - Callback to be executed

Returns:

This instance for method chaining.

onReject

Promise<T,F,P> onReject(OnReject<? super F> then)

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

Parameters:

then - Callback to be executed

Returns:

This instance for method chaining.

onCancel

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

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

Parameters:

then - Callback to be executed

Returns:

This instance for method chaining.

onComplete

Promise<T,F,P> 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.

onProgress

Promise<T,F,P> onProgress(OnProgress<? super P> then)

Triggered when Deferred.progress(Object) is called.

An implementation MUST ensure that the value from a call to Deferred.progress(Object) is reported to every listener that is registered prior to that call. Values from calls to Deferred.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 Deferred.progress(Object);

Parameters:

then - Callback to be executed

Returns:

This instance for method chaining.

onGet

Promise<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 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).

Parameters:

then - Callback to be executed

Returns:

This instance for method chaining.

then

<Tx> Promise<Tx,F,P> then(Resolve<? super T,Tx,F,P> then)

Return a new promise that will have the resolved value of the original Promise converted to the new type using the Resolve parameter.

The new promise MUST end in the same state as the Promise that created it if the Deferred reaches a terminal state through either of Deferred.reject(Object) or cancel(boolean). If Deferred.resolve(Object) is called then this promise may reach any terminal state from a call to the Deferred provided to Resolve.resolve(Object, Deferred).

Type Parameters:

Tx - Type of the new promise Deferred.resolve(Object).

Parameters:

then - A processor to convert the resolved value from type T to type Tx.

Returns:

A new promise with resolved type Tx.

See Also:

Resolve

then

<Tx,Fx> Promise<Tx,Fx,P> then(Reject<? super T,? super F,Tx,Fx,P> then)

Return a new promise that will have the resolved value of the original Promise converted to the new type using then.

The new promise MUST end in the same state as the Promise that created it if the Deferred reaches a terminal state through cancel(boolean). If Deferred.resolve(Object) or Deferred.reject(Object) is called then this promise may reach any terminal state from a call to the Deferred provided to either Reject.resolve(Object, Deferred) or Reject.reject(Object, Deferred) respectively.

Type Parameters:

Tx - Type of the new promise Deferred.resolve(Object).

Fx - Type of the new promise Deferred.reject(Object).

Parameters:

then - A processor to convert a resolved value from type T to type Tx or rejected value from F to Fx.

Returns:

A new promise with resolved type Tx and rejected type Fx.

See Also:

Reject

then

<Tx,Fx,Px> Promise<Tx,Fx,Px> then(Progress<? super T,? super F,? super P,Tx,Fx,Px> then)

Return a new promise that will have the resolved value of the original Promise converted to the new type using then.

The new promise MUST end in the same state as the Promise that created it if the Deferred reaches a terminal state through cancel(boolean). If Deferred.resolve(Object) or Deferred.reject(Object) is called then this promise SHOULD reach a terminal state from a call to the Deferred provided to either Progress.resolve(Object, Deferred) or Progress.reject(Object, Deferred) respectively. It MAY reach a terminal state through Progress.progress(Object, Deferred).

Type Parameters:

Tx - Type of the new promise Deferred.resolve(Object).

Fx - Type of the new promise Deferred.reject(Object).

Px - Type of the new promise Deferred.progress(Object).

Parameters:

then - A processor to convert a resolved value from type T to type Tx, rejected value from F to Fx or progress value from P to Px.

Returns:

A new promise with resolved type Tx, rejected type Fx and progress type Px.

See Also:

Progress