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

インタフェースCompletionStage<T>

型パラメータ:
T - ステージが生成または消費する値のタイプ
既知のすべての実装クラス:
CompletableFuture
public interface CompletionStage<T>
CompletionStageが完了したときにアクションの実行または値の計算を行う、非同期の可能性がある計算のステージです。 ステージはその計算が終了したときに完了しますが、これに続いて他の依存ステージがトリガーされる場合があります。 このインタフェースで定義される機能は、少数の基本形式しか取りませんが、それらがより大規模なメソッドのセットに展開することで、一定範囲の使用スタイルに対応します。
  • ステージによって実行される計算は、引数を必要とするか、結果を生成するか、あるいはその両方かに応じて、Function、ConsumerまたはRunnableとして(それぞれapply、acceptまたはrunを含む名前を持つメソッドを使用して)表されます。 たとえば、 
     
 stage.thenApply(x -> square(x))
      .thenAccept(x -> System.out.print(x))
      .thenRun(() -> System.out.println());
    追加の形式(compose)を使用すると、完了ステージを返す関数から計算パイプラインを構築できます。

    ステージの計算に対する引数は、トリガー・ステージの計算の結果です。

  • あるステージの実行は、1つのステージの完了、2つのステージの両方の完了または2つのステージのどちらかの完了によってトリガーされます。 1つのステージへの依存関係は、接頭辞thenを持つメソッドを使用して配置されます。 2つのステージの両方の完了によってトリガーされたステージでは、対応する名前を持つメソッドを使用して、それらの結果または効果を結合できます。 2つのステージのどちらかによってトリガーされたステージでは、どちらの結果または効果が依存ステージの計算に使用されるかに関して何も保証されません。
  • ステージ間の依存関係によって計算のトリガーは制御されますが、それ以外については特定の順序は保証されません。 また、新しいステージの計算の実行は、デフォルトの実行、デフォルトの非同期実行(ステージのデフォルトの非同期実行機能を使用する接尾辞asyncを持つメソッドを使用)、カスタム(指定されたExecutorを使用)の3つの方法のいずれかで配置されます。 デフォルトおよび非同期モードの実行プロパティは、このインタフェースではなく、CompletionStageの実装で指定されます。 明示的なExecutor引数を持つメソッドは、任意の実行プロパティを持っている場合や、同時実行をサポートしない場合もありますが、非同期性に対応する方法で処理が配置されます。
  • トリガー・ステージが正常に完了したか、例外的に完了したかに関係なく、(handleとwhenComplete)形式の2つのメソッドで無条件計算がサポートされます。 メソッドexceptionallyは、トリガー・ステージが例外的に完了し、java catchキーワードと同様に置換結果を計算する場合にのみ、計算をサポートします。 他のすべてのケースでは、ステージの計算が(非チェック)例外またはエラーで異常終了した場合、その完了を必要とするすべての依存ステージは、その例外を原因として保持するCompletionExceptionで、例外で完了します。 ステージが2つのステージの両方に依存しており、両方が例外で完了した場合、CompletionExceptionはそれらの例外のどちらか1つに対応できます。 ステージが2つのステージのどちらかに依存しており、どちらか1つのみが例外で完了した場合は、依存ステージが正常に完了するか例外で完了するかに関して何も保証されません。 メソッドwhenCompleteの場合、指定されたアクション自体で例外が発生すると、ソース・ステージも例外的に完了しないかぎり、ステージはこの例外で例外的に完了します。この場合、ソース・ステージからの例外的な完了は優先され、依存ステージに伝播されます。

すべてのメソッドは、前述のトリガー、実行および例外完了の仕様に準拠します(これについては、各メソッドの仕様では繰り返し言及しません)。 また、完了の結果を受け入れるメソッドに結果を渡すために使用する(つまり、型Tのパラメータ用の)引数をnullにすることはできますが、他のパラメータにnull値を渡すとNullPointerExceptionがスローされます。

メソッド形式handleは、継続ステージを作成し、トリガーするCompletionStageの結果と例外の(もしあれば)の両方を与え、任意の結果を計算する、無条件に計算を実行する最も一般的な方法です。 メソッドwhenCompleteは似ていますが、新しいメソッドを計算するのではなく、トリガー・ステージの結果を保持します。 ステージの通常の結果はnullになる可能性があるため、どちらのメソッドも計算構造化する必要があります: 

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

このインタフェースでは、初期の作成、強制的な正常または例外完了、完了のステータスまたは結果の調査、あるいはステージの完了の待機を行うメソッドは定義されません。 必要に応じて、CompletionStageを実装することで、このような効果を実現する手段を提供できます。 toCompletableFuture()メソッドは、共通の変換型を提供することにより、このインタフェースの異なる実装間の相互運用を可能にします。

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