Module java.base
Package java.util.concurrent

Class CompletableFuture<T>

java.lang.Object
java.util.concurrent.CompletableFuture<T>
类型参数:
T - 由此future的join和get方法返回的结果类型
所有实现的接口:
CompletionStage<T>, Future<T>
public class CompletableFuture<T> extends Object implements Future<T>, CompletionStage<T>
一个可能被显式完成（设置其值和状态）的Future，并且可以用作CompletionStage，支持依赖函数和在其完成时触发的操作。

当两个或更多线程尝试complete、completeExceptionally或cancel一个CompletableFuture时，只有其中一个成功。

除了这些直接操作状态和结果的相关方法外，CompletableFuture还实现了接口CompletionStage，具有以下策略：

  • 为非异步方法的依赖完成提供的操作可以由完成当前CompletableFuture的线程执行，也可以由任何其他调用者调用完成方法。
  • 所有没有显式Executor参数的异步方法都使用ForkJoinPool.commonPool()执行（除非它不支持至少两个并行级别，在这种情况下，将创建一个新线程来运行每个任务）。这可以通过在子类中定义方法defaultExecutor()来覆盖。为了简化监视、调试和跟踪，所有生成的异步任务都是CompletableFuture.AsynchronousCompletionTask接口的实例。具有时间延迟的操作可以使用此类中定义的适配器方法，例如：supplyAsync(supplier, delayedExecutor(timeout, timeUnit))。为了支持具有延迟和超时的方法，此类最多维护一个守护线程来触发和取消操作，而不是运行它们。
  • 所有CompletionStage方法都独立于其他公共方法实现，因此一个方法的行为不受子类中其他方法的覆盖影响。
  • 所有CompletionStage方法都返回CompletableFutures。要将用法限制为仅限于接口CompletionStage中定义的方法，请使用方法minimalCompletionStage()。或者为了确保客户端不修改future本身，使用方法copy()。

CompletableFuture还实现了接口Future，具有以下策略：

  • 由于（与FutureTask不同）此类无法直接控制导致其完成的计算，因此取消被视为异常完成的另一种形式。方法cancel的效果与completeExceptionally(new CancellationException())相同。方法isCompletedExceptionally()可用于确定CompletableFuture是否以任何异常方式完成。
  • 在使用CompletionException异常完成的情况下，方法get()和get(long, TimeUnit)会抛出一个与相应CompletionException中保存的原因相同的ExecutionException。为了在大多数情况下简化使用，此类还定义了方法join()和getNow(T)，在这些情况下直接抛出CompletionException。

用于传递完成结果（即类型为T的参数）的参数可以为null，但为任何其他参数传递null值将导致抛出NullPointerException。

此类的子类通常应该覆盖“虚拟构造函数”方法newIncompleteFuture()，该方法确定由CompletionStage方法返回的具体类型。例如，这是一个替换不同默认Executor并禁用obtrude方法的类：

 
 class MyCompletableFuture<T> extends CompletableFuture<T> {
   static final Executor myExecutor = ...;
   public MyCompletableFuture() { }
   public <U> CompletableFuture<U> newIncompleteFuture() {
     return new MyCompletableFuture<U>(); }
   public Executor defaultExecutor() {
     return myExecutor; }
   public void obtrudeValue(T value) {
     throw new UnsupportedOperationException(); }
   public void obtrudeException(Throwable ex) {
     throw new UnsupportedOperationException(); }
 }
自Java版本:
1.8

  • Constructor Details

    • CompletableFuture

      public CompletableFuture()
      Creates a new incomplete CompletableFuture.

  • Method Details

    • supplyAsync

      public static <U> CompletableFuture<U> supplyAsync(Supplier<U> supplier)
      Returns a new CompletableFuture that is asynchronously completed by a task running in the ForkJoinPool.commonPool() with the value obtained by calling the given Supplier.
      类型参数：
      U - 函数的返回类型
      参数：
      supplier - 返回值以完成返回的CompletableFuture的函数
      返回：
      新的CompletableFuture

    • supplyAsync

      public static <U> CompletableFuture<U> supplyAsync(Supplier<U> supplier, Executor executor)
      返回一个新的CompletableFuture，由在给定执行器中运行的任务异步完成，之后运行给定操作。
      类型参数：
      U - 函数的返回类型
      参数：
      supplier - 返回值以完成返回的CompletableFuture的函数
      executor - 用于异步执行的执行器
      返回：
      新的CompletableFuture

    • runAsync

      public static CompletableFuture<Void> runAsync(Runnable runnable)
      返回一个新的CompletableFuture，由在ForkJoinPool.commonPool()中运行的任务异步完成，之后运行给定操作。
      参数：
      runnable - 在完成返回的CompletableFuture之前运行的操作
      返回：
      新的CompletableFuture

    • runAsync

      public static CompletableFuture<Void> runAsync(Runnable runnable, Executor executor)
      返回一个新的CompletableFuture，由在给定执行器中运行的任务异步完成，之后运行给定操作。
      参数：
      runnable - 在完成返回的CompletableFuture之前运行的操作
      executor - 用于异步执行的执行器
      返回：
      新的CompletableFuture

    • completedFuture

      public static <U> CompletableFuture<U> completedFuture(U value)
      返回一个已使用给定值完成的新CompletableFuture。
      类型参数：
      U - 值的类型
      参数：
      value - 值
      返回：
      已完成的CompletableFuture

    • isDone

      public boolean isDone()
      返回true，如果以任何方式完成：正常完成、异常完成或通过取消完成。
      指定者：
      isDone 在接口 Future<T>
      返回：
      如果已完成，则返回true

    • get

      public T get() throws InterruptedException, ExecutionException
      如果需要，等待此future完成，然后返回其结果。
      指定者：
      get 在接口 Future<T>
      返回：
      结果值
      抛出：
      CancellationException - 如果此future被取消
      ExecutionException - 如果此future异常完成
      InterruptedException - 如果当前线程在等待时被中断

    • get

      public T get(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException
      在必要时等待最多给定时间，以使此future完成，然后返回其结果（如果可用）。
      指定者：
      get 在接口 Future<T>中
      参数：
      timeout - 最长等待时间
      unit - 超时参数的时间单位
      返回：
      结果值
      抛出：
      CancellationException - 如果此future被取消
      ExecutionException - 如果此future异常完成
      InterruptedException - 如果当前线程在等待时被中断
      TimeoutException - 如果等待超时

    • join

      public T join()
      当完成时返回结果值，或者如果异常完成则抛出（未经检查的）异常。为了更好地符合常见函数形式的使用，如果在完成此CompletableFuture的过程中涉及的计算引发异常，则此方法将抛出（未经检查的）CompletionException，其根本异常作为其原因。
      返回：
      结果值
      抛出：
      CancellationException - 如果计算被取消
      CompletionException - 如果此future异常完成或完成计算引发异常

    • getNow

      public T getNow(T valueIfAbsent)
      如果已完成，则返回结果值（或抛出任何遇到的异常），否则返回给定的valueIfAbsent。
      参数：
      valueIfAbsent - 如果未完成，则返回的值
      返回：
      结果值，如果已完成，则为给定的valueIfAbsent
      抛出：
      CancellationException - 如果计算被取消
      CompletionException - 如果此future异常完成或完成计算引发异常

    • complete

      public boolean complete(T value)
      如果尚未完成，则将由get()和相关方法返回的值设置为给定值。
      参数：
      value - 结果值
      返回：
      如果此调用导致此CompletableFuture过渡到已完成状态，则为true，否则为false

    • completeExceptionally

      public boolean completeExceptionally(Throwable ex)
      如果尚未完成，则导致get()和相关方法的调用抛出给定的异常。
      参数：
      ex - 异常
      返回：
      如果此调用导致此CompletableFuture过渡到已完成状态，则为true，否则为false

    • thenApply

      public <U> CompletableFuture<U> thenApply(Function<? super T,? extends U> fn)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，当此阶段正常完成时，将使用此阶段的结果作为提供的函数的参数执行。

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

      请参阅CompletionStage文档，了解异常完成的规则。

      指定者：
      thenApply 在接口 CompletionStage<T>中
      类型参数：
      U - 函数的返回类型
      参数：
      fn - 用于计算返回的CompletionStage值的函数
      返回：
      新的CompletionStage

    • thenApplyAsync

      public <U> CompletableFuture<U> thenApplyAsync(Function<? super T,? extends U> fn)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，当此阶段正常完成时，将使用此阶段的默认异步执行设施执行，将此阶段的结果作为提供的函数的参数。请参阅CompletionStage文档，了解异常完成的规则。
      指定者：
      thenApplyAsync 在接口 CompletionStage<T>中
      类型参数：
      U - 函数的返回类型
      参数：
      fn - 用于计算返回的CompletionStage值的函数
      返回：
      新的CompletionStage

    • thenApplyAsync

      public <U> CompletableFuture<U> thenApplyAsync(Function<? super T,? extends U> fn, Executor executor)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，当此阶段正常完成时，将使用提供的Executor执行，将此阶段的结果作为提供的函数的参数。请参阅CompletionStage文档，了解异常完成的规则。
      指定者：
      thenApplyAsync 在接口 CompletionStage<T>中
      类型参数：
      U - 函数的返回类型
      参数：
      fn - 用于计算返回的CompletionStage值的函数
      executor - 用于异步执行的执行程序
      返回：
      新的CompletionStage

    • thenAccept

      public CompletableFuture<Void> thenAccept(Consumer<? super T> action)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，当此阶段正常完成时，将使用此阶段的结果作为提供的操作的参数执行。请参阅CompletionStage文档，了解异常完成的规则。
      指定者：
      thenAccept 在接口 CompletionStage<T>中
      参数：
      action - 在完成返回的CompletionStage之前执行的操作
      返回：
      新的CompletionStage

    • thenAcceptAsync

      public CompletableFuture<Void> thenAcceptAsync(Consumer<? super T> action)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，当此阶段正常完成时，将使用此阶段的默认异步执行设施执行，将此阶段的结果作为提供的操作的参数。请参阅CompletionStage文档，了解异常完成的规则。
      指定者：
      thenAcceptAsync 在接口 CompletionStage<T>中
      参数：
      action - 在完成返回的CompletionStage之前执行的操作
      返回：
      新的CompletionStage

    • thenAcceptAsync

      public CompletableFuture<Void> thenAcceptAsync(Consumer<? super T> action, Executor executor)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，当此阶段正常完成时，将使用提供的Executor执行，将此阶段的结果作为提供的操作的参数。请参阅CompletionStage文档，了解异常完成的规则。
      指定者：
      thenAcceptAsync 在接口 CompletionStage<T>中
      参数：
      action - 在完成返回的CompletionStage之前执行的操作
      executor - 用于异步执行的执行程序
      返回：
      新的CompletionStage

    • thenRun

      public CompletableFuture<Void> thenRun(Runnable action)
      从接口复制的描述: CompletionStage
      返回一个新的CompletionStage，当此阶段正常完成时，执行给定的操作。请参阅CompletionStage文档，了解异常完成的规则。
      指定者:
      thenRun 在接口 CompletionStage<T>
      参数:
      action - 在完成返回的CompletionStage之前执行的操作
      返回:
      新的CompletionStage

    • thenRunAsync

      public CompletableFuture<Void> thenRunAsync(Runnable action)
      从接口复制的描述: CompletionStage
      返回一个新的CompletionStage，当此阶段正常完成时，使用此阶段的默认异步执行设施执行给定的操作。请参阅CompletionStage文档，了解异常完成的规则。
      指定者:
      thenRunAsync 在接口 CompletionStage<T>
      参数:
      action - 在完成返回的CompletionStage之前执行的操作
      返回:
      新的CompletionStage

    • thenRunAsync

      public CompletableFuture<Void> thenRunAsync(Runnable action, Executor executor)
      从接口复制的描述: CompletionStage
      返回一个新的CompletionStage，当此阶段正常完成时，使用提供的Executor执行给定的操作。请参阅CompletionStage文档，了解异常完成的规则。
      指定者:
      thenRunAsync 在接口 CompletionStage<T>
      参数:
      action - 在完成返回的CompletionStage之前执行的操作
      executor - 用于异步执行的执行器
      返回:
      新的CompletionStage

    • thenCombine

      public <U, V> CompletableFuture<V> thenCombine(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn)
      从接口复制的描述: CompletionStage
      返回一个新的CompletionStage，当此阶段和另一个给定阶段都正常完成时，使用两个结果作为提供的函数的参数执行。请参阅CompletionStage文档，了解异常完成的规则。
      指定者:
      thenCombine 在接口 CompletionStage<T>
      类型参数:
      U - 另一个CompletionStage结果的类型
      V - 函数的返回类型
      参数:
      other - 另一个CompletionStage
      fn - 用于计算返回的CompletionStage值的函数
      返回:
      新的CompletionStage

    • thenCombineAsync

      public <U, V> CompletableFuture<V> thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn)
      从接口复制的描述: CompletionStage
      返回一个新的CompletionStage，当此阶段和另一个给定阶段都正常完成时，使用此阶段的默认异步执行设施，将两个结果作为提供的函数的参数执行。请参阅CompletionStage文档，了解异常完成的规则。
      指定者:
      thenCombineAsync 在接口 CompletionStage<T>
      类型参数:
      U - 另一个CompletionStage结果的类型
      V - 函数的返回类型
      参数:
      other - 另一个CompletionStage
      fn - 用于计算返回的CompletionStage值的函数
      返回:
      新的CompletionStage

    • thenCombineAsync

      public <U, V> CompletableFuture<V> thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn, Executor executor)
      从接口复制的描述: CompletionStage
      返回一个新的CompletionStage，当此阶段和另一个给定阶段都正常完成时，使用提供的执行器执行，将两个结果作为提供的函数的参数执行。请参阅CompletionStage文档，了解异常完成的规则。
      指定者:
      thenCombineAsync 在接口 CompletionStage<T>
      类型参数:
      U - 另一个CompletionStage结果的类型
      V - 函数的返回类型
      参数:
      other - 另一个CompletionStage
      fn - 用于计算返回的CompletionStage值的函数
      executor - 用于异步执行的执行器
      返回:
      新的CompletionStage

    • thenAcceptBoth

      public <U> CompletableFuture<Void> thenAcceptBoth(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action)
      从接口复制的描述: CompletionStage
      返回一个新的CompletionStage，当此阶段和另一个给定阶段都正常完成时，使用两个结果作为提供的操作的参数执行。请参阅CompletionStage文档，了解异常完成的规则。
      指定者:
      thenAcceptBoth 在接口 CompletionStage<T>
      类型参数:
      U - 另一个CompletionStage结果的类型
      参数:
      other - 另一个CompletionStage
      action - 在完成返回的CompletionStage之前执行的操作
      返回:
      新的CompletionStage

    • thenAcceptBothAsync

      public <U> CompletableFuture<Void> thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action)
      从接口复制的描述: CompletionStage
      返回一个新的CompletionStage，当此阶段和另一个给定阶段都正常完成时，使用此阶段的默认异步执行设施，将两个结果作为提供的操作的参数执行。请参阅CompletionStage文档，了解异常完成的规则。
      指定者:
      thenAcceptBothAsync 在接口 CompletionStage<T>
      类型参数:
      U - 另一个CompletionStage结果的类型
      参数:
      other - 另一个CompletionStage
      action - 在完成返回的CompletionStage之前执行的操作
      返回:
      新的CompletionStage

    • thenAcceptBothAsync

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

    • runAfterBoth

      public CompletableFuture<Void> runAfterBoth(CompletionStage<?> other, Runnable action)
      从接口复制的描述: CompletionStage
      返回一个新的CompletionStage，当此CompletionStage和另一个给定的阶段都正常完成时，执行给定的操作。请参阅CompletionStage文档，了解异常完成的规则。
      指定者:
      runAfterBoth 在接口 CompletionStage<T>中
      参数:
      other - 另一个CompletionStage
      action - 在完成返回的CompletionStage之前执行的操作
      返回:
      新的CompletionStage

    • runAfterBothAsync

      public CompletableFuture<Void> runAfterBothAsync(CompletionStage<?> other, Runnable action)
      从接口复制的描述: CompletionStage
      返回一个新的CompletionStage，当此CompletionStage和另一个给定的阶段都正常完成时，使用此阶段的默认异步执行设施执行给定的操作。请参阅CompletionStage文档，了解异常完成的规则。
      指定者:
      runAfterBothAsync 在接口 CompletionStage<T>中
      参数:
      other - 另一个CompletionStage
      action - 在完成返回的CompletionStage之前执行的操作
      返回:
      新的CompletionStage

    • runAfterBothAsync

      public CompletableFuture<Void> runAfterBothAsync(CompletionStage<?> other, Runnable action, Executor executor)
      从接口复制的描述: CompletionStage
      返回一个新的CompletionStage，当此CompletionStage和另一个给定的阶段都正常完成时，使用提供的执行器执行给定的操作。请参阅CompletionStage文档，了解异常完成的规则。
      指定者:
      runAfterBothAsync 在接口 CompletionStage<T>中
      参数:
      other - 另一个CompletionStage
      action - 在完成返回的CompletionStage之前执行的操作
      executor - 用于异步执行的执行器
      返回:
      新的CompletionStage

    • applyToEither

      public <U> CompletableFuture<U> applyToEither(CompletionStage<? extends T> other, Function<? super T,U> fn)
      从接口复制的描述: CompletionStage
      返回一个新的CompletionStage，当此CompletionStage或另一个给定的阶段正常完成时，使用相应的结果作为参数执行提供的函数。请参阅CompletionStage文档，了解异常完成的规则。
      指定者:
      applyToEither 在接口 CompletionStage<T>中
      类型参数:
      U - 函数的返回类型
      参数:
      other - 另一个CompletionStage
      fn - 用于计算返回的CompletionStage值的函数
      返回:
      新的CompletionStage

    • applyToEitherAsync

      public <U> CompletableFuture<U> applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T,U> fn)
      从接口复制的描述: CompletionStage
      返回一个新的CompletionStage，当此CompletionStage或另一个给定的阶段正常完成时，使用此阶段的默认异步执行设施执行提供的函数，将相应的结果作为参数。请参阅CompletionStage文档，了解异常完成的规则。
      指定者:
      applyToEitherAsync 在接口 CompletionStage<T>中
      类型参数:
      U - 函数的返回类型
      参数:
      other - 另一个CompletionStage
      fn - 用于计算返回的CompletionStage值的函数
      返回:
      新的CompletionStage

    • applyToEitherAsync

      public <U> CompletableFuture<U> applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T,U> fn, Executor executor)
      从接口复制的描述: CompletionStage
      返回一个新的CompletionStage，当此CompletionStage或另一个给定的阶段正常完成时，使用提供的执行器执行提供的函数，将相应的结果作为参数。请参阅CompletionStage文档，了解异常完成的规则。
      指定者:
      applyToEitherAsync 在接口 CompletionStage<T>中
      类型参数:
      U - 函数的返回类型
      参数:
      other - 另一个CompletionStage
      fn - 用于计算返回的CompletionStage值的函数
      executor - 用于异步执行的执行器
      返回:
      新的CompletionStage

    • acceptEither

      public CompletableFuture<Void> acceptEither(CompletionStage<? extends T> other, Consumer<? super T> action)
      从接口复制的描述: CompletionStage
      返回一个新的CompletionStage，当此CompletionStage或另一个给定的阶段正常完成时，使用相应的结果作为参数执行提供的操作。请参阅CompletionStage文档，了解异常完成的规则。
      指定者:
      acceptEither 在接口 CompletionStage<T>中
      参数:
      other - 另一个CompletionStage
      action - 在完成返回的CompletionStage之前执行的操作
      返回:
      新的CompletionStage

    • acceptEitherAsync

      public CompletableFuture<Void> acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action)
      从接口复制的描述: CompletionStage
      返回一个新的CompletionStage，当此CompletionStage或另一个给定的阶段正常完成时，使用此阶段的默认异步执行设施执行提供的操作，将相应的结果作为参数。请参阅CompletionStage文档，了解异常完成的规则。
      指定由：
      acceptEitherAsync 在接口 CompletionStage<T>
      参数：
      other - 另一个CompletionStage
      action - 在完成返回的CompletionStage之前执行的操作
      返回：
      新的CompletionStage

    • acceptEitherAsync

      public CompletableFuture<Void> acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action, Executor executor)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，当这个或另一个给定的阶段正常完成时，将使用提供的执行程序执行，将相应的结果作为参数传递给提供的操作。请参阅CompletionStage文档，了解异常完成的规则。
      指定由：
      acceptEitherAsync 在接口 CompletionStage<T>
      参数：
      other - 另一个CompletionStage
      action - 在完成返回的CompletionStage之前执行的操作
      executor - 用于异步执行的执行程序
      返回：
      新的CompletionStage

    • runAfterEither

      public CompletableFuture<Void> runAfterEither(CompletionStage<?> other, Runnable action)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，当这个或另一个给定的阶段正常完成时，执行给定的操作。请参阅CompletionStage文档，了解异常完成的规则。
      指定由：
      runAfterEither 在接口 CompletionStage<T>
      参数：
      other - 另一个CompletionStage
      action - 在完成返回的CompletionStage之前执行的操作
      返回：
      新的CompletionStage

    • runAfterEitherAsync

      public CompletableFuture<Void> runAfterEitherAsync(CompletionStage<?> other, Runnable action)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，当这个或另一个给定的阶段正常完成时，使用此阶段的默认异步执行设施执行给定的操作。请参阅CompletionStage文档，了解异常完成的规则。
      指定由：
      runAfterEitherAsync 在接口 CompletionStage<T>
      参数：
      other - 另一个CompletionStage
      action - 在完成返回的CompletionStage之前执行的操作
      返回：
      新的CompletionStage

    • runAfterEitherAsync

      public CompletableFuture<Void> runAfterEitherAsync(CompletionStage<?> other, Runnable action, Executor executor)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，当这个或另一个给定的阶段正常完成时，使用提供的执行程序执行给定的操作。请参阅CompletionStage文档，了解异常完成的规则。
      指定由：
      runAfterEitherAsync 在接口 CompletionStage<T>
      参数：
      other - 另一个CompletionStage
      action - 在完成返回的CompletionStage之前执行的操作
      executor - 用于异步执行的执行程序
      返回：
      新的CompletionStage

    • thenCompose

      public <U> CompletableFuture<U> thenCompose(Function<? super T,? extends CompletionStage<U>> fn)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，其完成值与给定函数返回的CompletionStage的值相同。

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

      为了确保进展，提供的函数必须安排其结果的最终完成。

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

      请参阅CompletionStage文档，了解异常完成的规则。

      指定由：
      thenCompose 在接口 CompletionStage<T>
      类型参数：
      U - 返回的CompletionStage结果的类型
      参数：
      fn - 用于计算另一个CompletionStage的函数
      返回：
      新的CompletionStage

    • thenComposeAsync

      public <U> CompletableFuture<U> thenComposeAsync(Function<? super T,? extends CompletionStage<U>> fn)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，其完成值与使用此阶段的默认异步执行设施执行的给定函数返回的CompletionStage的值相同。

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

      为了确保进展，提供的函数必须安排其结果的最终完成。

      请参阅CompletionStage文档，了解异常完成的规则。

      指定由：
      thenComposeAsync 在接口 CompletionStage<T>
      类型参数：
      U - 返回的CompletionStage结果的类型
      参数：
      fn - 用于计算另一个CompletionStage的函数
      返回：
      新的CompletionStage

    • thenComposeAsync

      public <U> CompletableFuture<U> thenComposeAsync(Function<? super T,? extends CompletionStage<U>> fn, Executor executor)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，其完成值与使用提供的执行程序执行的给定函数返回的CompletionStage的值相同。

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

      为了确保进展，提供的函数必须安排其结果的最终完成。

      请参阅CompletionStage文档，了解异常完成的规则。

      指定由：
      thenComposeAsync 在接口 CompletionStage<T>
      类型参数：
      U - 返回的CompletionStage结果的类型
      参数：
      fn - 用于计算另一个CompletionStage的函数
      executor - 用于异步执行的执行程序
      返回：
      新的CompletionStage

    • whenComplete

      public CompletableFuture<T> whenComplete(BiConsumer<? super T,? super Throwable> action)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，其结果或异常与此阶段相同，在此阶段完成时执行给定操作。

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

      与方法handle不同，此方法不设计用于转换完成结果，因此提供的操作不应抛出异常。但是，如果抛出异常，则适用以下规则：如果此阶段正常完成但提供的操作抛出异常，则返回的阶段将异常完成，并带有提供的操作的异常。或者，如果此阶段异常完成且提供的操作抛出异常，则返回的阶段将异常完成，并带有此阶段的异常。

      指定者：
      whenComplete 在接口 CompletionStage<T>中
      参数：
      action - 要执行的操作
      返回：
      新的CompletionStage

    • whenCompleteAsync

      public CompletableFuture<T> whenCompleteAsync(BiConsumer<? super T,? super Throwable> action)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，其结果或异常与此阶段相同，在此阶段完成时使用此阶段的默认异步执行设施执行给定操作。

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

      与方法handleAsync不同，此方法不设计用于转换完成结果，因此提供的操作不应抛出异常。但是，如果抛出异常，则适用以下规则：如果此阶段正常完成但提供的操作抛出异常，则返回的阶段将异常完成，并带有提供的操作的异常。或者，如果此阶段异常完成且提供的操作抛出异常，则返回的阶段将异常完成，并带有此阶段的异常。

      指定者：
      whenCompleteAsync 在接口 CompletionStage<T>中
      参数：
      action - 要执行的操作
      返回：
      新的CompletionStage

    • whenCompleteAsync

      public CompletableFuture<T> whenCompleteAsync(BiConsumer<? super T,? super Throwable> action, Executor executor)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，其结果或异常与此阶段相同，在此阶段完成时使用提供的Executor执行给定操作。

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

      与方法handleAsync不同，此方法不设计用于转换完成结果，因此提供的操作不应抛出异常。但是，如果抛出异常，则适用以下规则：如果此阶段正常完成但提供的操作抛出异常，则返回的阶段将异常完成，并带有提供的操作的异常。或者，如果此阶段异常完成且提供的操作抛出异常，则返回的阶段将异常完成，并带有此阶段的异常。

      指定者：
      whenCompleteAsync 在接口 CompletionStage<T>中
      参数：
      action - 要执行的操作
      executor - 用于异步执行的执行器
      返回：
      新的CompletionStage

    • handle

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

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

      指定者：
      handle 在接口 CompletionStage<T>中
      类型参数：
      U - 函数的返回类型
      参数：
      fn - 用于计算返回的CompletionStage值的函数
      返回：
      新的CompletionStage

    • handleAsync

      public <U> CompletableFuture<U> handleAsync(BiFunction<? super T,Throwable,? extends U> fn)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，当此阶段正常或异常完成时，将使用此阶段的结果和异常作为提供的函数的参数使用此阶段的默认异步执行设施执行。

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

      指定者：
      handleAsync 在接口 CompletionStage<T>中
      类型参数：
      U - 函数的返回类型
      参数：
      fn - 用于计算返回的CompletionStage值的函数
      返回：
      新的CompletionStage

    • handleAsync

      public <U> CompletableFuture<U> handleAsync(BiFunction<? super T,Throwable,? extends U> fn, Executor executor)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，当此阶段正常或异常完成时，将使用提供的执行器，将此阶段的结果和异常作为提供的函数的参数执行。

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

      指定者：
      handleAsync 在接口 CompletionStage<T>中
      类型参数：
      U - 函数的返回类型
      参数：
      fn - 用于计算返回的CompletionStage值的函数
      executor - 用于异步执行的执行器
      返回：
      新的CompletionStage

    • toCompletableFuture

      public CompletableFuture<T> toCompletableFuture()
      返回此CompletableFuture。
      指定者：
      toCompletableFuture 在接口 CompletionStage<T>中
      返回：
      此CompletableFuture

    • exceptionally

      public CompletableFuture<T> exceptionally(Function<Throwable,? extends T> fn)
      从接口复制的描述： CompletionStage
      返回一个新的CompletionStage，当此阶段异常完成时，将使用此阶段的异常作为提供的函数的参数执行。否则，如果此阶段正常完成，则返回的阶段也将以相同的值正常完成。
      指定者：
      exceptionally 在接口 CompletionStage<T>中
      参数：
      fn - 如果此CompletionStage异常完成，则用于计算返回的CompletionStage值的函数
      返回：
      新的CompletionStage

    • allOf

      public static CompletableFuture<Void> allOf(CompletableFuture<?>... cfs)
      返回一个新的CompletableFuture，当所有给定的CompletableFutures完成时，它也完成。如果任何给定的CompletableFutures异常完成，则返回的CompletableFuture也会异常完成，其中包含此异常作为其原因的CompletionException。否则，给定的CompletableFutures的结果（如果有）不会反映在返回的CompletableFuture中，但可以通过单独检查它们来获取。如果没有提供CompletableFutures，则返回一个完成值为null的CompletableFuture。

      此方法的应用之一是在继续程序之前等待一组独立CompletableFutures完成，如：CompletableFuture.allOf(c1, c2, c3).join();。

      参数:
      cfs - CompletableFutures
      返回:
      一个新的CompletableFuture，当所有给定的CompletableFutures完成时完成
      抛出:
      NullPointerException - 如果数组或其任何元素为null

    • anyOf

      public static CompletableFuture<Object> anyOf(CompletableFuture<?>... cfs)
      返回一个新的CompletableFuture，当给定的任何CompletableFutures完成时，它也完成，并具有相同的结果。否则，如果它异常完成，返回的CompletableFuture也会异常完成，其中包含此异常作为原因的CompletionException。如果没有提供CompletableFutures，则返回一个不完整的CompletableFuture。
      参数:
      cfs - CompletableFutures
      返回:
      一个新的CompletableFuture，当给定的任何CompletableFutures完成时，使用其结果或异常完成
      抛出:
      NullPointerException - 如果数组或其任何元素为null

    • cancel

      public boolean cancel(boolean mayInterruptIfRunning)
      如果尚未完成，则使用CancellationException完成此CompletableFuture。尚未完成的依赖CompletableFutures也将异常完成，其中包含由此引起的CompletionException。
      指定者:
      cancel 在接口 Future<T>
      参数:
      mayInterruptIfRunning - 此值在此实现中不起作用，因为中断不用于控制处理。
      返回:
      如果此任务现在已取消，则为true

    • isCancelled

      public boolean isCancelled()
      如果此CompletableFuture在正常完成之前被取消，则返回true。
      指定者:
      isCancelled 在接口 Future<T>
      返回:
      如果此CompletableFuture在正常完成之前被取消，则为true

    • isCompletedExceptionally

      public boolean isCompletedExceptionally()
      如果此CompletableFuture以任何方式异常完成，则返回true。可能的原因包括取消、显式调用completeExceptionally以及CompletionStage操作的突然终止。
      返回:
      如果此CompletableFuture以任何方式异常完成，则为true

    • obtrudeValue

      public void obtrudeValue(T value)
      强制设置或重置随后由方法get()及相关方法返回的值，无论是否已经完成。此方法仅设计用于错误恢复操作，即使在这种情况下，也可能导致使用已建立的结果与被覆盖结果进行持续依赖完成。
      参数:
      value - 完成值

    • obtrudeException

      public void obtrudeException(Throwable ex)
      强制导致随后对方法get()及相关方法的调用抛出给定异常，无论是否已经完成。此方法仅设计用于错误恢复操作，即使在这种情况下，也可能导致使用已建立的结果与被覆盖结果进行持续依赖完成。
      参数:
      ex - 异常
      抛出:
      NullPointerException - 如果异常为null

    • getNumberOfDependents

      public int getNumberOfDependents()
      返回等待此CompletableFuture完成的CompletableFutures估计数量。此方法设计用于监视系统状态，而不是用于同步控制。
      返回:
      依赖CompletableFutures的数量

    • toString

      public String toString()
      返回一个标识此CompletableFuture及其完成状态的字符串。状态在括号中包含字符串"Completed Normally"或字符串"Completed Exceptionally"，或字符串"Not completed"，后跟依赖于其完成的CompletableFutures数量（如果有）。
      覆盖:
      toString 在类 Object
      返回:
      标识此CompletableFuture及其状态的字符串

    • newIncompleteFuture

      public <U> CompletableFuture<U> newIncompleteFuture()
      返回一个新的未完成的CompletableFuture，其类型与CompletionStage方法返回的类型相同。子类通常应覆盖此方法，以返回与此CompletableFuture相同类的实例。默认实现返回CompletableFuture类的实例。
      类型参数:
      U - 值的类型
      返回:
      一个新的CompletableFuture
      自:
      9

    • defaultExecutor

      public Executor defaultExecutor()
      返回用于未指定Executor的异步方法的默认Executor。如果支持多个并行线程，则此类使用ForkJoinPool.commonPool()，否则使用每个异步任务一个线程的Executor。子类可以重写此方法，以返回提供至少一个独立线程的Executor。
      返回:
      Executor
      自:
      9

    • copy

      public CompletableFuture<T> copy()
      返回一个新的CompletableFuture，当此CompletableFuture正常完成时，它也正常完成并具有相同的值。如果此CompletableFuture异常完成，则返回的CompletableFuture将以此异常作为原因异常完成。行为等效于thenApply(x -> x)。此方法可能作为一种“防御性复制”形式有用，以防止客户端完成，同时仍能安排依赖操作。
      返回:
      新的CompletableFuture
      自:
      9

    • minimalCompletionStage

      public CompletionStage<T> minimalCompletionStage()
      返回一个新的CompletionStage，当此CompletableFuture正常完成时，它也正常完成，并且不能独立完成或以接口CompletionStage方法未定义的方式使用。如果此CompletableFuture异常完成，则返回的CompletionStage将以此异常作为原因异常完成。

      除非子类覆盖，否则可以通过toCompletableFuture()从最小CompletionStage获得具有所有可用方法的新的非最小CompletableFuture。例如，可以通过

       minimalStage.toCompletableFuture().join();
      等待最小阶段的完成
      返回:
      新的CompletionStage
      自:
      9

    • completeAsync

      public CompletableFuture<T> completeAsync(Supplier<? extends T> supplier, Executor executor)
      使用给定的执行器从异步任务中调用的Supplier函数的结果完成此CompletableFuture。
      参数:
      supplier - 返回用于完成此CompletableFuture的值的函数
      executor - 用于异步执行的执行器
      返回:
      此CompletableFuture
      自:
      9

    • completeAsync

      public CompletableFuture<T> completeAsync(Supplier<? extends T> supplier)
      使用默认执行器从异步任务中调用的Supplier函数的结果完成此CompletableFuture。
      参数:
      supplier - 返回用于完成此CompletableFuture的值的函数
      返回:
      此CompletableFuture
      自:
      9

    • orTimeout

      public CompletableFuture<T> orTimeout(long timeout, TimeUnit unit)
      如果在给定超时之前未完成，则异常完成此CompletableFuture，使用TimeoutException。
      参数:
      timeout - 在单位unit的时间内等待多久后使用TimeoutException异常完成
      unit - 确定如何解释timeout参数的TimeUnit
      返回:
      此CompletableFuture
      自:
      9

    • completeOnTimeout

      public CompletableFuture<T> completeOnTimeout(T value, long timeout, TimeUnit unit)
      如果在给定超时之前未完成，则使用给定值完成此CompletableFuture。
      参数:
      value - 超时后使用的值
      timeout - 在单位unit的时间内等待多久后使用给定值正常完成
      unit - 确定如何解释timeout参数的TimeUnit
      返回:
      此CompletableFuture
      自:
      9

    • delayedExecutor

      public static Executor delayedExecutor(long delay, TimeUnit unit, Executor executor)
      返回一个新的Executor，在给定延迟（如果非正数则没有延迟）后将任务提交给给定的基本执行器。每个延迟都从返回的执行器的execute方法的调用开始。
      参数:
      delay - 延迟时间，以unit为单位
      unit - 一个TimeUnit，确定如何解释delay参数
      executor - 基础执行器
      返回:
      新的延迟执行器
      自版本:
      9

    • delayedExecutor

      public static Executor delayedExecutor(long delay, TimeUnit unit)
      返回一个新的执行器，它在给定延迟后（如果非正数则没有延迟）将任务提交给默认执行器。每个延迟都从返回执行器的execute方法的调用开始。
      参数:
      delay - 延迟时间，以unit为单位
      unit - 一个TimeUnit，确定如何解释delay参数
      返回:
      新的延迟执行器
      自版本:
      9

    • completedStage

      public static <U> CompletionStage<U> completedStage(U value)
      返回一个已经使用给定值完成的新的CompletionStage，并且仅支持接口CompletionStage中的方法。
      类型参数:
      U - 值的类型
      参数:
      value - 值
      返回:
      已完成的CompletionStage
      自版本:
      9

    • failedFuture

      public static <U> CompletableFuture<U> failedFuture(Throwable ex)
      返回一个已经使用给定异常异常完成的新的CompletableFuture。
      类型参数:
      U - 值的类型
      参数:
      ex - 异常
      返回:
      异常完成的CompletableFuture
      自版本:
      9

    • failedStage

      public static <U> CompletionStage<U> failedStage(Throwable ex)
      返回一个已经使用给定异常异常完成的新的CompletionStage，并且仅支持接口CompletionStage中的方法。
      类型参数:
      U - 值的类型
      参数:
      ex - 异常
      返回:
      异常完成的CompletionStage
      自版本:
      9