Module  java.base
软件包  java.util.concurrent

Interface CompletionStage<T>

  • 所有已知实现类：
    CompletableFuture 

    public interface CompletionStage<T>
    可能的异步计算的阶段，当另一个完成时间完成时，执行一个动作或计算一个值。 一个阶段在其计算结束时完成，但这又可能触发其他相关阶段。 此界面中定义的功能只需要几种基本形式，从而扩展到更大的方法来捕获一系列使用风格：
    • 阶段执行的计算可以表示为功能，消费者或可运行 （分别使用名称包括apply ， accept或run的方法 ），具体取决于是否需要参数和/或生成结果。 例如： 
         stage.thenApply(x -> square(x)) .thenAccept(x -> System.out.print(x)) .thenRun(() -> System.out.println());
      附加的形式（ 组合 ）允许从返回完成阶段的功能构建计算管道。

      舞台计算的任何论据是触发阶段计算的结果。

    • 一个阶段的执行可以通过完成一个阶段，或两个阶段的完成，或两个阶段中的任一阶段来触发。 在一个单级的依赖关系使用的是带有前缀方法然后配置。 这些都通过两个阶段的结束为契机可以结合自己的成绩和效果，使用相应的命名方法。 由两个阶段中的任一阶段触发的那些都不能保证结果或效果中的哪一个用于依赖阶段的计算。
    • 阶段之间的依赖性控制计算的触发，但是否则不保证任何特定的顺序。 另外，新阶段计算的执行可以通过以下三种方式进行排列：默认执行，默认异步执行（使用使用阶段的默认异步执行工具的后缀async的方法）或定制（通过提供的Executor ）。 默认和异步模式的执行属性由CompletionStage实现指定，而不是此接口。 具有显式Executor参数的方法可能具有任意执行属性，甚至可能不支持并发执行，而是以适应异步方式进行处理。
    • 两种方法形式（ handle和whenComplete ）支持无条件计算触发阶段是否正常或异常完成。 方法exceptionally支持计算，只有当触发阶段完成异常时，计算替换结果，类似于java catch关键字。 在所有其他情况下，如果一个阶段的计算突然出现（未检查）的异常或错误，那么所有依赖阶段都需要完成，例外情况除外，其中CompletionException将其作为原因。 如果一个阶段是依赖于两个两个阶段，都非常完整，那么CompletionException可以对应于这些例外的任何一个。 如果一个阶段依赖于两个其他的任何一个，并且只有一个完成异常，则不能保证依赖阶段是否正常或异常完成。 在方法whenComplete的情况下，当所提供的动作本身遇到异常时，则除非源whenComplete也异常完成，否则该阶段完成异常，在这种情况下，来自源级的异常完成被赋予优先权并且被传播到从属阶段。

    所有方法都遵循上述触发，执行和特殊完成规范（在各个方法规范中不重复）。 另外，对于接受它们的方法，用于传递完成结果的参数（即T参数）可能为null，传递任何其他参数的空值将导致抛出一个NullPointerException 。

    方法形式handle是创建连续阶段的最通用方法，无条件地执行给出触发CompletionStage的结果和异常（如果有的话）的计算，并计算任意结果。 方法whenComplete是类似的，但保留了触发阶段的结果，而不是计算新的结果。 因为阶段的正常结果可能是null ，所以这两种方法应该具有如下结构： 

      (result, exception) -> { if (exception == null) { // triggering stage completed normally } else { // triggering stage completed exceptionally } }

    该接口没有定义初始创建方法，强制完成正常或异常的探测完成状态或结果，或等待阶段完成。 CompletionStage的实施可能会提供适当的方式来实现这种效果。 方法toCompletableFuture()通过提供公共转换类型来实现该接口的不同实现之间的互操作性。

    从以下版本开始：
    1.8

    • 方法详细信息

      • thenApply

        <U> CompletionStage<U> thenApply​(Function<? super T,? extends U> fn)
        返回一个新的CompletionStage，当此阶段正常完成时，将以该阶段的结果作为所提供函数的参数执行。

        该方法类似于Optional.map和Stream.map 。

        请参阅CompletionStage文档，了解完整的规则。

        参数类型
        U - 函数的返回类型
        参数
        fn - 用于计算返回的CompletionStage的值的函数
        结果
        新的CompletionStage

      • thenApplyAsync

        <U> CompletionStage<U> thenApplyAsync​(Function<? super T,? extends U> fn)
        返回一个新的CompletionStage，当该阶段正常完成时，将使用此阶段的默认异步执行工具执行此阶段的结果作为所提供函数的参数。 请参阅CompletionStage文档，了解涵盖特殊完成的规则。
        参数类型
        U - 函数的返回类型
        参数
        fn - 用于计算返回的CompletionStage的值的函数
        结果
        新的CompletionStage

      • thenApplyAsync

        <U> CompletionStage<U> thenApplyAsync​(Function<? super T,? extends U> fn,
                                      Executor executor)
        返回一个新的CompletionStage，当此阶段正常完成时，将使用提供的执行程序执行此阶段的结果作为提供函数的参数。 请参阅CompletionStage文档，了解覆盖异常完成的规则。
        参数类型
        U - 函数的返回类型
        参数
        fn - 用于计算返回的CompletionStage的值的函数
        executor - 执行器用于异步执行
        结果
        新的CompletionStage

      • thenAccept

        CompletionStage<Void> thenAccept​(Consumer<? super T> action)
        返回一个新的CompletionStage，当此阶段正常完成时，以该阶段的结果作为提供的操作的参数执行。 请参阅CompletionStage文档，了解有关特殊完成的规则。
        参数
        action - 在完成返回的CompletionStage之前执行的操作
        结果
        新的CompletionStage

      • thenAcceptAsync

        CompletionStage<Void> thenAcceptAsync​(Consumer<? super T> action)
        返回一个新的CompletionStage，当此阶段正常完成时，将使用此阶段的默认异步执行工具执行，此阶段的结果作为提供的操作的参数。 请参阅CompletionStage文档，了解完整的规则。
        参数
        action - 在完成返回的CompletionStage之前执行的操作
        结果
        新的CompletionStage

      • thenAcceptAsync

        CompletionStage<Void> thenAcceptAsync​(Consumer<? super T> action,
                                      Executor executor)
        返回一个新的CompletionStage，当此阶段正常完成时，将使用提供的执行程序执行此阶段的结果作为提供的操作的参数。 请参阅CompletionStage文档，了解完整的规则。
        参数
        action - 在完成返回的CompletionStage之前执行的操作
        executor - 执行器用于异步执行
        结果
        新的CompletionStage

      • thenRun

        CompletionStage<Void> thenRun​(Runnable action)
        返回一个新的CompletionStage，当此阶段正常完成时，执行给定的操作。 请参阅CompletionStage文档，了解完整的规则。
        参数
        action - 在完成返回的CompletionStage之前执行的操作
        结果
        新的CompletionStage

      • thenRunAsync

        CompletionStage<Void> thenRunAsync​(Runnable action)
        返回一个新的CompletionStage，当此阶段正常完成时，使用此阶段的默认异步执行工具执行给定的操作。 有关特殊完成的规则，请参阅CompletionStage文档。
        参数
        action - 在完成返回的CompletionStage之前执行的操作
        结果
        新的CompletionStage

      • thenRunAsync

        CompletionStage<Void> thenRunAsync​(Runnable action,
                                   Executor executor)
        返回一个新的CompletionStage，当此阶段正常完成时，使用提供的执行程序执行给定的操作。 有关特殊完成的规则，请参阅CompletionStage文档。
        参数
        action - 在完成返回的CompletionStage之前执行的操作
        executor - 执行器用于异步执行
        结果
        新的CompletionStage

      • thenCombine

        <U,V> CompletionStage<V> thenCombine​(CompletionStage<? extends U> other,
                                     BiFunction<? super T,? super U,? extends V> fn)
        返回一个新的CompletionStage，当这个和另一个给定的阶段都正常完成时，两个结果作为提供函数的参数执行。 请参阅CompletionStage文档，了解完整的规则。
        参数类型
        U - 其他CompletionStage的结果的类型
        V - 函数的返回类型
        参数
        other - 其他CompletionStage
        fn - 用于计算返回的CompletionStage的值的函数
        结果
        新的CompletionStage

      • thenCombineAsync

        <U,V> CompletionStage<V> thenCombineAsync​(CompletionStage<? extends U> other,
                                          BiFunction<? super T,? super U,? extends V> fn)
        返回一个新的CompletionStage，当这个和另一个给定的阶段都正常完成时，将使用此阶段的默认异步执行工具执行，其中两个结果作为提供函数的参数。 有关特殊完成的规则，请参阅CompletionStage文档。
        参数类型
        U - 其他CompletionStage的结果类型
        V - 函数的返回类型
        参数
        other - 其他CompletionStage
        fn - 用于计算返回的CompletionStage的值的函数
        结果
        新的CompletionStage

      • thenCombineAsync

        <U,V> CompletionStage<V> thenCombineAsync​(CompletionStage<? extends U> other,
                                          BiFunction<? super T,? super U,? extends V> fn,
                                          Executor executor)
        返回一个新的CompletionStage，当这个和另一个给定的阶段都正常完成时，使用提供的执行器执行，其中两个结果作为提供的函数的参数。 请参阅CompletionStage文档，了解完整的规则。
        参数类型
        U - 其他CompletionStage的结果的类型
        V - 函数的返回类型
        参数
        other - 其他CompletionStage
        fn - 用于计算返回的CompletionStage的值的函数
        executor - 执行器用于异步执行
        结果
        新的CompletionStage

      • thenAcceptBoth

        <U> CompletionStage<Void> thenAcceptBoth​(CompletionStage<? extends U> other,
                                         BiConsumer<? super T,? super U> action)
        返回一个新的CompletionStage，当这个和另一个给定的阶段都正常完成时，两个结果作为提供的操作的参数被执行。 有关特殊完成的规则，请参阅CompletionStage文档。
        参数类型
        U - 其他CompletionStage的结果的类型
        参数
        other - 其他CompletionStage
        action - 在完成返回的CompletionStage之前执行的操作
        结果
        新的CompletionStage

      • thenAcceptBothAsync

        <U> CompletionStage<Void> thenAcceptBothAsync​(CompletionStage<? extends U> other,
                                              BiConsumer<? super T,? super U> action)
        返回一个新的CompletionStage，当这个和另一个给定阶段都正常完成时，将使用此阶段的默认异步执行工具执行，其中两个结果作为提供的操作的参数。 有关特殊完成的规则，请参阅CompletionStage文档。
        参数类型
        U - 其他CompletionStage的结果的类型
        参数
        other - 其他CompletionStage
        action - 在完成返回的CompletionStage之前执行的操作
        结果
        新的CompletionStage

      • thenAcceptBothAsync

        <U> CompletionStage<Void> thenAcceptBothAsync​(CompletionStage<? extends U> other,
                                              BiConsumer<? super T,? super U> action,
                                              Executor executor)
        返回一个新的CompletionStage，当这个和另一个给定的阶段都正常完成时，将使用提供的执行器执行，其中两个结果作为提供的操作的参数。 请参阅CompletionStage文档，了解完整的规则。
        参数类型
        U - 其他CompletionStage的结果的类型
        参数
        other - 其他CompletionStage
        action - 在完成返回的CompletionStage之前执行的操作
        executor - 执行器用于异步执行
        结果
        新的CompletionStage

      • runAfterBoth

        CompletionStage<Void> runAfterBoth​(CompletionStage<?> other,
                                   Runnable action)
        返回一个新的CompletionStage，当这个和另一个给定的阶段都正常完成时，执行给定的动作。 请参阅CompletionStage有关特殊完成规则的文档。
        参数
        other - 其他CompletionStage
        action - 在完成返回的CompletionStage之前执行的操作
        结果
        新的CompletionStage

      • runAfterBothAsync

        CompletionStage<Void> runAfterBothAsync​(CompletionStage<?> other,
                                        Runnable action)
        返回一个新的CompletionStage，当这个和另一个给定阶段都正常完成时，使用此阶段的默认异步执行工具执行给定的操作。 有关特殊完成的规则，请参阅CompletionStage文档。
        参数
        other - 其他CompletionStage
        action - 在完成返回的CompletionStage之前执行的操作
        结果
        新的CompletionStage

      • runAfterBothAsync

        CompletionStage<Void> runAfterBothAsync​(CompletionStage<?> other,
                                        Runnable action,
                                        Executor executor)
        返回一个新的CompletionStage，当这个和另一个给定的阶段都正常完成时，使用提供的执行器执行给定的动作。 请参阅CompletionStage文档，了解覆盖异常完成的规则。
        参数
        other - 其他CompletionStage
        action - 在完成返回的CompletionStage之前执行的操作
        executor - 执行器用于异步执行
        结果
        新的CompletionStage

      • applyToEither

        <U> CompletionStage<U> applyToEither​(CompletionStage<? extends T> other,
                                     Function<? super T,U> fn)
        返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，执行相应的结果作为提供的函数的参数。 请参阅CompletionStage有关特殊完成规则的文档。
        参数类型
        U - 函数的返回类型
        参数
        other - 其他CompletionStage
        fn - 用于计算返回的CompletionStage的值的函数
        结果
        新的CompletionStage

      • applyToEitherAsync

        <U> CompletionStage<U> applyToEitherAsync​(CompletionStage<? extends T> other,
                                          Function<? super T,U> fn)
        返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，将使用此阶段的默认异步执行工具执行，其中相应的结果作为提供函数的参数。 请参阅CompletionStage文档，了解完整的规则。
        参数类型
        U - 函数的返回类型
        参数
        other - 其他CompletionStage
        fn - 用于计算返回的CompletionStage的值的函数
        结果
        新的CompletionStage

      • applyToEitherAsync

        <U> CompletionStage<U> applyToEitherAsync​(CompletionStage<? extends T> other,
                                          Function<? super T,U> fn,
                                          Executor executor)
        返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，将使用提供的执行器执行，其中相应的结果作为参数提供给函数。 请参阅CompletionStage文档，了解完整的规则。
        参数类型
        U - 函数的返回类型
        参数
        other - 其他CompletionStage
        fn - 用于计算返回的CompletionStage的值的函数
        executor - 执行器用于异步执行
        结果
        新的CompletionStage

      • acceptEither

        CompletionStage<Void> acceptEither​(CompletionStage<? extends T> other,
                                   Consumer<? super T> action)
        返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，执行相应的结果作为提供的操作的参数。 请参阅CompletionStage文档，了解完整的规则。
        参数
        other - 其他CompletionStage
        action - 在完成返回的CompletionStage之前执行的操作
        结果
        新的CompletionStage

      • acceptEitherAsync

        CompletionStage<Void> acceptEitherAsync​(CompletionStage<? extends T> other,
                                        Consumer<? super T> action)
        返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，将使用此阶段的默认异步执行工具执行，其中相应的结果作为提供的操作的参数。 有关特殊完成的规则，请参阅CompletionStage文档。
        参数
        other - 其他CompletionStage
        action - 在完成返回的CompletionStage之前执行的操作
        结果
        新的CompletionStage

      • acceptEitherAsync

        CompletionStage<Void> acceptEitherAsync​(CompletionStage<? extends T> other,
                                        Consumer<? super T> action,
                                        Executor executor)
        返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，使用提供的执行器执行，其中相应的结果作为参数提供的操作。 请参阅CompletionStage文档，了解完整的规则。
        参数
        other - 其他CompletionStage
        action - 在完成返回的CompletionStage之前执行的操作
        executor - 执行器用于异步执行
        结果
        新的CompletionStage

      • runAfterEither

        CompletionStage<Void> runAfterEither​(CompletionStage<?> other,
                                     Runnable action)
        返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，执行给定的操作。 有关特殊完成的规则，请参阅CompletionStage文档。
        参数
        other - 其他CompletionStage
        action - 在完成返回的CompletionStage之前执行的操作
        结果
        新的CompletionStage

      • runAfterEitherAsync

        CompletionStage<Void> runAfterEitherAsync​(CompletionStage<?> other,
                                          Runnable action)
        返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，使用此阶段的默认异步执行工具执行给定的操作。 请参阅CompletionStage文档，了解覆盖异常完成的规则。
        参数
        other - 其他CompletionStage
        action - 在完成返回的CompletionStage之前执行的操作
        结果
        新的CompletionStage

      • runAfterEitherAsync

        CompletionStage<Void> runAfterEitherAsync​(CompletionStage<?> other,
                                          Runnable action,
                                          Executor executor)
        返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，使用提供的执行器执行给定的操作。 请参阅CompletionStage文档，了解完整的规则。
        参数
        other - 其他CompletionStage
        action - 在完成返回的CompletionStage之前执行的操作
        executor - 执行器用于异步执行
        结果
        新的CompletionStage

      • thenCompose

        <U> CompletionStage<U> thenCompose​(Function<? super T,? extends CompletionStage<U>> fn)
        返回一个完成的新的CompletionStage，其值与给定函数返回的CompletionStage相同。

        当这个阶段正常完成时，以该阶段的结果作为参数调用给定的函数，返回另一个CompletionStage。 当该阶段正常完成时，此方法返回的CompletionStage将以相同的值完成。

        为了确保进度，提供的功能必须最终完成其结果。

        该方法类似于Optional.flatMap和Stream.flatMap 。

        有关特殊完成的规则，请参阅CompletionStage文档。

        参数类型
        U - 返回的CompletionStage结果的类型
        参数
        fn - 用于计算另一个CompletionStage的函数
        结果
        新的CompletionStage

      • thenComposeAsync

        <U> CompletionStage<U> thenComposeAsync​(Function<? super T,? extends CompletionStage<U>> fn)
        返回一个新的CompletionStage，其完成值与给定函数返回的CompletionStage值相同，并使用该阶段的默认异步执行工具执行。

        当这个阶段正常完成时，以该阶段的结果作为参数调用给定的函数，返回另一个CompletionStage。 当该阶段正常完成时，此方法返回的CompletionStage将以相同的值完成。

        为了确保进度，提供的功能必须最终完成其结果。

        请参阅CompletionStage文档，了解完整的规则。

        参数类型
        U - 返回的CompletionStage结果的类型
        参数
        fn - 用于计算另一个CompletionStage的函数
        结果
        新的CompletionStage

      • thenComposeAsync

        <U> CompletionStage<U> thenComposeAsync​(Function<? super T,? extends CompletionStage<U>> fn,
                                        Executor executor)
        返回一个新的CompletionStage，其完成值与给定函数返回的CompletionStage值相同，并使用提供的Executor执行。

        当这个阶段正常完成时，以该阶段的结果作为参数调用给定的函数，返回另一个CompletionStage。 当该阶段正常完成时，此方法返回的CompletionStage将以相同的值完成。

        为了确保进度，提供的功能必须最终完成其结果。

        请参阅CompletionStage文档，了解覆盖完成的规则。

        参数类型
        U - 返回的CompletionStage结果的类型
        参数
        fn - 用于计算另一个CompletionStage的函数
        executor - 执行器用于异步执行
        结果
        新的CompletionStage

      • handle

        <U> CompletionStage<U> handle​(BiFunction<? super T,Throwable,? extends U> fn)
        返回一个新的CompletionStage，当此阶段正常或异常完成时，将使用此阶段的结果和异常作为所提供函数的参数执行。

        当这个阶段完成时，使用结果（或null如果没有））和此阶段的异常（或null如果没有）作为参数）调用给定的函数，并且使用函数的结果来完成返回的阶段。

        参数类型
        U - 函数的返回类型
        参数
        fn - 用于计算返回的CompletionStage的值的函数
        结果
        新的CompletionStage

      • handleAsync

        <U> CompletionStage<U> handleAsync​(BiFunction<? super T,Throwable,? extends U> fn)
        返回一个新的CompletionStage，当该阶段完成正常或异常时，将使用此阶段的默认异步执行工具执行，此阶段的结果和异常作为提供函数的参数。

        当这个阶段完成时，使用结果（或null如果没有））和此阶段的异常（或null如果没有）作为参数）调用给定函数，并使用函数的结果来完成返回的阶段。

        参数类型
        U - 函数的返回类型
        参数
        fn - 用于计算返回的CompletionStage的值的函数
        结果
        新的CompletionStage

      • handleAsync

        <U> CompletionStage<U> handleAsync​(BiFunction<? super T,Throwable,? extends U> fn,
                                   Executor executor)
        返回一个新的CompletionStage，当此阶段正常或异常完成时，将使用提供的执行程序执行此阶段的结果和异常作为提供的函数的参数。

        当这个阶段完成时，使用结果（或者null如果没有）和这个阶段的异常（或者null如果没有）作为参数）调用给定的函数，并且使用函数的结果来完成返回的阶段。

        参数类型
        U - 函数的返回类型
        参数
        fn - 用于计算返回的CompletionStage的值的函数
        executor - 执行器用于异步执行
        结果
        新的CompletionStage

      • whenComplete

        CompletionStage<T> whenComplete​(BiConsumer<? super T,? super Throwable> action)
        返回与此阶段相同的结果或异常的新CompletionStage，当此阶段完成时，它将执行给定的操作。

        当这个阶段完成时，使用结果（或null如果没有））和此阶段的异常（或null如果没有）作为参数）调用给定的操作。 返回的阶段在行动返回时完成。

        与方法handle不同，此方法不是设计为翻译完成结果，因此提供的操作不应抛出异常。 但是，如果这样做，则适用以下规则：如果此阶段正常完成，但提供的操作引发异常，则返回的阶段会以提供的操作异常完成。 或者，如果此阶段完成异常且提供的操作引发异常，那么返回的阶段会在此阶段异常结束。

        参数
        action - 要执行的动作
        结果
        新的CompletionStage

      • whenCompleteAsync

        CompletionStage<T> whenCompleteAsync​(BiConsumer<? super T,? super Throwable> action)
        返回与此阶段相同结果或异常的新CompletionStage，当此阶段完成时，将使用此阶段的默认异步执行工具执行给定操作。

        当这个阶段完成时，使用结果（或null如果没有））和此阶段的异常（或null如果没有）作为参数）调用给定的操作。 返回的阶段在行动返回时完成。

        与方法handleAsync不同，此方法不是设计为翻译完成结果，因此提供的操作不应抛出异常。 但是，如果这样做，则适用以下规则：如果此阶段正常完成但提供的操作引发异常，那么返回的阶段会以提供的操作异常完成。 或者，如果此阶段完成异常且提供的操作引发异常，那么返回的阶段会在此阶段异常结束。

        参数
        action - 要执行的动作
        结果
        新的CompletionStage

      • whenCompleteAsync

        CompletionStage<T> whenCompleteAsync​(BiConsumer<? super T,? super Throwable> action,
                                     Executor executor)
        返回与此阶段相同结果或异常的新CompletionStage，当此阶段完成时，使用提供的执行程序执行给定操作。

        当这个阶段完成时，使用结果（或者null如果没有）和异常（或null如果没有）作为参数调用给定的动作。 返回的阶段在行动返回时完成。

        与方法handleAsync不同，此方法不是设计为翻译完成结果，因此提供的操作不应抛出异常。 但是，如果这样做，则适用以下规则：如果此阶段正常完成但提供的操作引发异常，那么返回的阶段会以提供的操作异常完成。 或者，如果此阶段完成异常且提供的操作引发异常，那么返回的阶段会在此阶段异常结束。

        参数
        action - 要执行的动作
        executor - 执行器用于异步执行
        结果
        新的CompletionStage

      • exceptionally

        CompletionStage<T> exceptionally​(Function<Throwable,? extends T> fn)
        返回一个新的CompletionStage，当此阶段完成异常时，将以此阶段的异常作为提供函数的参数执行。 否则，如果此阶段正常完成，那么返回的阶段也会以相同的值正常完成。
        参数
        fn - 用于计算返回的CompletionStage的值的函数，如果此CompletionStage异常完成
        结果
        新的CompletionStage

      • toCompletableFuture

        CompletableFuture<T> toCompletableFuture​()
        返回一个CompletableFuture，保持与此阶段相同的完成属性。 如果这个阶段已经是一个CompletableFuture，那么这个方法本身就可以返回这个阶段。 否则，此方法的调用可能等同于thenApply(x -> x) ，但返回的类型为CompletableFuture的实例。
        结果
        the CompletableFuture