T
- The result type returned by this future's join
and get
methodsCompletionStage<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:
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 method defaultExecutor()
. 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. minimalCompletionStage()
. Or to ensure only that clients do not themselves modify a future, use method copy()
. CompletableFuture also implements Future
with the following policies:
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. 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.
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(); }
}
Modifier and Type | Class | Description |
---|---|---|
static interface |
CompletableFuture.AsynchronousCompletionTask |
A marker interface identifying asynchronous tasks produced by async methods. |
Future.State
Constructor | Description |
---|---|
CompletableFuture() |
Creates a new incomplete CompletableFuture. |
Modifier and Type | Method | Description |
---|---|---|
CompletableFuture |
acceptEither |
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 |
acceptEitherAsync |
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 |
acceptEitherAsync |
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 |
allOf |
Returns a new CompletableFuture that is completed when all of the given CompletableFutures complete. |
static CompletableFuture |
anyOf |
Returns a new CompletableFuture that is completed when any of the given CompletableFutures complete, with the same result. |
<U> CompletableFuture |
applyToEither |
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 |
applyToEitherAsync |
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 |
applyToEitherAsync |
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 |
If not already completed, completes this CompletableFuture with a CancellationException . |
boolean |
complete |
If not already completed, sets the value returned by get() and related methods to the given value. |
CompletableFuture |
completeAsync |
Completes this CompletableFuture with the result of the given Supplier function invoked from an asynchronous task using the default executor. |
CompletableFuture |
completeAsync |
Completes this CompletableFuture with the result of the given Supplier function invoked from an asynchronous task using the given executor. |
static <U> CompletableFuture |
completedFuture |
Returns a new CompletableFuture that is already completed with the given value. |
static <U> CompletionStage |
completedStage |
Returns a new CompletionStage that is already completed with the given value and supports only those methods in interface CompletionStage . |
boolean |
completeExceptionally |
If not already completed, causes invocations of get() and related methods to throw the given exception. |
CompletableFuture |
completeOnTimeout |
Completes this CompletableFuture with the given value if not otherwise completed before the given timeout. |
CompletableFuture |
copy() |
Returns a new CompletableFuture that is completed normally with the same value as this CompletableFuture when it completes normally. |
Executor |
defaultExecutor() |
Returns the default Executor used for async methods that do not specify an Executor. |
static Executor |
delayedExecutor |
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 |
Returns a new Executor that submits a task to the given base executor after the given delay (or no delay if non-positive). |
CompletableFuture |
exceptionally |
Returns a new CompletionStage that, when this stage completes exceptionally, is executed with this stage's exception as the argument to the supplied function. |
static <U> CompletableFuture |
failedFuture |
Returns a new CompletableFuture that is already completed exceptionally with the given exception. |
static <U> CompletionStage |
failedStage |
Returns a new CompletionStage that is already completed exceptionally with the given exception and supports only those methods in interface CompletionStage . |
T |
get() |
Waits if necessary for this future to complete, and then returns its result. |
T |
get |
Waits if necessary for at most the given time for this future to complete, and then returns its result, if available. |
T |
getNow |
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 |
handle |
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 |
handleAsync |
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 |
handleAsync |
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. |
CompletionStage |
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 interface CompletionStage . |
<U> CompletableFuture |
newIncompleteFuture() |
Returns a new incomplete CompletableFuture of the type to be returned by a CompletionStage method. |
void |
obtrudeException |
Forcibly causes subsequent invocations of method get() and related methods to throw the given exception, whether or not already completed. |
void |
obtrudeValue |
Forcibly sets or resets the value subsequently returned by method get() and related methods, whether or not already completed. |
CompletableFuture |
orTimeout |
Exceptionally completes this CompletableFuture with a TimeoutException if not otherwise completed before the given timeout. |
CompletableFuture |
runAfterBoth |
Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action. |
CompletableFuture |
runAfterBothAsync |
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 |
runAfterBothAsync |
Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action using the supplied executor. |
CompletableFuture |
runAfterEither |
Returns a new CompletionStage that, when either this or the other given stage complete normally, executes the given action. |
CompletableFuture |
runAfterEitherAsync |
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 |
runAfterEitherAsync |
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 |
runAsync |
Returns a new CompletableFuture that is asynchronously completed by a task running in the ForkJoinPool.commonPool() after it runs the given action. |
static CompletableFuture |
runAsync |
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 |
supplyAsync |
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 |
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. |
CompletableFuture |
thenAccept |
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 |
thenAcceptAsync |
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 |
thenAcceptAsync |
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 |
thenAcceptBoth |
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 |
thenAcceptBothAsync |
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 |
thenAcceptBothAsync |
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 |
thenApply |
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 |
thenApplyAsync |
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 |
thenApplyAsync |
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, |
thenCombine |
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, |
thenCombineAsync |
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, |
thenCombineAsync |
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> CompletableFuture |
thenCompose |
Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function. |
<U> CompletableFuture |
thenComposeAsync |
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. |
<U> CompletableFuture |
thenComposeAsync |
Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function, executed using the supplied Executor. |
CompletableFuture |
thenRun |
Returns a new CompletionStage that, when this stage completes normally, executes the given action. |
CompletableFuture |
thenRunAsync |
Returns a new CompletionStage that, when this stage completes normally, executes the given action using this stage's default asynchronous execution facility. |
CompletableFuture |
thenRunAsync |
Returns a new CompletionStage that, when this stage completes normally, executes the given action using the supplied Executor. |
CompletableFuture |
toCompletableFuture() |
Returns this CompletableFuture. |
String |
toString() |
Returns a string identifying this CompletableFuture, as well as its completion state. |
CompletableFuture |
whenComplete |
Returns a new CompletionStage with the same result or exception as this stage, that executes the given action when this stage completes. |
CompletableFuture |
whenCompleteAsync |
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 |
whenCompleteAsync |
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. |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
exceptionallyAsync, exceptionallyAsync, exceptionallyCompose, exceptionallyComposeAsync, exceptionallyComposeAsync
exceptionNow, resultNow, state
public CompletableFuture()
public static <U> CompletableFuture<U> supplyAsync(Supplier<U> supplier)
ForkJoinPool.commonPool()
with the value obtained by calling the given Supplier.U
- the function's return typesupplier
- a function returning the value to be used to complete the returned CompletableFuturepublic static <U> CompletableFuture<U> supplyAsync(Supplier<U> supplier, Executor executor)
U
- the function's return typesupplier
- a function returning the value to be used to complete the returned CompletableFutureexecutor
- the executor to use for asynchronous executionpublic static CompletableFuture<Void> runAsync(Runnable runnable)
ForkJoinPool.commonPool()
after it runs the given action.runnable
- the action to run before completing the returned CompletableFuturepublic static CompletableFuture<Void> runAsync(Runnable runnable, Executor executor)
runnable
- the action to run before completing the returned CompletableFutureexecutor
- the executor to use for asynchronous executionpublic static <U> CompletableFuture<U> completedFuture(U value)
U
- the type of the valuevalue
- the valuepublic boolean isDone()
true
if completed in any fashion: normally, exceptionally, or via cancellation.public T get() throws InterruptedException, ExecutionException
get
in interface Future<T>
CancellationException
- if this future was cancelledExecutionException
- if this future completed exceptionallyInterruptedException
- if the current thread was interrupted while waitingpublic T get(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException
get
in interface Future<T>
timeout
- the maximum time to waitunit
- the time unit of the timeout argumentCancellationException
- if this future was cancelledExecutionException
- if this future completed exceptionallyInterruptedException
- if the current thread was interrupted while waitingTimeoutException
- if the wait timed outpublic T join()
CompletionException
with the underlying exception as its cause.CancellationException
- if the computation was cancelledCompletionException
- if this future completed exceptionally or a completion computation threw an exceptionpublic T getNow(T valueIfAbsent)
valueIfAbsent
- the value to return if not completedCancellationException
- if the computation was cancelledCompletionException
- if this future completed exceptionally or a completion computation threw an exceptionpublic boolean complete(T value)
get()
and related methods to the given value.value
- the result valuetrue
if this invocation caused this CompletableFuture to transition to a completed state, else false
public boolean completeExceptionally(Throwable ex)
get()
and related methods to throw the given exception.ex
- the exceptiontrue
if this invocation caused this CompletableFuture to transition to a completed state, else false
public <U> CompletableFuture<U> thenApply(Function<? super T,? extends U> fn)
CompletionStage
This method is analogous to Optional.map
and Stream.map
.
See the CompletionStage
documentation for rules covering exceptional completion.
thenApply
in interface CompletionStage<T>
U
- the function's return typefn
- the function to use to compute the value of the returned CompletionStagepublic <U> CompletableFuture<U> thenApplyAsync(Function<? super T,? extends U> fn)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.thenApplyAsync
in interface CompletionStage<T>
U
- the function's return typefn
- the function to use to compute the value of the returned CompletionStagepublic <U> CompletableFuture<U> thenApplyAsync(Function<? super T,? extends U> fn, Executor executor)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.thenApplyAsync
in interface CompletionStage<T>
U
- the function's return typefn
- the function to use to compute the value of the returned CompletionStageexecutor
- the executor to use for asynchronous executionpublic CompletableFuture<Void> thenAccept(Consumer<? super T> action)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.thenAccept
in interface CompletionStage<T>
action
- the action to perform before completing the returned CompletionStagepublic CompletableFuture<Void> thenAcceptAsync(Consumer<? super T> action)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.thenAcceptAsync
in interface CompletionStage<T>
action
- the action to perform before completing the returned CompletionStagepublic CompletableFuture<Void> thenAcceptAsync(Consumer<? super T> action, Executor executor)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.thenAcceptAsync
in interface CompletionStage<T>
action
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous executionpublic CompletableFuture<Void> thenRun(Runnable action)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.thenRun
in interface CompletionStage<T>
action
- the action to perform before completing the returned CompletionStagepublic CompletableFuture<Void> thenRunAsync(Runnable action)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.thenRunAsync
in interface CompletionStage<T>
action
- the action to perform before completing the returned CompletionStagepublic CompletableFuture<Void> thenRunAsync(Runnable action, Executor executor)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.thenRunAsync
in interface CompletionStage<T>
action
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous executionpublic <U, V> CompletableFuture<V> thenCombine(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.thenCombine
in interface CompletionStage<T>
U
- the type of the other CompletionStage's resultV
- the function's return typeother
- the other CompletionStagefn
- the function to use to compute the value of the returned CompletionStagepublic <U, V> CompletableFuture<V> thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.thenCombineAsync
in interface CompletionStage<T>
U
- the type of the other CompletionStage's resultV
- the function's return typeother
- the other CompletionStagefn
- the function to use to compute the value of the returned CompletionStagepublic <U, V> CompletableFuture<V> thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn, Executor executor)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.thenCombineAsync
in interface CompletionStage<T>
U
- the type of the other CompletionStage's resultV
- the function's return typeother
- the other CompletionStagefn
- the function to use to compute the value of the returned CompletionStageexecutor
- the executor to use for asynchronous executionpublic <U> CompletableFuture<Void> thenAcceptBoth(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.thenAcceptBoth
in interface CompletionStage<T>
U
- the type of the other CompletionStage's resultother
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStagepublic <U> CompletableFuture<Void> thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.thenAcceptBothAsync
in interface CompletionStage<T>
U
- the type of the other CompletionStage's resultother
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStagepublic <U> CompletableFuture<Void> thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action, Executor executor)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.thenAcceptBothAsync
in interface CompletionStage<T>
U
- the type of the other CompletionStage's resultother
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous executionpublic CompletableFuture<Void> runAfterBoth(CompletionStage<?> other, Runnable action)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.runAfterBoth
in interface CompletionStage<T>
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStagepublic CompletableFuture<Void> runAfterBothAsync(CompletionStage<?> other, Runnable action)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.runAfterBothAsync
in interface CompletionStage<T>
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStagepublic CompletableFuture<Void> runAfterBothAsync(CompletionStage<?> other, Runnable action, Executor executor)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.runAfterBothAsync
in interface CompletionStage<T>
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous executionpublic <U> CompletableFuture<U> applyToEither(CompletionStage<? extends T> other, Function<? super T,U> fn)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.applyToEither
in interface CompletionStage<T>
U
- the function's return typeother
- the other CompletionStagefn
- the function to use to compute the value of the returned CompletionStagepublic <U> CompletableFuture<U> applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T,U> fn)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.applyToEitherAsync
in interface CompletionStage<T>
U
- the function's return typeother
- the other CompletionStagefn
- the function to use to compute the value of the returned CompletionStagepublic <U> CompletableFuture<U> applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T,U> fn, Executor executor)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.applyToEitherAsync
in interface CompletionStage<T>
U
- the function's return typeother
- the other CompletionStagefn
- the function to use to compute the value of the returned CompletionStageexecutor
- the executor to use for asynchronous executionpublic CompletableFuture<Void> acceptEither(CompletionStage<? extends T> other, Consumer<? super T> action)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.acceptEither
in interface CompletionStage<T>
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStagepublic CompletableFuture<Void> acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.acceptEitherAsync
in interface CompletionStage<T>
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStagepublic CompletableFuture<Void> acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action, Executor executor)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.acceptEitherAsync
in interface CompletionStage<T>
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous executionpublic CompletableFuture<Void> runAfterEither(CompletionStage<?> other, Runnable action)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.runAfterEither
in interface CompletionStage<T>
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStagepublic CompletableFuture<Void> runAfterEitherAsync(CompletionStage<?> other, Runnable action)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.runAfterEitherAsync
in interface CompletionStage<T>
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStagepublic CompletableFuture<Void> runAfterEitherAsync(CompletionStage<?> other, Runnable action, Executor executor)
CompletionStage
CompletionStage
documentation for rules covering exceptional completion.runAfterEitherAsync
in interface CompletionStage<T>
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous executionpublic <U> CompletableFuture<U> thenCompose(Function<? super T,? extends CompletionStage<U>> fn)
CompletionStage
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.
thenCompose
in interface CompletionStage<T>
U
- the type of the returned CompletionStage's resultfn
- the function to use to compute another CompletionStagepublic <U> CompletableFuture<U> thenComposeAsync(Function<? super T,? extends CompletionStage<U>> fn)
CompletionStage
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.
thenComposeAsync
in interface CompletionStage<T>
U
- the type of the returned CompletionStage's resultfn
- the function to use to compute another CompletionStagepublic <U> CompletableFuture<U> thenComposeAsync(Function<? super T,? extends CompletionStage<U>> fn, Executor executor)
CompletionStage
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.
thenComposeAsync
in interface CompletionStage<T>
U
- the type of the returned CompletionStage's resultfn
- the function to use to compute another CompletionStageexecutor
- the executor to use for asynchronous executionpublic CompletableFuture<T> whenComplete(BiConsumer<? super T,? super Throwable> action)
CompletionStage
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.
whenComplete
in interface CompletionStage<T>
action
- the action to performpublic CompletableFuture<T> whenCompleteAsync(BiConsumer<? super T,? super Throwable> action)
CompletionStage
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.
whenCompleteAsync
in interface CompletionStage<T>
action
- the action to performpublic CompletableFuture<T> whenCompleteAsync(BiConsumer<? super T,? super Throwable> action, Executor executor)
CompletionStage
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.
whenCompleteAsync
in interface CompletionStage<T>
action
- the action to performexecutor
- the executor to use for asynchronous executionpublic <U> CompletableFuture<U> handle(BiFunction<? super T,Throwable,? extends U> fn)
CompletionStage
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.
handle
in interface CompletionStage<T>
U
- the function's return typefn
- the function to use to compute the value of the returned CompletionStagepublic <U> CompletableFuture<U> handleAsync(BiFunction<? super T,Throwable,? extends U> fn)
CompletionStage
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.
handleAsync
in interface CompletionStage<T>
U
- the function's return typefn
- the function to use to compute the value of the returned CompletionStagepublic <U> CompletableFuture<U> handleAsync(BiFunction<? super T,Throwable,? extends U> fn, Executor executor)
CompletionStage
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.
handleAsync
in interface CompletionStage<T>
U
- the function's return typefn
- the function to use to compute the value of the returned CompletionStageexecutor
- the executor to use for asynchronous executionpublic CompletableFuture<T> toCompletableFuture()
toCompletableFuture
in interface CompletionStage<T>
public CompletableFuture<T> exceptionally(Function<Throwable,? extends T> fn)
CompletionStage
exceptionally
in interface CompletionStage<T>
fn
- the function to use to compute the value of the returned CompletionStage if this CompletionStage completed exceptionallypublic static CompletableFuture<Void> allOf(CompletableFuture<?>... cfs)
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();
.
cfs
- the CompletableFuturesNullPointerException
- if the array or any of its elements are null
public static CompletableFuture<Object> anyOf(CompletableFuture<?>... cfs)
cfs
- the CompletableFuturesNullPointerException
- if the array or any of its elements are null
public boolean cancel(boolean mayInterruptIfRunning)
CancellationException
. Dependent CompletableFutures that have not already completed will also complete exceptionally, with a CompletionException
caused by this CancellationException
.public boolean isCancelled()
true
if this CompletableFuture was cancelled before it completed normally.isCancelled
in interface Future<T>
true
if this CompletableFuture was cancelled before it completed normallypublic boolean isCompletedExceptionally()
true
if this CompletableFuture completed exceptionally, in any way. Possible causes include cancellation, explicit invocation of
completeExceptionally
, and abrupt termination of a CompletionStage action.true
if this CompletableFuture completed exceptionallypublic void obtrudeValue(T value)
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.value
- the completion valuepublic void obtrudeException(Throwable ex)
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.ex
- the exceptionNullPointerException
- if the exception is nullpublic int getNumberOfDependents()
public String toString()
"Completed Normally"
or the String
"Completed Exceptionally"
, or the String "Not
completed"
followed by the number of CompletableFutures dependent upon its completion, if any.public <U> CompletableFuture<U> newIncompleteFuture()
U
- the type of the valuepublic Executor defaultExecutor()
ForkJoinPool.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.public CompletableFuture<T> copy()
thenApply(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.public CompletionStage<T> minimalCompletionStage()
CompletionStage
. 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 by
minimalStage.toCompletableFuture().join();
public CompletableFuture<T> completeAsync(Supplier<? extends T> supplier, Executor executor)
supplier
- a function returning the value to be used to complete this CompletableFutureexecutor
- the executor to use for asynchronous executionpublic CompletableFuture<T> completeAsync(Supplier<? extends T> supplier)
supplier
- a function returning the value to be used to complete this CompletableFuturepublic CompletableFuture<T> orTimeout(long timeout, TimeUnit unit)
TimeoutException
if not otherwise completed before the given timeout.timeout
- how long to wait before completing exceptionally with a TimeoutException, in units of unit
unit
- a TimeUnit
determining how to interpret the timeout
parameterpublic CompletableFuture<T> completeOnTimeout(T value, long timeout, TimeUnit unit)
value
- the value to use upon timeouttimeout
- how long to wait before completing normally with the given value, in units of unit
unit
- a TimeUnit
determining how to interpret the timeout
parameterpublic static Executor delayedExecutor(long delay, TimeUnit unit, Executor executor)
execute
method.delay
- how long to delay, in units of unit
unit
- a TimeUnit
determining how to interpret the delay
parameterexecutor
- the base executorpublic static Executor delayedExecutor(long delay, TimeUnit unit)
execute
method.delay
- how long to delay, in units of unit
unit
- a TimeUnit
determining how to interpret the delay
parameterpublic static <U> CompletionStage<U> completedStage(U value)
CompletionStage
.U
- the type of the valuevalue
- the valuepublic static <U> CompletableFuture<U> failedFuture(Throwable ex)
U
- the type of the valueex
- the exceptionpublic static <U> CompletionStage<U> failedStage(Throwable ex)
CompletionStage
.U
- the type of the valueex
- the exception
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/concurrent/CompletableFuture.html