CompletableFuture

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

A Future that may be explicitly completed (setting its value and status), and may be used as a CompletionStage, supporting 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.

In addition to these and related methods for directly manipulating status and results, CompletableFuture implements interface CompletionStage with the following policies:

• 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 a completion method.
• All async methods without an explicit Executor argument are performed using the ForkJoinPool.commonPool() (unless it does not support a parallelism level of at least two, in which case, a new Thread is created to run each task). To simplify monitoring, debugging, and tracking, all generated asynchronous tasks are instances of the marker interface CompletableFuture.AsynchronousCompletionTask. Operations with time-delays can use adapter methods defined in this class, for example: supplyAsync(supplier, delayedExecutor(timeout, timeUnit)). To support methods with delays and timeouts, this class maintains at most one daemon thread for triggering and cancelling actions, not for running them.
• All CompletionStage methods are implemented independently of other public methods, so the behavior of one method is not impacted by overrides of others in subclasses.

CompletableFuture also implements Future with the following policies:

• 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()). Method isCompletedExceptionally() can be used to determine if a CompletableFuture completed in any exceptional fashion.
• 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. To simplify usage in most contexts, this class also defines methods join() and getNow(T) that instead throw the CompletionException directly in these cases.

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

Nested Class Summary

interface

CompletableFuture.AsynchronousCompletionTask

A marker interface identifying asynchronous tasks produced by async methods.

Public Constructor Summary

CompletableFuture() Creates a new incomplete CompletableFuture.

Public Method Summary

CompletableFuture<Void>	acceptEither(CompletionStage<? extends T> other, Consumer<? super T> action) Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed with the corresponding result as argument to the supplied action.
CompletableFuture<Void>	acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action) Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using this stage's default asynchronous execution facility, with the corresponding result as argument to the supplied action.
CompletableFuture<Void>	acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action, Executor executor) Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using the supplied executor, with the corresponding result as argument to the supplied action.
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(CompletionStage<? extends T> other, Function<? super T, U> fn) Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed with the corresponding result as argument to the supplied function.
<U> CompletableFuture<U>	applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T, U> fn) Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using this stage's default asynchronous execution facility, with the corresponding result as argument to the supplied function.
<U> CompletableFuture<U>	applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T, U> fn, Executor executor) Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using the supplied executor, with the corresponding result as argument to the supplied function.
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.
boolean	completeExceptionally(Throwable ex) If not already completed, causes invocations of get() and related methods to throw the given exception.
static <U> CompletableFuture<U>	completedFuture(U value) Returns a new CompletableFuture that is already completed with the given value.
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(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	get() Waits if necessary for this future to complete, and then returns its result.
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 CompletionStage that, when this stage completes either normally or exceptionally, is executed with this stage's result and exception as arguments to the supplied function.
<U> CompletableFuture<U>	handleAsync(BiFunction<? super T, Throwable, ? extends U> fn, Executor executor) Returns a new CompletionStage that, when this stage completes either normally or exceptionally, is executed using the supplied executor, with this stage's result and exception as arguments to the supplied function.
<U> CompletableFuture<U>	handleAsync(BiFunction<? super T, Throwable, ? extends U> fn) Returns a new CompletionStage that, when this stage completes either normally or exceptionally, is executed using this stage's default asynchronous execution facility, with this stage's result and exception as arguments to the supplied function.
boolean	isCancelled() Returns true if this CompletableFuture was cancelled before it completed normally.
boolean	isCompletedExceptionally() Returns true if this CompletableFuture completed exceptionally, in any way.
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(CompletionStage<?> other, Runnable action) Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action.
CompletableFuture<Void>	runAfterBothAsync(CompletionStage<?> other, Runnable action) Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action using this stage's default asynchronous execution facility.
CompletableFuture<Void>	runAfterBothAsync(CompletionStage<?> other, Runnable action, Executor executor) Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action using the supplied executor.
CompletableFuture<Void>	runAfterEither(CompletionStage<?> other, Runnable action) Returns a new CompletionStage that, when either this or the other given stage complete normally, executes the given action.
CompletableFuture<Void>	runAfterEitherAsync(CompletionStage<?> other, Runnable action, Executor executor) Returns a new CompletionStage that, when either this or the other given stage complete normally, executes the given action using the supplied executor.
CompletableFuture<Void>	runAfterEitherAsync(CompletionStage<?> other, Runnable action) Returns a new CompletionStage that, when either this or the other given stage complete normally, executes the given action using this stage's default asynchronous execution facility.
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> action) Returns a new CompletionStage that, when this stage completes normally, is executed with this stage's result as the argument to the supplied action.
CompletableFuture<Void>	thenAcceptAsync(Consumer<? super T> action, Executor executor) Returns a new CompletionStage that, when this stage completes normally, is executed using the supplied Executor, with this stage's result as the argument to the supplied action.
CompletableFuture<Void>	thenAcceptAsync(Consumer<? super T> action) Returns a new CompletionStage that, when this stage completes normally, is executed using this stage's default asynchronous execution facility, with this stage's result as the argument to the supplied action.
<U> CompletableFuture<Void>	thenAcceptBoth(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action) Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed with the two results as arguments to the supplied action.
<U> CompletableFuture<Void>	thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action, Executor executor) Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using the supplied executor, with the two results as arguments to the supplied action.
<U> CompletableFuture<Void>	thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action) Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using this stage's default asynchronous execution facility, with the two results as arguments to the supplied action.
<U> CompletableFuture<U>	thenApply(Function<? super T, ? extends U> fn) Returns a new CompletionStage that, when this stage completes normally, is executed with this stage's result as the argument to the supplied function.
<U> CompletableFuture<U>	thenApplyAsync(Function<? super T, ? extends U> fn) Returns a new CompletionStage that, when this stage completes normally, is executed using this stage's default asynchronous execution facility, with this stage's result as the argument to the supplied function.
<U> CompletableFuture<U>	thenApplyAsync(Function<? super T, ? extends U> fn, Executor executor) Returns a new CompletionStage that, when this stage completes normally, is executed using the supplied Executor, with this stage's result as the argument to the supplied function.
<U, V> CompletableFuture<V>	thenCombine(CompletionStage<? extends U> other, BiFunction<? super T, ? super U, ? extends V> fn) Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed with the two results as arguments to the supplied function.
<U, V> CompletableFuture<V>	thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T, ? super U, ? extends V> fn, Executor executor) Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using the supplied executor, with the two results as arguments to the supplied function.
<U, V> CompletableFuture<V>	thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T, ? super U, ? extends V> fn) Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using this stage's default asynchronous execution facility, with the two results as arguments to the supplied function.
<U> CompletableFuture<U>	thenCompose(Function<? super T, ? extends CompletionStage<U>> fn) Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function.
<U> CompletableFuture<U>	thenComposeAsync(Function<? super T, ? extends CompletionStage<U>> fn, Executor executor) Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function, executed using the supplied Executor.
<U> CompletableFuture<U>	thenComposeAsync(Function<? super T, ? extends CompletionStage<U>> fn) Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function, executed using this stage's default asynchronous execution facility.
CompletableFuture<Void>	thenRun(Runnable action) Returns a new CompletionStage that, when this stage completes normally, executes the given action.
CompletableFuture<Void>	thenRunAsync(Runnable action, Executor executor) Returns a new CompletionStage that, when this stage completes normally, executes the given action using the supplied Executor.
CompletableFuture<Void>	thenRunAsync(Runnable action) Returns a new CompletionStage that, when this stage completes normally, executes the given action using this stage's default asynchronous execution facility.
CompletableFuture<T>	toCompletableFuture() Returns this CompletableFuture.
String	toString() Returns a string identifying this CompletableFuture, as well as its completion state.
CompletableFuture<T>	whenComplete(BiConsumer<? super T, ? super Throwable> action) Returns a new CompletionStage with the same result or exception as this stage, that executes the given action when this stage completes.
CompletableFuture<T>	whenCompleteAsync(BiConsumer<? super T, ? super Throwable> action) Returns a new CompletionStage with the same result or exception as this stage, that executes the given action using this stage's default asynchronous execution facility when this stage completes.
CompletableFuture<T>	whenCompleteAsync(BiConsumer<? super T, ? super Throwable> action, Executor executor) Returns a new CompletionStage with the same result or exception as this stage, that executes the given action using the supplied Executor when this stage completes.

Inherited Method Summary

From class java.lang.Object

Object	clone() Creates and returns a copy of this Object.
boolean	equals(Object obj) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of Class that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait(long timeout, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait(long timeout) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object.

From interface java.util.concurrent.Future

abstract boolean	cancel(boolean mayInterruptIfRunning) Attempts to cancel execution of this task.
abstract T	get(long timeout, TimeUnit unit) Waits if necessary for at most the given time for the computation to complete, and then retrieves its result, if available.
abstract T	get() Waits if necessary for the computation to complete, and then retrieves its result.
abstract boolean	isCancelled() Returns true if this task was cancelled before it completed normally.
abstract boolean	isDone() Returns true if this task completed.

From interface java.util.concurrent.CompletionStage

abstract CompletionStage<Void>	acceptEither(CompletionStage<? extends T> other, Consumer<? super T> action) Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed with the corresponding result as argument to the supplied action.
abstract CompletionStage<Void>	acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action, Executor executor) Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using the supplied executor, with the corresponding result as argument to the supplied action.
abstract CompletionStage<Void>	acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action) Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using this stage's default asynchronous execution facility, with the corresponding result as argument to the supplied action.
abstract <U> CompletionStage<U>	applyToEither(CompletionStage<? extends T> other, Function<? super T, U> fn) Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed with the corresponding result as argument to the supplied function.
abstract <U> CompletionStage<U>	applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T, U> fn, Executor executor) Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using the supplied executor, with the corresponding result as argument to the supplied function.
abstract <U> CompletionStage<U>	applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T, U> fn) Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using this stage's default asynchronous execution facility, with the corresponding result as argument to the supplied function.
abstract CompletionStage<T>	exceptionally(Function<Throwable, ? extends T> fn) Returns a new CompletionStage that, when this stage completes exceptionally, is executed with this stage's exception as the argument to the supplied function.
abstract <U> CompletionStage<U>	handle(BiFunction<? super T, Throwable, ? extends U> fn) Returns a new CompletionStage that, when this stage completes either normally or exceptionally, is executed with this stage's result and exception as arguments to the supplied function.
abstract <U> CompletionStage<U>	handleAsync(BiFunction<? super T, Throwable, ? extends U> fn, Executor executor) Returns a new CompletionStage that, when this stage completes either normally or exceptionally, is executed using the supplied executor, with this stage's result and exception as arguments to the supplied function.
abstract <U> CompletionStage<U>	handleAsync(BiFunction<? super T, Throwable, ? extends U> fn) Returns a new CompletionStage that, when this stage completes either normally or exceptionally, is executed using this stage's default asynchronous execution facility, with this stage's result and exception as arguments to the supplied function.
abstract CompletionStage<Void>	runAfterBoth(CompletionStage<?> other, Runnable action) Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action.
abstract CompletionStage<Void>	runAfterBothAsync(CompletionStage<?> other, Runnable action) Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action using this stage's default asynchronous execution facility.
abstract CompletionStage<Void>	runAfterBothAsync(CompletionStage<?> other, Runnable action, Executor executor) Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action using the supplied executor.
abstract CompletionStage<Void>	runAfterEither(CompletionStage<?> other, Runnable action) Returns a new CompletionStage that, when either this or the other given stage complete normally, executes the given action.
abstract CompletionStage<Void>	runAfterEitherAsync(CompletionStage<?> other, Runnable action) Returns a new CompletionStage that, when either this or the other given stage complete normally, executes the given action using this stage's default asynchronous execution facility.
abstract CompletionStage<Void>	runAfterEitherAsync(CompletionStage<?> other, Runnable action, Executor executor) Returns a new CompletionStage that, when either this or the other given stage complete normally, executes the given action using the supplied executor.
abstract CompletionStage<Void>	thenAccept(Consumer<? super T> action) Returns a new CompletionStage that, when this stage completes normally, is executed with this stage's result as the argument to the supplied action.
abstract CompletionStage<Void>	thenAcceptAsync(Consumer<? super T> action, Executor executor) Returns a new CompletionStage that, when this stage completes normally, is executed using the supplied Executor, with this stage's result as the argument to the supplied action.
abstract CompletionStage<Void>	thenAcceptAsync(Consumer<? super T> action) Returns a new CompletionStage that, when this stage completes normally, is executed using this stage's default asynchronous execution facility, with this stage's result as the argument to the supplied action.
abstract <U> CompletionStage<Void>	thenAcceptBoth(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action) Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed with the two results as arguments to the supplied action.
abstract <U> CompletionStage<Void>	thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action, Executor executor) Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using the supplied executor, with the two results as arguments to the supplied action.
abstract <U> CompletionStage<Void>	thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action) Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using this stage's default asynchronous execution facility, with the two results as arguments to the supplied action.
abstract <U> CompletionStage<U>	thenApply(Function<? super T, ? extends U> fn) Returns a new CompletionStage that, when this stage completes normally, is executed with this stage's result as the argument to the supplied function.
abstract <U> CompletionStage<U>	thenApplyAsync(Function<? super T, ? extends U> fn) Returns a new CompletionStage that, when this stage completes normally, is executed using this stage's default asynchronous execution facility, with this stage's result as the argument to the supplied function.
abstract <U> CompletionStage<U>	thenApplyAsync(Function<? super T, ? extends U> fn, Executor executor) Returns a new CompletionStage that, when this stage completes normally, is executed using the supplied Executor, with this stage's result as the argument to the supplied function.
abstract <U, V> CompletionStage<V>	thenCombine(CompletionStage<? extends U> other, BiFunction<? super T, ? super U, ? extends V> fn) Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed with the two results as arguments to the supplied function.
abstract <U, V> CompletionStage<V>	thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T, ? super U, ? extends V> fn) Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using this stage's default asynchronous execution facility, with the two results as arguments to the supplied function.
abstract <U, V> CompletionStage<V>	thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T, ? super U, ? extends V> fn, Executor executor) Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using the supplied executor, with the two results as arguments to the supplied function.
abstract <U> CompletionStage<U>	thenCompose(Function<? super T, ? extends CompletionStage<U>> fn) Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function.
abstract <U> CompletionStage<U>	thenComposeAsync(Function<? super T, ? extends CompletionStage<U>> fn, Executor executor) Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function, executed using the supplied Executor.
abstract <U> CompletionStage<U>	thenComposeAsync(Function<? super T, ? extends CompletionStage<U>> fn) Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function, executed using this stage's default asynchronous execution facility.
abstract CompletionStage<Void>	thenRun(Runnable action) Returns a new CompletionStage that, when this stage completes normally, executes the given action.
abstract CompletionStage<Void>	thenRunAsync(Runnable action, Executor executor) Returns a new CompletionStage that, when this stage completes normally, executes the given action using the supplied Executor.
abstract CompletionStage<Void>	thenRunAsync(Runnable action) Returns a new CompletionStage that, when this stage completes normally, executes the given action using this stage's default asynchronous execution facility.
abstract CompletableFuture<T>	toCompletableFuture() Returns a CompletableFuture maintaining the same completion properties as this stage.
abstract CompletionStage<T>	whenComplete(BiConsumer<? super T, ? super Throwable> action) Returns a new CompletionStage with the same result or exception as this stage, that executes the given action when this stage completes.
abstract CompletionStage<T>	whenCompleteAsync(BiConsumer<? super T, ? super Throwable> action) Returns a new CompletionStage with the same result or exception as this stage, that executes the given action using this stage's default asynchronous execution facility when this stage completes.
abstract CompletionStage<T>	whenCompleteAsync(BiConsumer<? super T, ? super Throwable> action, Executor executor) Returns a new CompletionStage with the same result or exception as this stage, that executes the given action using the supplied Executor when this stage completes.

Public Constructors

public CompletableFuture ()

Creates a new incomplete CompletableFuture.

Public Methods

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

Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed with the corresponding result as argument to the supplied action. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

other	the other CompletionStage
action	the action to perform before completing the returned CompletionStage

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using this stage's default asynchronous execution facility, with the corresponding result as argument to the supplied action. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

other	the other CompletionStage
action	the action to perform before completing the returned CompletionStage

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using the supplied executor, with the corresponding result as argument to the supplied action. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

other	the other CompletionStage
action	the action to perform before completing the returned CompletionStage
executor	the executor to use for asynchronous execution

Returns

• the new CompletionStage

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

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

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

Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed with the corresponding result as argument to the supplied function. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

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

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using this stage's default asynchronous execution facility, with the corresponding result as argument to the supplied function. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

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

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when either this or the other given stage complete normally, is executed using the supplied executor, with the corresponding result as argument to the supplied function. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

other	the other CompletionStage
fn	the function to use to compute the value of the returned CompletionStage
executor	the executor to use for asynchronous execution

Returns

• the new CompletionStage

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.

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

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

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

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

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. Note: More flexible versions of this functionality are available using methods whenComplete and handle.

Parameters

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

Returns

• the new CompletableFuture

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

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

public T get ()

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

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

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

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

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

Returns a new CompletionStage 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.

Parameters

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

Returns

• the new CompletionStage

public CompletableFuture<U> handleAsync (BiFunction<? super T, Throwable, ? extends U> fn, Executor executor)

Returns a new CompletionStage that, when this stage completes either normally or exceptionally, is executed using the supplied executor, 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.

Parameters

fn	the function to use to compute the value of the returned CompletionStage
executor	the executor to use for asynchronous execution

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when this stage completes either normally or exceptionally, is executed using this stage's default asynchronous execution facility, 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.

Parameters

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

Returns

• the new CompletionStage

public boolean isCancelled ()

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

Returns

• true if this CompletableFuture was cancelled before it completed normally

public boolean isCompletedExceptionally ()

Returns true if this CompletableFuture completed exceptionally, in any way. Possible causes include cancellation, explicit invocation of completeExceptionally, and abrupt termination of a CompletionStage action.

Returns

• true if this CompletableFuture completed exceptionally

public boolean isDone ()

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

Returns

• true if completed

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

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 error recovery actions, and even in such situations may result in ongoing dependent completions using established versus overwritten outcomes.

Parameters

ex	the exception

Throws

NullPointerException	if the exception is null

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

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

Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

other	the other CompletionStage
action	the action to perform before completing the returned CompletionStage

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action using this stage's default asynchronous execution facility. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

other	the other CompletionStage
action	the action to perform before completing the returned CompletionStage

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action using the supplied executor. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

other	the other CompletionStage
action	the action to perform before completing the returned CompletionStage
executor	the executor to use for asynchronous execution

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when either this or the other given stage complete normally, executes the given action. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

other	the other CompletionStage
action	the action to perform before completing the returned CompletionStage

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when either this or the other given stage complete normally, executes the given action using the supplied executor. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

other	the other CompletionStage
action	the action to perform before completing the returned CompletionStage
executor	the executor to use for asynchronous execution

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when either this or the other given stage complete normally, executes the given action using this stage's default asynchronous execution facility. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

other	the other CompletionStage
action	the action to perform before completing the returned CompletionStage

Returns

• the new CompletionStage

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

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

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

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

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

Returns a new CompletionStage that, when this stage completes normally, is executed with this stage's result as the argument to the supplied action. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

action	the action to perform before completing the returned CompletionStage

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when this stage completes normally, is executed using the supplied Executor, with this stage's result as the argument to the supplied action. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

action	the action to perform before completing the returned CompletionStage
executor	the executor to use for asynchronous execution

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when this stage completes normally, is executed using this stage's default asynchronous execution facility, with this stage's result as the argument to the supplied action. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

action	the action to perform before completing the returned CompletionStage

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed with the two results as arguments to the supplied action. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

other	the other CompletionStage
action	the action to perform before completing the returned CompletionStage

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using the supplied executor, with the two results as arguments to the supplied action. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

other	the other CompletionStage
action	the action to perform before completing the returned CompletionStage
executor	the executor to use for asynchronous execution

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using this stage's default asynchronous execution facility, with the two results as arguments to the supplied action. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

other	the other CompletionStage
action	the action to perform before completing the returned CompletionStage

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when this stage completes normally, is executed with this stage's result as the argument to the supplied function.

This method is analogous to Optional.map and Stream.map.

See the CompletionStage documentation for rules covering exceptional completion.

Parameters

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

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when this stage completes normally, is executed using this stage's default asynchronous execution facility, with this stage's result as the argument to the supplied function. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

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

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when this stage completes normally, is executed using the supplied Executor, with this stage's result as the argument to the supplied function. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

fn	the function to use to compute the value of the returned CompletionStage
executor	the executor to use for asynchronous execution

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed with the two results as arguments to the supplied function. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

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

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using the supplied executor, with the two results as arguments to the supplied function. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

other	the other CompletionStage
fn	the function to use to compute the value of the returned CompletionStage
executor	the executor to use for asynchronous execution

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using this stage's default asynchronous execution facility, with the two results as arguments to the supplied function. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

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

Returns

• the new CompletionStage

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

Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function.

When this stage completes normally, the given function is invoked with this stage's result as the argument, returning another CompletionStage. When that stage completes normally, the CompletionStage returned by this method is completed with the same value.

To ensure progress, the supplied function must arrange eventual completion of its result.

This method is analogous to Optional.flatMap and Stream.flatMap.

See the CompletionStage documentation for rules covering exceptional completion.

Parameters

fn	the function to use to compute another CompletionStage

Returns

• the new CompletionStage

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

Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function, executed using the supplied Executor.

When this stage completes normally, the given function is invoked with this stage's result as the argument, returning another CompletionStage. When that stage completes normally, the CompletionStage returned by this method is completed with the same value.

To ensure progress, the supplied function must arrange eventual completion of its result.

See the CompletionStage documentation for rules covering exceptional completion.

Parameters

fn	the function to use to compute another CompletionStage
executor	the executor to use for asynchronous execution

Returns

• the new CompletionStage

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

Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function, executed using this stage's default asynchronous execution facility.

When this stage completes normally, the given function is invoked with this stage's result as the argument, returning another CompletionStage. When that stage completes normally, the CompletionStage returned by this method is completed with the same value.

To ensure progress, the supplied function must arrange eventual completion of its result.

See the CompletionStage documentation for rules covering exceptional completion.

Parameters

fn	the function to use to compute another CompletionStage

Returns

• the new CompletionStage

public CompletableFuture<Void> thenRun (Runnable action)

Returns a new CompletionStage that, when this stage completes normally, executes the given action. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

action	the action to perform before completing the returned CompletionStage

Returns

• the new CompletionStage

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

Returns a new CompletionStage that, when this stage completes normally, executes the given action using the supplied Executor. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

action	the action to perform before completing the returned CompletionStage
executor	the executor to use for asynchronous execution

Returns

• the new CompletionStage

public CompletableFuture<Void> thenRunAsync (Runnable action)

Returns a new CompletionStage that, when this stage completes normally, executes the given action using this stage's default asynchronous execution facility. See the CompletionStage documentation for rules covering exceptional completion.

Parameters

action	the action to perform before completing the returned CompletionStage

Returns

• the new CompletionStage

public CompletableFuture<T> toCompletableFuture ()

Returns this CompletableFuture.

Returns

• this CompletableFuture

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.

Returns

• a string identifying this CompletableFuture, as well as its state

public CompletableFuture<T> whenComplete (BiConsumer<? super T, ? super Throwable> action)

Returns a new CompletionStage with the same result or exception as this stage, that executes the given action when this stage completes.

When this stage is complete, the given action is invoked with the result (or null if none) and the exception (or null if none) of this stage as arguments. The returned stage is completed when the action returns.

Unlike method handle, this method is not designed to translate completion outcomes, so the supplied action should not throw an exception. However, if it does, the following rules apply: if this stage completed normally but the supplied action throws an exception, then the returned stage completes exceptionally with the supplied action's exception. Or, if this stage completed exceptionally and the supplied action throws an exception, then the returned stage completes exceptionally with this stage's exception.

Parameters

action	the action to perform

Returns

• the new CompletionStage

public CompletableFuture<T> whenCompleteAsync (BiConsumer<? super T, ? super Throwable> action)

Returns a new CompletionStage with the same result or exception as this stage, that executes the given action using this stage's default asynchronous execution facility when this stage completes.

When this stage is complete, the given action is invoked with the result (or null if none) and the exception (or null if none) of this stage as arguments. The returned stage is completed when the action returns.

Unlike method handleAsync, this method is not designed to translate completion outcomes, so the supplied action should not throw an exception. However, if it does, the following rules apply: If this stage completed normally but the supplied action throws an exception, then the returned stage completes exceptionally with the supplied action's exception. Or, if this stage completed exceptionally and the supplied action throws an exception, then the returned stage completes exceptionally with this stage's exception.

Parameters

action	the action to perform

Returns

• the new CompletionStage

public CompletableFuture<T> whenCompleteAsync (BiConsumer<? super T, ? super Throwable> action, Executor executor)

Returns a new CompletionStage with the same result or exception as this stage, that executes the given action using the supplied Executor when this stage completes.

When this stage is complete, the given action is invoked with the result (or null if none) and the exception (or null if none) of this stage as arguments. The returned stage is completed when the action returns.

Unlike method handleAsync, this method is not designed to translate completion outcomes, so the supplied action should not throw an exception. However, if it does, the following rules apply: If this stage completed normally but the supplied action throws an exception, then the returned stage completes exceptionally with the supplied action's exception. Or, if this stage completed exceptionally and the supplied action throws an exception, then the returned stage completes exceptionally with this stage's exception.

Parameters

action	the action to perform
executor	the executor to use for asynchronous execution

Returns

• the new CompletionStage