- Type Parameters:
T
- The result type returned by this future'sjoin
andget
methods
- All Implemented Interfaces:
CompletionStage<T>
,Future<T>
public class CompletableFuture<T> extends Object implements Future<T>, CompletionStage<T>
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). This may be overridden for non-static methods in subclasses by defining methoddefaultExecutor()
. To simplify monitoring, debugging, and tracking, all generated asynchronous tasks are instances of the marker interfaceCompletableFuture.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.
- All CompletionStage methods return CompletableFutures. To
restrict usages to only those methods defined in interface
CompletionStage, use method
minimalCompletionStage()
. Or to ensure only that clients do not themselves modify a future, use methodcopy()
.
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. Methodcancel
has the same effect ascompleteExceptionally(new CancellationException())
. MethodisCompletedExceptionally()
can be used to determine if a CompletableFuture completed in any exceptional fashion. - In case of exceptional completion with a CompletionException,
methods
get()
andget(long, TimeUnit)
throw anExecutionException
with the same cause as held in the corresponding CompletionException. To simplify usage in most contexts, this class also defines methodsjoin()
andgetNow(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.
Subclasses of this class should normally override the "virtual
constructor" method newIncompleteFuture()
, which establishes
the concrete type returned by CompletionStage methods. For example,
here is a class that substitutes a different default Executor and
disables the obtrude
methods:
class MyCompletableFuture<T> extends CompletableFuture<T> {
static final Executor myExecutor = ...;
public MyCompletableFuture() { }
public <U> CompletableFuture<U> newIncompleteFuture() {
return new MyCompletableFuture<U>(); }
public Executor defaultExecutor() {
return myExecutor; }
public void obtrudeValue(T value) {
throw new UnsupportedOperationException(); }
public void obtrudeException(Throwable ex) {
throw new UnsupportedOperationException(); }
}
- Since:
- 1.8
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic interface
A marker interface identifying asynchronous tasks produced byasync
methods. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionacceptEither(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.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.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.boolean
cancel(boolean mayInterruptIfRunning)
If not already completed, completes this CompletableFuture with aCancellationException
.boolean
If not already completed, sets the value returned byget()
and related methods to the given value.completeAsync(Supplier<? extends T> supplier)
Completes this CompletableFuture with the result of the given Supplier function invoked from an asynchronous task using the default executor.completeAsync(Supplier<? extends T> supplier, Executor executor)
Completes this CompletableFuture with the result of the given Supplier function invoked from an asynchronous task using the given executor.static <U> CompletableFuture<U>
completedFuture(U value)
Returns a new CompletableFuture that is already completed with the given value.static <U> CompletionStage<U>
completedStage(U value)
Returns a new CompletionStage that is already completed with the given value and supports only those methods in interfaceCompletionStage
.boolean
If not already completed, causes invocations ofget()
and related methods to throw the given exception.completeOnTimeout(T value, long timeout, TimeUnit unit)
Completes this CompletableFuture with the given value if not otherwise completed before the given timeout.copy()
Returns a new CompletableFuture that is completed normally with the same value as this CompletableFuture when it completes normally.Returns the default Executor used for async methods that do not specify an Executor.static Executor
delayedExecutor(long delay, TimeUnit unit)
Returns a new Executor that submits a task to the default executor after the given delay (or no delay if non-positive).static Executor
delayedExecutor(long delay, TimeUnit unit, Executor executor)
Returns a new Executor that submits a task to the given base executor after the given delay (or no delay if non-positive).static <U> CompletableFuture<U>
failedFuture(Throwable ex)
Returns a new CompletableFuture that is already completed exceptionally with the given exception.static <U> CompletionStage<U>
failedStage(Throwable ex)
Returns a new CompletionStage that is already completed exceptionally with the given exception and supports only those methods in interfaceCompletionStage
.get()
Waits if necessary for this future to complete, and then returns its result.Waits if necessary for at most the given time for this future to complete, and then returns its result, if available.Returns the result value (or throws any encountered exception) if completed, else returns the given valueIfAbsent.int
Returns the estimated number of CompletableFutures whose completions are awaiting completion of this CompletableFuture.boolean
Returnstrue
if this CompletableFuture was cancelled before it completed normally.boolean
Returnstrue
if this CompletableFuture completed exceptionally, in any way.boolean
isDone()
Returnstrue
if completed in any fashion: normally, exceptionally, or via cancellation.join()
Returns the result value when complete, or throws an (unchecked) exception if completed exceptionally.Returns a new CompletionStage that is completed normally with the same value as this CompletableFuture when it completes normally, and cannot be independently completed or otherwise used in ways not defined by the methods of interfaceCompletionStage
.<U> CompletableFuture<U>
Returns a new incomplete CompletableFuture of the type to be returned by a CompletionStage method.void
Forcibly causes subsequent invocations of methodget()
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 methodget()
and related methods, whether or not already completed.Exceptionally completes this CompletableFuture with aTimeoutException
if not otherwise completed before the given timeout.runAfterBoth(CompletionStage<?> other, Runnable action)
Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action.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.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.runAfterEither(CompletionStage<?> other, Runnable action)
Returns a new CompletionStage that, when either this or the other given stage complete normally, executes the given action.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.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>
Returns a new CompletableFuture that is asynchronously completed by a task running in theForkJoinPool.commonPool()
after it runs the given action.static CompletableFuture<Void>
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 theForkJoinPool.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.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.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.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 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<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.Returns a new CompletionStage that, when this stage completes normally, executes the given action.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.thenRunAsync(Runnable action, Executor executor)
Returns a new CompletionStage that, when this stage completes normally, executes the given action using the supplied Executor.Returns this CompletableFuture.toString()
Returns a string identifying this CompletableFuture, as well as its completion state.Methods declared in class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods declared in interface java.util.concurrent.CompletionStage
applyToEither, applyToEitherAsync, applyToEitherAsync, exceptionally, exceptionallyAsync, exceptionallyAsync, exceptionallyCompose, exceptionallyComposeAsync, exceptionallyComposeAsync, handle, handleAsync, handleAsync, thenApply, thenApplyAsync, thenApplyAsync, thenCombine, thenCombineAsync, thenCombineAsync, thenCompose, thenComposeAsync, thenComposeAsync, whenComplete, whenCompleteAsync, whenCompleteAsync
-
Constructor Details
-
CompletableFuture
public CompletableFuture()Creates a new incomplete CompletableFuture.
-
-
Method Details
-
supplyAsync
Returns a new CompletableFuture that is asynchronously completed by a task running in theForkJoinPool.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
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 CompletableFutureexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletableFuture
-
runAsync
Returns a new CompletableFuture that is asynchronously completed by a task running in theForkJoinPool.commonPool()
after it runs the given action.- Parameters:
runnable
- the action to run before completing the returned CompletableFuture- Returns:
- the new CompletableFuture
-
runAsync
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 CompletableFutureexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletableFuture
-
completedFuture
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()Returnstrue
if completed in any fashion: normally, exceptionally, or via cancellation. -
get
Waits if necessary for this future to complete, and then returns its result.- Specified by:
get
in interfaceFuture<T>
- Returns:
- the result value
- Throws:
CancellationException
- if this future was cancelledExecutionException
- if this future completed exceptionallyInterruptedException
- if the current thread was interrupted while waiting
-
get
public T get(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutExceptionWaits if necessary for at most the given time for this future to complete, and then returns its result, if available.- Specified by:
get
in interfaceFuture<T>
- Parameters:
timeout
- the maximum time to waitunit
- the time unit of the timeout argument- Returns:
- the result value
- Throws:
CancellationException
- if this future was cancelledExecutionException
- if this future completed exceptionallyInterruptedException
- if the current thread was interrupted while waitingTimeoutException
- if the wait timed out
-
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 cancelledCompletionException
- if this future completed exceptionally or a completion computation threw an exception
-
getNow
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 cancelledCompletionException
- if this future completed exceptionally or a completion computation threw an exception
-
complete
If not already completed, sets the value returned byget()
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, elsefalse
-
completeExceptionally
If not already completed, causes invocations ofget()
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, elsefalse
-
thenAccept
Description copied from interface:CompletionStage
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 theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
thenAccept
in interfaceCompletionStage<T>
- Parameters:
action
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
thenAcceptAsync
Description copied from interface:CompletionStage
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 theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
thenAcceptAsync
in interfaceCompletionStage<T>
- Parameters:
action
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
thenAcceptAsync
Description copied from interface:CompletionStage
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 theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
thenAcceptAsync
in interfaceCompletionStage<T>
- Parameters:
action
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
thenRun
Description copied from interface:CompletionStage
Returns a new CompletionStage that, when this stage completes normally, executes the given action. See theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
thenRun
in interfaceCompletionStage<T>
- Parameters:
action
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
thenRunAsync
Description copied from interface:CompletionStage
Returns a new CompletionStage that, when this stage completes normally, executes the given action using this stage's default asynchronous execution facility. See theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
thenRunAsync
in interfaceCompletionStage<T>
- Parameters:
action
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
thenRunAsync
Description copied from interface:CompletionStage
Returns a new CompletionStage that, when this stage completes normally, executes the given action using the supplied Executor. See theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
thenRunAsync
in interfaceCompletionStage<T>
- Parameters:
action
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
thenAcceptBoth
public <U> CompletableFuture<Void> thenAcceptBoth(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action)Description copied from interface:CompletionStage
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 theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
thenAcceptBoth
in interfaceCompletionStage<T>
- Type Parameters:
U
- the type of the other CompletionStage's result- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
thenAcceptBothAsync
public <U> CompletableFuture<Void> thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action)Description copied from interface:CompletionStage
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 theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
thenAcceptBothAsync
in interfaceCompletionStage<T>
- Type Parameters:
U
- the type of the other CompletionStage's result- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
thenAcceptBothAsync
public <U> CompletableFuture<Void> thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action, Executor executor)Description copied from interface:CompletionStage
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 theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
thenAcceptBothAsync
in interfaceCompletionStage<T>
- Type Parameters:
U
- the type of the other CompletionStage's result- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
runAfterBoth
Description copied from interface:CompletionStage
Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action. See theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
runAfterBoth
in interfaceCompletionStage<T>
- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
runAfterBothAsync
Description copied from interface:CompletionStage
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 theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
runAfterBothAsync
in interfaceCompletionStage<T>
- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
runAfterBothAsync
public CompletableFuture<Void> runAfterBothAsync(CompletionStage<?> other, Runnable action, Executor executor)Description copied from interface:CompletionStage
Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action using the supplied executor. See theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
runAfterBothAsync
in interfaceCompletionStage<T>
- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
acceptEither
public CompletableFuture<Void> acceptEither(CompletionStage<? extends T> other, Consumer<? super T> action)Description copied from interface:CompletionStage
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 theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
acceptEither
in interfaceCompletionStage<T>
- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
acceptEitherAsync
public CompletableFuture<Void> acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action)Description copied from interface:CompletionStage
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 theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
acceptEitherAsync
in interfaceCompletionStage<T>
- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
acceptEitherAsync
public CompletableFuture<Void> acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action, Executor executor)Description copied from interface:CompletionStage
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 theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
acceptEitherAsync
in interfaceCompletionStage<T>
- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
runAfterEither
Description copied from interface:CompletionStage
Returns a new CompletionStage that, when either this or the other given stage complete normally, executes the given action. See theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
runAfterEither
in interfaceCompletionStage<T>
- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
runAfterEitherAsync
Description copied from interface:CompletionStage
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 theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
runAfterEitherAsync
in interfaceCompletionStage<T>
- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
runAfterEitherAsync
public CompletableFuture<Void> runAfterEitherAsync(CompletionStage<?> other, Runnable action, Executor executor)Description copied from interface:CompletionStage
Returns a new CompletionStage that, when either this or the other given stage complete normally, executes the given action using the supplied executor. See theCompletionStage
documentation for rules covering exceptional completion.- Specified by:
runAfterEitherAsync
in interfaceCompletionStage<T>
- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
toCompletableFuture
Returns this CompletableFuture.- Specified by:
toCompletableFuture
in interfaceCompletionStage<T>
- Returns:
- this CompletableFuture
-
allOf
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 valuenull
.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 arenull
-
anyOf
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 arenull
-
cancel
public boolean cancel(boolean mayInterruptIfRunning)If not already completed, completes this CompletableFuture with aCancellationException
. Dependent CompletableFutures that have not already completed will also complete exceptionally, with aCompletionException
caused by thisCancellationException
. -
isCancelled
public boolean isCancelled()Returnstrue
if this CompletableFuture was cancelled before it completed normally.- Specified by:
isCancelled
in interfaceFuture<T>
- Returns:
true
if this CompletableFuture was cancelled before it completed normally
-
isCompletedExceptionally
public boolean isCompletedExceptionally()Returnstrue
if this CompletableFuture completed exceptionally, in any way. Possible causes include cancellation, explicit invocation ofcompleteExceptionally
, and abrupt termination of a CompletionStage action.- Returns:
true
if this CompletableFuture completed exceptionally
-
obtrudeValue
Forcibly sets or resets the value subsequently returned by methodget()
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
Forcibly causes subsequent invocations of methodget()
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
-
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
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. -
newIncompleteFuture
Returns a new incomplete CompletableFuture of the type to be returned by a CompletionStage method. Subclasses should normally override this method to return an instance of the same class as this CompletableFuture. The default implementation returns an instance of class CompletableFuture.- Type Parameters:
U
- the type of the value- Returns:
- a new CompletableFuture
- Since:
- 9
-
defaultExecutor
Returns the default Executor used for async methods that do not specify an Executor. This class uses theForkJoinPool.commonPool()
if it supports more than one parallel thread, or else an Executor using one thread per async task. This method may be overridden in subclasses to return an Executor that provides at least one independent thread.- Returns:
- the executor
- Since:
- 9
-
copy
Returns a new CompletableFuture that is completed normally with the same value as this CompletableFuture when it completes normally. If this CompletableFuture completes exceptionally, then the returned CompletableFuture completes exceptionally with a CompletionException with this exception as cause. The behavior is equivalent tothenApply(x -> x)
. This method may be useful as a form of "defensive copying", to prevent clients from completing, while still being able to arrange dependent actions.- Returns:
- the new CompletableFuture
- Since:
- 9
-
minimalCompletionStage
Returns a new CompletionStage that is completed normally with the same value as this CompletableFuture when it completes normally, and cannot be independently completed or otherwise used in ways not defined by the methods of interfaceCompletionStage
. If this CompletableFuture completes exceptionally, then the returned CompletionStage completes exceptionally with a CompletionException with this exception as cause.Unless overridden by a subclass, a new non-minimal CompletableFuture with all methods available can be obtained from a minimal CompletionStage via
toCompletableFuture()
. For example, completion of a minimal stage can be awaited byminimalStage.toCompletableFuture().join();
- Returns:
- the new CompletionStage
- Since:
- 9
-
completeAsync
Completes this CompletableFuture with the result of the given Supplier function invoked from an asynchronous task using the given executor.- Parameters:
supplier
- a function returning the value to be used to complete this CompletableFutureexecutor
- the executor to use for asynchronous execution- Returns:
- this CompletableFuture
- Since:
- 9
-
completeAsync
Completes this CompletableFuture with the result of the given Supplier function invoked from an asynchronous task using the default executor.- Parameters:
supplier
- a function returning the value to be used to complete this CompletableFuture- Returns:
- this CompletableFuture
- Since:
- 9
-
orTimeout
Exceptionally completes this CompletableFuture with aTimeoutException
if not otherwise completed before the given timeout.- Parameters:
timeout
- how long to wait before completing exceptionally with a TimeoutException, in units ofunit
unit
- aTimeUnit
determining how to interpret thetimeout
parameter- Returns:
- this CompletableFuture
- Since:
- 9
-
completeOnTimeout
Completes this CompletableFuture with the given value if not otherwise completed before the given timeout.- Parameters:
value
- the value to use upon timeouttimeout
- how long to wait before completing normally with the given value, in units ofunit
unit
- aTimeUnit
determining how to interpret thetimeout
parameter- Returns:
- this CompletableFuture
- Since:
- 9
-
delayedExecutor
Returns a new Executor that submits a task to the given base executor after the given delay (or no delay if non-positive). Each delay commences upon invocation of the returned executor'sexecute
method.- Parameters:
delay
- how long to delay, in units ofunit
unit
- aTimeUnit
determining how to interpret thedelay
parameterexecutor
- the base executor- Returns:
- the new delayed executor
- Since:
- 9
-
delayedExecutor
Returns a new Executor that submits a task to the default executor after the given delay (or no delay if non-positive). Each delay commences upon invocation of the returned executor'sexecute
method.- Parameters:
delay
- how long to delay, in units ofunit
unit
- aTimeUnit
determining how to interpret thedelay
parameter- Returns:
- the new delayed executor
- Since:
- 9
-
completedStage
Returns a new CompletionStage that is already completed with the given value and supports only those methods in interfaceCompletionStage
.- Type Parameters:
U
- the type of the value- Parameters:
value
- the value- Returns:
- the completed CompletionStage
- Since:
- 9
-
failedFuture
Returns a new CompletableFuture that is already completed exceptionally with the given exception.- Type Parameters:
U
- the type of the value- Parameters:
ex
- the exception- Returns:
- the exceptionally completed CompletableFuture
- Since:
- 9
-
failedStage
Returns a new CompletionStage that is already completed exceptionally with the given exception and supports only those methods in interfaceCompletionStage
.- Type Parameters:
U
- the type of the value- Parameters:
ex
- the exception- Returns:
- the exceptionally completed CompletionStage
- Since:
- 9
-