/* * Written by Doug Lea with assistance from members of JCP JSR-166 * Expert Group and released to the public domain, as explained at * http://creativecommons.org/publicdomain/zero/1.0/ */ package java.util.concurrent; import java.util.function.BiConsumer; import java.util.function.BiFunction; import java.util.function.Consumer; import java.util.function.Function; /** * 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: * *
{@code * stage.thenApply(x -> square(x)) * .thenAccept(x -> System.out.print(x)) * .thenRun(() -> System.out.println())}* * An additional form (compose) allows the construction of * computation pipelines from functions returning completion stages. * *
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. * *
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
* @since 1.8
*/
public interface CompletionStage This method is analogous to
* {@link java.util.Optional#map Optional.map} and
* {@link java.util.stream.Stream#map Stream.map}.
*
* See the {@link CompletionStage} documentation for rules
* covering exceptional completion.
*
* @param fn the function to use to compute the value of the
* returned CompletionStage
* @param the function's return type
* @return the new CompletionStage
*/
public CompletionStage thenApply(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 {@link CompletionStage} documentation for rules
* covering exceptional completion.
*
* @param fn the function to use to compute the value of the
* returned CompletionStage
* @param the function's return type
* @return the new CompletionStage
*/
public CompletionStage thenApplyAsync
(Function super T,? extends U> fn);
/**
* 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 {@link CompletionStage} documentation for rules
* covering exceptional completion.
*
* @param fn the function to use to compute the value of the
* returned CompletionStage
* @param executor the executor to use for asynchronous execution
* @param the function's return type
* @return the new CompletionStage
*/
public CompletionStage thenApplyAsync
(Function super T,? extends U> fn,
Executor executor);
/**
* 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 {@link CompletionStage} documentation for rules
* covering exceptional completion.
*
* @param action the action to perform before completing the
* returned CompletionStage
* @return the new CompletionStage
*/
public CompletionStage 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
* {@link java.util.Optional#flatMap Optional.flatMap} and
* {@link java.util.stream.Stream#flatMap Stream.flatMap}.
*
* See the {@link CompletionStage} documentation for rules
* covering exceptional completion.
*
* @param fn the function to use to compute another CompletionStage
* @param the type of the returned CompletionStage's result
* @return the new CompletionStage
*/
public CompletionStage thenCompose
(Function super T, ? extends CompletionStage> 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 {@link CompletionStage} documentation for rules
* covering exceptional completion.
*
* @param fn the function to use to compute another CompletionStage
* @param the type of the returned CompletionStage's result
* @return the new CompletionStage
*/
public CompletionStage thenComposeAsync
(Function super T, ? extends CompletionStage> fn);
/**
* 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 {@link CompletionStage} documentation for rules
* covering exceptional completion.
*
* @param fn the function to use to compute another CompletionStage
* @param executor the executor to use for asynchronous execution
* @param the type of the returned CompletionStage's result
* @return the new CompletionStage
*/
public CompletionStage thenComposeAsync
(Function super T, ? extends CompletionStage> fn,
Executor executor);
/**
* 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.
*
* @param fn the function to use to compute the value of the
* returned CompletionStage if this CompletionStage completed
* exceptionally
* @return the new CompletionStage
*/
public CompletionStage When this stage is complete, the given action is invoked
* with the result (or {@code null} if none) and the exception (or
* {@code null} if none) of this stage as arguments. The returned
* stage is completed when the action returns.
*
* Unlike method {@link #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.
*
* @param action the action to perform
* @return the new CompletionStage
*/
public CompletionStage When this stage is complete, the given action is invoked with the
* result (or {@code null} if none) and the exception (or {@code null}
* if none) of this stage as arguments. The returned stage is completed
* when the action returns.
*
* Unlike method {@link #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.
*
* @param action the action to perform
* @return the new CompletionStage
*/
public CompletionStage When this stage is complete, the given action is invoked with the
* result (or {@code null} if none) and the exception (or {@code null}
* if none) of this stage as arguments. The returned stage is completed
* when the action returns.
*
* Unlike method {@link #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.
*
* @param action the action to perform
* @param executor the executor to use for asynchronous execution
* @return the new CompletionStage
*/
public CompletionStage When this stage is complete, the given function is invoked
* with the result (or {@code null} if none) and the exception (or
* {@code null} if none) of this stage as arguments, and the
* function's result is used to complete the returned stage.
*
* @param fn the function to use to compute the value of the
* returned CompletionStage
* @param the function's return type
* @return the new CompletionStage
*/
public CompletionStage handle
(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 {@code null} if none) and the exception (or
* {@code null} if none) of this stage as arguments, and the
* function's result is used to complete the returned stage.
*
* @param fn the function to use to compute the value of the
* returned CompletionStage
* @param the function's return type
* @return the new CompletionStage
*/
public CompletionStage handleAsync
(BiFunction super T, Throwable, ? extends U> fn);
/**
* 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 {@code null} if none) and the exception (or
* {@code null} if none) of this stage as arguments, and the
* function's result is used to complete the returned stage.
*
* @param fn the function to use to compute the value of the
* returned CompletionStage
* @param executor the executor to use for asynchronous execution
* @param the function's return type
* @return the new CompletionStage
*/
public CompletionStage handleAsync
(BiFunction super T, Throwable, ? extends U> fn,
Executor 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}. A CompletionStage
* implementation that does not choose to interoperate with others
* may throw {@code UnsupportedOperationException}.
*
* @return the CompletableFuture
* @throws UnsupportedOperationException if this implementation
* does not interoperate with CompletableFuture
*/
public CompletableFuture