Java tutorial
/* * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ /* * This file is available under and governed by the GNU General Public * License version 2 only, as published by the Free Software Foundation. * However, the following notice accompanied the original version of this * file: * * 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: * * <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 == 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 * @since 1.8 */ public interface CompletionStage<T> { /** * Returns a new CompletionStage that, when this stage completes * normally, is executed with this stage's result as the argument * to the supplied function. * * <p>This method is analogous to * {@link java.util.Optional#map Optional.map} and * {@link java.util.stream.Stream#map Stream.map}. * * <p>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 <U> the function's return type * @return the new CompletionStage */ public <U> CompletionStage<U> 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 <U> the function's return type * @return the new CompletionStage */ public <U> CompletionStage<U> 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 <U> the function's return type * @return the new CompletionStage */ public <U> CompletionStage<U> 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<Void> thenAccept(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 {@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<Void> thenAcceptAsync(Consumer<? super T> 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. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param action the action to perform before completing the * returned CompletionStage * @param executor the executor to use for asynchronous execution * @return the new CompletionStage */ public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action, Executor executor); /** * Returns a new CompletionStage that, when this stage completes * normally, executes the given 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<Void> thenRun(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 {@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<Void> thenRunAsync(Runnable action); /** * Returns a new CompletionStage that, when this stage completes * normally, executes the given action using the supplied Executor. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param action the action to perform before completing the * returned CompletionStage * @param executor the executor to use for asynchronous execution * @return the new CompletionStage */ public CompletionStage<Void> thenRunAsync(Runnable action, Executor executor); /** * 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 {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param fn the function to use to compute the value of the * returned CompletionStage * @param <U> the type of the other CompletionStage's result * @param <V> the function's return type * @return the new CompletionStage */ public <U, V> CompletionStage<V> thenCombine(CompletionStage<? extends U> other, BiFunction<? super T, ? super U, ? extends V> fn); /** * Returns a new CompletionStage that, when this and the other * given stage both complete normally, is executed using this * stage's default asynchronous execution facility, with the two * results as arguments to the supplied function. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param fn the function to use to compute the value of the * returned CompletionStage * @param <U> the type of the other CompletionStage's result * @param <V> the function's return type * @return the new CompletionStage */ public <U, V> CompletionStage<V> thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T, ? super U, ? extends V> fn); /** * Returns a new CompletionStage that, when this and the other * given stage both complete normally, is executed using the * supplied executor, with the two results as arguments to the * supplied function. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param fn the function to use to compute the value of the * returned CompletionStage * @param executor the executor to use for asynchronous execution * @param <U> the type of the other CompletionStage's result * @param <V> the function's return type * @return the new CompletionStage */ public <U, V> CompletionStage<V> thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T, ? super U, ? extends V> fn, Executor executor); /** * Returns a new CompletionStage that, when this and the other * given stage both complete normally, is executed with the two * results as arguments to the supplied action. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param action the action to perform before completing the * returned CompletionStage * @param <U> the type of the other CompletionStage's result * @return the new CompletionStage */ public <U> CompletionStage<Void> thenAcceptBoth(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action); /** * Returns a new CompletionStage that, when this and the other * given stage both complete normally, is executed using this * stage's default asynchronous execution facility, with the two * results as arguments to the supplied action. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param action the action to perform before completing the * returned CompletionStage * @param <U> the type of the other CompletionStage's result * @return the new CompletionStage */ public <U> CompletionStage<Void> thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action); /** * Returns a new CompletionStage that, when this and the other * given stage both complete normally, is executed using the * supplied executor, with the two results as arguments to the * supplied action. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param action the action to perform before completing the * returned CompletionStage * @param executor the executor to use for asynchronous execution * @param <U> the type of the other CompletionStage's result * @return the new CompletionStage */ public <U> CompletionStage<Void> thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action, Executor executor); /** * Returns a new CompletionStage that, when this and the other * given stage both complete normally, executes the given action. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param action the action to perform before completing the * returned CompletionStage * @return the new CompletionStage */ public CompletionStage<Void> runAfterBoth(CompletionStage<?> other, Runnable action); /** * Returns a new CompletionStage that, when this and the other * given stage both complete normally, executes the given action * using this stage's default asynchronous execution facility. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param action the action to perform before completing the * returned CompletionStage * @return the new CompletionStage */ public CompletionStage<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 the supplied executor. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param action the action to perform before completing the * returned CompletionStage * @param executor the executor to use for asynchronous execution * @return the new CompletionStage */ public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other, Runnable action, Executor executor); /** * 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 {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param fn the function to use to compute the value of the * returned CompletionStage * @param <U> the function's return type * @return the new CompletionStage */ public <U> CompletionStage<U> applyToEither(CompletionStage<? extends T> other, Function<? super T, U> fn); /** * Returns a new CompletionStage that, when either this or the * other given stage complete normally, is executed using this * stage's default asynchronous execution facility, with the * corresponding result as argument to the supplied function. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param fn the function to use to compute the value of the * returned CompletionStage * @param <U> the function's return type * @return the new CompletionStage */ public <U> CompletionStage<U> applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T, U> fn); /** * Returns a new CompletionStage that, when either this or the * other given stage complete normally, is executed using the * supplied executor, with the corresponding result as argument to * the supplied function. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param fn the function to use to compute the value of the * returned CompletionStage * @param executor the executor to use for asynchronous execution * @param <U> the function's return type * @return the new CompletionStage */ public <U> CompletionStage<U> applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T, U> fn, Executor executor); /** * Returns a new CompletionStage that, when either this or the * other given stage complete normally, is executed with the * corresponding result as argument to the supplied action. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param action the action to perform before completing the * returned CompletionStage * @return the new CompletionStage */ public CompletionStage<Void> acceptEither(CompletionStage<? extends T> other, Consumer<? super T> action); /** * Returns a new CompletionStage that, when either this or the * other given stage complete normally, is executed using this * stage's default asynchronous execution facility, with the * corresponding result as argument to the supplied action. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param action the action to perform before completing the * returned CompletionStage * @return the new CompletionStage */ public CompletionStage<Void> acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action); /** * Returns a new CompletionStage that, when either this or the * other given stage complete normally, is executed using the * supplied executor, with the corresponding result as argument to * the supplied action. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param action the action to perform before completing the * returned CompletionStage * @param executor the executor to use for asynchronous execution * @return the new CompletionStage */ public CompletionStage<Void> acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action, Executor executor); /** * Returns a new CompletionStage that, when either this or the * other given stage complete normally, executes the given action. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param action the action to perform before completing the * returned CompletionStage * @return the new CompletionStage */ public CompletionStage<Void> runAfterEither(CompletionStage<?> other, Runnable action); /** * Returns a new CompletionStage that, when either this or the * other given stage complete normally, executes the given action * using this stage's default asynchronous execution facility. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param action the action to perform before completing the * returned CompletionStage * @return the new CompletionStage */ public CompletionStage<Void> runAfterEitherAsync(CompletionStage<?> other, Runnable action); /** * Returns a new CompletionStage that, when either this or the * other given stage complete normally, executes the given action * using the supplied executor. * * See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param other the other CompletionStage * @param action the action to perform before completing the * returned CompletionStage * @param executor the executor to use for asynchronous execution * @return the new CompletionStage */ public CompletionStage<Void> runAfterEitherAsync(CompletionStage<?> other, Runnable action, Executor executor); /** * Returns a new CompletionStage that is completed with the same * value as the CompletionStage returned by the given function. * * <p>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. * * <p>To ensure progress, the supplied function must arrange * eventual completion of its result. * * <p>This method is analogous to * {@link java.util.Optional#flatMap Optional.flatMap} and * {@link java.util.stream.Stream#flatMap Stream.flatMap}. * * <p>See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param fn the function to use to compute another CompletionStage * @param <U> the type of the returned CompletionStage's result * @return the new CompletionStage */ public <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, * executed using this stage's default asynchronous execution * facility. * * <p>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. * * <p>To ensure progress, the supplied function must arrange * eventual completion of its result. * * <p>See the {@link CompletionStage} documentation for rules * covering exceptional completion. * * @param fn the function to use to compute another CompletionStage * @param <U> the type of the returned CompletionStage's result * @return the new CompletionStage */ public <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 using the supplied Executor. * * <p>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. * * <p>To ensure progress, the supplied function must arrange * eventual completion of its result. * * <p>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 <U> the type of the returned CompletionStage's result * @return the new CompletionStage */ public <U> CompletionStage<U> thenComposeAsync(Function<? super T, ? extends CompletionStage<U>> fn, Executor executor); /** * 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. * * <p>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 <U> the function's return type * @return the new CompletionStage */ public <U> CompletionStage<U> handle(BiFunction<? super T, Throwable, ? extends U> fn); /** * Returns a new CompletionStage that, when this stage completes * either normally or exceptionally, is executed using this stage's * default asynchronous execution facility, with this stage's * result and exception as arguments to the supplied function. * * <p>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 <U> the function's return type * @return the new CompletionStage */ public <U> CompletionStage<U> handleAsync(BiFunction<? super T, Throwable, ? extends U> fn); /** * Returns a new CompletionStage that, when this stage completes * either normally or exceptionally, is executed using the * supplied executor, with this stage's result and exception as * arguments to the supplied function. * * <p>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 <U> the function's return type * @return the new CompletionStage */ public <U> CompletionStage<U> handleAsync(BiFunction<? super T, Throwable, ? extends U> fn, Executor executor); /** * Returns a new CompletionStage with the same result or exception as * this stage, that executes the given action when this stage completes. * * <p>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. * * <p>Unlike method {@link #handle 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<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 using this stage's * default asynchronous execution facility when this stage completes. * * <p>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. * * <p>Unlike method {@link #handleAsync(BiFunction) 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. * * @param action the action to perform * @return the new CompletionStage */ public CompletionStage<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 the supplied * Executor when this stage completes. * * <p>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. * * <p>Unlike method {@link #handleAsync(BiFunction,Executor) 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. * * @param action the action to perform * @param executor the executor to use for asynchronous execution * @return the new CompletionStage */ public CompletionStage<T> whenCompleteAsync(BiConsumer<? super T, ? super Throwable> action, 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<T> exceptionally(Function<Throwable, ? extends T> fn); /** * Returns a new CompletionStage that, when this stage completes * exceptionally, is executed with this stage's exception as the * argument to the supplied function, using this stage's default * asynchronous execution facility. Otherwise, if this stage * completes normally, then the returned stage also completes * normally with the same value. * * @implSpec The default implementation invokes {@link #handle}, * relaying to {@link #handleAsync} on exception, then {@link * #thenCompose} for result. * * @param fn the function to use to compute the value of the * returned CompletionStage if this CompletionStage completed * exceptionally * @return the new CompletionStage * @since 12 */ public default CompletionStage<T> exceptionallyAsync(Function<Throwable, ? extends T> fn) { return handle((r, ex) -> (ex == null) ? this : this.<T>handleAsync((r1, ex1) -> fn.apply(ex1))) .thenCompose(Function.identity()); } /** * Returns a new CompletionStage that, when this stage completes * exceptionally, is executed with this stage's exception as the * argument to the supplied function, using the supplied Executor. * Otherwise, if this stage completes normally, then the returned * stage also completes normally with the same value. * * @implSpec The default implementation invokes {@link #handle}, * relaying to {@link #handleAsync} on exception, then {@link * #thenCompose} for result. * * @param fn the function to use to compute the value of the * returned CompletionStage if this CompletionStage completed * exceptionally * @param executor the executor to use for asynchronous execution * @return the new CompletionStage * @since 12 */ public default CompletionStage<T> exceptionallyAsync(Function<Throwable, ? extends T> fn, Executor executor) { return handle((r, ex) -> (ex == null) ? this : this.<T>handleAsync((r1, ex1) -> fn.apply(ex1), executor)) .thenCompose(Function.identity()); } /** * Returns a new CompletionStage that, when this stage completes * exceptionally, is composed using the results of the supplied * function applied to this stage's exception. * * @implSpec The default implementation invokes {@link #handle}, * invoking the given function on exception, then {@link * #thenCompose} for result. * * @param fn the function to use to compute the returned * CompletionStage if this CompletionStage completed exceptionally * @return the new CompletionStage * @since 12 */ public default CompletionStage<T> exceptionallyCompose(Function<Throwable, ? extends CompletionStage<T>> fn) { return handle((r, ex) -> (ex == null) ? this : fn.apply(ex)).thenCompose(Function.identity()); } /** * Returns a new CompletionStage that, when this stage completes * exceptionally, is composed using the results of the supplied * function applied to this stage's exception, using this stage's * default asynchronous execution facility. * * @implSpec The default implementation invokes {@link #handle}, * relaying to {@link #handleAsync} on exception, then {@link * #thenCompose} for result. * * @param fn the function to use to compute the returned * CompletionStage if this CompletionStage completed exceptionally * @return the new CompletionStage * @since 12 */ public default CompletionStage<T> exceptionallyComposeAsync( Function<Throwable, ? extends CompletionStage<T>> fn) { return handle((r, ex) -> (ex == null) ? this : this.handleAsync((r1, ex1) -> fn.apply(ex1)).thenCompose(Function.identity())) .thenCompose(Function.identity()); } /** * Returns a new CompletionStage that, when this stage completes * exceptionally, is composed using the results of the supplied * function applied to this stage's exception, using the * supplied Executor. * * @implSpec The default implementation invokes {@link #handle}, * relaying to {@link #handleAsync} on exception, then {@link * #thenCompose} for result. * * @param fn the function to use to compute the returned * CompletionStage if this CompletionStage completed exceptionally * @param executor the executor to use for asynchronous execution * @return the new CompletionStage * @since 12 */ public default CompletionStage<T> exceptionallyComposeAsync( Function<Throwable, ? extends CompletionStage<T>> fn, Executor executor) { return handle((r, ex) -> (ex == null) ? this : this.handleAsync((r1, ex1) -> fn.apply(ex1), executor).thenCompose(Function.identity())) .thenCompose(Function.identity()); } /** * 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}. * * @return the CompletableFuture */ public CompletableFuture<T> toCompletableFuture(); }