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

インタフェースHttpResponse.BodyHandler<T>

  • 型パラメータ:
    T - レスポンス本文型
    含まれているクラス:
    HttpResponse < T>
    関数型インタフェース:
    これは関数型インタフェースなので、ラムダ式またはメソッド参照の代入先として使用できます。
    @FunctionalInterface
public static interface HttpResponse.BodyHandler<T>
    レスポンス本文のハンドラ。
    インキュベーション機能。将来のリリースで削除されます。

    これは、2つのパラメータ: レスポンス・ステータス・コード、およびレスポンス・ヘッダーを返し、HttpResponse.BodySubscriberを返します。 この関数は、レスポンス本文が読み込まれる直前に常に呼び出されます。 その実装は、ステータス・コードまたはヘッダーを調べ、レスポンス本文を受け入れるか廃棄するか、それを受け入れるかどうかを決める必要があります。

    ステータス・コードまたはヘッダー(体は常に受け入れられている)を使用しない事前定義された実装がいくつか定義されています:

    これらの実装は同等のHttpResponse.BodySubscriberを返します。 あるいは、ハンドラを使用して、ステータス・コードまたはヘッダーを検査し、適切な場合に異なる本文サブスクライバを返すことができます。

    ハンドラの使用例

    最初の例では、レスポンス・ヘッダーとステータスを無視し、常に同じ方法でレスポンス本文を処理する事前定義されたハンドラ関数の1つを使用しています。 

     
      HttpResponse<Path> resp = HttpRequest
              .create(URI.create("http://www.foo.com"))
              .GET()
              .response(BodyHandler.asFile(Paths.get("/tmp/f")));
    これらの事前定義されたハンドラがステータス・コードとヘッダーを無視しても、HttpResponseから返されるときには、この情報に引き続きアクセスできます。

    2番目の例では、この関数はステータス・コードに応じて異なるサブスクライバを返します。 

     
      HttpResponse<Path> resp1 = HttpRequest
              .create(URI.create("http://www.foo.com"))
              .GET()
              .response(
                  (status, headers) -> status == 200
                      ? BodySubscriber.asFile(Paths.get("/tmp/f"))
                      : BodySubscriber.discard(Paths.get("/NULL")));

    • メソッドの詳細

      • apply

        HttpResponse.BodySubscriber<T> apply​(int statusCode,
                                     HttpHeaders responseHeaders)
        与えられたレスポンス・ステータス・コードとヘッダーを考慮してBodySubscriberを返します。 このメソッドは、本文が読み込まれる前に常に呼び出され、その実装は本文を保持してどこかに格納するか、discardから返された BodySubscriberを返すことで破棄します。
        パラメータ:
        statusCode - 受信したHTTPステータス・コード
        responseHeaders - 受信したレスポンス・ヘッダー
        戻り値:
        本文サブスクライバ

      • fromSubscriber

        static HttpResponse.BodyHandler<Void> fromSubscriber​(Flow.Subscriber<? super List<ByteBuffer>> subscriber)
        HttpResponse.BodySubscriber.fromSubscriber(Subscriber)から取得したBodySubscriber <Void>を、指定されたsubscriberを返して返すレスポンス本文ハンドラを返します。

        レスポンス本文はこれ、または HttpResponse APIでは利用できませんが、代わりにすべてのレスポンス本文が特定のsubscriberに転送されます。

        APIの注:
        このメソッドは、 BodySubscriberとFlow.Subscriberの間のアダプタとして使用できます。

        次に例を示します。 

         
  TextSubscriber subscriber = new TextSubscriber();
  HttpResponse<Void> response = client.sendAsync(request,
      BodyHandler.fromSubscriber(subscriber)).join();
  System.out.println(response.statusCode());
        パラメータ:
        subscriber - サブスクライバ
        戻り値:
        レスポンス本文ハンドラ

      • fromSubscriber

        static <S extends Flow.Subscriber<? super List<ByteBuffer>>,T> HttpResponse.BodyHandler<T> fromSubscriber​(S subscriber,
                                                                                                          Function<S,T> finisher)
        指定されたsubscriberおよびfinisher関数を使用して、HttpResponse.BodySubscriber.fromSubscriber(Subscriber, Function)から取得したBodySubscriber <T>を返すレスポンス本文ハンドラを返します。

        指定されたfinisher関数は、指定されたサブスクライバonCompleteが呼び出された後に適用されます。 finisher関数は、指定されたサブスクライバとともに起動され、レスポンス本文として設定された値を返します。

        APIの注:
        このメソッドは、 BodySubscriberとFlow.Subscriberの間のアダプタとして使用できます。

        次に例を示します。 

         
 TextSubscriber subscriber = ...;  // accumulates bytes and transforms them into a String
 HttpResponse<String> response = client.sendAsync(request,
     BodyHandler.fromSubscriber(subscriber, TextSubscriber::getTextResult)).join();
 String text = response.body();
        型パラメータ:
        S - サブスクライバのタイプ
        T - レスポンス本文のタイプ
        パラメータ:
        subscriber - サブスクライバ
        finisher - サブスクライバが完了した後に適用される機能
        戻り値:
        レスポンス本文ハンドラ

      • discard

        static <U> HttpResponse.BodyHandler<U> discard​(U value)
        レスポンス本文を破棄し、指定された値をその代わりに使用するレスポンス本文ハンドラを返します。
        型パラメータ:
        U - レスポンス本文型
        パラメータ:
        value - 本文として返すUの値は、null
        戻り値:
        レスポンス本文ハンドラ

      • asFile

        static HttpResponse.BodyHandler<Path> asFile​(Path file,
                                             OpenOption... openOptions)
        BodySubscriber.asFile(Path,OpenOption...)から取得したBodySubscriber <Path>を返すBodyHandler<Path>を返します。

        HttpResponseオブジェクトが返されると、本文はファイルに完全に書き込まれ、HttpResponse.body()はそのPathへの参照を返します。

        パラメータ:
        file - 本文を格納するファイル名
        openOptions - ファイルのオープン/作成時に使用するオプション
        戻り値:
        レスポンス本文ハンドラ
        例外:
        SecurityException - セキュリティ・マネージャがインストールされていて、ファイルにwrite accessが拒否されている場合。 DELETE_ON_CLOSEオプションでファイルが開かれた場合は、checkDeleteメソッドが呼び出されて削除アクセスがチェックされます。

      • asFileDownload

        static HttpResponse.BodyHandler<Path> asFileDownload​(Path directory,
                                                     OpenOption... openOptions)
        ダウンロード・ディレクトリが指定されているBodySubscriber<Path>を返すBodyHandler<Path>を返しますが、ファイル名はContent-Dispositionレスポンス・ヘッダーから取得されます。 Content-Dispositionヘッダーにはattachment型を指定する必要があり、filenameパラメータも含める必要があります。 ファイル名に複数のパス・コンポーネントが指定されている場合、最終コンポーネントのみがファイル名(与えられたディレクトリ名で)として使用されます。

        HttpResponseオブジェクトが返されると、本文はファイルに完全に書き込まれ、HttpResponse.body()はファイルのPathオブジェクトを返します。 返されるPathは、提供されたディレクトリ名とサーバーによって提供されるファイル名の組み合わせです。 宛先ディレクトリが存在しないか、または書き込めない場合は、IOExceptionを実行するとレスポンスは失敗します。

        パラメータ:
        directory - ファイルを格納するディレクトリ
        openOptions - オープン・オプション
        戻り値:
        レスポンス本文ハンドラ
        例外:
        SecurityException - セキュリティ・マネージャがインストールされていて、ファイルにwrite accessが拒否されている場合。 DELETE_ON_CLOSEオプションでファイルが開かれた場合は、checkDeleteメソッドが呼び出されて削除アクセスがチェックされます。

      • asByteArray

        static HttpResponse.BodyHandler<byte[]> asByteArray()
        BodySubscriber.asByteArray()から取得したBodySubscriber < byte[] >を返すBodyHandler<byte[]>を返します。

        HttpResponseオブジェクトが返されると、本文はバイト配列に完全に書き込まれます。

        戻り値:
        レスポンス本文ハンドラ

      • asString

        static HttpResponse.BodyHandler<String> asString()
        BodySubscriber.asString(Charset)から取得したBodySubscriber <String>を返すBodyHandler<String>を返します。 本文はContent-encodingレスポンス・ヘッダーで指定された文字セットを使用して復号化されます。 そのようなヘッダーがない場合、または文字セットがサポートされていない場合は、UTF_8が使用されます。

        HttpResponseオブジェクトが返されると、本文は文字列に完全に書き込まれます。

        戻り値:
        レスポンス本文ハンドラ

      • buffering

        static <T> HttpResponse.BodyHandler<T> buffering​(HttpResponse.BodyHandler<T> downstreamHandler,
                                                 int bufferSize)
        BodyHandlerを返します。BodyHandlerは、呼び出されるとデータをバッファリングして下流のサブスクライバに配信する「BodySubscriberをバッファリング」を返します。 これらのBodySubscriberインスタンスは、指定されたダウンストリーム・ハンドラから取得したサブスクライバとbufferSizeパラメータを使用してBodySubscriber.bufferingを呼び出すことによって作成されます。
        パラメータ:
        downstreamHandler - 下流のハンドラ
        bufferSize - BodySubscriber.bufferingに渡されるバッファ・サイズ・パラメータ
        戻り値:
        本文ハンドラ
        例外:
        IllegalArgumentException - bufferSize <= 0の場合