public
class
CompletableFuture
extends Object
implements
Future<T>,
CompletionStage<T>
java.lang.Object | |
↳ | java.util.concurrent.CompletableFuture<T> |
A Future
that may be explicitly completed (setting its
value and status), and may be used as a CompletionStage
,
supporting dependent functions and actions that trigger upon its
completion.
When two or more threads attempt to
complete
,
completeExceptionally
, or
cancel
a CompletableFuture, only one of them succeeds.
In addition to these and related methods for directly
manipulating status and results, CompletableFuture implements
interface CompletionStage
with the following policies:
commonPool()
(unless it does not support a parallelism level of at least two, in
which case, a new Thread is created to run each task).
To simplify monitoring, debugging,
and tracking, all generated asynchronous tasks are instances of the
marker interface CompletableFuture.AsynchronousCompletionTask
. Operations
with time-delays can use adapter methods defined in this class, for
example: supplyAsync(supplier, delayedExecutor(timeout,
timeUnit))
. To support methods with delays and timeouts, this
class maintains at most one daemon thread for triggering and
cancelling actions, not for running them.
CompletableFuture also implements Future
with the following
policies:
FutureTask
) this class has no direct
control over the computation that causes it to be completed,
cancellation is treated as just another form of exceptional
completion. Method cancel
has the same effect as
completeExceptionally(new CancellationException())
. Method
isCompletedExceptionally()
can be used to determine if a
CompletableFuture completed in any exceptional fashion.
get()
and get(long, TimeUnit)
throw an
ExecutionException
with the same cause as held in the
corresponding CompletionException. To simplify usage in most
contexts, this class also defines methods join()
and
getNow(T)
that instead throw the CompletionException directly
in these cases.
Arguments used to pass a completion result (that is, for
parameters of type T
) for methods accepting them may be
null, but passing a null value for any other parameter will result
in a NullPointerException
being thrown.
Nested classes | |
---|---|
interface |
CompletableFuture.AsynchronousCompletionTask
A marker interface identifying asynchronous tasks produced by
|
Public constructors | |
---|---|
CompletableFuture()
Creates a new incomplete CompletableFuture. |
Public methods | |
---|---|
CompletableFuture<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. |
CompletableFuture<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. |
CompletableFuture<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 action. |
static
CompletableFuture<Void>
|
allOf(CompletableFuture...<?> cfs)
Returns a new CompletableFuture that is completed when all of the given CompletableFutures complete. |
static
CompletableFuture<Object>
|
anyOf(CompletableFuture...<?> cfs)
Returns a new CompletableFuture that is completed when any of the given CompletableFutures complete, with the same result. |
<U>
CompletableFuture<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>
CompletableFuture<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>
CompletableFuture<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. |
boolean
|
cancel(boolean mayInterruptIfRunning)
If not already completed, completes this CompletableFuture with
a |
boolean
|
complete(T value)
If not already completed, sets the value returned by |
boolean
|
completeExceptionally(Throwable ex)
If not already completed, causes invocations of |
static
<U>
CompletableFuture<U>
|
completedFuture(U value)
Returns a new CompletableFuture that is already completed with the given value. |
CompletableFuture<T>
|
exceptionally(Function<Throwable, ? extends T> fn)
Returns a new CompletableFuture that is completed when this CompletableFuture completes, with the result of the given function of the exception triggering this CompletableFuture's completion when it completes exceptionally; otherwise, if this CompletableFuture completes normally, then the returned CompletableFuture also completes normally with the same value. |
T
|
get(long timeout, TimeUnit unit)
Waits if necessary for at most the given time for this future to complete, and then returns its result, if available. |
T
|
get()
Waits if necessary for this future to complete, and then returns its result. |
T
|
getNow(T valueIfAbsent)
Returns the result value (or throws any encountered exception) if completed, else returns the given valueIfAbsent. |
int
|
getNumberOfDependents()
Returns the estimated number of CompletableFutures whose completions are awaiting completion of this CompletableFuture. |
<U>
CompletableFuture<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>
CompletableFuture<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. |
<U>
CompletableFuture<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. |
boolean
|
isCancelled()
Returns |
boolean
|
isCompletedExceptionally()
Returns |
boolean
|
isDone()
Returns |
T
|
join()
Returns the result value when complete, or throws an (unchecked) exception if completed exceptionally. |
void
|
obtrudeException(Throwable ex)
Forcibly causes subsequent invocations of method |
void
|
obtrudeValue(T value)
Forcibly sets or resets the value subsequently returned by
method |
CompletableFuture<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. |
CompletableFuture<Void>
|
runAfterBothAsync(CompletionStage<?> other, Runnable action)
Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action using this stage's default asynchronous execution facility. |
CompletableFuture<Void>
|
runAfterBothAsync(CompletionStage<?> other, Runnable action, Executor executor)
Returns a new CompletionStage that, when this and the other given stage both complete normally, executes the given action using the supplied executor. |
CompletableFuture<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. |
CompletableFuture<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. |
CompletableFuture<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. |
static
CompletableFuture<Void>
|
runAsync(Runnable runnable)
Returns a new CompletableFuture that is asynchronously completed
by a task running in the |
static
CompletableFuture<Void>
|
runAsync(Runnable runnable, Executor executor)
Returns a new CompletableFuture that is asynchronously completed by a task running in the given executor after it runs the given action. |
static
<U>
CompletableFuture<U>
|
supplyAsync(Supplier<U> supplier)
Returns a new CompletableFuture that is asynchronously completed
by a task running in the |
static
<U>
CompletableFuture<U>
|
supplyAsync(Supplier<U> supplier, Executor executor)
Returns a new CompletableFuture that is asynchronously completed by a task running in the given executor with the value obtained by calling the given Supplier. |
CompletableFuture<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. |
CompletableFuture<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. |
CompletableFuture<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. |
<U>
CompletableFuture<Void>
|
thenAcceptBoth(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action)
Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed with the two results as arguments to the supplied action. |
<U>
CompletableFuture<Void>
|
thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action, Executor executor)
Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using the supplied executor, with the two results as arguments to the supplied action. |
<U>
CompletableFuture<Void>
|
thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action)
Returns a new CompletionStage that, when this and the other given stage both complete normally, is executed using this stage's default asynchronous execution facility, with the two results as arguments to the supplied action. |
<U>
CompletableFuture<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>
CompletableFuture<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>
CompletableFuture<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>
CompletableFuture<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>
CompletableFuture<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 both complete normally, is executed using the supplied executor, with the two results as arguments to the supplied function. |
<U, V>
CompletableFuture<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 both complete normally, is executed using this stage's default asynchronous execution facility, with the two results as arguments to the supplied function. |
<U>
CompletableFuture<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>
CompletableFuture<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. |
<U>
CompletableFuture<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 using this stage's default asynchronous execution facility. |
CompletableFuture<Void>
|
thenRun(Runnable action)
Returns a new CompletionStage that, when this stage completes normally, executes the given action. |
CompletableFuture<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<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. |
CompletableFuture<T>
|
toCompletableFuture()
Returns this CompletableFuture. |
String
|
toString()
Returns a string identifying this CompletableFuture, as well as its completion state. |
CompletableFuture<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. |
CompletableFuture<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. |
CompletableFuture<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. |
Inherited methods | |
---|---|
From
class
java.lang.Object
| |
From
interface
java.util.concurrent.Future
| |
From
interface
java.util.concurrent.CompletionStage
|
CompletableFuture ()
Creates a new incomplete CompletableFuture.
CompletableFuture<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.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
action |
Consumer :
the action to perform before completing the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<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.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
action |
Consumer :
the action to perform before completing the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<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 action.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
action |
Consumer :
the action to perform before completing the
returned CompletionStage |
executor |
Executor :
the executor to use for asynchronous execution |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<Void> allOf (CompletableFuture...<?> cfs)
Returns a new CompletableFuture that is completed when all of
the given CompletableFutures complete. If any of the given
CompletableFutures complete exceptionally, then the returned
CompletableFuture also does so, with a CompletionException
holding this exception as its cause. Otherwise, the results,
if any, of the given CompletableFutures are not reflected in
the returned CompletableFuture, but may be obtained by
inspecting them individually. If no CompletableFutures are
provided, returns a CompletableFuture completed with the value
null
.
Among the applications of this method is to await completion
of a set of independent CompletableFutures before continuing a
program, as in: CompletableFuture.allOf(c1, c2,
c3).join();
.
Parameters | |
---|---|
cfs |
CompletableFuture :
the CompletableFutures |
Returns | |
---|---|
CompletableFuture<Void> |
a new CompletableFuture that is completed when all of the given CompletableFutures complete |
Throws | |
---|---|
NullPointerException |
if the array or any of its elements are
null
|
CompletableFuture<Object> anyOf (CompletableFuture...<?> cfs)
Returns a new CompletableFuture that is completed when any of the given CompletableFutures complete, with the same result. Otherwise, if it completed exceptionally, the returned CompletableFuture also does so, with a CompletionException holding this exception as its cause. If no CompletableFutures are provided, returns an incomplete CompletableFuture.
Parameters | |
---|---|
cfs |
CompletableFuture :
the CompletableFutures |
Returns | |
---|---|
CompletableFuture<Object> |
a new CompletableFuture that is completed with the result or exception of any of the given CompletableFutures when one completes |
Throws | |
---|---|
NullPointerException |
if the array or any of its elements are
null
|
CompletableFuture<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.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
fn |
Function :
the function to use to compute the value of the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<U> |
the new CompletionStage |
CompletableFuture<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.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
fn |
Function :
the function to use to compute the value of the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<U> |
the new CompletionStage |
CompletableFuture<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.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
fn |
Function :
the function to use to compute the value of the
returned CompletionStage |
executor |
Executor :
the executor to use for asynchronous execution |
Returns | |
---|---|
CompletableFuture<U> |
the new CompletionStage |
boolean cancel (boolean mayInterruptIfRunning)
If not already completed, completes this CompletableFuture with
a CancellationException
. Dependent CompletableFutures
that have not already completed will also complete
exceptionally, with a CompletionException
caused by
this CancellationException
.
Parameters | |
---|---|
mayInterruptIfRunning |
boolean :
this value has no effect in this
implementation because interrupts are not used to control
processing. |
Returns | |
---|---|
boolean |
true if this task is now cancelled
|
boolean complete (T value)
If not already completed, sets the value returned by get()
and related methods to the given value.
Parameters | |
---|---|
value |
T :
the result value |
Returns | |
---|---|
boolean |
true if this invocation caused this CompletableFuture
to transition to a completed state, else false
|
boolean completeExceptionally (Throwable ex)
If not already completed, causes invocations of get()
and related methods to throw the given exception.
Parameters | |
---|---|
ex |
Throwable :
the exception |
Returns | |
---|---|
boolean |
true if this invocation caused this CompletableFuture
to transition to a completed state, else false
|
CompletableFuture<U> completedFuture (U value)
Returns a new CompletableFuture that is already completed with the given value.
Parameters | |
---|---|
value |
U :
the value |
Returns | |
---|---|
CompletableFuture<U> |
the completed CompletableFuture |
CompletableFuture<T> exceptionally (Function<Throwable, ? extends T> fn)
Returns a new CompletableFuture that is completed when this
CompletableFuture completes, with the result of the given
function of the exception triggering this CompletableFuture's
completion when it completes exceptionally; otherwise, if this
CompletableFuture completes normally, then the returned
CompletableFuture also completes normally with the same value.
Note: More flexible versions of this functionality are
available using methods whenComplete
and handle
.
Parameters | |
---|---|
fn |
Function :
the function to use to compute the value of the
returned CompletableFuture if this CompletableFuture completed
exceptionally |
Returns | |
---|---|
CompletableFuture<T> |
the new CompletableFuture |
T get (long timeout, TimeUnit unit)
Waits if necessary for at most the given time for this future to complete, and then returns its result, if available.
Parameters | |
---|---|
timeout |
long :
the maximum time to wait |
unit |
TimeUnit :
the time unit of the timeout argument |
Returns | |
---|---|
T |
the result value |
Throws | |
---|---|
CancellationException |
if this future was cancelled |
ExecutionException |
if this future completed exceptionally |
InterruptedException |
if the current thread was interrupted while waiting |
TimeoutException |
if the wait timed out |
T get ()
Waits if necessary for this future to complete, and then returns its result.
Returns | |
---|---|
T |
the result value |
Throws | |
---|---|
CancellationException |
if this future was cancelled |
ExecutionException |
if this future completed exceptionally |
InterruptedException |
if the current thread was interrupted while waiting |
T getNow (T valueIfAbsent)
Returns the result value (or throws any encountered exception) if completed, else returns the given valueIfAbsent.
Parameters | |
---|---|
valueIfAbsent |
T :
the value to return if not completed |
Returns | |
---|---|
T |
the result value, if completed, else the given valueIfAbsent |
Throws | |
---|---|
CancellationException |
if the computation was cancelled |
CompletionException |
if this future completed exceptionally or a completion computation threw an exception |
int getNumberOfDependents ()
Returns the estimated number of CompletableFutures whose completions are awaiting completion of this CompletableFuture. This method is designed for use in monitoring system state, not for synchronization control.
Returns | |
---|---|
int |
the number of dependent CompletableFutures |
CompletableFuture<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.
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.
Parameters | |
---|---|
fn |
BiFunction :
the function to use to compute the value of the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<U> |
the new CompletionStage |
CompletableFuture<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.
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.
Parameters | |
---|---|
fn |
BiFunction :
the function to use to compute the value of the
returned CompletionStage |
executor |
Executor :
the executor to use for asynchronous execution |
Returns | |
---|---|
CompletableFuture<U> |
the new CompletionStage |
CompletableFuture<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.
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.
Parameters | |
---|---|
fn |
BiFunction :
the function to use to compute the value of the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<U> |
the new CompletionStage |
boolean isCancelled ()
Returns true
if this CompletableFuture was cancelled
before it completed normally.
Returns | |
---|---|
boolean |
true if this CompletableFuture was cancelled
before it completed normally
|
boolean isCompletedExceptionally ()
Returns true
if this CompletableFuture completed
exceptionally, in any way. Possible causes include
cancellation, explicit invocation of completeExceptionally
, and abrupt termination of a
CompletionStage action.
Returns | |
---|---|
boolean |
true if this CompletableFuture completed
exceptionally
|
boolean isDone ()
Returns true
if completed in any fashion: normally,
exceptionally, or via cancellation.
Returns | |
---|---|
boolean |
true if completed
|
T join ()
Returns the result value when complete, or throws an
(unchecked) exception if completed exceptionally. To better
conform with the use of common functional forms, if a
computation involved in the completion of this
CompletableFuture threw an exception, this method throws an
(unchecked) CompletionException
with the underlying
exception as its cause.
Returns | |
---|---|
T |
the result value |
Throws | |
---|---|
CancellationException |
if the computation was cancelled |
CompletionException |
if this future completed exceptionally or a completion computation threw an exception |
void obtrudeException (Throwable ex)
Forcibly causes subsequent invocations of method get()
and related methods to throw the given exception, whether or
not already completed. This method is designed for use only in
error recovery actions, and even in such situations may result
in ongoing dependent completions using established versus
overwritten outcomes.
Parameters | |
---|---|
ex |
Throwable :
the exception |
Throws | |
---|---|
NullPointerException |
if the exception is null |
void obtrudeValue (T value)
Forcibly sets or resets the value subsequently returned by
method get()
and related methods, whether or not
already completed. This method is designed for use only in
error recovery actions, and even in such situations may result
in ongoing dependent completions using established versus
overwritten outcomes.
Parameters | |
---|---|
value |
T :
the completion value
|
CompletableFuture<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.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
action |
Runnable :
the action to perform before completing the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<Void> runAfterBothAsync (CompletionStage<?> other, Runnable action)
Returns a new CompletionStage that, when this and the other
given stage both complete normally, executes the given action
using this stage's default asynchronous execution facility.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
action |
Runnable :
the action to perform before completing the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<Void> runAfterBothAsync (CompletionStage<?> other, Runnable action, Executor executor)
Returns a new CompletionStage that, when this and the other
given stage both complete normally, executes the given action
using the supplied executor.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
action |
Runnable :
the action to perform before completing the
returned CompletionStage |
executor |
Executor :
the executor to use for asynchronous execution |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<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.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
action |
Runnable :
the action to perform before completing the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<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.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
action |
Runnable :
the action to perform before completing the
returned CompletionStage |
executor |
Executor :
the executor to use for asynchronous execution |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<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.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
action |
Runnable :
the action to perform before completing the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<Void> runAsync (Runnable runnable)
Returns a new CompletableFuture that is asynchronously completed
by a task running in the commonPool()
after
it runs the given action.
Parameters | |
---|---|
runnable |
Runnable :
the action to run before completing the
returned CompletableFuture |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletableFuture |
CompletableFuture<Void> runAsync (Runnable runnable, Executor executor)
Returns a new CompletableFuture that is asynchronously completed by a task running in the given executor after it runs the given action.
Parameters | |
---|---|
runnable |
Runnable :
the action to run before completing the
returned CompletableFuture |
executor |
Executor :
the executor to use for asynchronous execution |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletableFuture |
CompletableFuture<U> supplyAsync (Supplier<U> supplier)
Returns a new CompletableFuture that is asynchronously completed
by a task running in the commonPool()
with
the value obtained by calling the given Supplier.
Parameters | |
---|---|
supplier |
Supplier :
a function returning the value to be used
to complete the returned CompletableFuture |
Returns | |
---|---|
CompletableFuture<U> |
the new CompletableFuture |
CompletableFuture<U> supplyAsync (Supplier<U> supplier, Executor executor)
Returns a new CompletableFuture that is asynchronously completed by a task running in the given executor with the value obtained by calling the given Supplier.
Parameters | |
---|---|
supplier |
Supplier :
a function returning the value to be used
to complete the returned CompletableFuture |
executor |
Executor :
the executor to use for asynchronous execution |
Returns | |
---|---|
CompletableFuture<U> |
the new CompletableFuture |
CompletableFuture<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.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
action |
Consumer :
the action to perform before completing the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<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.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
action |
Consumer :
the action to perform before completing the
returned CompletionStage |
executor |
Executor :
the executor to use for asynchronous execution |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<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.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
action |
Consumer :
the action to perform before completing the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<Void> thenAcceptBoth (CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action)
Returns a new CompletionStage that, when this and the other
given stage both complete normally, is executed with the two
results as arguments to the supplied action.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
action |
BiConsumer :
the action to perform before completing the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<Void> thenAcceptBothAsync (CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action, Executor executor)
Returns a new CompletionStage that, when this and the other
given stage both complete normally, is executed using the
supplied executor, with the two results as arguments to the
supplied action.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
action |
BiConsumer :
the action to perform before completing the
returned CompletionStage |
executor |
Executor :
the executor to use for asynchronous execution |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<Void> thenAcceptBothAsync (CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action)
Returns a new CompletionStage that, when this and the other
given stage both complete normally, is executed using this
stage's default asynchronous execution facility, with the two
results as arguments to the supplied action.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
action |
BiConsumer :
the action to perform before completing the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<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.
This method is analogous to
Optional.map
and
Stream.map
.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
fn |
Function :
the function to use to compute the value of the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<U> |
the new CompletionStage |
CompletableFuture<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.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
fn |
Function :
the function to use to compute the value of the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<U> |
the new CompletionStage |
CompletableFuture<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.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
fn |
Function :
the function to use to compute the value of the
returned CompletionStage |
executor |
Executor :
the executor to use for asynchronous execution |
Returns | |
---|---|
CompletableFuture<U> |
the new CompletionStage |
CompletableFuture<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.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
fn |
BiFunction :
the function to use to compute the value of the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<V> |
the new CompletionStage |
CompletableFuture<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 both complete normally, is executed using the
supplied executor, with the two results as arguments to the
supplied function.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
fn |
BiFunction :
the function to use to compute the value of the
returned CompletionStage |
executor |
Executor :
the executor to use for asynchronous execution |
Returns | |
---|---|
CompletableFuture<V> |
the new CompletionStage |
CompletableFuture<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 both complete normally, is executed using this
stage's default asynchronous execution facility, with the two
results as arguments to the supplied function.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
other |
CompletionStage :
the other CompletionStage |
fn |
BiFunction :
the function to use to compute the value of the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<V> |
the new CompletionStage |
CompletableFuture<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.
When this stage completes normally, the given function is invoked with this stage's result as the argument, returning another CompletionStage. When that stage completes normally, the CompletionStage returned by this method is completed with the same value.
To ensure progress, the supplied function must arrange eventual completion of its result.
This method is analogous to
Optional.flatMap
and
Stream.flatMap
.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
fn |
Function :
the function to use to compute another CompletionStage |
Returns | |
---|---|
CompletableFuture<U> |
the new CompletionStage |
CompletableFuture<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 with this stage's result as the argument, returning another CompletionStage. When that stage completes normally, the CompletionStage returned by this method is completed with the same value.
To ensure progress, the supplied function must arrange eventual completion of its result.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
fn |
Function :
the function to use to compute another CompletionStage |
executor |
Executor :
the executor to use for asynchronous execution |
Returns | |
---|---|
CompletableFuture<U> |
the new CompletionStage |
CompletableFuture<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 using this stage's default asynchronous execution facility.
When this stage completes normally, the given function is invoked with this stage's result as the argument, returning another CompletionStage. When that stage completes normally, the CompletionStage returned by this method is completed with the same value.
To ensure progress, the supplied function must arrange eventual completion of its result.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
fn |
Function :
the function to use to compute another CompletionStage |
Returns | |
---|---|
CompletableFuture<U> |
the new CompletionStage |
CompletableFuture<Void> thenRun (Runnable action)
Returns a new CompletionStage that, when this stage completes
normally, executes the given action.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
action |
Runnable :
the action to perform before completing the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<Void> thenRunAsync (Runnable action, Executor executor)
Returns a new CompletionStage that, when this stage completes
normally, executes the given action using the supplied Executor.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
action |
Runnable :
the action to perform before completing the
returned CompletionStage |
executor |
Executor :
the executor to use for asynchronous execution |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<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.
See the CompletionStage
documentation for rules
covering exceptional completion.
Parameters | |
---|---|
action |
Runnable :
the action to perform before completing the
returned CompletionStage |
Returns | |
---|---|
CompletableFuture<Void> |
the new CompletionStage |
CompletableFuture<T> toCompletableFuture ()
Returns this CompletableFuture.
Returns | |
---|---|
CompletableFuture<T> |
this CompletableFuture |
String toString ()
Returns a string identifying this CompletableFuture, as well as
its completion state. The state, in brackets, contains the
String "Completed Normally"
or the String "Completed Exceptionally"
, or the String "Not
completed"
followed by the number of CompletableFutures
dependent upon its completion, if any.
Returns | |
---|---|
String |
a string identifying this CompletableFuture, as well as its state |
CompletableFuture<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.
When this stage is complete, the given action is invoked
with the result (or null
if none) and the exception (or
null
if none) of this stage as arguments. The returned
stage is completed when the action returns.
Unlike method handle
,
this method is not designed to translate completion outcomes,
so the supplied action should not throw an exception. However,
if it does, the following rules apply: if this stage completed
normally but the supplied action throws an exception, then the
returned stage completes exceptionally with the supplied
action's exception. Or, if this stage completed exceptionally
and the supplied action throws an exception, then the returned
stage completes exceptionally with this stage's exception.
Parameters | |
---|---|
action |
BiConsumer :
the action to perform |
Returns | |
---|---|
CompletableFuture<T> |
the new CompletionStage |
CompletableFuture<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.
When this stage is complete, the given action is invoked with the
result (or null
if none) and the exception (or null
if none) of this stage as arguments. The returned stage is completed
when the action returns.
Unlike method handleAsync
,
this method is not designed to translate completion outcomes,
so the supplied action should not throw an exception. However,
if it does, the following rules apply: If this stage completed
normally but the supplied action throws an exception, then the
returned stage completes exceptionally with the supplied
action's exception. Or, if this stage completed exceptionally
and the supplied action throws an exception, then the returned
stage completes exceptionally with this stage's exception.
Parameters | |
---|---|
action |
BiConsumer :
the action to perform |
Returns | |
---|---|
CompletableFuture<T> |
the new CompletionStage |
CompletableFuture<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.
When this stage is complete, the given action is invoked with the
result (or null
if none) and the exception (or null
if none) of this stage as arguments. The returned stage is completed
when the action returns.
Unlike method handleAsync
,
this method is not designed to translate completion outcomes,
so the supplied action should not throw an exception. However,
if it does, the following rules apply: If this stage completed
normally but the supplied action throws an exception, then the
returned stage completes exceptionally with the supplied
action's exception. Or, if this stage completed exceptionally
and the supplied action throws an exception, then the returned
stage completes exceptionally with this stage's exception.
Parameters | |
---|---|
action |
BiConsumer :
the action to perform |
executor |
Executor :
the executor to use for asynchronous execution |
Returns | |
---|---|
CompletableFuture<T> |
the new CompletionStage |