CompletableFuture相关API

本文介绍相关API，使用上的介绍参见CompletableFuture 示例。
CompletableFuture是 jdk 8里面的新的API，类似于google guava的 ListenableFuture和SettableFuture，提供了对future结果的监听(在future到达某个状态时执行指定action)和自行设置future的状态（状态只能设置一次，但也有强制设值的接口）的能力，正常结束complete, 或者异常结束completeExceptionally。listener的能力由CompletionStage接口声明， settable能力由CompletableFuture定义。CompletableFuture实现了CompletionStage接口。

1. 对CompletableFuture的监听的API

  这类API基本都提供了同步、异步两类接口。同步接口是在指定future结束时，使用当时thread执行回调函数(action)；异步接口是在指定future接收时，使用额外的executor执行回调函数。异步接口又有两个，一个是使用默认executor(default asynchronous execution facility,据观察使用的是ForkJoinPool)执行异步，一个是使用指定executor执行异步。

• thenApply
• thenAccept
• thenRun
• handle（入参是Function）
• exceptionally（入参是Function）
• whenComplete（入参是Consumer）

/**
 * 当future正常返回、异常结束时动作， 入参是BiFunction
 */
public <U> CompletionStage<U> handle (BiFunction<? super T, Throwable, ? extends U> fn);
public <U> CompletionStage<U> handleAsync (BiFunction<? super T, Throwable, ? extends U> fn);
public <U> CompletionStage<U> handleAsync (BiFunction<? super T, Throwable, ? extends U> fn, Executor executor);

/**
 * 当future正常返回时才会动作， 入参是Function
 */
public <U> CompletionStage<U> thenApply(Function<? super T,? extends U> fn);
public <U> CompletionStage<U> thenApplyAsync (Function<? super T,? extends U> fn);
public <U> CompletionStage<U> thenApplyAsync (Function<? super T,? extends U> fn, Executor executor);

/**
 * 同thenApply， 不过入参是Consumer， 返回值也变成了CompletionStage<Void>
 */
public CompletionStage<Void> thenAccept(Consumer<? super T> action);
public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action);
public CompletionStage<Void> thenAcceptAsync(Consumer<? super T> action, Executor executor);

/**
 * 当future正常返回时，执行动作Runnable,不需要future的结果
 */
public CompletionStage<Void> thenRun(Runnable action);
public CompletionStage<Void> thenRunAsync(Runnable action);
public CompletionStage<Void> thenRunAsync(Runnable action, Executor executor);

/**
 * 当future正常返回、异常结束时，执行动作, 将future的结果、异常传入BiConsumer， 当future为正常返回时，exception是null,否则 result是null
 */
public CompletionStage<T> whenComplete (BiConsumer<? super T, ? super Throwable> action);
public CompletionStage<T> whenCompleteAsync (BiConsumer<? super T, ? super Throwable> action);
public CompletionStage<T> whenCompleteAsync (BiConsumer<? super T, ? super Throwable> action, Executor executor);

/**
 * 当future异常结束时，执行动作, 将future的异常传入Function
 */
public CompletionStage<T> exceptionally (Function<Throwable, ? extends T> fn);

2. 与其他CompletableFuture的协同的API

协同一词不知道描述是否恰当，这类API提供了当前CompletableFuture与两外一个CompletableFuture组合的能力，比如两个Future都正常返回的动作；两个future任意一个正常返回；

• thenCombine
• thenAcceptBoth
• runAfterBoth
• applyToEither
• acceptEither
• allOf
• anyOf

/**
 * 当this, other都正常返回时，执行动作
 */
public <U,V> CompletionStage<V> thenCombine (CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn);
public <U,V> CompletionStage<V> thenCombineAsync (CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn);
public <U,V> CompletionStage<V> thenCombineAsync (CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn, Executor executor);

/**
 * 同#thenCombine， 不过入参是BiConsumer
 */
public <U> CompletionStage<Void> thenAcceptBoth (CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action); public <U> CompletionStage<Void> thenAcceptBothAsync (CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action);
public <U> CompletionStage<Void> thenAcceptBothAsync (CompletionStage<? extends U> other, BiConsumer<? super T, ? super U> action, Executor executor);

/**
 * this, other都正常返回之后执行action, 类似于#thenRun
 */
public CompletionStage<Void> runAfterBoth(CompletionStage<?> other, Runnable action);
public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other, Runnable action);
public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other, Runnable action, Executor executor);

/**
 * this, other任意一个正常返回,执行Funcion, 不同于#thenCombine, other的类型是兼容this的，而thenCombine不需要兼容，而且thenCombine的action是BiFunction类型
 */
public <U> CompletionStage<U> applyToEither (CompletionStage<? extends T> other, Function<? super T, U> fn);
public <U> CompletionStage<U> applyToEitherAsync (CompletionStage<? extends T> other, Function<? super T, U> fn);
public <U> CompletionStage<U> applyToEitherAsync (CompletionStage<? extends T> other, Function<? super T, U> fn, Executor executor);

/**
 * 同#applyToEither， 不过入参是Consumer
 */
public CompletionStage<Void> acceptEither (CompletionStage<? extends T> other, Consumer<? super T> action);
public CompletionStage<Void> acceptEitherAsync (CompletionStage<? extends T> other, Consumer<? super T> action);
public CompletionStage<Void> acceptEitherAsync (CompletionStage<? extends T> other, Consumer<? super T> action, Executor executor);

public static CompletableFuture<Void> allOf(CompletableFuture<?>... cfs) ;
public static CompletableFuture<Object> anyOf(CompletableFuture<?>... cfs)；

3.CompletableFuture类似functional的API

• thenCompose 类似于Function.andThen，组合多个future成链式调用。当前future正常返回后， fn使用该结果正常继续处理，并返回CompletableFuture；与上面监听API不同的是，入参的fn返回类型是CompletableFuture/** * 当this正常返回之后， fn使用this future的结果继续处理，并返回一个新的CompletableFuture */ public <U> CompletionStage<U> thenCompose (Function<? super T, ? extends CompletionStage<U>> fn); public <U> CompletionStage<U> thenComposeAsync (Function<? super T, ? extends CompletionStage<U>> fn); public <U> CompletionStage<U> thenComposeAsync (Function<? super T, ? extends CompletionStage<U>> fn, Executor executor);

4. 设值相关API

对CompletableFuture设值，是由CompletableFuture生命并实现，并不是CompleteStage的接口。主要有两类正常结果设值，异常设值。还有一些静态辅助方法设值。

• complete
• completeExceptionally

/**
 * 设值正常结果，且this future之前未设值，get一类的方法返回指定的value。如果有监听动作，则相关监听动作触发
 */
public boolean complete(T value);

/**
 * 设值正常结果，且this future之前未设值，get一类的方法抛出异常。如果有监听动作，则相关监听动作触发
 */
public boolean completeExceptionally(Throwable ex);

/**
 * 静态方法，返回一个已经被设值的future
 */
public static <U> CompletableFuture<U> completedFuture(U value);