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.
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.
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.
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.
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.
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.
Returns a new CompletionStage that, when this stage completes exceptionally, is executed with this stage's exception as the argument to the supplied function. Otherwise, if this stage completes normally, then the returned stage also completes normally with the same value.
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.
Returns a new CompletionStage that, when this stage completes normally, is executed with this stage's result as the argument to the supplied action.
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.
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.
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.
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.
Returns a new CompletionStage that, when this stage completes normally, is executed with this stage's result as the argument to the supplied function.
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.
Returns a new CompletionStage that, when this stage completes normally, executes the given action.
Returns a new CompletionStage that, when this stage completes normally, executes the given action using this stage's default asynchronous execution facility.
Returns a new CompletionStage that, when this stage completes normally, executes the given action using the supplied Executor.
Returns a {@link CompletableFuture} maintaining the same completion properties as this stage. If this stage is already a CompletableFuture, this method may return this stage itself. Otherwise, invocation of this method may be equivalent in effect to {@code thenApply(x -> x)}, but returning an instance of type {@code CompletableFuture}.
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.
Returns a new CompletionStage with the same result or exception as this stage, that executes the given action when this stage completes.
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.
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.
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.
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.
A stage of a possibly asynchronous computation, that performs an action or computes a value when another CompletionStage completes. A stage completes upon termination of its computation, but this may in turn trigger other dependent stages. The functionality defined in this interface takes only a few basic forms, which expand out to a larger set of methods to capture a range of usage styles:
<ul>
<li>The computation performed by a stage may be expressed as a Function, Consumer, or Runnable (using methods with names including <em>apply</em>, <em>accept</em>, or <em>run</em>, respectively) depending on whether it requires arguments and/or produces results. For example: <pre> {@code stage.thenApply(x -> square(x)) .thenAccept(x -> System.out.print(x)) .thenRun(() -> System.out.println());}</pre>
An additional form (<em>compose</em>) allows the construction of computation pipelines from functions returning completion stages.
<p>Any argument to a stage's computation is the outcome of a triggering stage's computation.
<li>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 <em>then</em>. Those triggered by completion of <em>both</em> of two stages may <em>combine</em> their results or effects, using correspondingly named methods. Those triggered by <em>either</em> of two stages make no guarantees about which of the results or effects are used for the dependent stage's computation.
<li>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 <em>async</em> that employ the stage's default asynchronous execution facility), or custom (via a supplied {@link 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.
<li>Two method forms ({@link #handle handle} and {@link #whenComplete whenComplete}) support unconditional computation whether the triggering stage completed normally or exceptionally. Method {@link #exceptionally exceptionally} supports computation only when the triggering stage completes exceptionally, computing a replacement result, similarly to the java {@code catch} 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 a {@link CompletionException} holding the exception as its cause. If a stage is dependent on <em>both</em> of two stages, and both complete exceptionally, then the CompletionException may correspond to either one of these exceptions. If a stage is dependent on <em>either</em> of two others, and only one of them completes exceptionally, no guarantees are made about whether the dependent stage completes normally or exceptionally. In the case of method {@code whenComplete}, when the supplied action itself encounters an exception, then the stage completes exceptionally with this 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.
</ul>
<p>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 {@code T}) for methods accepting them may be null, passing a null value for any other parameter will result in a {@link NullPointerException} being thrown.
<p>Method form {@link #handle 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 {@link #whenComplete 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 {@code null}, both methods should have a computation structured thus:
<pre>{@code (result, exception) -> { if (exception is null) { // triggering stage completed normally } else { // triggering stage completed exceptionally } }}</pre>
<p>This interface does not define methods for initially creating, forcibly completing normally or exceptionally, probing completion status or results, or awaiting completion of a stage. Implementations of CompletionStage may provide means of achieving such effects, as appropriate. Method {@link #toCompletableFuture} enables interoperability among different implementations of this interface by providing a common conversion type.
@author Doug Lea