モジュール 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<Path> response = client
  .send(request, responseInfo -> BodySubscribers.ofFile(Paths.get("example.html"));

// 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<String>としてストリームするBodySubscriberを返します。このStream<String>は、ストリーム内の各文字列が、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.Objectで宣言されたメソッド

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の作成時にこのファクトリ・メソッドで実行されます。 そうしないと、ファイル・アクセス時にコール元コンテキストに対して「権限チェック」が非同期に実行される可能性があります。 BodySubscriberが信頼できないコードと共有されないことに注意してください。

パラメータ:

file - 本文を格納するファイル

openOptions - ファイルを開くためのオプションのリスト

戻り値:

本文サブスクライバ

例外:

IllegalArgumentException - 無効なオープン・オプション・セットが指定されている場合

SecurityException - デフォルトのファイル・システム・プロバイダで、セキュリティ・マネージャがインストールされている場合は、指定されたファイルへの書込みアクセスをチェックするためにcheckWriteが起動されます。

ofFile

public static HttpResponse.BodySubscriber<Path> ofFile(Path file)

指定された名前でオープンされたファイルにレスポンス本文を格納するBodySubscriberを返します。

同等: ofFile(file, CREATE, WRITE)

デフォルトのファイル・システム・プロバイダの場合、セキュリティ・マネージャのパーミッション・チェックは、BodySubscriberの作成時にこのファクトリ・メソッドで実行されます。 そうしないと、ファイル・アクセス時にコール元コンテキストに対して「権限チェック」が非同期に実行される可能性があります。 BodySubscriberが信頼できないコードと共有されないことに注意してください。

パラメータ:

file - 本文を格納するファイル

戻り値:

本文サブスクライバ

例外:

SecurityException - デフォルトのファイル・システム・プロバイダで、セキュリティ・マネージャがインストールされている場合は、指定されたファイルへの書込みアクセスをチェックするためにcheckWriteが起動されます。

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のreadメソッドは、読取りのブロック中にスレッドが中断された場合、「スレッド割り込みステータスが設定されました」とともにIOExceptionをスローします。 その場合、リクエストも取り消され、InputStreamがクローズされます。

戻り値:

レスポンス本文をInputStreamとしてストリームするボディ・サブスクライバ。

ofLines

public static HttpResponse.BodySubscriber<Stream<String>> ofLines(Charset charset)

レスポンス本文をStream<String>としてストリームするBodySubscriberを返します。このStream<String>は、ストリーム内の各文字列が、BufferedReader.lines()で定義された行に対応します。

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

APIのノート:

対応する交換に関連付けられているすべてのリソースが正常に解放されるようにするには、コール元が、ストリームが使い果たされるまですべての行を読み取るか、またはそれを使用不可にするか、BaseStream.close()を呼び出します。 ストリームを使い切る前にcloseを呼び出すと、基になるHTTP接続が閉じられ、後続の操作で再利用されなくなる可能性があります。

パラメータ:

charset - バイトを文字に変換する場合に使用する文字セット

戻り値:

レスポンス本文をStream<String>としてストリームする本文サブスクライバ。

関連項目:

• 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のブロックなどのレスポンス本文のタイプをマップするために使用できます。 ただし、マッパー関数でブロック操作を実行すると、(少なくともブロッキング操作が終了するまで)の実行時間が不明な時間帯にはエグゼキュータ・スレッドをブロックするリスクがあり、使用可能なスレッドの実行時間が長くなる可能性があります。 したがって、目的の型へのマッピングが(例:InputStreamを読み込む場合)をブロックする場合、次の例に示すように、目的の型のSupplierにマッピングして、コール元のスレッドによってSupplier::getが起動されるまでブロック操作を遅延します。この場合、次の例では、一般的なJSONパーサーを使用して、InputStreamを注釈付きのいずれかのJava型に変換します。

たとえば、

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

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

戻り値:

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