モジュール java.base
パッケージ java.util.concurrent

クラスCompletableFuture<T>

  • 型パラメータ:
    T - この将来のjoinメソッドおよびgetメソッドによって返される結果型
    すべての実装されたインタフェース:
    CompletionStage<T>, Future<T>
    public class CompletableFuture<T>
extends Object
implements Future<T>, CompletionStage<T>
    明示的に(その値とステータスを設定して)完了できるFutureです。その完了時に発生する依存関数およびアクションをサポートし、CompletionStageとして使用できます。

    2つ以上のスレッドがCompletableFutureのcomplete、completeExceptionallyまたはcancelを試行すると、1つのスレッドのみが成功します。

    ステータスと結果を直接操作するこれらのメソッドおよび関連メソッドに加えて、CompletableFutureには次のポリシーを持つインタフェースCompletionStageが実装されています。

    • 非同期でないメソッドの依存する完了のために提供されるアクションは、現在のCompletableFutureを完了するスレッド、または完了メソッドの他の呼出し元で実行できます。
    • 明示的なExecutor引数を持たないすべての非同期メソッドは、ForkJoinPool.commonPool()を使用して実行されます(ただし、少なくとも2個の並列性レベルがサポートされない場合は、新しいスレッドが作成されてそれぞれのタスクを実行します)。 これは、メソッドdefaultExecutor()を定義することで、サブクラスの非静的メソッドでオーバーライドできます。 モニタリング、デバッグおよびトラッキングを簡素化するために、生成されたすべての非同期タスクは、マーカー・インタフェースCompletableFuture.AsynchronousCompletionTaskのインスタンスです。 時間遅延を伴う操作では、このクラスで定義されたアダプタ・メソッドを使用できます(例: supplyAsync(supplier, delayedExecutor(timeout, timeUnit)))。 遅延およびタイムアウトを伴うメソッドをサポートするために、このクラスはアクションの実行ではなく、アクションのトリガーおよび取消しのために最大1つのデーモン・スレッドを保持します。
    • CompletionStageのすべてのメソッドは、他のpublicメソッドとは独立して実装されているため、1つのメソッドの動作がサブクラス内の他のメソッドのオーバーライドによって影響されることはありません。
    • すべてのCompletionStageメソッドは、CompletableFuturesを返します。 使用方法を、インタフェースCompletionStageで定義されているメソッドのみに制限するには、メソッドminimalCompletionStage()を使用します。 または、クライアント自身が将来を変更しないようにするには、メソッド copy()を使用します。

    CompletableFutureには、次のポリシーを持つFutureも実装されています。

    • (FutureTaskとは異なり)このクラスは自身を完了させる計算を直接制御できないため、取消しは単に別形式の例外完了として処理されます。 cancelメソッドの効果はcompleteExceptionally(new CancellationException())と同じです。 isCompletedExceptionally()メソッドは、CompletableFutureが例外で完了したかどうかを判定するために使用できます。
    • CompletionExceptionによる例外完了の場合、get()およびget(long, TimeUnit)メソッドは対応するCompletionExceptionと同じ原因でExecutionExceptionをスローします。 ほとんどのコンテキストで簡単に使用できるように、このクラスにはこれらの場合にCompletionExceptionをかわりに直接スローするjoin()およびgetNow(T)メソッドも定義されています。

    それらを受け入れるメソッドの完了結果(つまり、T型のパラメータ)を渡すために使用される引数はnullですが、他のパラメータにnull値を渡すと、NullPointerExceptionがスローされます。

    通常、このクラスのサブクラスは、CompletionStageメソッドによって返される具象型を確立する仮想コンストラクタ・メソッドnewIncompleteFuture()をオーバーライドする必要があります。 たとえば、別のデフォルト・エグゼキュータを置換し、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(); }
 }

    導入されたバージョン:
    1.8

    • コンストラクタの詳細

      • CompletableFuture

        public CompletableFuture()
        新しい不完全なCompletableFutureを作成します。

    • メソッドの詳細

      • supplyAsync

        public static <U> CompletableFuture<U> supplyAsync​(Supplier<U> supplier)
        ForkJoinPool.commonPool()で実行されているタスクが指定されたサプライヤを呼び出して取得した値を使用して非同期的に完了する新しいCompletableFutureを返します。
        型パラメータ:
        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)
        ForkJoinPool.commonPool()で実行されているタスクが指定されたアクションの実行後に非同期に完了する新しいCompletableFutureを返します。
        パラメータ:
        runnable - 返されるCompletableFutureを完了する前に実行するアクション
        戻り値:
        新しいCompletableFuture

      • runAsync

        public static CompletableFuture<Void> runAsync​(Runnable runnable,
                                               Executor 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

      • 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

      • exceptionally

        public CompletableFuture<T> exceptionally​(Function<Throwable,​? extends T> fn)
        このCompletableFutureが完了したときに完了する新しいCompletableFutureを返します。例外で完了した場合は、このCompletableFutureの完了をトリガーした例外の指定された関数の結果を含みます。このCompletableFutureが正常に完了した場合は、返されるCompletableFutureも同じ値で正常に完了します。 ノート: この機能のより柔軟なバージョンは、whenCompleteおよびhandleメソッドを使用して利用できます。
        定義:
        exceptionally、インタフェースCompletionStage<T>
        パラメータ:
        fn - このCompletableFutureが例外で完了した場合に返されるCompletableFutureの値を計算するために使用される関数
        戻り値:
        新しいCompletableFuture

      • allOf

        public static CompletableFuture<Void> allOf​(CompletableFuture<?>... cfs)
        指定されたすべてのCompletableFutureが完了したときに完了する新しいCompletableFutureを返します。 指定されたいずれかのCompletableFutureが例外で完了した場合は、返されるCompletableFutureも例外で完了し、その原因としてこの例外がCompletionExceptionに保持されます。 それ以外の場合、指定されたCompletableFutureの結果(ある場合)は返されるCompletableFutureに反映されませんが、個別に調べることで取得できます。 CompletableFutureが1つも指定されなかった場合は、値nullで完了したCompletableFutureが返されます。

        このメソッドの用途の1つは、CompletableFuture.allOf(c1, c2, c3).join();のように、プログラムを続行する前に一連の独立したCompletableFutureの完了を待機することです。

        パラメータ:
        cfs - CompletableFuture
        戻り値:
        指定されたCompletableFutureがすべて完了したときに完了する新しいCompletableFuture
        例外:
        NullPointerException - 配列またはそのいずれかの要素がnullである場合

      • anyOf

        public static CompletableFuture<Object> anyOf​(CompletableFuture<?>... cfs)
        指定されたいずれかのCompletableFutureが完了したときに同じ結果で完了する新しいCompletableFutureを返します。 例外で完了した場合は、返されるCompletableFutureも例外で完了し、その原因としてこの例外がCompletionExceptionに保持されます。 CompletableFutureが1つも指定されなかった場合は、完了していないCompletableFutureが返されます。
        パラメータ:
        cfs - CompletableFuture
        戻り値:
        指定されたいずれかのCompletableFutureが完了したときにその結果または例外で完了する新しいCompletableFuture
        例外:
        NullPointerException - 配列またはそのいずれかの要素がnullである場合

      • cancel

        public boolean cancel​(boolean mayInterruptIfRunning)
        まだ完了していない場合は、このCompletableFutureをCancellationExceptionで完了します。 このCancellationExceptionによってCompletionExceptionが発生するため、まだ完了していない依存するCompletableFutureも例外で完了します。
        定義:
        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の完了を待機しているCompletableFutureの推定数を返します。 このメソッドは、同期の制御用としてではなく、システム状態の監視用として設計されています。
        戻り値:
        依存するCompletableFutureの数

      • toString

        public String toString()
        このCompletableFutureおよびその完了状態を識別する文字列を返します。 括弧で囲まれた状態には、文字列"Completed Normally"、文字列 "Completed Exceptionally"または文字列"Not completed"に続いてその完了に依存するCompletableFutureの数(ある場合)が含まれています。
        オーバーライド:
        toString、クラスObject
        戻り値:
        このCompletableFutureおよびその状態を識別する文字列

      • newIncompleteFuture

        public <U> CompletableFuture<U> newIncompleteFuture()
        CompletionStageメソッドによって返される型の新しい不完全なCompletableFutureを返します。 サブクラスは通常、このメソッドをオーバーライドして、このCompletableFutureと同じクラスのインスタンスを返す必要があります。 デフォルトの実装は、クラスCompletableFutureのインスタンスを返します。
        型パラメータ:
        U - 値の型
        戻り値:
        新しいCompletableFuture
        導入されたバージョン:
        9

      • defaultExecutor

        public Executor defaultExecutor()
        Executorを指定しない非同期メソッドに使用されるデフォルトのExecutorを返します。 このクラスは、複数のパラレル・スレッドをサポートしている場合はForkJoinPool.commonPool()を使用し、それ以外の場合は非同期タスクごとに1つのスレッドを使用するエグゼキュータを使用します。 このメソッドは、少なくとも1つの独立したスレッドを提供するエグゼキュータを返すように、サブクラスでオーバーライドできます。
        戻り値:
        実行者
        導入されたバージョン:
        9

      • copy

        public CompletableFuture<T> copy()
        正常に完了したときに、このCompletableFutureと同じ値で正常に完了する新しいCompletableFutureを返します。 このCompletableFutureが例外的に完了した場合、戻されたCompletableFutureは例外的にCompletionExceptionで完了し、この例外は原因です。 この動作は、thenApply(x -> x)と同等です。 この方法は、クライアントが依存アクションを手配できる間に完了するのを防ぐために、「防御コピー」の形式として役立つ場合があります。
        戻り値:
        新しいCompletableFuture
        導入されたバージョン:
        9

      • minimalCompletionStage

        public CompletionStage<T> minimalCompletionStage()
        正常に完了したときにこのCompletableFutureと同じ値で正常に完了し、インタフェースCompletionStageのメソッドによって定義されていない方法で独立して完了したり、その他の方法で使用できない新しいCompletionStageを返します。 このCompletableFutureが例外的に完了した場合、戻されたCompletionStageは例外的にCompletionExceptionで完了し、この例外は原因です。

        サブクラスによってオーバーライドされないかぎり、使用可能なすべてのメソッドを含む新しい非最小のCompletableFutureは、toCompletableFuture()を介して最小のCompletionStageから取得できます。 たとえば、最小ステージの完了を待機できます。 

         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)
        このCompletableFutureを、デフォルト・エグゼキュータを使用して非同期タスクから呼び出された特定のSupplier関数の結果で完了します。
        パラメータ:
        supplier - このCompletableFutureの完了に使用する値を戻す関数
        戻り値:
        このCompletableFuture
        導入されたバージョン:
        9

      • orTimeout

        public CompletableFuture<T> orTimeout​(long timeout,
                                      TimeUnit unit)
        このCompletableFutureをTimeoutExceptionで例外的に完了します。それ以外の場合は、指定されたタイムアウトより前に完了します。
        パラメータ:
        timeout - TimeoutExceptionで例外的に完了するまでの待機時間(単位はunit)
        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)
        指定された遅延の後に指定されたベース・エグゼキュータにタスクを送信する新しいエグゼキュータを返します(正でない場合は遅延なし)。 各遅延は、返されるエグゼキュータのexecuteメソッドの呼出し時に開始されます。
        パラメータ:
        delay - 遅延時間(単位: unit)
        unit - delayパラメータの解釈方法を決定するTimeUnit
        executor - ベース・エグゼキュータ
        戻り値:
        新しい遅延エグゼキュータ
        導入されたバージョン:
        9

      • delayedExecutor

        public static Executor delayedExecutor​(long delay,
                                       TimeUnit unit)
        指定された遅延の後にタスクをデフォルト・エグゼキュータに送信する新しいエグゼキュータを返します(正でない場合は遅延なし)。 各遅延は、返されるエグゼキュータのexecuteメソッドの呼出し時に開始されます。
        パラメータ:
        delay - 遅延時間(単位: unit)
        unit - delayパラメータの解釈方法を決定するTimeUnit
        戻り値:
        新しい遅延エグゼキュータ
        導入されたバージョン:
        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