java.util.concurrent

Class CompletableFuture<T>

java.lang.Object

java.util.concurrent.CompletableFuture<T>

All Implemented Interfaces:

Future<T>

public class CompletableFuture<T>
extends Object
implements Future<T>

A Future that may be explicitly completed (setting its value and status), and may include dependent functions and actions that trigger upon its completion.

When two or more threads attempt to complete, completeExceptionally, or cancel a CompletableFuture, only one of them succeeds.

Methods are available for adding dependents based on user-provided Functions, Consumers, or Runnables. The appropriate form to use depends on whether actions require arguments and/or produce results. Completion of a dependent action will trigger the completion of another CompletableFuture. Actions may also be triggered after either or both the current and another CompletableFuture complete. Multiple CompletableFutures may also be grouped as one using anyOf(CompletableFuture...) and allOf(CompletableFuture...).

CompletableFutures themselves do not execute asynchronously. However, actions supplied for dependent completions of another CompletableFuture may do so, depending on whether they are provided via one of the async methods (that is, methods with names of the form xxxAsync). The async methods provide a way to commence asynchronous processing of an action using either a given Executor or by default the ForkJoinPool.commonPool(). To simplify monitoring, debugging, and tracking, all generated asynchronous tasks are instances of the marker interface CompletableFuture.AsynchronousCompletionTask.

Actions supplied for dependent completions of non-async methods may be performed by the thread that completes the current CompletableFuture, or by any other caller of these methods. There are no guarantees about the order of processing completions unless constrained by these methods.

Since (unlike FutureTask) this class has no direct control over the computation that causes it to be completed, cancellation is treated as just another form of exceptional completion. Method cancel has the same effect as completeExceptionally(new CancellationException()).

Upon exceptional completion (including cancellation), or when a completion entails an additional computation which terminates abruptly with an (unchecked) exception or error, then all of their dependent completions (and their dependents in turn) generally act as completeExceptionally with a CompletionException holding that exception as its cause. However, the exceptionally and handle completions are able to handle exceptional completions of the CompletableFutures they depend on.

In case of exceptional completion with a CompletionException, methods get() and get(long, TimeUnit) throw an ExecutionException with the same cause as held in the corresponding CompletionException. However, in these cases, methods join() and getNow(T) throw the CompletionException, which simplifies usage.

Arguments used to pass a completion result (that is, for parameters of type T) may be null, but passing a null value for any other parameter will result in a NullPointerException being thrown.

Since:

1.8

Author:

Doug Lea

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	CompletableFuture.AsynchronousCompletionTask A marker interface identifying asynchronous tasks produced by async methods.

Constructor Summary

Constructors

Constructor and Description
CompletableFuture() Creates a new incomplete CompletableFuture.

Method Summary

Modifier and Type	Method and Description
CompletableFuture<Void>	acceptEither(CompletableFuture<? extends T> other, Consumer<? super T> block) Returns a new CompletableFuture that is completed when either this or the other given CompletableFuture completes, after performing the given action with the result of either this or the other CompletableFuture's result.
CompletableFuture<Void>	acceptEitherAsync(CompletableFuture<? extends T> other, Consumer<? super T> block) Returns a new CompletableFuture that is asynchronously completed when either this or the other given CompletableFuture completes, after performing the given action with the result of either this or the other CompletableFuture's result from a task running in the ForkJoinPool.commonPool().
CompletableFuture<Void>	acceptEitherAsync(CompletableFuture<? extends T> other, Consumer<? super T> block, Executor executor) Returns a new CompletableFuture that is asynchronously completed when either this or the other given CompletableFuture completes, after performing the given action with the result of either this or the other CompletableFuture's result from a task running in the given executor.
static CompletableFuture<Void>	allOf(CompletableFuture<?>... cfs) Returns a new CompletableFuture that is completed when all of the given CompletableFutures complete.
static CompletableFuture<Object>	anyOf(CompletableFuture<?>... cfs) Returns a new CompletableFuture that is completed when any of the given CompletableFutures complete, with the same result.
<U> CompletableFuture<U>	applyToEither(CompletableFuture<? extends T> other, Function<? super T,U> fn) Returns a new CompletableFuture that is completed when either this or the other given CompletableFuture completes, with the result of the given function of either this or the other CompletableFuture's result.
<U> CompletableFuture<U>	applyToEitherAsync(CompletableFuture<? extends T> other, Function<? super T,U> fn) Returns a new CompletableFuture that is asynchronously completed when either this or the other given CompletableFuture completes, with the result of the given function of either this or the other CompletableFuture's result from a task running in the ForkJoinPool.commonPool().
<U> CompletableFuture<U>	applyToEitherAsync(CompletableFuture<? extends T> other, Function<? super T,U> fn, Executor executor) Returns a new CompletableFuture that is asynchronously completed when either this or the other given CompletableFuture completes, with the result of the given function of either this or the other CompletableFuture's result from a task running in the given executor.
boolean	cancel(boolean mayInterruptIfRunning) If not already completed, completes this CompletableFuture with a CancellationException.
boolean	complete(T value) If not already completed, sets the value returned by get() and related methods to the given value.
static <U> CompletableFuture<U>	completedFuture(U value) Returns a new CompletableFuture that is already completed with the given value.
boolean	completeExceptionally(Throwable ex) If not already completed, causes invocations of get() and related methods to throw the given exception.
CompletableFuture<T>	exceptionally(Function<Throwable,? extends T> fn) Returns a new CompletableFuture that is completed when this CompletableFuture completes, with the result of the given function of the exception triggering this CompletableFuture's completion when it completes exceptionally; otherwise, if this CompletableFuture completes normally, then the returned CompletableFuture also completes normally with the same value.
T	get() Waits if necessary for this future to complete, and then returns its result.
T	get(long timeout, TimeUnit unit) Waits if necessary for at most the given time for this future to complete, and then returns its result, if available.
T	getNow(T valueIfAbsent) Returns the result value (or throws any encountered exception) if completed, else returns the given valueIfAbsent.
int	getNumberOfDependents() Returns the estimated number of CompletableFutures whose completions are awaiting completion of this CompletableFuture.
<U> CompletableFuture<U>	handle(BiFunction<? super T,Throwable,? extends U> fn) Returns a new CompletableFuture that is completed when this CompletableFuture completes, with the result of the given function of the result and exception of this CompletableFuture's completion.
boolean	isCancelled() Returns true if this CompletableFuture was cancelled before it completed normally.
boolean	isDone() Returns true if completed in any fashion: normally, exceptionally, or via cancellation.
T	join() Returns the result value when complete, or throws an (unchecked) exception if completed exceptionally.
void	obtrudeException(Throwable ex) Forcibly causes subsequent invocations of method get() and related methods to throw the given exception, whether or not already completed.
void	obtrudeValue(T value) Forcibly sets or resets the value subsequently returned by method get() and related methods, whether or not already completed.
CompletableFuture<Void>	runAfterBoth(CompletableFuture<?> other, Runnable action) Returns a new CompletableFuture that is completed when both this and the other given CompletableFuture complete, after performing the given action.
CompletableFuture<Void>	runAfterBothAsync(CompletableFuture<?> other, Runnable action) Returns a new CompletableFuture that is asynchronously completed when both this and the other given CompletableFuture complete, after performing the given action from a task running in the ForkJoinPool.commonPool().
CompletableFuture<Void>	runAfterBothAsync(CompletableFuture<?> other, Runnable action, Executor executor) Returns a new CompletableFuture that is asynchronously completed when both this and the other given CompletableFuture complete, after performing the given action from a task running in the given executor.
CompletableFuture<Void>	runAfterEither(CompletableFuture<?> other, Runnable action) Returns a new CompletableFuture that is completed when either this or the other given CompletableFuture completes, after performing the given action.
CompletableFuture<Void>	runAfterEitherAsync(CompletableFuture<?> other, Runnable action) Returns a new CompletableFuture that is asynchronously completed when either this or the other given CompletableFuture completes, after performing the given action from a task running in the ForkJoinPool.commonPool().
CompletableFuture<Void>	runAfterEitherAsync(CompletableFuture<?> other, Runnable action, Executor executor) Returns a new CompletableFuture that is asynchronously completed when either this or the other given CompletableFuture completes, after performing the given action from a task running in the given executor.
static CompletableFuture<Void>	runAsync(Runnable runnable) Returns a new CompletableFuture that is asynchronously completed by a task running in the ForkJoinPool.commonPool() after it runs the given action.
static CompletableFuture<Void>	runAsync(Runnable runnable, Executor executor) Returns a new CompletableFuture that is asynchronously completed by a task running in the given executor after it runs the given action.
static <U> CompletableFuture<U>	supplyAsync(Supplier<U> supplier) Returns a new CompletableFuture that is asynchronously completed by a task running in the ForkJoinPool.commonPool() with the value obtained by calling the given Supplier.
static <U> CompletableFuture<U>	supplyAsync(Supplier<U> supplier, Executor executor) Returns a new CompletableFuture that is asynchronously completed by a task running in the given executor with the value obtained by calling the given Supplier.
CompletableFuture<Void>	thenAccept(Consumer<? super T> block) Returns a new CompletableFuture that is completed when this CompletableFuture completes, after performing the given action with this CompletableFuture's result.
CompletableFuture<Void>	thenAcceptAsync(Consumer<? super T> block) Returns a new CompletableFuture that is asynchronously completed when this CompletableFuture completes, after performing the given action with this CompletableFuture's result from a task running in the ForkJoinPool.commonPool().
CompletableFuture<Void>	thenAcceptAsync(Consumer<? super T> block, Executor executor) Returns a new CompletableFuture that is asynchronously completed when this CompletableFuture completes, after performing the given action with this CompletableFuture's result from a task running in the given executor.
<U> CompletableFuture<Void>	thenAcceptBoth(CompletableFuture<? extends U> other, BiConsumer<? super T,? super U> block) Returns a new CompletableFuture that is completed when both this and the other given CompletableFuture complete, after performing the given action with the results of the two CompletableFutures.
<U> CompletableFuture<Void>	thenAcceptBothAsync(CompletableFuture<? extends U> other, BiConsumer<? super T,? super U> block) Returns a new CompletableFuture that is asynchronously completed when both this and the other given CompletableFuture complete, after performing the given action with the results of the two CompletableFutures from a task running in the ForkJoinPool.commonPool().
<U> CompletableFuture<Void>	thenAcceptBothAsync(CompletableFuture<? extends U> other, BiConsumer<? super T,? super U> block, Executor executor) Returns a new CompletableFuture that is asynchronously completed when both this and the other given CompletableFuture complete, after performing the given action with the results of the two CompletableFutures from a task running in the given executor.
<U> CompletableFuture<U>	thenApply(Function<? super T,? extends U> fn) Returns a new CompletableFuture that is completed when this CompletableFuture completes, with the result of the given function of this CompletableFuture's result.
<U> CompletableFuture<U>	thenApplyAsync(Function<? super T,? extends U> fn) Returns a new CompletableFuture that is asynchronously completed when this CompletableFuture completes, with the result of the given function of this CompletableFuture's result from a task running in the ForkJoinPool.commonPool().
<U> CompletableFuture<U>	thenApplyAsync(Function<? super T,? extends U> fn, Executor executor) Returns a new CompletableFuture that is asynchronously completed when this CompletableFuture completes, with the result of the given function of this CompletableFuture's result from a task running in the given executor.
<U,V> CompletableFuture<V>	thenCombine(CompletableFuture<? extends U> other, BiFunction<? super T,? super U,? extends V> fn) Returns a new CompletableFuture that is completed when both this and the other given CompletableFuture complete, with the result of the given function of the results of the two CompletableFutures.
<U,V> CompletableFuture<V>	thenCombineAsync(CompletableFuture<? extends U> other, BiFunction<? super T,? super U,? extends V> fn) Returns a new CompletableFuture that is asynchronously completed when both this and the other given CompletableFuture complete, with the result of the given function of the results of the two CompletableFutures from a task running in the ForkJoinPool.commonPool().
<U,V> CompletableFuture<V>	thenCombineAsync(CompletableFuture<? extends U> other, BiFunction<? super T,? super U,? extends V> fn, Executor executor) Returns a new CompletableFuture that is asynchronously completed when both this and the other given CompletableFuture complete, with the result of the given function of the results of the two CompletableFutures from a task running in the given executor.
<U> CompletableFuture<U>	thenCompose(Function<? super T,CompletableFuture<U>> fn) Returns a CompletableFuture that upon completion, has the same value as produced by the given function of the result of this CompletableFuture.
<U> CompletableFuture<U>	thenComposeAsync(Function<? super T,CompletableFuture<U>> fn) Returns a CompletableFuture that upon completion, has the same value as that produced asynchronously using the ForkJoinPool.commonPool() by the given function of the result of this CompletableFuture.
<U> CompletableFuture<U>	thenComposeAsync(Function<? super T,CompletableFuture<U>> fn, Executor executor) Returns a CompletableFuture that upon completion, has the same value as that produced asynchronously using the given executor by the given function of this CompletableFuture.
CompletableFuture<Void>	thenRun(Runnable action) Returns a new CompletableFuture that is completed when this CompletableFuture completes, after performing the given action.
CompletableFuture<Void>	thenRunAsync(Runnable action) Returns a new CompletableFuture that is asynchronously completed when this CompletableFuture completes, after performing the given action from a task running in the ForkJoinPool.commonPool().
CompletableFuture<Void>	thenRunAsync(Runnable action, Executor executor) Returns a new CompletableFuture that is asynchronously completed when this CompletableFuture completes, after performing the given action from a task running in the given executor.
String	toString() Returns a string identifying this CompletableFuture, as well as its completion state.

Methods inherited from class java.lang.Object

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

Constructor Detail

CompletableFuture

public CompletableFuture()

Creates a new incomplete CompletableFuture.

Method Detail

supplyAsync

public static <U> CompletableFuture<U> supplyAsync(Supplier<U> supplier)

Returns a new CompletableFuture that is asynchronously completed by a task running in the ForkJoinPool.commonPool() with the value obtained by calling the given Supplier.

Parameters:

supplier - a function returning the value to be used to complete the returned CompletableFuture

Returns:

the new CompletableFuture

supplyAsync

public static <U> CompletableFuture<U> supplyAsync(Supplier<U> supplier,
                                                   Executor executor)

Returns a new CompletableFuture that is asynchronously completed by a task running in the given executor with the value obtained by calling the given Supplier.

Parameters:

supplier - a function returning the value to be used to complete the returned CompletableFuture

executor - the executor to use for asynchronous execution

Returns:

the new CompletableFuture

runAsync

public static CompletableFuture<Void> runAsync(Runnable runnable)

Returns a new CompletableFuture that is asynchronously completed by a task running in the ForkJoinPool.commonPool() after it runs the given action.

Parameters:

runnable - the action to run before completing the returned CompletableFuture

Returns:

the new CompletableFuture

runAsync

public static CompletableFuture<Void> runAsync(Runnable runnable,
                                               Executor executor)

Returns a new CompletableFuture that is asynchronously completed by a task running in the given executor after it runs the given action.

Parameters:

runnable - the action to run before completing the returned CompletableFuture

executor - the executor to use for asynchronous execution

Returns:

the new CompletableFuture

completedFuture

public static <U> CompletableFuture<U> completedFuture(U value)

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

Parameters:

value - the value

Returns:

the completed CompletableFuture

isDone

public boolean isDone()

Returns true if completed in any fashion: normally, exceptionally, or via cancellation.

Specified by:

isDone in interface Future<T>

Returns:

true if completed

get

public T get()
      throws InterruptedException,
             ExecutionException

Waits if necessary for this future to complete, and then returns its result.

Specified by:

get in interface Future<T>

Returns:

the result value

Throws:

CancellationException - if this future was cancelled

ExecutionException - if this future completed exceptionally

InterruptedException - if the current thread was interrupted while waiting

get

public T get(long timeout,
             TimeUnit unit)
      throws InterruptedException,
             ExecutionException,
             TimeoutException

Waits if necessary for at most the given time for this future to complete, and then returns its result, if available.

Specified by:

get in interface Future<T>

Parameters:

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

the result value

Throws:

CancellationException - if this future was cancelled

ExecutionException - if this future completed exceptionally

InterruptedException - if the current thread was interrupted while waiting

TimeoutException - if the wait timed out

join

public T join()

Returns the result value when complete, or throws an (unchecked) exception if completed exceptionally. To better conform with the use of common functional forms, if a computation involved in the completion of this CompletableFuture threw an exception, this method throws an (unchecked) CompletionException with the underlying exception as its cause.

Returns:

the result value

Throws:

CancellationException - if the computation was cancelled

CompletionException - if this future completed exceptionally or a completion computation threw an exception

getNow

public T getNow(T valueIfAbsent)

Returns the result value (or throws any encountered exception) if completed, else returns the given valueIfAbsent.

Parameters:

valueIfAbsent - the value to return if not completed

Returns:

the result value, if completed, else the given valueIfAbsent

Throws:

CancellationException - if the computation was cancelled

CompletionException - if this future completed exceptionally or a completion computation threw an exception

complete

public boolean complete(T value)

If not already completed, sets the value returned by get() and related methods to the given value.

Parameters:

value - the result value

Returns:

true if this invocation caused this CompletableFuture to transition to a completed state, else false

completeExceptionally

public boolean completeExceptionally(Throwable ex)

If not already completed, causes invocations of get() and related methods to throw the given exception.

Parameters:

ex - the exception

Returns:

true if this invocation caused this CompletableFuture to transition to a completed state, else false

thenApply

public <U> CompletableFuture<U> thenApply(Function<? super T,? extends U> fn)

Returns a new CompletableFuture that is completed when this CompletableFuture completes, with the result of the given function of this CompletableFuture's result.

If this CompletableFuture completes exceptionally, or the supplied function throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

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

Returns:

the new CompletableFuture

thenApplyAsync

public <U> CompletableFuture<U> thenApplyAsync(Function<? super T,? extends U> fn)

Returns a new CompletableFuture that is asynchronously completed when this CompletableFuture completes, with the result of the given function of this CompletableFuture's result from a task running in the ForkJoinPool.commonPool().

If this CompletableFuture completes exceptionally, or the supplied function throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

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

Returns:

the new CompletableFuture

thenApplyAsync

public <U> CompletableFuture<U> thenApplyAsync(Function<? super T,? extends U> fn,
                                               Executor executor)

Returns a new CompletableFuture that is asynchronously completed when this CompletableFuture completes, with the result of the given function of this CompletableFuture's result from a task running in the given executor.

If this CompletableFuture completes exceptionally, or the supplied function throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

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

executor - the executor to use for asynchronous execution

Returns:

the new CompletableFuture

thenAccept

public CompletableFuture<Void> thenAccept(Consumer<? super T> block)

Returns a new CompletableFuture that is completed when this CompletableFuture completes, after performing the given action with this CompletableFuture's result.

If this CompletableFuture completes exceptionally, or the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

block - the action to perform before completing the returned CompletableFuture

Returns:

the new CompletableFuture

thenAcceptAsync

public CompletableFuture<Void> thenAcceptAsync(Consumer<? super T> block)

Returns a new CompletableFuture that is asynchronously completed when this CompletableFuture completes, after performing the given action with this CompletableFuture's result from a task running in the ForkJoinPool.commonPool().

If this CompletableFuture completes exceptionally, or the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

block - the action to perform before completing the returned CompletableFuture

Returns:

the new CompletableFuture

thenAcceptAsync

public CompletableFuture<Void> thenAcceptAsync(Consumer<? super T> block,
                                               Executor executor)

Returns a new CompletableFuture that is asynchronously completed when this CompletableFuture completes, after performing the given action with this CompletableFuture's result from a task running in the given executor.

If this CompletableFuture completes exceptionally, or the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

block - the action to perform before completing the returned CompletableFuture

executor - the executor to use for asynchronous execution

Returns:

the new CompletableFuture

thenRun

public CompletableFuture<Void> thenRun(Runnable action)

Returns a new CompletableFuture that is completed when this CompletableFuture completes, after performing the given action.

If this CompletableFuture completes exceptionally, or the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

action - the action to perform before completing the returned CompletableFuture

Returns:

the new CompletableFuture

thenRunAsync

public CompletableFuture<Void> thenRunAsync(Runnable action)

Returns a new CompletableFuture that is asynchronously completed when this CompletableFuture completes, after performing the given action from a task running in the ForkJoinPool.commonPool().

If this CompletableFuture completes exceptionally, or the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

action - the action to perform before completing the returned CompletableFuture

Returns:

the new CompletableFuture

thenRunAsync

public CompletableFuture<Void> thenRunAsync(Runnable action,
                                            Executor executor)

Returns a new CompletableFuture that is asynchronously completed when this CompletableFuture completes, after performing the given action from a task running in the given executor.

If this CompletableFuture completes exceptionally, or the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

action - the action to perform before completing the returned CompletableFuture

executor - the executor to use for asynchronous execution

Returns:

the new CompletableFuture

thenCombine

public <U,V> CompletableFuture<V> thenCombine(CompletableFuture<? extends U> other,
                                              BiFunction<? super T,? super U,? extends V> fn)

Returns a new CompletableFuture that is completed when both this and the other given CompletableFuture complete, with the result of the given function of the results of the two CompletableFutures.

If this and/or the other CompletableFuture complete exceptionally, or the supplied function throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

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

Returns:

the new CompletableFuture

thenCombineAsync

public <U,V> CompletableFuture<V> thenCombineAsync(CompletableFuture<? extends U> other,
                                                   BiFunction<? super T,? super U,? extends V> fn)

Returns a new CompletableFuture that is asynchronously completed when both this and the other given CompletableFuture complete, with the result of the given function of the results of the two CompletableFutures from a task running in the ForkJoinPool.commonPool().

If this and/or the other CompletableFuture complete exceptionally, or the supplied function throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

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

Returns:

the new CompletableFuture

thenCombineAsync

public <U,V> CompletableFuture<V> thenCombineAsync(CompletableFuture<? extends U> other,
                                                   BiFunction<? super T,? super U,? extends V> fn,
                                                   Executor executor)

Returns a new CompletableFuture that is asynchronously completed when both this and the other given CompletableFuture complete, with the result of the given function of the results of the two CompletableFutures from a task running in the given executor.

If this and/or the other CompletableFuture complete exceptionally, or the supplied function throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

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

executor - the executor to use for asynchronous execution

Returns:

the new CompletableFuture

thenAcceptBoth

public <U> CompletableFuture<Void> thenAcceptBoth(CompletableFuture<? extends U> other,
                                                  BiConsumer<? super T,? super U> block)

Returns a new CompletableFuture that is completed when both this and the other given CompletableFuture complete, after performing the given action with the results of the two CompletableFutures.

If this and/or the other CompletableFuture complete exceptionally, or the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

block - the action to perform before completing the returned CompletableFuture

Returns:

the new CompletableFuture

thenAcceptBothAsync

public <U> CompletableFuture<Void> thenAcceptBothAsync(CompletableFuture<? extends U> other,
                                                       BiConsumer<? super T,? super U> block)

Returns a new CompletableFuture that is asynchronously completed when both this and the other given CompletableFuture complete, after performing the given action with the results of the two CompletableFutures from a task running in the ForkJoinPool.commonPool().

If this and/or the other CompletableFuture complete exceptionally, or the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

block - the action to perform before completing the returned CompletableFuture

Returns:

the new CompletableFuture

thenAcceptBothAsync

public <U> CompletableFuture<Void> thenAcceptBothAsync(CompletableFuture<? extends U> other,
                                                       BiConsumer<? super T,? super U> block,
                                                       Executor executor)

Returns a new CompletableFuture that is asynchronously completed when both this and the other given CompletableFuture complete, after performing the given action with the results of the two CompletableFutures from a task running in the given executor.

If this and/or the other CompletableFuture complete exceptionally, or the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

block - the action to perform before completing the returned CompletableFuture

executor - the executor to use for asynchronous execution

Returns:

the new CompletableFuture

runAfterBoth

public CompletableFuture<Void> runAfterBoth(CompletableFuture<?> other,
                                            Runnable action)

Returns a new CompletableFuture that is completed when both this and the other given CompletableFuture complete, after performing the given action.

If this and/or the other CompletableFuture complete exceptionally, or the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

action - the action to perform before completing the returned CompletableFuture

Returns:

the new CompletableFuture

runAfterBothAsync

public CompletableFuture<Void> runAfterBothAsync(CompletableFuture<?> other,
                                                 Runnable action)

Returns a new CompletableFuture that is asynchronously completed when both this and the other given CompletableFuture complete, after performing the given action from a task running in the ForkJoinPool.commonPool().

If this and/or the other CompletableFuture complete exceptionally, or the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

action - the action to perform before completing the returned CompletableFuture

Returns:

the new CompletableFuture

runAfterBothAsync

public CompletableFuture<Void> runAfterBothAsync(CompletableFuture<?> other,
                                                 Runnable action,
                                                 Executor executor)

Returns a new CompletableFuture that is asynchronously completed when both this and the other given CompletableFuture complete, after performing the given action from a task running in the given executor.

If this and/or the other CompletableFuture complete exceptionally, or the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

action - the action to perform before completing the returned CompletableFuture

executor - the executor to use for asynchronous execution

Returns:

the new CompletableFuture

applyToEither

public <U> CompletableFuture<U> applyToEither(CompletableFuture<? extends T> other,
                                              Function<? super T,U> fn)

Returns a new CompletableFuture that is completed when either this or the other given CompletableFuture completes, with the result of the given function of either this or the other CompletableFuture's result.

If this and/or the other CompletableFuture complete exceptionally, then the returned CompletableFuture may also do so, with a CompletionException holding one of these exceptions as its cause. No guarantees are made about which result or exception is used in the returned CompletableFuture. If the supplied function throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

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

Returns:

the new CompletableFuture

applyToEitherAsync

public <U> CompletableFuture<U> applyToEitherAsync(CompletableFuture<? extends T> other,
                                                   Function<? super T,U> fn)

Returns a new CompletableFuture that is asynchronously completed when either this or the other given CompletableFuture completes, with the result of the given function of either this or the other CompletableFuture's result from a task running in the ForkJoinPool.commonPool().

If this and/or the other CompletableFuture complete exceptionally, then the returned CompletableFuture may also do so, with a CompletionException holding one of these exceptions as its cause. No guarantees are made about which result or exception is used in the returned CompletableFuture. If the supplied function throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

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

Returns:

the new CompletableFuture

applyToEitherAsync

public <U> CompletableFuture<U> applyToEitherAsync(CompletableFuture<? extends T> other,
                                                   Function<? super T,U> fn,
                                                   Executor executor)

Returns a new CompletableFuture that is asynchronously completed when either this or the other given CompletableFuture completes, with the result of the given function of either this or the other CompletableFuture's result from a task running in the given executor.

If this and/or the other CompletableFuture complete exceptionally, then the returned CompletableFuture may also do so, with a CompletionException holding one of these exceptions as its cause. No guarantees are made about which result or exception is used in the returned CompletableFuture. If the supplied function throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

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

executor - the executor to use for asynchronous execution

Returns:

the new CompletableFuture

acceptEither

public CompletableFuture<Void> acceptEither(CompletableFuture<? extends T> other,
                                            Consumer<? super T> block)

Returns a new CompletableFuture that is completed when either this or the other given CompletableFuture completes, after performing the given action with the result of either this or the other CompletableFuture's result.

If this and/or the other CompletableFuture complete exceptionally, then the returned CompletableFuture may also do so, with a CompletionException holding one of these exceptions as its cause. No guarantees are made about which result or exception is used in the returned CompletableFuture. If the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

block - the action to perform before completing the returned CompletableFuture

Returns:

the new CompletableFuture

acceptEitherAsync

public CompletableFuture<Void> acceptEitherAsync(CompletableFuture<? extends T> other,
                                                 Consumer<? super T> block)

Returns a new CompletableFuture that is asynchronously completed when either this or the other given CompletableFuture completes, after performing the given action with the result of either this or the other CompletableFuture's result from a task running in the ForkJoinPool.commonPool().

If this and/or the other CompletableFuture complete exceptionally, then the returned CompletableFuture may also do so, with a CompletionException holding one of these exceptions as its cause. No guarantees are made about which result or exception is used in the returned CompletableFuture. If the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

block - the action to perform before completing the returned CompletableFuture

Returns:

the new CompletableFuture

acceptEitherAsync

public CompletableFuture<Void> acceptEitherAsync(CompletableFuture<? extends T> other,
                                                 Consumer<? super T> block,
                                                 Executor executor)

Returns a new CompletableFuture that is asynchronously completed when either this or the other given CompletableFuture completes, after performing the given action with the result of either this or the other CompletableFuture's result from a task running in the given executor.

If this and/or the other CompletableFuture complete exceptionally, then the returned CompletableFuture may also do so, with a CompletionException holding one of these exceptions as its cause. No guarantees are made about which result or exception is used in the returned CompletableFuture. If the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

block - the action to perform before completing the returned CompletableFuture

executor - the executor to use for asynchronous execution

Returns:

the new CompletableFuture

runAfterEither

public CompletableFuture<Void> runAfterEither(CompletableFuture<?> other,
                                              Runnable action)

Returns a new CompletableFuture that is completed when either this or the other given CompletableFuture completes, after performing the given action.

If this and/or the other CompletableFuture complete exceptionally, then the returned CompletableFuture may also do so, with a CompletionException holding one of these exceptions as its cause. No guarantees are made about which result or exception is used in the returned CompletableFuture. If the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

action - the action to perform before completing the returned CompletableFuture

Returns:

the new CompletableFuture

runAfterEitherAsync

public CompletableFuture<Void> runAfterEitherAsync(CompletableFuture<?> other,
                                                   Runnable action)

Returns a new CompletableFuture that is asynchronously completed when either this or the other given CompletableFuture completes, after performing the given action from a task running in the ForkJoinPool.commonPool().

If this and/or the other CompletableFuture complete exceptionally, then the returned CompletableFuture may also do so, with a CompletionException holding one of these exceptions as its cause. No guarantees are made about which result or exception is used in the returned CompletableFuture. If the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

action - the action to perform before completing the returned CompletableFuture

Returns:

the new CompletableFuture

runAfterEitherAsync

public CompletableFuture<Void> runAfterEitherAsync(CompletableFuture<?> other,
                                                   Runnable action,
                                                   Executor executor)

Returns a new CompletableFuture that is asynchronously completed when either this or the other given CompletableFuture completes, after performing the given action from a task running in the given executor.

If this and/or the other CompletableFuture complete exceptionally, then the returned CompletableFuture may also do so, with a CompletionException holding one of these exceptions as its cause. No guarantees are made about which result or exception is used in the returned CompletableFuture. If the supplied action throws an exception, then the returned CompletableFuture completes exceptionally with a CompletionException holding the exception as its cause.

Parameters:

other - the other CompletableFuture

action - the action to perform before completing the returned CompletableFuture

executor - the executor to use for asynchronous execution

Returns:

the new CompletableFuture

thenCompose

public <U> CompletableFuture<U> thenCompose(Function<? super T,CompletableFuture<U>> fn)

Returns a CompletableFuture that upon completion, has the same value as produced by the given function of the result of this CompletableFuture.

If this CompletableFuture completes exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause. Similarly, if the computed CompletableFuture completes exceptionally, then so does the returned CompletableFuture.

Parameters:

fn - the function returning a new CompletableFuture

Returns:

the CompletableFuture

thenComposeAsync

public <U> CompletableFuture<U> thenComposeAsync(Function<? super T,CompletableFuture<U>> fn)

Returns a CompletableFuture that upon completion, has the same value as that produced asynchronously using the ForkJoinPool.commonPool() by the given function of the result of this CompletableFuture.

If this CompletableFuture completes exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause. Similarly, if the computed CompletableFuture completes exceptionally, then so does the returned CompletableFuture.

Parameters:

fn - the function returning a new CompletableFuture

Returns:

the CompletableFuture

thenComposeAsync

public <U> CompletableFuture<U> thenComposeAsync(Function<? super T,CompletableFuture<U>> fn,
                                                 Executor executor)

Returns a CompletableFuture that upon completion, has the same value as that produced asynchronously using the given executor by the given function of this CompletableFuture.

If this CompletableFuture completes exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause. Similarly, if the computed CompletableFuture completes exceptionally, then so does the returned CompletableFuture.

Parameters:

fn - the function returning a new CompletableFuture

executor - the executor to use for asynchronous execution

Returns:

the CompletableFuture

exceptionally

public CompletableFuture<T> exceptionally(Function<Throwable,? extends T> fn)

Returns a new CompletableFuture that is completed when this CompletableFuture completes, with the result of the given function of the exception triggering this CompletableFuture's completion when it completes exceptionally; otherwise, if this CompletableFuture completes normally, then the returned CompletableFuture also completes normally with the same value.

Parameters:

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

Returns:

the new CompletableFuture

handle

public <U> CompletableFuture<U> handle(BiFunction<? super T,Throwable,? extends U> fn)

Returns a new CompletableFuture that is completed when this CompletableFuture completes, with the result of the given function of the result and exception of this CompletableFuture's completion. The given function is invoked with the result (or null if none) and the exception (or null if none) of this CompletableFuture when complete.

Parameters:

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

Returns:

the new CompletableFuture

allOf

public static CompletableFuture<Void> allOf(CompletableFuture<?>... cfs)

Returns a new CompletableFuture that is completed when all of the given CompletableFutures complete. If any of the given CompletableFutures complete exceptionally, then the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause. Otherwise, the results, if any, of the given CompletableFutures are not reflected in the returned CompletableFuture, but may be obtained by inspecting them individually. If no CompletableFutures are provided, returns a CompletableFuture completed with the value null.

Among the applications of this method is to await completion of a set of independent CompletableFutures before continuing a program, as in: CompletableFuture.allOf(c1, c2, c3).join();.

Parameters:

cfs - the CompletableFutures

Returns:

a new CompletableFuture that is completed when all of the given CompletableFutures complete

Throws:

NullPointerException - if the array or any of its elements are null

anyOf

public static CompletableFuture<Object> anyOf(CompletableFuture<?>... cfs)

Returns a new CompletableFuture that is completed when any of the given CompletableFutures complete, with the same result. Otherwise, if it completed exceptionally, the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause. If no CompletableFutures are provided, returns an incomplete CompletableFuture.

Parameters:

cfs - the CompletableFutures

Returns:

a new CompletableFuture that is completed with the result or exception of any of the given CompletableFutures when one completes

Throws:

NullPointerException - if the array or any of its elements are null

cancel

public boolean cancel(boolean mayInterruptIfRunning)

If not already completed, completes this CompletableFuture with a CancellationException. Dependent CompletableFutures that have not already completed will also complete exceptionally, with a CompletionException caused by this CancellationException.

Specified by:

cancel in interface Future<T>

Parameters:

mayInterruptIfRunning - this value has no effect in this implementation because interrupts are not used to control processing.

Returns:

true if this task is now cancelled

isCancelled

public boolean isCancelled()

Returns true if this CompletableFuture was cancelled before it completed normally.

Specified by:

isCancelled in interface Future<T>

Returns:

true if this CompletableFuture was cancelled before it completed normally

obtrudeValue

public void obtrudeValue(T value)

Forcibly sets or resets the value subsequently returned by method get() and related methods, whether or not already completed. This method is designed for use only in error recovery actions, and even in such situations may result in ongoing dependent completions using established versus overwritten outcomes.

Parameters:

value - the completion value

obtrudeException

public void obtrudeException(Throwable ex)

Forcibly causes subsequent invocations of method get() and related methods to throw the given exception, whether or not already completed. This method is designed for use only in recovery actions, and even in such situations may result in ongoing dependent completions using established versus overwritten outcomes.

Parameters:

ex - the exception

getNumberOfDependents

public int getNumberOfDependents()

Returns the estimated number of CompletableFutures whose completions are awaiting completion of this CompletableFuture. This method is designed for use in monitoring system state, not for synchronization control.

Returns:

the number of dependent CompletableFutures

toString

public String toString()

Returns a string identifying this CompletableFuture, as well as its completion state. The state, in brackets, contains the String "Completed Normally" or the String "Completed Exceptionally", or the String "Not completed" followed by the number of CompletableFutures dependent upon its completion, if any.

Overrides:

toString in class Object

Returns:

a string identifying this CompletableFuture, as well as its state