com.spotify.futures

Class CompletableFutures

java.lang.Object

com.spotify.futures.CompletableFutures

public final class CompletableFutures
extends Object

A collection of static utility methods that extend the Java completable future API.

Since:

0.1.0

Method Summary

Modifier and Type	Method and Description
static <T> CompletableFuture<List<T>>	allAsList(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 void	checkCompleted(CompletionStage<?> stage) Checks that a stage is completed.
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 <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,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> 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> 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> 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 <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,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> 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> 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 <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> CompletableFuture<T>	exceptionallyCompletedFuture(Throwable throwable) Returns a new CompletableFuture that is already exceptionally completed with the given exception.
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> CompletableFuture<T>	poll(Supplier<Optional<T>> pollingTask, Duration frequency, ScheduledExecutorService executorService) Polls an external resource periodically until it returns a non-empty result.
static <T> CompletableFuture<List<T>>	successfulAsList(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.

Methods inherited from class java.lang.Object

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

Method Detail

allAsList

public static <T> CompletableFuture<List<T>> allAsList(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.

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 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

successfulAsList

public static <T> CompletableFuture<List<T>> successfulAsList(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

exceptionallyCompletedFuture

public static <T> CompletableFuture<T> exceptionallyCompletedFuture(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

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

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