モジュール java.net.http
パッケージ java.net.http

クラスHttpResponse.BodySubscribers

  • 含まれているインタフェース:
    HttpResponse<T>
    public static class HttpResponse.BodySubscribers
extends Object
    レスポンス本文バイトをStringに変換したり、バイトをファイルにストリーミングするなど、様々な有用なサブスクライバを実装するBodySubscriberの実装。

    次に、事前定義済の本文サブスクライバを使用して、レスポンス本文データのフローを一般的な高水準のJavaオブジェクトに変換する例を示します。 

       // Streams the response body to a File
   HttpResponse<byte[]> response = client
     .send(request, responseInfo -> BodySubscribers.ofByteArray());

   // Accumulates the response body and returns it as a byte[]
   HttpResponse<byte[]> response = client
     .send(request, responseInfo -> BodySubscribers.ofByteArray());

   // Discards the response body
   HttpResponse<Void> response = client
     .send(request, responseInfo -> BodySubscribers.discarding());

   // Accumulates the response body as a String then maps it to its bytes
   HttpResponse<byte[]> response = client
     .send(request, responseInfo ->
        BodySubscribers.mapping(BodySubscribers.ofString(UTF_8), String::getBytes));

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

    • メソッドの詳細

      • fromSubscriber

        public static HttpResponse.BodySubscriber<Void> fromSubscriber​(Flow.Subscriber<? super List<ByteBuffer>> subscriber)
        すべてのレスポンス本文を指定されたFlow.Subscriberに転送する本文サブスクライバを返します。 返された本文サブスクライバの「完了ステージ」は、指定されたサブスクライバonCompleteまたはonErrorのいずれかが呼び出されると完了します。
        APIに関するノート:
        このメソッドは、 BodySubscriberとFlow.Subscriberの間のアダプタとして使用できます。
        パラメータ:
        subscriber - サブスクライバ
        戻り値:
        本文サブスクライバ

      • fromSubscriber

        public static <S extends Flow.Subscriber<? super List<ByteBuffer>>,​T> HttpResponse.BodySubscriber<T> fromSubscriber​(S subscriber,
                                                                                                                          Function<? super S,​? extends T> finisher)
        すべてのレスポンス本文を指定されたFlow.Subscriberに転送する本文サブスクライバを返します。 返された本文サブスクライバの「完了ステージ」は、指定されたサブスクライバonCompleteまたはonErrorのいずれかが呼び出されると完了します。

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

        APIに関するノート:
        このメソッドは、 BodySubscriberとFlow.Subscriberの間のアダプタとして使用できます。
        型パラメータ:
        S - サブスクライバのタイプ
        T - レスポンス本文のタイプ
        パラメータ:
        subscriber - サブスクライバ
        finisher - サブスクライバが完了した後に適用される機能
        戻り値:
        本文サブスクライバ

      • fromLineSubscriber

        public static HttpResponse.BodySubscriber<Void> fromLineSubscriber​(Flow.Subscriber<? super String> subscriber)
        指定されたFlow.Subscriberの行ごとにすべてのレスポンス本文を転送する本体サブスクライバを返します。 返された本文サブスクライバの「完了ステージ」は、指定されたサブスクライバonCompleteまたはonErrorのいずれかが呼び出されると完了します。 UTF-8文字セットを使用してバイトがデコードされ、行がBufferedReader.readLine()と同じように区切られます。
        APIに関するノート:
        このメソッドは、 BodySubscriberとFlow.Subscriberの間のアダプタとして使用できます。
        実装上のノート:
        これは、呼出しに相当します。 
        
      fromLineSubscriber(subscriber, s -> null, StandardCharsets.UTF_8, null)
        パラメータ:
        subscriber - サブスクライバ
        戻り値:
        本文サブスクライバ

      • fromLineSubscriber

        public static <S extends Flow.Subscriber<? super String>,​T> HttpResponse.BodySubscriber<T> fromLineSubscriber​(S subscriber,
                                                                                                                    Function<? super S,​? extends T> finisher,
                                                                                                                    Charset charset,
                                                                                                                    String lineSeparator)
        指定されたFlow.Subscriberの行ごとにすべてのレスポンス本文を転送する本体サブスクライバを返します。 返された本文サブスクライバの「完了ステージ」は、指定されたサブスクライバonCompleteまたはonErrorのいずれかが呼び出されると完了します。

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

        APIに関するノート:
        このメソッドは、 BodySubscriberとFlow.Subscriberの間のアダプタとして使用できます。
        型パラメータ:
        S - サブスクライバのタイプ
        T - レスポンス本文のタイプ
        パラメータ:
        subscriber - サブスクライバ
        finisher - サブスクライバが完了した後に適用される機能
        charset - バイトをデコードするCharset
        lineSeparator - 行セパレータ(オプション): BufferedReader.readLine()のように線が区切られるnullにすることができます。
        戻り値:
        本文サブスクライバ
        例外:
        IllegalArgumentException - 指定されたlineSeparatorが空の文字列であるかどうか

      • ofString

        public static HttpResponse.BodySubscriber<String> ofString​(Charset charset)
        指定されたCharsetを使用して変換された Stringとしてレスポンス本文を格納する本文サブスクライバを返します。

        このサブスクライバを使用するHttpResponseは、レスポンス全体を読み取った後に使用できます。

        パラメータ:
        charset - 文字列を変換する文字セット
        戻り値:
        本文サブスクライバ

      • ofByteArray

        public static HttpResponse.BodySubscriber<byte[]> ofByteArray()
        レスポンス本文をバイト配列として格納するBodySubscriberを返します。

        このサブスクライバを使用するHttpResponseは、レスポンス全体を読み取った後に使用できます。

        戻り値:
        本文サブスクライバ

      • ofFile

        public static HttpResponse.BodySubscriber<Path> ofFile​(Path file,
                                                       OpenOption... openOptions)
        与えられたオプションと名前でオープンされたファイルにレスポンス本文を格納するBodySubscriberを返します。 ファイルは、本文が読み込まれる直前にFileChannel.openを使用して、指定されたオプションで開かれます。 スローされた例外は、必要に応じてHttpClient::sendまたはHttpClient::sendAsyncから返されるか、スローされます。

        このサブスクライバを使用するHttpResponseは、レスポンス全体を読み取った後に使用できます。

        BodySubscriberが作成されると、このファクトリ・メソッドでセキュリティ・マネージャの権限チェックが実行されます。 BodyHandlerが信頼できないコードと共有されないことに注意してください。

        パラメータ:
        file - 本文を格納するファイル
        openOptions - ファイルを開くためのオプションのリスト
        戻り値:
        本文サブスクライバ
        例外:
        IllegalArgumentException - 無効なオープン・オプション・セットが指定されている場合
        SecurityException - セキュリティ・マネージャがインストールされていて、ファイルへのwrite accessを拒否した場合

      • ofFile

        public static HttpResponse.BodySubscriber<Path> ofFile​(Path file)
        指定された名前でオープンされたファイルにレスポンス本文を格納するBodySubscriberを返します。

        同等: ofFile(file, CREATE, WRITE)

        BodySubscriberが作成されると、このファクトリ・メソッドでセキュリティ・マネージャの権限チェックが実行されます。 BodyHandlerが信頼できないコードと共有されないことに注意してください。

        パラメータ:
        file - 本文を格納するファイル
        戻り値:
        本文サブスクライバ
        例外:
        SecurityException - セキュリティ・マネージャがインストールされていて、ファイルへのwrite accessを拒否した場合

      • ofByteArrayConsumer

        public static HttpResponse.BodySubscriber<Void> ofByteArrayConsumer​(Consumer<Optional<byte[]>> consumer)
        提供されたOptional<byte[]>のコンシューマに着信する本文データを提供するBodySubscriberを返します。 Optionalが空の場合、Consumer.accept()の各呼び出しには、空のOptionalが含まれます。ただし、すべての本文データが読み込まれた後の最終呼び出しを除きます。

        このサブスクライバを使用するHttpResponseは、レスポンス全体を読み取った後に使用できます。

        APIに関するノート:
        このサブスクライバはフロー制御されません。 したがって、指定されたコンシューマは、タイム・リに配信されるデータ量を処理できる必要があります。
        パラメータ:
        consumer - バイト配列のコンシューマ
        戻り値:
        a BodySubscriber

      • ofInputStream

        public static HttpResponse.BodySubscriber<InputStream> ofInputStream()
        レスポンス本文をInputStreamとしてストリームするBodySubscriberを返します。

        このサブスクライバを使用するHttpResponseは、レスポンス・ヘッダーが読み込まれた直後に利用でき、本文全体が処理されるまで待つ必要はありません。 レスポンス本文は、InputStreamから直接読み取ることができます。

        APIに関するノート:
        対応するチェンジに関連付けられたすべてのリソースが適切に解放されるようにするには、呼び出し側はEOFに達するまですべてのバイトを読み取るか、InputStream.close()を呼び出すことができない場合は呼び出します。 ストリームを使い切る前にcloseを呼び出すと、基になるHTTP接続が閉じられ、後続の操作で再利用されなくなる可能性があります。
        戻り値:
        レスポンス本文をInputStreamとしてストリームする本文 サブスクライバ。

      • ofLines

        public static HttpResponse.BodySubscriber<Stream<String>> ofLines​(Charset charset)
        レスポンス本文をStreamとしてストリーム化するBodySubscriberを返します。ストリーム内の各文字列はBufferedReader.lines()で定義される行に対応します。

        このサブスクライバを使用するHttpResponseは、レスポンス・ヘッダーが読み込まれた直後に利用でき、本文全体が処理されるまで待つ必要はありません。 レスポンス本文は、Streamから直接読み取ることができます。

        APIに関するノート:
        対応する交換に関連付けられているすべてのリソースが正常に解放されるようにするには、コール元が、ストリームが使い果たされるまですべての行を読み取るか、またはそれを使用不可にするか、BaseStream.close()を呼び出します。 ストリームを使い切る前にcloseを呼び出すと、基になるHTTP接続が閉じられ、後続の操作で再利用されなくなる可能性があります。
        パラメータ:
        charset - バイトを文字に変換する場合に使用するキャラクタ・セット
        戻り値:
        レスポンス本文をStreamとしてストリーミングするbodyサブスクライバ。
        関連項目:
        BufferedReader.lines()

      • ofPublisher

        public static HttpResponse.BodySubscriber<Flow.Publisher<List<ByteBuffer>>> ofPublisher()
        Publisher<List<ByteBuffer>>を介してレスポンス本文をパブリッシュするレスポンス・サブスクライバを返します。

        このサブスクライバを使用するHttpResponseは、レスポンス・ヘッダーが読み込まれた直後に利用でき、本文全体が処理されるまで待つ必要はありません。 その後、HttpResponse bodyメソッドによって返されたパブリッシャにサブスクライブすることによって、レスポンス本文のバイトを取得できます。

        bodyメソッドによって返されたパブリッシャは、一度のみサブスクライブできます。 最初のサブスクライバは、正常にサブスクライブされた場合は本文レスポンス・バイトを受信し、それ以外の場合はサブスクリプションが取り消されます。 さらに多くのサブスクリプションが試行されると、後続のサブスクライバは空のサブスクリプションでただちにサブスクライブされ、onErrorメソッドはIllegalStateExceptionで呼び出されます。

        APIに関するノート:
        対応する交換に関連付けられたすべてのリソースが適切に解放されるようにするには、呼出し側が、指定されたパブリッシャが一度サブスクライブされ、onCompleteまたはonErrorが起動されるまですべてのバイトがサブスクライブされるようにするか、提供されたsubscriptionが起動できない場合はその操作を取り消す必要があります。 交換に使用される実際のHTTPプロトコルversionに応じて、フローを流用するかわりにサブスクリプションを取り消すと、基礎となるHTTP接続がクローズされ、後続の操作で再利用されるのを防ぐことができます。
        戻り値:
        Publisher<List<ByteBuffer>>を介してレスポンス本文をに公開するBodySubscriber。

      • replacing

        public static <U> HttpResponse.BodySubscriber<U> replacing​(U value)
        レスポンス本文を破棄するレスポンス・サブスクライバを返します。 指定された値は、HttpResponse.body()から返される値です。
        型パラメータ:
        U - レスポンス本文のタイプ
        パラメータ:
        value - HttpResponse.body()から返される値は、null
        戻り値:
        a BodySubscriber

      • discarding

        public static HttpResponse.BodySubscriber<Void> discarding()
        レスポンス本文を破棄するレスポンス・サブスクライバを返します。
        戻り値:
        レスポンス本文サブスクライバ

      • buffering

        public static <T> HttpResponse.BodySubscriber<T> buffering​(HttpResponse.BodySubscriber<T> downstream,
                                                           int bufferSize)
        特定のダウンストリーム・サブスクライバにデータを配信する前にデータをバッファリングするBodySubscriberを返します。 サブスクライバは、onCompleteが呼び出される直前に、最後の呼び出しを除いて、bufferSizeバイトのデータをダウンストリームonNextメソッドの各呼び出しに渡すことを保証します。 onNextの最後の呼び出しには、bufferSizeバイトより少ないバイト数が含まれている可能性があります。

        返されたサブスクライバは、getBody()メソッドをダウンストリーム・サブスクライバに委譲します。

        型パラメータ:
        T - レスポンス本文のタイプ
        パラメータ:
        downstream - ダウンストリーム・サブスクライバ
        bufferSize - バッファ・サイズ
        戻り値:
        バッファリング・ボディ・サブスクライバ
        例外:
        IllegalArgumentException - bufferSize <= 0の場合

      • mapping

        public static <T,​U> HttpResponse.BodySubscriber<U> mapping​(HttpResponse.BodySubscriber<T> upstream,
                                                                 Function<? super T,​? extends U> mapper)
        指定されたupstream BodySubscriberの本体オブジェクトに指定された関数を適用した結果がレスポンス本文の値であるBodySubscriberを返します。

        マッピング関数はクライアントexecutorを使用して実行されるため、次の例に示すように、InputStreamのブロックなどのレスポンス本文のタイプのマッピングに使用できます(次の例では、well-known JSONパーサーを使用してInputStreamを任意の注釈付きJava型に変換しています)。

        たとえば、 

          public static <W> BodySubscriber<W> asJSON(Class<W> targetType) {
     BodySubscriber<InputStream> upstream = BodySubscribers.ofInputStream();

     BodySubscriber<W> downstream = BodySubscribers.mapping(
           upstream,
           (InputStream is) -> {
               try (InputStream stream = is) {
                   ObjectMapper objectMapper = new ObjectMapper();
                   return objectMapper.readValue(stream, targetType);
               } catch (IOException e) {
                   throw new UncheckedIOException(e);
               }
           });
    return downstream;
 }

        型パラメータ:
        T - アップストリーム本文タイプ
        U - 戻された本文サブスクライバの型
        パラメータ:
        upstream - マップされる本文サブスクライバ
        mapper - マッピング関数
        戻り値:
        マッピング本文サブスクライバ