モジュール java.net.http

パッケージ java.net.http

クラスHttpResponse.BodySubscribers

java.lang.Object

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

メソッドのサマリー

修飾子と型	メソッド	説明
static <T> HttpResponse.BodySubscriber<T>	buffering(HttpResponse.BodySubscriber<T> downstream, int bufferSize)	指定されたダウンストリーム・サブスクライバにデータを配信する前にデータをバッファするBodySubscriberを返します。
static HttpResponse.BodySubscriber<Void>	discarding()	レスポンス本文を破棄するレスポンス・サブスクライバを返します。
static HttpResponse.BodySubscriber<Void>	fromLineSubscriber(Flow.Subscriber<? super String> subscriber)	指定されたFlow.Subscriberの行ごとにすべてのレスポンス本文を転送する本体サブスクライバを返します。
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の行ごとにすべてのレスポンス本文を転送する本体サブスクライバを返します。
static HttpResponse.BodySubscriber<Void>	fromSubscriber(Flow.Subscriber<? super List<ByteBuffer>> subscriber)	指定されたFlow.Subscriberにすべてのレスポンス本文を転送する本文サブスクライバを返します。
static <S extends Flow.Subscriber<? super List<ByteBuffer>>,T> HttpResponse.BodySubscriber<T>	fromSubscriber(S subscriber, Function<? super S,? extends T> finisher)	指定されたFlow.Subscriberにすべてのレスポンス本文を転送する本文サブスクライバを返します。
static <T,U> HttpResponse.BodySubscriber<U>	mapping(HttpResponse.BodySubscriber<T> upstream, Function<? super T,? extends U> mapper)	指定されたupstream BodySubscriberの本体オブジェクトに指定された関数を適用した結果がレスポンス本文の値であるBodySubscriberを返します。
static HttpResponse.BodySubscriber<byte[]>	ofByteArray()	レスポンス本文をバイト配列として格納するBodySubscriberを返します。
static HttpResponse.BodySubscriber<Void>	ofByteArrayConsumer(Consumer<Optional<byte[]>> consumer)	Optional<byte[]>の指定されたコンシューマに受信ボディ・データを提供するBodySubscriberを返します。
static HttpResponse.BodySubscriber<Path>	ofFile(Path file)	指定された名前で開かれたファイルにレスポンス本文を格納するBodySubscriberを返します。
static HttpResponse.BodySubscriber<Path>	ofFile(Path file, OpenOption... openOptions)	指定されたオプションおよび名前で開かれたファイルにレスポンス本文を格納するBodySubscriberを返します。
static HttpResponse.BodySubscriber<InputStream>	ofInputStream()	レスポンス本文をInputStreamとしてストリーミングするBodySubscriberを返します。
static HttpResponse.BodySubscriber<Stream<String>>	ofLines(Charset charset)	レスポンス本文をStreamとしてストリーム化するBodySubscriberを返します。ストリーム内の各文字列はBufferedReader.lines()で定義される行に対応します。
static HttpResponse.BodySubscriber<Flow.Publisher<List<ByteBuffer>>>	ofPublisher()	Publisher<List<ByteBuffer>>を介してレスポンス本文をパブリッシュするレスポンス・サブスクライバを返します。
static HttpResponse.BodySubscriber<String>	ofString(Charset charset)	指定されたCharsetを使用して変換された Stringとしてレスポンス本文を格納する本文サブスクライバを返します。
static <U> HttpResponse.BodySubscriber<U>	replacing(U value)	レスポンス本文を破棄するレスポンス・サブスクライバを返します。

クラスjava.langで宣言されたメソッド。オブジェクト

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

メソッドの詳細

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を返します。 Consumer.accept()への各コールには空でないOptionalが含まれます。ただし、 Optionalが空になると、すべてのボディ・データが読み取られた後の最終呼出しを除きます。

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

APIに関するノート:

このサブスクライバはフロー制御されません。 したがって、指定されたコンシューマは、タイム・リに配信されるデータ量を処理できる必要があります。

パラメータ:

consumer - バイト配列のコンシューマ

戻り値:

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です

戻り値:

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 - マッピング関数

戻り値:

マッピング本文サブスクライバ