Package com.infilos.utils

Class Futures

java.lang.Object

com.infilos.utils.Futures

public final class Futures
extends Object

CompletableFuture utils.

See Also:

Method Summary

Modifier and Type	Method	Description
static void	checkCompleted(CompletionStage<?> stage)	Checks that a stage is completed.
static <R,A,B,C> CompletionStage<R>	combine(CompletionStage<A> a, CompletionStage<B> b, CompletionStage<C> c, Function3<A,B,C,R> function)	Combines multiple stages by applying a function.
static <R,A,B,C,D> CompletionStage<R>	combine(CompletionStage<A> a, CompletionStage<B> b, CompletionStage<C> c, CompletionStage<D> d, Function4<A,B,C,D,R> function)	Combines multiple stages by applying a function.
static <R,A,B,C,D,E> CompletionStage<R>	combine(CompletionStage<A> a, CompletionStage<B> b, CompletionStage<C> c, CompletionStage<D> d, CompletionStage<E> e, Function5<A,B,C,D,E,R> function)	Combines multiple stages by applying a function.
static <R,A,B,C,D,E,F> CompletionStage<R>	combine(CompletionStage<A> a, CompletionStage<B> b, CompletionStage<C> c, CompletionStage<D> d, CompletionStage<E> e, CompletionStage<F> f, Function6<A,B,C,D,E,F,R> function)	Combines multiple stages by applying a function.
static <R,A,B> CompletionStage<R>	combine(CompletionStage<A> a, CompletionStage<B> b, BiFunction<A,B,R> function)	Combines multiple stages by applying a function.
static <T> CompletionStage<T>	combine(Function<CombinedFutures,T> function, CompletionStage<?>... stages)	Combines multiple stages by applying a function.
static <T> CompletionStage<T>	combine(Function<CombinedFutures,T> function, List<? extends CompletionStage<?>> stages)	Combines multiple stages by applying a function.
static <R,A,B,C> CompletionStage<R>	combineFutures(CompletionStage<A> a, CompletionStage<B> b, CompletionStage<C> c, Function3<A,B,C,CompletionStage<R>> function)	Composes multiple stages into another stage using a function.
static <R,A,B,C,D> CompletionStage<R>	combineFutures(CompletionStage<A> a, CompletionStage<B> b, CompletionStage<C> c, CompletionStage<D> d, Function4<A,B,C,D,CompletionStage<R>> function)	Composes multiple stages into another stage using a function.
static <R,A,B,C,D,E> CompletionStage<R>	combineFutures(CompletionStage<A> a, CompletionStage<B> b, CompletionStage<C> c, CompletionStage<D> d, CompletionStage<E> e, Function5<A,B,C,D,E,CompletionStage<R>> function)	Composes multiple stages into another stage using a function.
static <R,A,B,C,D,E,F> CompletionStage<R>	combineFutures(CompletionStage<A> a, CompletionStage<B> b, CompletionStage<C> c, CompletionStage<D> d, CompletionStage<E> e, CompletionStage<F> f, Function6<A,B,C,D,E,F,CompletionStage<R>> function)	Composes multiple stages into another stage using a function.
static <R,A,B> CompletionStage<R>	combineFutures(CompletionStage<A> a, CompletionStage<B> b, BiFunction<A,B,CompletionStage<R>> function)	Composes multiple stages into another stage using a function.
static <T> CompletionStage<T>	dereference(CompletionStage<? extends CompletionStage<T>> stage)	This takes a stage of a stage of a value and returns a plain stage of a value.
static <T> CompletionStage<T>	exceptionallyCompose(CompletionStage<T> stage, Function<Throwable,? extends CompletionStage<T>> fn)	Returns a new stage that, when this stage completes exceptionally, is executed with this stage's exception as the argument to the supplied function.
static <T> T	getCompleted(CompletionStage<T> stage)	Gets the value of a completed stage.
static <T> Throwable	getException(CompletionStage<T> stage)	Gets the exception from an exceptionally completed future
static <T,U> CompletionStage<U>	handleCompose(CompletionStage<T> stage, BiFunction<? super T,Throwable,? extends CompletionStage<U>> fn)	Returns a new stage that, when this stage completes either normally or exceptionally, is executed with this stage's result and exception as arguments to the supplied function.
static <T,S extends CompletionStage<? extends T>> Collector<S,?,CompletableFuture<List<T>>>	joinList()	Collect a stream of CompletionStages into a single future holding a list of the joined entities.
static <T,K,V> Collector<T,?,CompletableFuture<Map<K,V>>>	joinMap(Function<? super T,? extends K> keyMapper, Function<? super T,? extends CompletionStage<? extends V>> valueFutureMapper)	Collect a stream of Objects into a single future holding a Map whose keys are the result of applying the provided mapping function to the input elements, and whose values are the corresponding joined entities.
static <T> CompletableFuture<T>	ofFailed(Throwable throwable)	Returns a new CompletableFuture that is already exceptionally completed with the given exception.
static <T> CompletableFuture<List<T>>	ofList(List<? extends CompletionStage<? extends T>> stages)	Returns a new CompletableFuture which completes to a list of all values of its input stages, if all succeed.
static <U,T> CompletableFuture<Map<U,T>>	ofMap(Map<U,? extends CompletionStage<? extends T>> map)	Returns a new CompletableFuture which completes to a map of all values of its input stages, if all succeed.
static <T> CompletableFuture<List<T>>	ofSuccedList(List<? extends CompletionStage<T>> stages, Function<Throwable,? extends T> defaultValueMapper)	Returns a new CompletableFuture which completes to a list of values of those input stages that succeeded.
static <T> CompletableFuture<T>	poll(Supplier<Optional<T>> pollingTask, Duration frequency, ScheduledExecutorService executorService)	Polls an external resource periodically until it returns a non-empty result.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

ofList

public static <T> CompletableFuture<List<T>> ofList(List<? extends CompletionStage<? extends T>> stages)

Returns a new CompletableFuture which completes to a list of all values of its input stages, if all succeed. The list of results is in the same order as the input stages.

As soon as any of the given stages complete exceptionally, then the returned future also does so, with a CompletionException holding this exception as its cause.

If no stages are provided, returns a future holding an empty list.

Type Parameters:

T - the common super-type of all of the input stages, that determines the monomorphic type of the output future

Parameters:

stages - the stages to combine

Returns:

a future that completes to a list of the results of the supplied stages

Throws:

NullPointerException - if the stages list or any of its elements are null

Since:

0.1.0

ofMap

public static <U,T> CompletableFuture<Map<U,T>> ofMap(Map<U,? extends CompletionStage<? extends T>> map)

Returns a new CompletableFuture which completes to a map of all values of its input stages, if all succeed.

If any of the given stages complete exceptionally, then the returned future also does so, with a CompletionException holding this exception as its cause.

If no stages are provided, returns a future holding an empty map.

Type Parameters:

U - the common super-type of the keys

T - the common super-type of all of the input value-stages, that determines the monomorphic type of the output future

Parameters:

map - the map of stages to combine

Returns:

a future that completes to a map of the results of the supplied keys and value-stages

Throws:

NullPointerException - if value-stages or any of its elements are null

Since:

0.3.3

ofSuccedList

public static <T> CompletableFuture<List<T>> ofSuccedList(List<? extends CompletionStage<T>> stages,
                                                          Function<Throwable,? extends T> defaultValueMapper)

Returns a new CompletableFuture which completes to a list of values of those input stages that succeeded. The list of results is in the same order as the input stages. For failed stages, the defaultValueMapper will be called, and the value returned from that function will be put in the resulting list.

If no stages are provided, returns a future holding an empty list.

Type Parameters:

T - the common type of all of the input stages, that determines the type of the output future

Parameters:

stages - the stages to combine.

defaultValueMapper - a function that will be called when a future completes exceptionally to provide a default value to place in the resulting list

Returns:

a future that completes to a list of the results of the supplied stages

Throws:

NullPointerException - if the stages list or any of its elements are null

ofFailed

public static <T> CompletableFuture<T> ofFailed(Throwable throwable)

Returns a new CompletableFuture that is already exceptionally completed with the given exception.

Type Parameters:

T - an arbitrary type for the returned future; can be anything since the future will be exceptionally completed and thus there will never be a value of type T

Parameters:

throwable - the exception

Returns:

a future that exceptionally completed with the supplied exception

Throws:

NullPointerException - if the supplied throwable is null

Since:

0.1.0

joinList

public static <T,S extends CompletionStage<? extends T>> Collector<S,?,CompletableFuture<List<T>>> joinList()

Collect a stream of CompletionStages into a single future holding a list of the joined entities.

Usage:

 collection.stream()
     .map(this::someAsyncFunc)
     .collect(joinList())
     .thenApply(this::consumeList)
 

The generated CompletableFuture will complete to a list of all entities, in the order they were encountered in the original stream. Similar to CompletableFuture.allOf(CompletableFuture[]), if any of the input futures complete exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause.

Type Parameters:

T - the common super-type of all of the input stages, that determines the monomorphic type of the output future

S - the implementation of CompletionStage that the stream contains

Returns:

a new CompletableFuture according to the rules outlined in the method description

Throws:

NullPointerException - if any future in the stream is null

Since:

0.1.0

joinMap

public static <T,K,V> Collector<T,?,CompletableFuture<Map<K,V>>> joinMap(Function<? super T,? extends K> keyMapper,
                                                                                                       Function<? super T,? extends CompletionStage<? extends V>> valueFutureMapper)

Collect a stream of Objects into a single future holding a Map whose keys are the result of applying the provided mapping function to the input elements, and whose values are the corresponding joined entities.

Usage:

 collection.stream()
     .collect(joinMap(this::toKey, this::someAsyncFunc))
     .thenApply(this::consumeMap)
 

The generated CompletableFuture will complete to a Map of all entities. Similar to CompletableFuture.allOf(CompletableFuture[]), if any of the input futures complete exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause.

Type Parameters:

T - the type of the input elements

K - the output type of the key mapping function

V - the common super-type of the stages returned by the value future mapping function

Parameters:

keyMapper - a mapping function to produce keys

valueFutureMapper - a mapping function to produce futures that will eventually produce the values

Returns:

a new CompletableFuture according to the rules outlined in the method description

Throws:

NullPointerException - if valueFutureMapper returns null for any input element

Since:

0.3.4

checkCompleted

public static void checkCompleted(CompletionStage<?> stage)

Checks that a stage is completed.

Parameters:

stage - the CompletionStage to check

Throws:

IllegalStateException - if the stage is not completed

Since:

0.1.0

getCompleted

public static <T> T getCompleted(CompletionStage<T> stage)

Gets the value of a completed stage.

Type Parameters:

T - the type of the value that the stage completes into

Parameters:

stage - a completed CompletionStage

Returns:

the value of the stage if it has one

Throws:

IllegalStateException - if the stage is not completed

Since:

0.1.0

getException

public static <T> Throwable getException(CompletionStage<T> stage)

Gets the exception from an exceptionally completed future

Type Parameters:

T - the type of the value that the stage completes into

Parameters:

stage - an exceptionally completed CompletionStage

Returns:

the exception the stage has completed with

Throws:

IllegalStateException - if the stage is not completed exceptionally

CancellationException - if the stage was cancelled

UnsupportedOperationException - if the CompletionStage does not support the CompletionStage.toCompletableFuture() operation

handleCompose

public static <T,U> CompletionStage<U> handleCompose(CompletionStage<T> stage,
                                                           BiFunction<? super T,Throwable,? extends CompletionStage<U>> fn)

Returns a new stage that, when this stage completes either normally or exceptionally, is executed with this stage's result and exception as arguments to the supplied function.

When this stage is complete, the given function is invoked with the result (or null if none) and the exception (or null if none) of this stage as arguments, and the function's result is used to complete the returned stage.

This differs from CompletionStage.handle(java.util.function.BiFunction) in that the function should return a CompletionStage rather than the value directly.

Type Parameters:

T - the type of the input stage's value.

U - the function's return type

Parameters:

stage - the CompletionStage to compose

fn - the function to use to compute the value of the returned CompletionStage

Returns:

the new CompletionStage

Since:

0.1.0

exceptionallyCompose

public static <T> CompletionStage<T> exceptionallyCompose(CompletionStage<T> stage,
                                                          Function<Throwable,? extends CompletionStage<T>> fn)

Returns a new stage that, when this stage completes exceptionally, is executed with this stage's exception as the argument to the supplied function. Otherwise, if this stage completes normally, then the returned stage also completes normally with the same value.

This differs from CompletionStage.exceptionally(java.util.function.Function) in that the function should return a CompletionStage rather than the value directly.

Type Parameters:

T - the type of the input stage's value.

Parameters:

stage - the CompletionStage to compose

fn - the function to use to compute the value of the returned CompletionStage if this stage completed exceptionally

Returns:

the new CompletionStage

Since:

0.1.0

dereference

public static <T> CompletionStage<T> dereference(CompletionStage<? extends CompletionStage<T>> stage)

This takes a stage of a stage of a value and returns a plain stage of a value.

Type Parameters:

T - the type of the inner stage's value.

Parameters:

stage - a CompletionStage of a CompletionStage of a value

Returns:

the CompletionStage of the value

Since:

0.1.0

combine

public static <R,A,B> CompletionStage<R> combine(CompletionStage<A> a,
                                                             CompletionStage<B> b,
                                                             BiFunction<A,B,R> function)

Combines multiple stages by applying a function.

Type Parameters:

R - the type of the combining function's return value.

A - the type of the first stage's value.

B - the type of the second stage's value.

Parameters:

a - the first stage.

b - the second stage.

function - the combining function.

Returns:

a stage that completes into the return value of the supplied function.

Since:

0.1.0

combine

public static <R,A,B,C> CompletionStage<R> combine(CompletionStage<A> a,
                                                                     CompletionStage<B> b,
                                                                     CompletionStage<C> c,
                                                                     Function3<A,B,C,R> function)

Combines multiple stages by applying a function.

Type Parameters:

R - the type of the combining function's return value.

A - the type of the first stage's value.

B - the type of the second stage's value.

C - the type of the third stage's value.

Parameters:

a - the first stage.

b - the second stage.

c - the third stage.

function - the combining function.

Returns:

a stage that completes into the return value of the supplied function.

Since:

0.1.0

combine

public static <R,A,B,C,D> CompletionStage<R> combine(CompletionStage<A> a,
                                                                             CompletionStage<B> b,
                                                                             CompletionStage<C> c,
                                                                             CompletionStage<D> d,
                                                                             Function4<A,B,C,D,R> function)

Combines multiple stages by applying a function.

Type Parameters:

R - the type of the combining function's return value.

A - the type of the first stage's value.

B - the type of the second stage's value.

C - the type of the third stage's value.

D - the type of the fourth stage's value.

Parameters:

a - the first stage.

b - the second stage.

c - the third stage.

d - the fourth stage.

function - the combining function.

Returns:

a stage that completes into the return value of the supplied function.

Since:

0.1.0

combine

public static <R,A,B,C,D,E> CompletionStage<R> combine(CompletionStage<A> a,
                                                                                     CompletionStage<B> b,
                                                                                     CompletionStage<C> c,
                                                                                     CompletionStage<D> d,
                                                                                     CompletionStage<E> e,
                                                                                     Function5<A,B,C,D,E,R> function)

Combines multiple stages by applying a function.

Type Parameters:

R - the type of the combining function's return value.

A - the type of the first stage's value.

B - the type of the second stage's value.

C - the type of the third stage's value.

D - the type of the fourth stage's value.

E - the type of the fifth stage's value.

Parameters:

a - the first stage.

b - the second stage.

c - the third stage.

d - the fourth stage.

e - the fifth stage.

function - the combining function.

Returns:

a stage that completes into the return value of the supplied function.

Since:

0.1.0

combine

public static <R,A,B,C,D,E,F> CompletionStage<R> combine(CompletionStage<A> a,
                                                                                             CompletionStage<B> b,
                                                                                             CompletionStage<C> c,
                                                                                             CompletionStage<D> d,
                                                                                             CompletionStage<E> e,
                                                                                             CompletionStage<F> f,
                                                                                             Function6<A,B,C,D,E,F,R> function)

Combines multiple stages by applying a function.

Type Parameters:

R - the type of the combining function's return value.

A - the type of the first stage's value.

B - the type of the second stage's value.

C - the type of the third stage's value.

D - the type of the fourth stage's value.

E - the type of the fifth stage's value.

F - the type of the sixth stage's value.

Parameters:

a - the first stage.

b - the second stage.

c - the third stage.

d - the fourth stage.

e - the fifth stage.

f - the sixth stage.

function - the combining function.

Returns:

a stage that completes into the return value of the supplied function.

Since:

0.3.2

combine

public static <T> CompletionStage<T> combine(Function<CombinedFutures,T> function,
                                             CompletionStage<?>... stages)

Combines multiple stages by applying a function.

Type Parameters:

T - the type of the combining function's return value.

Parameters:

function - the combining function.

stages - the stages to combine

Returns:

a stage that completes into the return value of the supplied function.

Since:

0.4.0

combine

public static <T> CompletionStage<T> combine(Function<CombinedFutures,T> function,
                                             List<? extends CompletionStage<?>> stages)

Combines multiple stages by applying a function.

Type Parameters:

T - the type of the combining function's return value.

Parameters:

function - the combining function.

stages - the stages to combine

Returns:

a stage that completes into the return value of the supplied function.

Since:

0.4.0

combineFutures

public static <R,A,B> CompletionStage<R> combineFutures(CompletionStage<A> a,
                                                                    CompletionStage<B> b,
                                                                    BiFunction<A,B,CompletionStage<R>> function)

Composes multiple stages into another stage using a function.

Type Parameters:

R - the type of the composed CompletionStage.

A - the type of the first stage's value.

B - the type of the second stage's value.

Parameters:

a - the first stage.

b - the second stage.

function - the combining function.

Returns:

a stage that is composed from the input stages using the function.

Throws:

UnsupportedOperationException - if any of the CompletionStages do not interoperate with CompletableFuture

combineFutures

public static <R,A,B,C> CompletionStage<R> combineFutures(CompletionStage<A> a,
                                                                            CompletionStage<B> b,
                                                                            CompletionStage<C> c,
                                                                            Function3<A,B,C,CompletionStage<R>> function)

Composes multiple stages into another stage using a function.

Type Parameters:

R - the type of the composed CompletionStage.

A - the type of the first stage's value.

B - the type of the second stage's value.

C - the type of the third stage's value.

Parameters:

a - the first stage.

b - the second stage.

c - the third stage.

function - the combining function.

Returns:

a stage that is composed from the input stages using the function.

Throws:

UnsupportedOperationException - if any of the CompletionStages do not interoperate with CompletableFuture

combineFutures

public static <R,A,B,C,D> CompletionStage<R> combineFutures(CompletionStage<A> a,
                                                                                    CompletionStage<B> b,
                                                                                    CompletionStage<C> c,
                                                                                    CompletionStage<D> d,
                                                                                    Function4<A,B,C,D,CompletionStage<R>> function)

Composes multiple stages into another stage using a function.

Type Parameters:

R - the type of the composed CompletionStage.

A - the type of the first stage's value.

B - the type of the second stage's value.

C - the type of the third stage's value.

D - the type of the fourth stage's value.

Parameters:

a - the first stage.

b - the second stage.

c - the third stage.

d - the fourth stage.

function - the combining function.

Returns:

a stage that is composed from the input stages using the function.

Throws:

UnsupportedOperationException - if any of the CompletionStages do not interoperate with CompletableFuture

combineFutures

public static <R,A,B,C,D,E> CompletionStage<R> combineFutures(CompletionStage<A> a,
                                                                                            CompletionStage<B> b,
                                                                                            CompletionStage<C> c,
                                                                                            CompletionStage<D> d,
                                                                                            CompletionStage<E> e,
                                                                                            Function5<A,B,C,D,E,CompletionStage<R>> function)

Composes multiple stages into another stage using a function.

Type Parameters:

R - the type of the composed CompletionStage.

A - the type of the first stage's value.

B - the type of the second stage's value.

C - the type of the third stage's value.

D - the type of the fourth stage's value.

E - the type of the fifth stage's value.

Parameters:

a - the first stage.

b - the second stage.

c - the third stage.

d - the fourth stage.

e - the fifth stage.

function - the combining function.

Returns:

a stage that is composed from the input stages using the function.

Throws:

UnsupportedOperationException - if any of the CompletionStages do not interoperate with CompletableFuture

combineFutures

public static <R,A,B,C,D,E,F> CompletionStage<R> combineFutures(CompletionStage<A> a,
                                                                                                    CompletionStage<B> b,
                                                                                                    CompletionStage<C> c,
                                                                                                    CompletionStage<D> d,
                                                                                                    CompletionStage<E> e,
                                                                                                    CompletionStage<F> f,
                                                                                                    Function6<A,B,C,D,E,F,CompletionStage<R>> function)

Composes multiple stages into another stage using a function.

Type Parameters:

R - the type of the composed CompletionStage.

A - the type of the first stage's value.

B - the type of the second stage's value.

C - the type of the third stage's value.

D - the type of the fourth stage's value.

E - the type of the fifth stage's value.

F - the type of the sixth stage's value.

Parameters:

a - the first stage.

b - the second stage.

c - the third stage.

d - the fourth stage.

e - the fifth stage.

f - the sixth stage.

function - the combining function.

Returns:

a stage that is composed from the input stages using the function.

Throws:

UnsupportedOperationException - if any of the CompletionStages do not interoperate with CompletableFuture

poll

public static <T> CompletableFuture<T> poll(Supplier<Optional<T>> pollingTask,
                                            Duration frequency,
                                            ScheduledExecutorService executorService)

Polls an external resource periodically until it returns a non-empty result.

The polling task should return Optional.empty() until it becomes available, and then Optional.of(result). If the polling task throws an exception or returns null, that will cause the result future to complete exceptionally.

Canceling the returned future will cancel the scheduled polling task as well.

Note that on a ScheduledThreadPoolExecutor the polling task might remain allocated for up to frequency time after completing or being cancelled. If you have lots of polling operations or a long polling frequency, consider setting removeOnCancelPolicy to true. See ScheduledThreadPoolExecutor.setRemoveOnCancelPolicy(boolean).

Type Parameters:

T - the type of the result of the polling task, that will be returned when the task succeeds.

Parameters:

pollingTask - the polling task

frequency - the frequency to run the polling task at

executorService - the executor service to schedule the polling task on

Returns:

a future completing to the result of the polling task once that becomes available