モジュール jdk.incubator.httpclient
パッケージ jdk.incubator.http

インタフェースHttpResponse.MultiSubscriber<U,T>

  • 型パラメータ:
    U - 集計結果を表す型
    T - すべてのレスポンス体を表す型
    含まれているクラス:
    HttpResponse < T>
    public static interface HttpResponse.MultiSubscriber<U,T>
    HTTP/2マルチ・レスポンスの応答サブスクライバ。
    インキュベーション機能。将来のリリースで削除されます。

    マルチ・レスポンスは、メイン・レスポンスと、ゼロ以上の追加レスポンスを含んでいます。 各追加レスポンスは、サーバーが生成するリクエスト(PUSH_PROMISEs)にレスポンスしてサーバーによって送信されます。 追加のレスポンスは通常、クライアントが最初のリクエストに関連して必要とすることをサーバーが期待するリソースです。

    注 このインタフェースを実装する代わりに、アプリケーションはまず、MultiSubscriber.asMap()によって提供されるメカニズム(このインタフェースで構築)を使用することを検討する必要があります。これは、やや単純化された汎用インタフェースです。

    サーバーによって生成されたリクエストは、「プッシュ約束」とも呼ばれます。 サーバーは、主なレスポンスが完全に受信されるまで、これらのリクエストをいくつでも送信することができます。 したがって、主レスポンスの完了後に、追加の追加レスポンスの数が分かります。 追加のレスポンスは取消される可能性がありますが、サーバーがレスポンスを送信する前に確認レスポンスを待機しない場合は、不要なデータ送信を避けるためにこれをすばやく実行する必要があります。

    MultiSubscriberは、受け取ったレスポンスの意味のある集約を表すタイプUでパラメータ化されています。 これは、典型的には、レスポンスまたはレスポンス本文オブジェクトの集合です。

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

    • メソッドの詳細

      • onPushPromise

        Optional<HttpResponse.BodyHandler<T>> onPushPromise​(HttpRequest pushPromise)
        受け取ったプッシュ・プロミスごとに呼び出されます。 HttpRequestパラメータは、PUSH_PROMISEを表します。 実装は、レスポンス本文に対してOptionalのHttpResponse.BodyHandlerを返す必要があります。 異なるハンドラ(同じタイプの)は、同じマルチ送信内の異なるプッシュに対して返すことができます。 ハンドラ(空の Optional)が返されない場合、プッシュは取消されます。 必要であれば、completion(CompletableFuture, CompletableFuture)の onFinalPushPromiseパラメータに供給されたCompletableFuture<Void>を使用して、最終的なPUSH_PROMISEがいつ受信されるかを判別することができます。
        パラメータ:
        pushPromise - プッシュ約束
        戻り値:
        オプションの本文ハンドラ

      • onResponse

        void onResponse​(HttpResponse<T> response)
        受信したレスポンスごとに呼び出されます。 リクエストごとに、onResponse()またはonError()のいずれか1つが呼び出されることが保証されていますが、両方ではありません。

        ノート: onRequest()に提供されたCompletableFuturesを使用するのではなく、このコールバック・インタフェースに切り替える理由は、これらのCFとcompletion() (onComplete()が以前に呼び出されたとき)から返されたCFとの間に微妙な相互作用があるからです。 completion() CFは、onResponse()呼び出しによって行われたすべての作業が完了するまで完了しません。 ただし、提供されたCF (onRequest()へ)に依存するCFを作成すると、その実装では従属CFの可視性がなく、依存CFが完了した後にonComplete() (またはcompletion() CFを完了)を呼び出すことは保証できません。

        パラメータ:
        response - 受信したレスポンス

      • onError

        void onError​(HttpRequest request,
             Throwable t)
        レスポンスを受信中にエラーが発生した場合に呼び出されます。 リクエストごとに、onResponse()またはonError()のいずれか1つが呼び出されることが保証されていますが、両方ではありません。
        パラメータ:
        request - 主なリクエストまたは後続のプッシュ・プロ・ミス
        t - エラーの原因となったThrowable

      • completion

        CompletableFuture<U> completion​(CompletableFuture<Void> onComplete,
                                CompletableFuture<Void> onFinalPushPromise)
        集計結果オブジェクト自体が利用可能な場合に完了するCompletableFuture <U>を返します。 返されたCompletableFutureは、マルチ・レスポンスに関連するすべての個々の応答が完了した後、またはすべてのプッシュ・プロビジョニングが受信された後に、それ自身が完了する特定のCompletableFuture<Voidの1つに依存することが期待されます。 このメソッドは、onRequest(HttpRequest)の後、他のメソッドの前に呼び出されます。
        実装上の注意:
        実装は以下のパターンに従うかもしれません 
         
      CompletableFuture<U> completion(
              CompletableFuture<Void> onComplete,
              CompletableFuture<Void> onFinalPushPromise)
      {
          return onComplete.thenApply((v) -> {
              U u = ... instantiate and populate a U instance
              return u;
          });
      }
        パラメータ:
        onComplete - このマルチ・リクエストに関連するすべてのレスポンスが受信された後に完了するCompletableFuture。
        onFinalPushPromise - すべてのプッシュ・プロビジョニングを受信した後に完了するCompletableFuture。
        戻り値:
        集約CFレスポンス・オブジェクト

      • asMap

        static <V> HttpResponse.MultiSubscriber<MultiMapResult<V>,V> asMap​(Function<HttpRequest,Optional<HttpResponse.BodyHandler<V>>> reqHandler,
                                                                   boolean completion)
        マルチ・レスポンス用の汎用ハンドラを返します。 このハンドラによって生成された集計結果オブジェクトは、Map<HttpRequest,CompletableFuture<HttpResponse<V>>>です。 各リクエスト(元のユーザー生成リクエストと各サーバーがプッシュ・プロビジョニングを生成した)はマップのキーとして返されます。 各キーに対応する値は、CompletableFuture<HttpResponse<V>>です。

        completionパラメータの値に応じて、これらのハンドラを使用する方法は2つあります。 補完がtrueであれば、すべてのレスポンス自体が完了した後で集計結果が利用可能になります。 completionがfalseの場合、最後のプッシュ・プロビジョニングが受信された直後に集約結果が使用可能になります。 前者の場合、これはマップ値のすべてのCompletableFuturesが完了したことを意味します。 後者の場合、それらはまだ完了していないかもしれません。

        これらのハンドラを使用する最も簡単な方法は、完了をtrueに設定することです。その後、マップ内のすべての(results)値はブロックせずにアクセスできます。

        このインタフェースを使用するコード・サンプルについては、asMap(java.util.function.Function, boolean)を参照してください。

        このインタフェースを使用するためのコード・サンプルについては、asMap(Function, boolean)を参照してください。

        型パラメータ:
        V - すべてのレスポンスに使用される本文型
        パラメータ:
        reqHandler - ユーザー・リクエストと各プッシュ・プロビジョニングのために呼び出される関数
        completion - trueすべてのレスポンスが受信された後に集合CompletableFutureが完了した場合、またはすべてのプッシュ・プロビジョニングが受信された後にfalseが完了した場合
        戻り値:
        a MultiSubscriber

      • asMap

        static <V> HttpResponse.MultiSubscriber<MultiMapResult<V>,V> asMap​(Function<HttpRequest,Optional<HttpResponse.BodyHandler<V>>> reqHandler)
        マルチ・レスポンス用の汎用ハンドラを返します。 これは、asMap(Function, true)を呼び出す便利なメソッドであり、すべてのレスポンスを受け取った後に集計結果オブジェクトが完了することを意味します。

        使用例: 

         
          HttpRequest request = HttpRequest.newBuilder()
                  .uri(URI.create("https://www.foo.com/"))
                  .GET()
                  .build();

          HttpClient client = HttpClient.newHttpClient();

          Map<HttpRequest,CompletableFuture<HttpResponse<String>>> results = client
              .sendAsync(request, MultiSubscriber.asMap(
                  (req) -> Optional.of(HttpResponse.BodyHandler.asString())))
              .join();

        この例のラムダは、可能な限り単純な実装であり、着信リクエストを調べたり、レスポンス・ヘッダーを送信したり、サーバーが送信するすべてのプッシュを受け付けたりすることはありません。 join()呼び出しが戻ると、すべてのHttpResponseとそれに関連する本文オブジェクトが使用可能になります。

        型パラメータ:
        V - すべてのレスポンスに使用される本文型
        パラメータ:
        reqHandler - 各プッシュ・プロビジョニングとメイン・リクエストに対して呼び出される関数
        戻り値:
        a MultiSubscriber