javascalautils.concurrent

Interface Future<T>

Type Parameters:

T - The type this Future will hold as result

public interface Future<T>

A Future that will hold the result of an asynchronous computation.
The Future is paired with an instance of Promise which is also the way to get hold of a Future.
One can see a Future as a holder for a value-to-be, not yet available but accessible sometime in the future.
The preferred way to get hold of the value-to-be is to register a listener on any of the provided listener types since this allows for asynchronous non-blocking operations.

• onComplete(Consumer)
• onSuccess(Consumer)
• onFailure(Consumer)

It is possible to register multiple listeners to several/same listener type.
One can register a listener both before and after a Future has been completed.
Should the Future already be completed when the listener is added it is fired immediately.
The guarantee is that a listener is only fired once.

All operations on this class are non-blocking, i.e. allowing for proper asynchronous/non-blocking programming patterns.
With one exception, for situations where it is necessary to maintain synchronous/blocking behavior the method result(long, TimeUnit) is provided.

For real short and consistent programming one can use the apply(ThrowableFunction0) method to provide a function that will be executed in the future.
The result of the function will be reported to the Future returned by the method.

 Future<Integer> resultSuccess = Future.apply(() -> 9 / 3); // The Future will at some point contain: Success(3)
 Future<Integer> resultFailure = Future.apply(() -> 9 / 0); // The Future will at some point contain: Failure(ArithmeticException)
 

Since:

1.2

Author:

Peter Nerg

Method Summary

Modifier and Type	Method and Description
static <T> Future<T>	apply(ThrowableFunction0<T> function) Allows for easy creation of asynchronous computations that will be executed in the future.
Future<T>	filter(java.util.function.Predicate<T> predicate) Creates a new Future that will filter the successful value of this instance once it is completed.
<R> Future<R>	flatMap(java.util.function.Function<T,Future<R>> function) Creates a new Future that will hold the mapped successful value of this instance once it is completed.
void	forEach(java.util.function.Consumer<T> consumer) Asynchronously processes the value in the Future once it is available.
boolean	isCompleted() Check if this Future is completed, with a value or an exception.
<R> Future<R>	map(java.util.function.Function<T,R> function) Creates a new Future that will hold the mapped successful value of this instance once it is completed.
void	onComplete(java.util.function.Consumer<Try<T>> completeHandler) Register a handler to be invoked if the Future gets completed with a value or a failure.
void	onFailure(java.util.function.Consumer<Throwable> failureHandler) Register a handler to be invoked if the Future gets completed with an exception.
void	onSuccess(java.util.function.Consumer<T> successHandler) Register a handler to be invoked if the Future gets completed with a value.
Future<T>	recover(java.util.function.Function<Throwable,T> recoverFunction) Creates a new Future that in case this Future is a 'failure' will apply the function to recover the 'failure' to a 'success'.
T	result(long duration, TimeUnit timeUnit) Blocks and waits for this Future to complete.
<R> Future<R>	transform(java.util.function.Function<T,R> onSuccess, java.util.function.Function<Throwable,Throwable> onFailure) Creates a new Future that will hold the mapped successful value of this instance once it is completed.
Option<Try<T>>	value() The current (completed or not) value of the future.

Method Detail

apply

static <T> Future<T> apply(ThrowableFunction0<T> function)

Allows for easy creation of asynchronous computations that will be executed in the future.
The method will use the Executors.getDefault() method to get hold of the default Executor to use for executing the provided job.
Simple examples:

 Future<Integer> resultSuccess = Future.apply(() -> 9 / 3); // The Future will at some point contain: Success(3)
 Future<Integer> resultFailure = Future.apply(() -> 9 / 0); // The Future will at some point contain: Failure(ArithmeticException)
 

Type Parameters:

T - The type for the Future

Parameters:

function - The function to render either the value T or raise an exception.

Returns:

The future that will hold the result provided by the function

Since:

1.3

isCompleted

boolean isCompleted()

Check if this Future is completed, with a value or an exception.

Returns:

true if completed, false otherwise.

value

Option<Try<T>> value()

The current (completed or not) value of the future.
This is a non-blocking method, it will return the current state/value of the Future.
There are three possible outcomes:

• The future has not been completed -> None is returned
• The execution of the Future was successful -> Some with a Success containing the value of the executed job
• The execution failed and an exception was reported -> Some with a Failure containing the Throwable

Returns:

An Option with the result.

onFailure

void onFailure(java.util.function.Consumer<Throwable> failureHandler)

Register a handler to be invoked if the Future gets completed with an exception.
If the Future has already been completed the notification will happen in the current thread.
Multiple handlers can be registered, without any guarantee of notification order.
Each individual event handler will only be invoked once.

Parameters:

failureHandler - Consumer to invoke.

onSuccess

void onSuccess(java.util.function.Consumer<T> successHandler)

Register a handler to be invoked if the Future gets completed with a value.
If the Future has already been completed the notification will happen in the current thread.
Multiple handlers can be registered, without any guarantee of notification order.
Each individual event handler will only be invoked once.

Parameters:

successHandler - Consumer to invoke.

onComplete

void onComplete(java.util.function.Consumer<Try<T>> completeHandler)

Register a handler to be invoked if the Future gets completed with a value or a failure.
If the Future has already been completed the notification will happen in the current thread.
Multiple handlers can be registered, without any guarantee of notification order.
Each individual event handler will only be invoked once.

Parameters:

completeHandler - Consumer to invoke.

forEach

void forEach(java.util.function.Consumer<T> consumer)

Asynchronously processes the value in the Future once it is available.
Only successful Futures are reported to the consumer.
This is pretty much the same as onSuccess(Consumer) but is here for completion keeping a consistent look and feel.

Parameters:

consumer - The consumer to digest the result

map

<R> Future<R> map(java.util.function.Function<T,R> function)

Creates a new Future that will hold the mapped successful value of this instance once it is completed.
Unsuccessful Futures will not be mapped, they are kept unsuccessful as they are.

Type Parameters:

R - The type for the value held by the mapped future

Parameters:

function - The function to apply

Returns:

The mapped Future

flatMap

<R> Future<R> flatMap(java.util.function.Function<T,Future<R>> function)

Creates a new Future that will hold the mapped successful value of this instance once it is completed.
Unsuccessful Futures will not be mapped, they are kept unsuccessful as they are.

Type Parameters:

R - The type for the value held by the mapped future

Parameters:

function - The function to apply

Returns:

The mapped Future

filter

Future<T> filter(java.util.function.Predicate<T> predicate)

Creates a new Future that will filter the successful value of this instance once it is completed.
The possible outcomes are:

• This Future is successful -> predicate matches -> The filtered future is completed with the value.
• This Future is successful -> predicate fails -> The filtered future is failed with NoSuchElementException.
• This Future is failure -> The failure is passed on to the filtered Future.

Parameters:

predicate - The predicate to apply

Returns:

The filtered Future

transform

<R> Future<R> transform(java.util.function.Function<T,R> onSuccess,
                        java.util.function.Function<Throwable,Throwable> onFailure)

Creates a new Future that will hold the mapped successful value of this instance once it is completed.
Successful futures are mapped with the onSuccess function and unsuccessful/failure futures are mapped with onFailure.

Type Parameters:

R - The type for the value held by the mapped future

Parameters:

onSuccess - The function to apply on a 'successful' result

onFailure - The function to apply on a 'failure' result

Returns:

The mapped Future

Since:

1.3

recover

Future<T> recover(java.util.function.Function<Throwable,T> recoverFunction)

Creates a new Future that in case this Future is a 'failure' will apply the function to recover the 'failure' to a 'success'.
Should this Future be a 'success' the value is propagated as-is.
E.g.

 Future<String> future = ...
 Future<String> recovered = future.recover(t -> t.getMessage());
 

In case of 'future' being successful then that value is passed on to 'recovered', in case of failure then the recover function kicks in and returns the message from the throwable.

Parameters:

recoverFunction - The function to apply in case of a 'failure'

Returns:

The recover Future

Since:

1.3

result

T result(long duration,
         TimeUnit timeUnit)
  throws Throwable,
         TimeoutException

Blocks and waits for this Future to complete.
Returns the result of a successful Future or throws the exception in case of a failure.
The methods blocks for at most the provided duration.
If the Future is already completed the method returns immediately.

Parameters:

duration - The duration to block

timeUnit - The unit for the duration

Returns:

The result in case successful

Throws:

Throwable - The error reported in case of a failure

TimeoutException - In case the waiting time is passed