javascalautils.concurrent

Interface Promise<T>

Type Parameters:

T - The type this Promise will produce as result

public interface Promise<T>

The Promise is the promise to deliver a value at some time in the future.
This is the handle the actual computation side of of the job uses.
Once a job is finished it will report the outcome to the Promise which in turn relays it to the Future the client/application is monitoring.
A promise can be fulfilled either by invoking success or failure but not both.
Nor can success/failure be invoked twice.
The principle is that a Promise will deliver exactly one successful or failure response.
The successful response is of any type whilst the failure is expected to be of type (or subclass of) Throwable.

Together with a Future this allows a safe publication of asynchronously calculated results into another thread.
The basic principle is to first create a Promise.

Promise<String> promise = Promise.apply();

Using that instance one can get hold of the Future that is the container for the value-to-be.

Future<String> future = promise.future();

To complete the Promise and by extension completing the Future one can use any of several methods:

• success(Object)
• failure(Throwable)
• complete(Try)
• completeWith(Future)

E.g.

promise.success("Peter was here");

Note that only one of the methods may be invoked as the Promise can only be fulfilled once.
The above methods come with a variant tryNNN which allows for multiple invocations without raising an exception.
Though still only the first invocation/completion counts.

Since:

1.2

Author:

Peter Nerg

Method Summary

Modifier and Type	Method and Description
static <T> Promise<T>	apply() Creates an instance of Promise.
void	complete(Try<T> result) Completes the Promise with either a Success or a Failure.
void	completeWith(Future<T> future) Completes the Promise with the value from the provided Future once that is completed.
void	failure(Throwable throwable) Completes the Promise with an exception.
Future<T>	future() Get a Future that will hold the value once this Promise is completed.
boolean	isCompleted() Check if the Promise have been completed, with a value or an exception.
void	success(T result) Completes the Promise with a value.
boolean	tryComplete(Try<T> result) Tries to complete the Promise with either a Success or a Failure.
boolean	tryCompleteWith(Future<T> future) Tries to complete this Promise with the value from the provided Future once that is completed.
boolean	tryFailure(Throwable throwable) Tries to complete the Promise with an exception.
boolean	trySuccess(T result) Tries to complete the Promise with a value.

Method Detail

apply

static <T> Promise<T> apply()

Creates an instance of Promise.
E.g. Promise<String> p = Promise.apply();

Type Parameters:

T - The type this Promise will produce as result

Returns:

The Promise instance

Since:

1.2

future

Future<T> future()

Get a Future that will hold the value once this Promise is completed.
Each Promise is connected to a single Future, invoking this method multiple times will always return the same Future instance.

Returns:

A Future that will hold the value once this Promise is completed.

Since:

1.2

isCompleted

boolean isCompleted()

Check if the Promise have been completed, with a value or an exception.

Returns:

true if the Promise has been completed. false otherwise.

Since:

1.2

complete

void complete(Try<T> result)

Completes the Promise with either a Success or a Failure.

Parameters:

result - The result to complete with.

Throws:

IllegalStateException - Thrown if the Promise is already completed.

Since:

1.3

completeWith

void completeWith(Future<T> future)

Completes the Promise with the value from the provided Future once that is completed.

Parameters:

future - The future whose value will complete this Promise

Throws:

IllegalStateException - Thrown if the Promise is already completed.

Since:

1.3

success

void success(T result)

Completes the Promise with a value.

Parameters:

result - The value to complete with.

Throws:

IllegalStateException - Thrown if the Promise is already completed.

Since:

1.2

failure

void failure(Throwable throwable)

Completes the Promise with an exception.

Parameters:

throwable - The Throwable to complete with.

Throws:

IllegalStateException - Thrown if the Promise is already completed.

Since:

1.2

tryComplete

boolean tryComplete(Try<T> result)

Tries to complete the Promise with either a Success or a Failure.
Contrary to the complete(Try) method this does not throw an exception in case the Promise is already completed.

Parameters:

result - The result to complete with.

Returns:

true if the Promise was not completed before, false otherwise

Since:

1.3

tryCompleteWith

boolean tryCompleteWith(Future<T> future)

Tries to complete this Promise with the value from the provided Future once that is completed.
Contrary to the complete(Try) method this does not throw an exception in case the Promise is already completed.

Parameters:

future - The future whose value will complete this Promise

Returns:

true if the Promise was not completed before, false otherwise

Since:

1.3

trySuccess

boolean trySuccess(T result)

Tries to complete the Promise with a value.
Contrary to the success(Object) method this does not throw an exception in case the Promise is already completed.

Parameters:

result - The value to complete with.

Returns:

true if the Promise was not completed before, false otherwise

Since:

1.3

tryFailure

boolean tryFailure(Throwable throwable)

Tries to complete the Promise with an exception.
Contrary to the failure(Throwable) method this does not throw an exception in case the Promise is already completed.

Parameters:

throwable - The Throwable to complete with.

Returns:

true if the Promise was not completed before, false otherwise

Since:

1.3