モジュール 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がスローされます。

    このクラスのサブクラスは、通常、"仮想コンストラクタ"メソッドnewIncompleteFuture()をオーバーライドする必要があります。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(); }
 }

    導入されたバージョン:
    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つのスレッドを使用するExecutorを使用します。 このメソッドは、サブクラスでオーバーライドされ、少なくとも1つの独立したスレッドを提供するExecutorを返すことがあります。
        戻り値:
        エグゼクティブ
        導入されたバージョン:
        9

      • copy

        public CompletableFuture<T> copy()
        正常に完了したときにこのCompletableFutureと同じ値で正常に完了する新しいCompletableFutureを返します。 このCompletableFutureが例外的に完了した場合、返されたCompletableFutureは、この例外をcauseとして持つCompletionExceptionを例外として完了します。 この動作はthenApply(x -> x)と同じです。 このメソッドは、クライアントが完了するのを防ぐために、依然として依存アクションを整理できるように、"防御的なコピー"のフォームとして役立ちます。
        戻り値:
        新しいCompletableFuture
        導入されたバージョン:
        9

      • minimalCompletionStage

        public CompletionStage<T> minimalCompletionStage()
        このCompletableFutureが正常に完了したときに、この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)
        指定されたExecutorを使用して非同期タスクから呼び出された、指定されたSupplier関数の結果でこのCompletableFutureを完了します。
        パラメータ:
        supplier - このCompletableFutureを完了するために使用される値を返す関数
        executor - 非同期実行に使用するエグゼキュータ
        戻り値:
        このCompletableFuture
        導入されたバージョン:
        9

      • completeAsync

        public CompletableFuture<T> completeAsync​(Supplier<? extends T> supplier)
        このCompletableFutureを、デフォルトExecutorを使用して非同期タスクから呼び出された、指定されたSupplier関数の結果で完了させます。
        パラメータ:
        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にタスクをサブ・ミットする新しいExecutorを返します。 各遅延は、返されたexecutor executeメソッドの呼び出し時に開始されます。
        パラメータ:
        delay - どのくらいの遅延、unitの単位で
        unit - delayパラメータの解釈方法を決定するTimeUnit
        executor - ベース・エグゼキュータ
        戻り値:
        新しい遅延エグゼキュータ
        導入されたバージョン:
        9

      • delayedExecutor

        public static Executor delayedExecutor​(long delay,
                                       TimeUnit unit)
        指定された遅延(非正の場合は遅延なし)の後にデフォルトのexecutorにタスクをサブ・ミットする新しいExecutorを返します。 各遅延は、返されたexecutor 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