Class CompletableFuture<T>

java.lang.Object
- java.util.concurrent.CompletableFuture<T>

All Implemented Interfaces:: CompletionStage<T>, Future<T>

public class CompletableFuture<T>
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.
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.

Since:: 1.8

Nested Classes

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

Constructors

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

Methods

Modifier and Type	Method and Description
`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 function.
`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.
`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 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)` 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.
`<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.
`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 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 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)` 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.
`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.
`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)` 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.
`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.
`<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)` Returns a new CompletionStage that, when this and the other given stage complete normally, is executed using this stage's default asynchronous execution facility, 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 complete normally, is executed using the supplied executor, with the two results as arguments to the supplied function.
`<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)` Returns a new CompletionStage that, when this and the other given stage complete normally, is executed using this stage's default asynchronous execution facility, 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 complete normally, is executed using the supplied executor, 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, when this stage completes normally, is executed with this stage as the argument to the supplied function.
`<U> CompletableFuture<U>`	`thenComposeAsync(Function<? super T,? extends CompletionStage<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 as the argument to the supplied function.
`<U> CompletableFuture<U>`	`thenComposeAsync(Function<? super T,? extends CompletionStage<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.
`CompletableFuture<Void>`	`thenRun(Runnable action)` Returns a new CompletionStage that, when this stage completes normally, executes the given action.
`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<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<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.

Methods inherited from class java.lang.Object

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

Constructors

CompletableFuture

public CompletableFuture()

Creates a new incomplete CompletableFuture.

Methods

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.

Type Parameters:: U - the function's return type
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.

Type Parameters:: U - the function's return type
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.

Type Parameters:: U - the type of the 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