public interface CompletionStage<T>
stage.thenApply(x -> square(x)).thenAccept(x ->
System.out.print(x)).thenRun(() -> System.out.println()). An
additional form (compose) applies functions of stages
themselves, rather than their results. Executor). The execution
properties of default and async modes are specified by
CompletionStage implementations, not this interface. Methods with
explicit Executor arguments may have arbitrary execution
properties, and might not even support concurrent execution, but
are arranged for processing in a way that accommodates asynchrony.
whenComplete allows injection of an action
regardless of outcome, otherwise preserving the outcome in its
completion. Method handle additionally allows the
stage to compute a replacement result that may enable further
processing by other dependent stages. In all other cases, if a
stage's computation terminates abruptly with an (unchecked)
exception or error, then all dependent stages requiring its
completion complete exceptionally as well, with a CompletionException holding the exception as its cause. If a
stage is dependent on both of two stages, and both
complete exceptionally, then the CompletionException may correspond
to either one of these exceptions. If a stage is dependent on
either of two others, and only one of them completes
exceptionally, no guarantees are made about whether the dependent
stage completes normally or exceptionally. In the case of method
whenComplete, when the supplied action itself encounters an
exception, then the stage exceptionally completes with this
exception if not already completed exceptionally.All methods adhere to the above triggering, execution, and
exceptional completion specifications (which are not repeated in
individual method specifications). Additionally, while arguments
used to pass a completion result (that is, for parameters of type
T) for methods accepting them may be null, passing a null
value for any other parameter will result in a NullPointerException being thrown.
This interface does not define methods for initially creating,
forcibly completing normally or exceptionally, probing completion
status or results, or awaiting completion of a stage.
Implementations of CompletionStage may provide means of achieving
such effects, as appropriate. Method toCompletableFuture()
enables interoperability among different implementations of this
interface by providing a common conversion type.
| Modifier and Type | Method and Description |
|---|---|
CompletionStage<Void> |
acceptEither(CompletionStage<? extends T> other,
Consumer<? super T> action)
Returns a new CompletionStage that, when either this or the
other given stage complete normally, is executed with the
corresponding result as argument to the supplied action.
|
CompletionStage<Void> |
acceptEitherAsync(CompletionStage<? extends T> other,
Consumer<? super T> action)
Returns a new CompletionStage that, when either this or the
other given stage complete normally, is executed using this
stage's default asynchronous execution facility, with the
corresponding result as argument to the supplied action.
|
CompletionStage<Void> |
acceptEitherAsync(CompletionStage<? extends T> other,
Consumer<? super T> action,
Executor executor)
Returns a new CompletionStage that, when either this or the
other given stage complete normally, is executed using the
supplied executor, with the corresponding result as argument to
the supplied function.
|
<U> CompletionStage<U> |
applyToEither(CompletionStage<? extends T> other,
Function<? super T,U> fn)
Returns a new CompletionStage that, when either this or the
other given stage complete normally, is executed with the
corresponding result as argument to the supplied function.
|
<U> CompletionStage<U> |
applyToEitherAsync(CompletionStage<? extends T> other,
Function<? super T,U> fn)
Returns a new CompletionStage that, when either this or the
other given stage complete normally, is executed using this
stage's default asynchronous execution facility, with the
corresponding result as argument to the supplied function.
|
<U> CompletionStage<U> |
applyToEitherAsync(CompletionStage<? extends T> other,
Function<? super T,U> fn,
Executor executor)
Returns a new CompletionStage that, when either this or the
other given stage complete normally, is executed using the
supplied executor, with the corresponding result as argument to
the supplied function.
|
CompletionStage<T> |
exceptionally(Function<Throwable,? extends T> fn)
Returns a new CompletionStage that, when this stage completes
exceptionally, is executed with this stage's exception as the
argument to the supplied function.
|
<U> CompletionStage<U> |
handle(BiFunction<? super T,Throwable,? extends U> fn)
Returns a new CompletionStage that, when this stage completes
either normally or exceptionally, is executed with this stage's
result and exception as arguments to the supplied function.
|
<U> CompletionStage<U> |
handleAsync(BiFunction<? super T,Throwable,? extends U> fn)
Returns a new CompletionStage that, when this stage completes
either normally or exceptionally, is executed using this stage's
default asynchronous execution facility, with this stage's
result and exception as arguments to the supplied function.
|
<U> CompletionStage<U> |
handleAsync(BiFunction<? super T,Throwable,? extends U> fn,
Executor executor)
Returns a new CompletionStage that, when this stage completes
either normally or exceptionally, is executed using the
supplied executor, with this stage's result and exception as
arguments to the supplied function.
|
CompletionStage<Void> |
runAfterBoth(CompletionStage<?> other,
Runnable action)
Returns a new CompletionStage that, when this and the other
given stage both complete normally, executes the given action.
|
CompletionStage<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.
|
CompletionStage<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.
|
CompletionStage<Void> |
runAfterEither(CompletionStage<?> other,
Runnable action)
Returns a new CompletionStage that, when either this or the
other given stage complete normally, executes the given action.
|
CompletionStage<Void> |
runAfterEitherAsync(CompletionStage<?> other,
Runnable action)
Returns a new CompletionStage that, when either this or the
other given stage complete normally, executes the given action
using this stage's default asynchronous execution facility.
|
CompletionStage<Void> |
runAfterEitherAsync(CompletionStage<?> other,
Runnable action,
Executor executor)
Returns a new CompletionStage that, when either this or the
other given stage complete normally, executes the given action
using the supplied executor.
|
CompletionStage<Void> |
thenAccept(Consumer<? super T> action)
Returns a new CompletionStage that, when this stage completes
normally, is executed with this stage's result as the argument
to the supplied action.
|
CompletionStage<Void> |
thenAcceptAsync(Consumer<? super T> action)
Returns a new CompletionStage that, when this stage completes
normally, is executed using this stage's default asynchronous
execution facility, with this stage's result as the argument to
the supplied action.
|
CompletionStage<Void> |
thenAcceptAsync(Consumer<? super T> action,
Executor executor)
Returns a new CompletionStage that, when this stage completes
normally, is executed using the supplied Executor, with this
stage's result as the argument to the supplied action.
|
<U> CompletionStage<Void> |
thenAcceptBoth(CompletionStage<? extends U> other,
BiConsumer<? super T,? super U> action)
Returns a new CompletionStage that, when this and the other
given stage both complete normally, is executed with the two
results as arguments to the supplied action.
|
<U> CompletionStage<Void> |
thenAcceptBothAsync(CompletionStage<? extends U> other,
BiConsumer<? super T,? super U> action)
Returns a new CompletionStage that, when this and the other
given stage complete normally, is executed using this stage's
default asynchronous execution facility, with the two results
as arguments to the supplied action.
|
<U> CompletionStage<Void> |
thenAcceptBothAsync(CompletionStage<? extends U> other,
BiConsumer<? super T,? super U> action,
Executor executor)
Returns a new CompletionStage that, when this and the other
given stage complete normally, is executed using the supplied
executor, with the two results as arguments to the supplied
function.
|
<U> CompletionStage<U> |
thenApply(Function<? super T,? extends U> fn)
Returns a new CompletionStage that, when this stage completes
normally, is executed with this stage's result as the argument
to the supplied function.
|
<U> CompletionStage<U> |
thenApplyAsync(Function<? super T,? extends U> fn)
Returns a new CompletionStage that, when this stage completes
normally, is executed using this stage's default asynchronous
execution facility, with this stage's result as the argument to
the supplied function.
|
<U> CompletionStage<U> |
thenApplyAsync(Function<? super T,? extends U> fn,
Executor executor)
Returns a new CompletionStage that, when this stage completes
normally, is executed using the supplied Executor, with this
stage's result as the argument to the supplied function.
|
<U,V> CompletionStage<V> |
thenCombine(CompletionStage<? extends U> other,
BiFunction<? super T,? super U,? extends V> fn)
Returns a new CompletionStage that, when this and the other
given stage both complete normally, is executed with the two
results as arguments to the supplied function.
|
<U,V> CompletionStage<V> |
thenCombineAsync(CompletionStage<? extends U> other,
BiFunction<? super T,? super U,? extends V> fn)
Returns a new CompletionStage that, when this and the other
given stage complete normally, is executed using this stage's
default asynchronous execution facility, with the two results
as arguments to the supplied function.
|
<U,V> CompletionStage<V> |
thenCombineAsync(CompletionStage<? extends U> other,
BiFunction<? super T,? super U,? extends V> fn,
Executor executor)
Returns a new CompletionStage that, when this and the other
given stage complete normally, is executed using the supplied
executor, with the two results as arguments to the supplied
function.
|
<U> CompletionStage<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> CompletionStage<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> CompletionStage<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.
|
CompletionStage<Void> |
thenRun(Runnable action)
Returns a new CompletionStage that, when this stage completes
normally, executes the given action.
|
CompletionStage<Void> |
thenRunAsync(Runnable action)
Returns a new CompletionStage that, when this stage completes
normally, executes the given action using this stage's default
asynchronous execution facility.
|
CompletionStage<Void> |
thenRunAsync(Runnable action,
Executor executor)
Returns a new CompletionStage that, when this stage completes
normally, executes the given action using the supplied Executor.
|
CompletableFuture<T> |
toCompletableFuture()
Returns a
CompletableFuture maintaining the same
completion properties as this stage. |
CompletionStage<T> |
whenComplete(BiConsumer<? super T,? super Throwable> action)
Returns a new CompletionStage with the same result or exception as
this stage, that executes the given action when this stage completes.
|
CompletionStage<T> |
whenCompleteAsync(BiConsumer<? super T,? super Throwable> action)
Returns a new CompletionStage with the same result or exception as
this stage, that executes the given action using this stage's
default asynchronous execution facility when this stage completes.
|
CompletionStage<T> |
whenCompleteAsync(BiConsumer<? super T,? super Throwable> action,
Executor executor)
Returns a new CompletionStage with the same result or exception as
this stage, that executes the given action using the supplied
Executor when this stage completes.
|
<U> CompletionStage<U> thenApply(Function<? super T,? extends U> fn)
CompletionStage documentation for rules
covering exceptional completion.U - the function's return typefn - the function to use to compute the value of
the returned CompletionStage<U> CompletionStage<U> thenApplyAsync(Function<? super T,? extends U> fn)
CompletionStage documentation for rules
covering exceptional completion.U - the function's return typefn - the function to use to compute the value of
the returned CompletionStage<U> CompletionStage<U> thenApplyAsync(Function<? super T,? extends U> fn, Executor executor)
CompletionStage documentation for rules
covering exceptional completion.U - the function's return typefn - the function to use to compute the value of
the returned CompletionStageexecutor - the executor to use for asynchronous executionCompletionStage<Void> thenAccept(Consumer<? super T> action)
CompletionStage documentation for rules
covering exceptional completion.action - the action to perform before completing the
returned CompletionStageCompletionStage<Void> thenAcceptAsync(Consumer<? super T> action)
CompletionStage documentation for rules
covering exceptional completion.action - the action to perform before completing the
returned CompletionStageCompletionStage<Void> thenAcceptAsync(Consumer<? super T> action, Executor executor)
CompletionStage documentation for rules
covering exceptional completion.action - the action to perform before completing the
returned CompletionStageexecutor - the executor to use for asynchronous executionCompletionStage<Void> thenRun(Runnable action)
CompletionStage documentation for rules
covering exceptional completion.action - the action to perform before completing the
returned CompletionStageCompletionStage<Void> thenRunAsync(Runnable action)
CompletionStage documentation for rules
covering exceptional completion.action - the action to perform before completing the
returned CompletionStageCompletionStage<Void> thenRunAsync(Runnable action, Executor executor)
CompletionStage documentation for rules
covering exceptional completion.action - the action to perform before completing the
returned CompletionStageexecutor - the executor to use for asynchronous execution<U,V> CompletionStage<V> thenCombine(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn)
CompletionStage documentation for rules
covering exceptional completion.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 CompletionStage<U,V> CompletionStage<V> thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn)
CompletionStage documentation for rules
covering exceptional completion.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 CompletionStage<U,V> CompletionStage<V> thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn, Executor executor)
CompletionStage documentation for rules
covering exceptional completion.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 execution<U> CompletionStage<Void> thenAcceptBoth(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action)
CompletionStage documentation for rules
covering exceptional completion.U - the type of the other CompletionStage's resultother - the other CompletionStageaction - the action to perform before completing the
returned CompletionStage<U> CompletionStage<Void> thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action)
U - the type of the other CompletionStage's resultother - the other CompletionStageaction - the action to perform before completing the
returned CompletionStage<U> CompletionStage<Void> thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action, Executor executor)
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 executionCompletionStage<Void> runAfterBoth(CompletionStage<?> other, Runnable action)
CompletionStage documentation for rules
covering exceptional completion.other - the other CompletionStageaction - the action to perform before completing the
returned CompletionStageCompletionStage<Void> runAfterBothAsync(CompletionStage<?> other, Runnable action)
CompletionStage documentation for rules
covering exceptional completion.other - the other CompletionStageaction - the action to perform before completing the
returned CompletionStageCompletionStage<Void> runAfterBothAsync(CompletionStage<?> other, Runnable action, Executor executor)
CompletionStage documentation for rules
covering exceptional completion.other - the other CompletionStageaction - the action to perform before completing the
returned CompletionStageexecutor - the executor to use for asynchronous execution<U> CompletionStage<U> applyToEither(CompletionStage<? extends T> other, Function<? super T,U> fn)
CompletionStage documentation for rules
covering exceptional completion.U - the function's return typeother - the other CompletionStagefn - the function to use to compute the value of
the returned CompletionStage<U> CompletionStage<U> applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T,U> fn)
CompletionStage documentation for rules
covering exceptional completion.U - the function's return typeother - the other CompletionStagefn - the function to use to compute the value of
the returned CompletionStage<U> CompletionStage<U> applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T,U> fn, Executor executor)
CompletionStage documentation for rules
covering exceptional completion.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 executionCompletionStage<Void> acceptEither(CompletionStage<? extends T> other, Consumer<? super T> action)
CompletionStage documentation for rules
covering exceptional completion.other - the other CompletionStageaction - the action to perform before completing the
returned CompletionStageCompletionStage<Void> acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action)
CompletionStage documentation for rules
covering exceptional completion.other - the other CompletionStageaction - the action to perform before completing the
returned CompletionStageCompletionStage<Void> acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action, Executor executor)
CompletionStage documentation for rules
covering exceptional completion.other - the other CompletionStageaction - the action to perform before completing the
returned CompletionStageexecutor - the executor to use for asynchronous executionCompletionStage<Void> runAfterEither(CompletionStage<?> other, Runnable action)
CompletionStage documentation for rules
covering exceptional completion.other - the other CompletionStageaction - the action to perform before completing the
returned CompletionStageCompletionStage<Void> runAfterEitherAsync(CompletionStage<?> other, Runnable action)
CompletionStage documentation for rules
covering exceptional completion.other - the other CompletionStageaction - the action to perform before completing the
returned CompletionStageCompletionStage<Void> runAfterEitherAsync(CompletionStage<?> other, Runnable action, Executor executor)
CompletionStage documentation for rules
covering exceptional completion.other - the other CompletionStageaction - the action to perform before completing the
returned CompletionStageexecutor - the executor to use for asynchronous execution<U> CompletionStage<U> thenCompose(Function<? super T,? extends CompletionStage<U>> fn)
CompletionStage documentation for rules
covering exceptional completion.U - the type of the returned CompletionStage's resultfn - the function returning a new CompletionStage<U> CompletionStage<U> thenComposeAsync(Function<? super T,? extends CompletionStage<U>> fn)
CompletionStage documentation for rules
covering exceptional completion.U - the type of the returned CompletionStage's resultfn - the function returning a new CompletionStage<U> CompletionStage<U> thenComposeAsync(Function<? super T,? extends CompletionStage<U>> fn, Executor executor)
CompletionStage documentation for rules
covering exceptional completion.U - the type of the returned CompletionStage's resultfn - the function returning a new CompletionStageexecutor - the executor to use for asynchronous executionCompletionStage<T> exceptionally(Function<Throwable,? extends T> fn)
fn - the function to use to compute the value of the
returned CompletionStage if this CompletionStage completed
exceptionallyCompletionStage<T> whenComplete(BiConsumer<? super T,? super Throwable> action)
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. If the supplied action itself encounters an
exception, then the returned stage exceptionally completes with this
exception unless this stage also completed exceptionally.
action - the action to performCompletionStage<T> whenCompleteAsync(BiConsumer<? super T,? super Throwable> action)
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. If the supplied action itself encounters an
exception, then the returned stage exceptionally completes with this
exception unless this stage also completed exceptionally.
action - the action to performCompletionStage<T> whenCompleteAsync(BiConsumer<? super T,? super Throwable> action, Executor executor)
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. If the supplied action itself encounters an
exception, then the returned stage exceptionally completes with this
exception unless this stage also completed exceptionally.
action - the action to performexecutor - the executor to use for asynchronous execution<U> CompletionStage<U> handle(BiFunction<? super T,Throwable,? extends U> fn)
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.
U - the function's return typefn - the function to use to compute the value of the
returned CompletionStage<U> CompletionStage<U> handleAsync(BiFunction<? super T,Throwable,? extends U> fn)
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.
U - the function's return typefn - the function to use to compute the value of the
returned CompletionStage<U> CompletionStage<U> handleAsync(BiFunction<? super T,Throwable,? extends U> fn, Executor executor)
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.
U - the function's return typefn - the function to use to compute the value of the
returned CompletionStageexecutor - the executor to use for asynchronous executionCompletableFuture<T> toCompletableFuture()
CompletableFuture maintaining the same
completion properties as this stage. If this stage is already a
CompletableFuture, this method may return this stage itself.
Otherwise, invocation of this method may be equivalent in
effect to thenApply(x -> x), but returning an instance
of type CompletableFuture. A CompletionStage
implementation that does not choose to interoperate with others
may throw UnsupportedOperationException.UnsupportedOperationException - if this implementation
does not interoperate with CompletableFuture Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2023, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.