javascalautils.concurrent

Interface Future<T>

Type Parameters:

T - The type this Future will hold as result

public interface Future<T>

A Future that holds the result of a computation executed asynchronously.

Since:

1.2

Author:

Peter Nerg

Method Summary

Modifier and Type	Method and Description
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.
T	result(long duration, TimeUnit timeUnit) Blocks and waits for this Future to complete.
Option<Try<T>>	value() The value of the future.

Method Detail

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 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 invocation will happen in the current thread.
Multiple handlers can be registered, without any guarantee of notification order.
Each individual 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 invocation will happen in the current thread.
Multiple handlers can be registered, without any guarantee of notification order.
Each individual 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 invocation will happen in the current thread.
Multiple handlers can be registered, without any guarantee of notification order.
Each individual 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

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