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
See the
CompletionStage documentation for rules
covering exceptional completion. |
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 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, and when this stage completes, executes the
given action with the result (or
null if none) and the
exception (or null if none) of this stage. |
CompletionStage<T> |
whenCompleteAsync(BiConsumer<? super T,? super Throwable> action)
Returns a new CompletionStage with the same result or exception
as this stage, and when this stage completes, executes the
given action executes the given action using this stage's
default asynchronous execution facility, with the result (or
null if none) and the exception (or null if
none) of this stage as arguments. |
CompletionStage<T> |
whenCompleteAsync(BiConsumer<? super T,? super Throwable> action,
Executor executor)
Returns a new CompletionStage with the same result or exception
as this stage, and when this stage completes, executes using
the supplied Executor, the given action with the result (or
null if none) and the exception (or null if
none) of this stage as arguments. |
<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)
null
if none) and the
exception (or null
if none) of this stage.action
- the action to performCompletionStage<T> whenCompleteAsync(BiConsumer<? super T,? super Throwable> action)
null
if none) and the exception (or null
if
none) of this stage as arguments.action
- the action to performCompletionStage<T> whenCompleteAsync(BiConsumer<? super T,? super Throwable> action, Executor executor)
null
if none) and the exception (or null
if
none) of this stage as arguments.action
- the action to performexecutor
- the executor to use for asynchronous execution<U> CompletionStage<U> handle(BiFunction<? super T,Throwable,? extends U> fn)
null
if none) and the exception (or null
if none) of this
stage when complete as arguments.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)
null
if none) and the exception (or null
if none) of this
stage when complete as arguments.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)
null
if none) and the
exception (or null
if none) of this stage when complete
as arguments.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, 2014, Oracle and/or its affiliates. All rights reserved.