Interface CompletionStage<T>
- Type Parameters:
T
- the type of values the stage produces or consumes
- All Known Implementing Classes:
CompletableFuture
- The computation performed by a stage may be expressed as a
Function, Consumer, or Runnable (using methods with names including
apply, accept, or run, respectively)
depending on whether it requires arguments and/or produces results.
For example:
An additional form (compose) allows the construction of computation pipelines from functions returning completion stages.stage.thenApply(x -> square(x)) .thenAccept(x -> System.out.print(x)) .thenRun(() -> System.out.println());
Any argument to a stage's computation is the outcome of a triggering stage's computation.
- One stage's execution may be triggered by completion of a single stage, or both of two stages, or either of two stages. Dependencies on a single stage are arranged using methods with prefix then. Those triggered by completion of both of two stages may combine their results or effects, using correspondingly named methods. Those triggered by either of two stages make no guarantees about which of the results or effects are used for the dependent stage's computation.
- Dependencies among stages control the triggering of
computations, but do not otherwise guarantee any particular
ordering. Additionally, execution of a new stage's computations may
be arranged in any of three ways: default execution, default
asynchronous execution (using methods with suffix async
that employ the stage's default asynchronous execution facility),
or custom (via a supplied
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. - Two method forms (
handle
andwhenComplete
) support unconditional computation whether the triggering stage completed normally or exceptionally. Methodexceptionally
supports computation only when the triggering stage completes exceptionally, computing a replacement result, similarly to the javacatch
keyword. 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 aCompletionException
holding the exception as its cause. This convention distinguishes exceptions in an action itself from those it depends on. If they are to be handled in the same way, instead catchRuntimeException
(possibly inspecting the exception'sgetCause()
). 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 methodwhenComplete
, when the supplied action itself encounters an exception, then the stage completes exceptionally with that exception unless the source stage also completed exceptionally, in which case the exceptional completion from the source stage is given preference and propagated to the dependent stage. Applications are encouraged to maintain these conventions, avoiding unnecessary nesting when rethrowing, as inthrow (ex instanceof CompletionException) ? ex : new CompletionException(ex)
.
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.
Method form handle
is the most general way of
creating a continuation stage, unconditionally performing a
computation that is given both the result and exception (if any) of
the triggering CompletionStage, and computing an arbitrary result.
Method whenComplete
is similar, but preserves
the result of the triggering stage instead of computing a new one.
Because a stage's normal result may be null
, both methods
should have a computation structured thus:
(result, exception) -> {
if (exception == null) {
// triggering stage completed normally
} else {
// triggering stage completed exceptionally
}
}
The CompletionStage
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.
Memory consistency effects: Actions in a thread prior to the
submission of a computation producing a CompletionStage
happen-before
that computation begins. And actions taken by
CompletionStage x
happen-before actions of any dependent
stage subsequent to x
's completion.
- Since:
- 1.8
-
Method Summary
Modifier and TypeMethodDescriptionacceptEither
(CompletionStage<? extends T> other, Consumer<? super T> action) Returns a new CompletionStage that, when eitherthis
or the other given stage complete normally, is executed with the corresponding result as argument to the supplied action.acceptEitherAsync
(CompletionStage<? extends T> other, Consumer<? super T> action) Returns a new CompletionStage that, when eitherthis
or the other given stage complete normally, is executed usingthis
stage's default asynchronous execution facility, with the corresponding result as argument to the supplied action.acceptEitherAsync
(CompletionStage<? extends T> other, Consumer<? super T> action, Executor executor) Returns a new CompletionStage that, when eitherthis
or the other given stage complete normally, is executed using the supplied executor, with the corresponding result as argument to the supplied action.<U> CompletionStage
<U> applyToEither
(CompletionStage<? extends T> other, Function<? super T, U> fn) Returns a new CompletionStage that, when eitherthis
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 eitherthis
or the other given stage complete normally, is executed usingthis
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 eitherthis
or the other given stage complete normally, is executed using the supplied executor, with the corresponding result as argument to the supplied function.exceptionally
(Function<Throwable, ? extends T> fn) Returns a new CompletionStage that, whenthis
stage completes exceptionally, is executed withthis
stage's exception as the argument to the supplied function.default CompletionStage
<T> exceptionallyAsync
(Function<Throwable, ? extends T> fn) Returns a new CompletionStage that, whenthis
stage completes exceptionally, is executed withthis
stage's exception as the argument to the supplied function, usingthis
stage's default asynchronous execution facility.default CompletionStage
<T> exceptionallyAsync
(Function<Throwable, ? extends T> fn, Executor executor) Returns a new CompletionStage that, whenthis
stage completes exceptionally, is executed withthis
stage's exception as the argument to the supplied function, using the supplied Executor.default CompletionStage
<T> exceptionallyCompose
(Function<Throwable, ? extends CompletionStage<T>> fn) Returns a new CompletionStage that, whenthis
stage completes exceptionally, is composed using the results of the supplied function applied tothis
stage's exception.default CompletionStage
<T> exceptionallyComposeAsync
(Function<Throwable, ? extends CompletionStage<T>> fn) Returns a new CompletionStage that, whenthis
stage completes exceptionally, is composed using the results of the supplied function applied tothis
stage's exception, usingthis
stage's default asynchronous execution facility.default CompletionStage
<T> exceptionallyComposeAsync
(Function<Throwable, ? extends CompletionStage<T>> fn, Executor executor) Returns a new CompletionStage that, whenthis
stage completes exceptionally, is composed using the results of the supplied function applied tothis
stage's exception, using the supplied Executor.<U> CompletionStage
<U> handle
(BiFunction<? super T, Throwable, ? extends U> fn) Returns a new CompletionStage that, whenthis
stage completes either normally or exceptionally, is executed withthis
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, whenthis
stage completes either normally or exceptionally, is executed usingthis
stage's default asynchronous execution facility, withthis
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, whenthis
stage completes either normally or exceptionally, is executed using the supplied executor, withthis
stage's result and exception as arguments to the supplied function.runAfterBoth
(CompletionStage<?> other, Runnable action) Returns a new CompletionStage that, whenthis
and the other given stage both complete normally, executes the given action.runAfterBothAsync
(CompletionStage<?> other, Runnable action) Returns a new CompletionStage that, whenthis
and the other given stage both complete normally, executes the given action usingthis
stage's default asynchronous execution facility.runAfterBothAsync
(CompletionStage<?> other, Runnable action, Executor executor) Returns a new CompletionStage that, whenthis
and the other given stage both complete normally, executes the given action using the supplied executor.runAfterEither
(CompletionStage<?> other, Runnable action) Returns a new CompletionStage that, when eitherthis
or the other given stage complete normally, executes the given action.runAfterEitherAsync
(CompletionStage<?> other, Runnable action) Returns a new CompletionStage that, when eitherthis
or the other given stage complete normally, executes the given action usingthis
stage's default asynchronous execution facility.runAfterEitherAsync
(CompletionStage<?> other, Runnable action, Executor executor) Returns a new CompletionStage that, when eitherthis
or the other given stage complete normally, executes the given action using the supplied executor.thenAccept
(Consumer<? super T> action) Returns a new CompletionStage that, whenthis
stage completes normally, is executed withthis
stage's result as the argument to the supplied action.thenAcceptAsync
(Consumer<? super T> action) Returns a new CompletionStage that, whenthis
stage completes normally, is executed usingthis
stage's default asynchronous execution facility, withthis
stage's result as the argument to the supplied action.thenAcceptAsync
(Consumer<? super T> action, Executor executor) Returns a new CompletionStage that, whenthis
stage completes normally, is executed using the supplied Executor, withthis
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, whenthis
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, whenthis
and the other given stage both complete normally, is executed usingthis
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, whenthis
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> CompletionStage
<U> Returns a new CompletionStage that, whenthis
stage completes normally, is executed withthis
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, whenthis
stage completes normally, is executed usingthis
stage's default asynchronous execution facility, withthis
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, whenthis
stage completes normally, is executed using the supplied Executor, withthis
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, whenthis
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, whenthis
and the other given stage both complete normally, is executed usingthis
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, whenthis
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> CompletionStage
<U> thenCompose
(Function<? super T, ? extends CompletionStage<U>> fn) Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function.<U> CompletionStage
<U> thenComposeAsync
(Function<? super T, ? extends CompletionStage<U>> fn) Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function, executed usingthis
stage's default asynchronous execution facility.<U> CompletionStage
<U> thenComposeAsync
(Function<? super T, ? extends CompletionStage<U>> fn, Executor executor) Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function, executed using the supplied Executor.Returns a new CompletionStage that, whenthis
stage completes normally, executes the given action.thenRunAsync
(Runnable action) Returns a new CompletionStage that, whenthis
stage completes normally, executes the given action usingthis
stage's default asynchronous execution facility.thenRunAsync
(Runnable action, Executor executor) Returns a new CompletionStage that, whenthis
stage completes normally, executes the given action using the supplied Executor.Returns aCompletableFuture
maintaining the same completion properties asthis
stage.whenComplete
(BiConsumer<? super T, ? super Throwable> action) Returns a new CompletionStage with the same result or exception asthis
stage, that executes the given action whenthis
stage completes.whenCompleteAsync
(BiConsumer<? super T, ? super Throwable> action) Returns a new CompletionStage with the same result or exception asthis
stage, that executes the given action usingthis
stage's default asynchronous execution facility whenthis
stage completes.whenCompleteAsync
(BiConsumer<? super T, ? super Throwable> action, Executor executor) Returns a new CompletionStage with the same result or exception asthis
stage, that executes the given action using the supplied Executor whenthis
stage completes.
-
Method Details
-
thenApply
Returns a new CompletionStage that, whenthis
stage completes normally, is executed withthis
stage's result as the argument to the supplied function.This method is analogous to
Optional.map
andStream.map
.See the
CompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- the function's return type- Parameters:
fn
- the function to use to compute the value of the returned CompletionStage- Returns:
- the new CompletionStage
-
thenApplyAsync
Returns a new CompletionStage that, whenthis
stage completes normally, is executed usingthis
stage's default asynchronous execution facility, withthis
stage's result as the argument to the supplied function. See theCompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- the function's return type- Parameters:
fn
- the function to use to compute the value of the returned CompletionStage- Returns:
- the new CompletionStage
-
thenApplyAsync
Returns a new CompletionStage that, whenthis
stage completes normally, is executed using the supplied Executor, withthis
stage's result as the argument to the supplied function. See theCompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- the function's return type- Parameters:
fn
- the function to use to compute the value of the returned CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
thenAccept
Returns a new CompletionStage that, whenthis
stage completes normally, is executed withthis
stage's result as the argument to the supplied action. See theCompletionStage
documentation for rules covering exceptional completion.- Parameters:
action
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
thenAcceptAsync
Returns a new CompletionStage that, whenthis
stage completes normally, is executed usingthis
stage's default asynchronous execution facility, withthis
stage's result as the argument to the supplied action. See theCompletionStage
documentation for rules covering exceptional completion.- Parameters:
action
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
thenAcceptAsync
Returns a new CompletionStage that, whenthis
stage completes normally, is executed using the supplied Executor, withthis
stage's result as the argument to the supplied action. See theCompletionStage
documentation for rules covering exceptional completion.- Parameters:
action
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
thenRun
Returns a new CompletionStage that, whenthis
stage completes normally, executes the given action. See theCompletionStage
documentation for rules covering exceptional completion.- Parameters:
action
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
thenRunAsync
Returns a new CompletionStage that, whenthis
stage completes normally, executes the given action usingthis
stage's default asynchronous execution facility. See theCompletionStage
documentation for rules covering exceptional completion.- Parameters:
action
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
thenRunAsync
Returns a new CompletionStage that, whenthis
stage completes normally, executes the given action using the supplied Executor. See theCompletionStage
documentation for rules covering exceptional completion.- Parameters:
action
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
thenCombine
<U,V> CompletionStage<V> thenCombine(CompletionStage<? extends U> other, BiFunction<? super T, ? super U, ? extends V> fn) Returns a new CompletionStage that, whenthis
and the other given stage both complete normally, is executed with the two results as arguments to the supplied function. See theCompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- the type of the other CompletionStage's resultV
- the function's return type- Parameters:
other
- the other CompletionStagefn
- the function to use to compute the value of the returned CompletionStage- Returns:
- the new CompletionStage
-
thenCombineAsync
<U,V> CompletionStage<V> thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T, ? super U, ? extends V> fn) Returns a new CompletionStage that, whenthis
and the other given stage both complete normally, is executed usingthis
stage's default asynchronous execution facility, with the two results as arguments to the supplied function. See theCompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- the type of the other CompletionStage's resultV
- the function's return type- Parameters:
other
- the other CompletionStagefn
- the function to use to compute the value of the returned CompletionStage- Returns:
- the new CompletionStage
-
thenCombineAsync
<U,V> CompletionStage<V> thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T, ? super U, ? extends V> fn, Executor executor) Returns a new CompletionStage that, whenthis
and the other given stage both complete normally, is executed using the supplied executor, with the two results as arguments to the supplied function. See theCompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- the type of the other CompletionStage's resultV
- the function's return type- Parameters:
other
- the other CompletionStagefn
- the function to use to compute the value of the returned CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
thenAcceptBoth
<U> CompletionStage<Void> thenAcceptBoth(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action) Returns a new CompletionStage that, whenthis
and the other given stage both complete normally, is executed with the two results as arguments to the supplied action. See theCompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- the type of the other CompletionStage's result- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
thenAcceptBothAsync
<U> CompletionStage<Void> thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action) Returns a new CompletionStage that, whenthis
and the other given stage both complete normally, is executed usingthis
stage's default asynchronous execution facility, with the two results as arguments to the supplied action. See theCompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- the type of the other CompletionStage's result- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
thenAcceptBothAsync
<U> CompletionStage<Void> thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action, Executor executor) Returns a new CompletionStage that, whenthis
and the other given stage both complete normally, is executed using the supplied executor, with the two results as arguments to the supplied action. See theCompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- the type of the other CompletionStage's result- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
runAfterBoth
Returns a new CompletionStage that, whenthis
and the other given stage both complete normally, executes the given action. See theCompletionStage
documentation for rules covering exceptional completion.- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
runAfterBothAsync
Returns a new CompletionStage that, whenthis
and the other given stage both complete normally, executes the given action usingthis
stage's default asynchronous execution facility. See theCompletionStage
documentation for rules covering exceptional completion.- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
runAfterBothAsync
CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other, Runnable action, Executor executor) Returns a new CompletionStage that, whenthis
and the other given stage both complete normally, executes the given action using the supplied executor. See theCompletionStage
documentation for rules covering exceptional completion.- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
applyToEither
Returns a new CompletionStage that, when eitherthis
or the other given stage complete normally, is executed with the corresponding result as argument to the supplied function. See theCompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- the function's return type- Parameters:
other
- the other CompletionStagefn
- the function to use to compute the value of the returned CompletionStage- Returns:
- the new CompletionStage
-
applyToEitherAsync
<U> CompletionStage<U> applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T, U> fn) Returns a new CompletionStage that, when eitherthis
or the other given stage complete normally, is executed usingthis
stage's default asynchronous execution facility, with the corresponding result as argument to the supplied function. See theCompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- the function's return type- Parameters:
other
- the other CompletionStagefn
- the function to use to compute the value of the returned CompletionStage- Returns:
- the new CompletionStage
-
applyToEitherAsync
<U> CompletionStage<U> applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T, U> fn, Executor executor) Returns a new CompletionStage that, when eitherthis
or the other given stage complete normally, is executed using the supplied executor, with the corresponding result as argument to the supplied function. See theCompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- the function's return type- Parameters:
other
- the other CompletionStagefn
- the function to use to compute the value of the returned CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
acceptEither
Returns a new CompletionStage that, when eitherthis
or the other given stage complete normally, is executed with the corresponding result as argument to the supplied action. See theCompletionStage
documentation for rules covering exceptional completion.- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
acceptEitherAsync
CompletionStage<Void> acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action) Returns a new CompletionStage that, when eitherthis
or the other given stage complete normally, is executed usingthis
stage's default asynchronous execution facility, with the corresponding result as argument to the supplied action. See theCompletionStage
documentation for rules covering exceptional completion.- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
acceptEitherAsync
CompletionStage<Void> acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action, Executor executor) Returns a new CompletionStage that, when eitherthis
or the other given stage complete normally, is executed using the supplied executor, with the corresponding result as argument to the supplied action. See theCompletionStage
documentation for rules covering exceptional completion.- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
runAfterEither
Returns a new CompletionStage that, when eitherthis
or the other given stage complete normally, executes the given action. See theCompletionStage
documentation for rules covering exceptional completion.- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
runAfterEitherAsync
Returns a new CompletionStage that, when eitherthis
or the other given stage complete normally, executes the given action usingthis
stage's default asynchronous execution facility. See theCompletionStage
documentation for rules covering exceptional completion.- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStage- Returns:
- the new CompletionStage
-
runAfterEitherAsync
CompletionStage<Void> runAfterEitherAsync(CompletionStage<?> other, Runnable action, Executor executor) Returns a new CompletionStage that, when eitherthis
or the other given stage complete normally, executes the given action using the supplied executor. See theCompletionStage
documentation for rules covering exceptional completion.- Parameters:
other
- the other CompletionStageaction
- the action to perform before completing the returned CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
thenCompose
Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function.When
this
stage completes normally, the given function is invoked withthis
stage's result as the argument, returning another CompletionStage. When that stage completes normally, the CompletionStage returned 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
andStream.flatMap
.See the
CompletionStage
documentation for rules covering exceptional completion.- Type Parameters:
U
- the type of the returned CompletionStage's result- Parameters:
fn
- the function to use to compute another CompletionStage- Returns:
- the new CompletionStage
-
thenComposeAsync
Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function, executed usingthis
stage's default asynchronous execution facility.When
this
stage completes normally, the given function is invoked withthis
stage's result as the argument, returning another CompletionStage. When that stage completes normally, the CompletionStage returned 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.- Type Parameters:
U
- the type of the returned CompletionStage's result- Parameters:
fn
- the function to use to compute another CompletionStage- Returns:
- the new CompletionStage
-
thenComposeAsync
<U> CompletionStage<U> thenComposeAsync(Function<? super T, ? extends CompletionStage<U>> fn, Executor executor) Returns a new CompletionStage that is completed with the same value as the CompletionStage returned by the given function, executed using the supplied Executor.When
this
stage completes normally, the given function is invoked withthis
stage's result as the argument, returning another CompletionStage. When that stage completes normally, the CompletionStage returned bythis
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.- Type Parameters:
U
- the type of the returned CompletionStage's result- Parameters:
fn
- the function to use to compute another CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
handle
Returns a new CompletionStage that, whenthis
stage completes either normally or exceptionally, is executed withthis
stage's result and exception as arguments to the supplied function.When
this
stage is complete, the given function is invoked with the result (ornull
if none) and the exception (ornull
if none) ofthis
stage as arguments, and the function's result is used to complete the returned stage.- Type Parameters:
U
- the function's return type- Parameters:
fn
- the function to use to compute the value of the returned CompletionStage- Returns:
- the new CompletionStage
-
handleAsync
Returns a new CompletionStage that, whenthis
stage completes either normally or exceptionally, is executed usingthis
stage's default asynchronous execution facility, withthis
stage's result and exception as arguments to the supplied function.When
this
stage is complete, the given function is invoked with the result (ornull
if none) and the exception (ornull
if none) ofthis
stage as arguments, and the function's result is used to complete the returned stage.- Type Parameters:
U
- the function's return type- Parameters:
fn
- the function to use to compute the value of the returned CompletionStage- Returns:
- the new CompletionStage
-
handleAsync
<U> CompletionStage<U> handleAsync(BiFunction<? super T, Throwable, ? extends U> fn, Executor executor) Returns a new CompletionStage that, whenthis
stage completes either normally or exceptionally, is executed using the supplied executor, withthis
stage's result and exception as arguments to the supplied function.When
this
stage is complete, the given function is invoked with the result (ornull
if none) and the exception (ornull
if none) ofthis
stage as arguments, and the function's result is used to complete the returned stage.- Type Parameters:
U
- the function's return type- Parameters:
fn
- the function to use to compute the value of the returned CompletionStageexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
whenComplete
Returns a new CompletionStage with the same result or exception asthis
stage, that executes the given action whenthis
stage completes.When
this
stage is complete, the given action is invoked with the result (ornull
if none) and the exception (ornull
if none) ofthis
stage as arguments. The returned stage is completed when the action returns.Unlike method
handle
, methodwhenComplete
is not designed to translate completion outcomes, so the supplied action should not throw an exception. However, if it does, the following rules apply: ifthis
stage completed normally but the supplied action throws an exception, then the returned stage completes exceptionally with the supplied action's exception. Or, ifthis
stage completed exceptionally and the supplied action throws an exception, then the returned stage completes exceptionally withthis
stage's exception.- Parameters:
action
- the action to perform- Returns:
- the new CompletionStage
-
whenCompleteAsync
Returns a new CompletionStage with the same result or exception asthis
stage, that executes the given action usingthis
stage's default asynchronous execution facility whenthis
stage completes.When
this
stage is complete, the given action is invoked with the result (ornull
if none) and the exception (ornull
if none) ofthis
stage as arguments. The returned stage is completed when the action returns.Unlike method
handleAsync
, methodwhenCompleteAsync
is not designed to translate completion outcomes, so the supplied action should not throw an exception. However, if it does, the following rules apply: Ifthis
stage completed normally but the supplied action throws an exception, then the returned stage completes exceptionally with the supplied action's exception. Or, ifthis
stage completed exceptionally and the supplied action throws an exception, then the returned stage completes exceptionally withthis
stage's exception.- Parameters:
action
- the action to perform- Returns:
- the new CompletionStage
-
whenCompleteAsync
CompletionStage<T> whenCompleteAsync(BiConsumer<? super T, ? super Throwable> action, Executor executor) Returns a new CompletionStage with the same result or exception asthis
stage, that executes the given action using the supplied Executor whenthis
stage completes.When
this
stage is complete, the given action is invoked with the result (ornull
if none) and the exception (ornull
if none) ofthis
stage as arguments. The returned stage is completed when the action returns.Unlike method
handleAsync
, methodwhenCompleteAsync
is not designed to translate completion outcomes, so the supplied action should not throw an exception. However, if it does, the following rules apply: Ifthis
stage completed normally but the supplied action throws an exception, then the returned stage completes exceptionally with the supplied action's exception. Or, ifthis
stage completed exceptionally and the supplied action throws an exception, then the returned stage completes exceptionally withthis
stage's exception.- Parameters:
action
- the action to performexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
-
exceptionally
Returns a new CompletionStage that, whenthis
stage completes exceptionally, is executed withthis
stage's exception as the argument to the supplied function. Otherwise, ifthis
stage completes normally, then the returned stage also completes normally with the same value.- Parameters:
fn
- the function to use to compute the value of the returned CompletionStage ifthis
CompletionStage completed exceptionally- Returns:
- the new CompletionStage
-
exceptionallyAsync
Returns a new CompletionStage that, whenthis
stage completes exceptionally, is executed withthis
stage's exception as the argument to the supplied function, usingthis
stage's default asynchronous execution facility. Otherwise, ifthis
stage completes normally, then the returned stage also completes normally with the same value.- Implementation Requirements:
- The default implementation invokes
handle(BiFunction)
, relaying tohandleAsync(BiFunction)
on exception, thenthenCompose(Function)
for result. - Parameters:
fn
- the function to use to compute the value of the returned CompletionStage ifthis
CompletionStage completed exceptionally- Returns:
- the new CompletionStage
- Since:
- 12
-
exceptionallyAsync
default CompletionStage<T> exceptionallyAsync(Function<Throwable, ? extends T> fn, Executor executor) Returns a new CompletionStage that, whenthis
stage completes exceptionally, is executed withthis
stage's exception as the argument to the supplied function, using the supplied Executor. Otherwise, ifthis
stage completes normally, then the returned stage also completes normally with the same value.- Implementation Requirements:
- The default implementation invokes
handle(BiFunction)
, relaying tohandleAsync(BiFunction)
on exception, thenthenCompose(Function)
for result. - Parameters:
fn
- the function to use to compute the value of the returned CompletionStage ifthis
CompletionStage completed exceptionallyexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
- Since:
- 12
-
exceptionallyCompose
default CompletionStage<T> exceptionallyCompose(Function<Throwable, ? extends CompletionStage<T>> fn) Returns a new CompletionStage that, whenthis
stage completes exceptionally, is composed using the results of the supplied function applied tothis
stage's exception.- Implementation Requirements:
- The default implementation invokes
handle(BiFunction)
, invoking the given function on exception, thenthenCompose(Function)
for result. - Parameters:
fn
- the function to use to compute the returned CompletionStage ifthis
CompletionStage completed exceptionally- Returns:
- the new CompletionStage
- Since:
- 12
-
exceptionallyComposeAsync
default CompletionStage<T> exceptionallyComposeAsync(Function<Throwable, ? extends CompletionStage<T>> fn) Returns a new CompletionStage that, whenthis
stage completes exceptionally, is composed using the results of the supplied function applied tothis
stage's exception, usingthis
stage's default asynchronous execution facility.- Implementation Requirements:
- The default implementation invokes
handle(BiFunction)
, relaying tohandleAsync(BiFunction)
on exception, thenthenCompose(Function)
for result. - Parameters:
fn
- the function to use to compute the returned CompletionStage ifthis
CompletionStage completed exceptionally- Returns:
- the new CompletionStage
- Since:
- 12
-
exceptionallyComposeAsync
default CompletionStage<T> exceptionallyComposeAsync(Function<Throwable, ? extends CompletionStage<T>> fn, Executor executor) Returns a new CompletionStage that, whenthis
stage completes exceptionally, is composed using the results of the supplied function applied tothis
stage's exception, using the supplied Executor.- Implementation Requirements:
- The default implementation invokes
handle(BiFunction)
, relaying tohandleAsync(BiFunction)
on exception, thenthenCompose(Function)
for result. - Parameters:
fn
- the function to use to compute the returned CompletionStage ifthis
CompletionStage completed exceptionallyexecutor
- the executor to use for asynchronous execution- Returns:
- the new CompletionStage
- Since:
- 12
-
toCompletableFuture
CompletableFuture<T> toCompletableFuture()Returns aCompletableFuture
maintaining the same completion properties asthis
stage. Ifthis
stage is already a CompletableFuture, methodtoCompletableFuture
may returnthis
stage itself. Otherwise, invocation may be equivalent in effect tothenApply(x -> x)
, but returning an instance of typeCompletableFuture
.- Returns:
- the CompletableFuture
-