モジュール java.net.http

パッケージ java.net.http

クラスHttpResponse.BodyHandlers

java.lang.Object

java.net.http.HttpResponse.BodyHandlers

含まれているインタフェース:

HttpResponse<T>

public static class HttpResponse.BodyHandlers extends Object

レスポンス本文を文字列として処理したり、レスポンス本文をファイルにストリーミングするなど、様々な便利なハンドラを実装するBodyHandlerの実装。

これらの実装では、ステータス・コードは調査されません。つまり、本文は常に受け入れられます。 通常は、同等の名前がBodySubscriberを戻します。 また、必要に応じて、カスタム・ハンドラを使用してステータス・コードおよびヘッダーを確認し、同じタイプの別の本文サブスクライバを返すこともできます。

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

// Receives the response body as a String
HttpResponse<String> response = client
  .send(request, BodyHandlers.ofString());

// Receives the response body as a file
HttpResponse<Path> response = client
  .send(request, BodyHandlers.ofFile(Paths.get("example.html")));

// Receives the response body as an InputStream
HttpResponse<InputStream> response = client
  .send(request, BodyHandlers.ofInputStream());

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

導入されたバージョン:

11

メソッドのサマリー

修飾子と型	メソッド	説明
static <T> HttpResponse.BodyHandler<T>	buffering(HttpResponse.BodyHandler<T> downstreamHandler, int bufferSize)	BodyHandlerを返します。BodyHandlerは、呼び出されるとデータをバッファリングして下流のサブスクライバに配信する「BodySubscriberをバッファリング」を返します。
static HttpResponse.BodyHandler<Void>	discarding()	レスポンス本文を破棄するレスポンス本文ハンドラを返します。
static HttpResponse.BodyHandler<Void>	fromLineSubscriber(Flow.Subscriber<? super String> subscriber)	指定されたBodySubscribers.fromLineSubscriber(subscriber, s -> null, charset, null)から取得されたBodySubscriber<Void>を返すレスポンス本文ハンドラを返します。
static <S extends Flow.Subscriber<? super String>, T> HttpResponse.BodyHandler<T>	fromLineSubscriber(S subscriber, Function<? super S,? extends T> finisher, String lineSeparator)	BodySubscribers.fromLineSubscriber(subscriber, finisher, charset, lineSeparator)から取得したBodySubscriber<T>を返し、指定されたsubscriber、finisher関数および行セパレータを含むレスポンス本文ハンドラを返します。
static HttpResponse.BodyHandler<Void>	fromSubscriber(Flow.Subscriber<? super List<ByteBuffer>> subscriber)	指定されたHttpResponse.BodySubscribers.fromSubscriber(Subscriber)から取得されたBodySubscriber<Void>を返すレスポンス本文ハンドラを返します。
static <S extends Flow.Subscriber<? super List<ByteBuffer>>, T> HttpResponse.BodyHandler<T>	fromSubscriber(S subscriber, Function<? super S,? extends T> finisher)	指定されたsubscriberおよびfinisher関数を使用して、HttpResponse.BodySubscribers.fromSubscriber(Subscriber, Function)から取得されたBodySubscriber<T>を返すレスポンス本文ハンドラを返します。
static HttpResponse.BodyHandler<byte[]>	ofByteArray()	BodySubscribers.ofByteArray()から取得したBodySubscriber<byte[]>を返すBodyHandler<byte[]>を返します。
static HttpResponse.BodyHandler<Void>	ofByteArrayConsumer(Consumer<Optional<byte[]>> consumer)	BodySubscribers.ofByteArrayConsumer(Consumer)から取得されたBodySubscriber<Void>を返すBodyHandler<Void>を返します。
static HttpResponse.BodyHandler<Path>	ofFile(Path file)	BodySubscriber<Path>を返すBodyHandler<Path>を返します。
static HttpResponse.BodyHandler<Path>	ofFile(Path file, OpenOption... openOptions)	BodySubscribers.ofFile(Path,OpenOption...)から取得されたBodySubscriber<Path>を返すBodyHandler<Path>を返します。
static HttpResponse.BodyHandler<Path>	ofFileDownload(Path directory, OpenOption... openOptions)	ダウンロード・ディレクトリが指定されているが、ファイル名がContent-Dispositionレスポンス・ヘッダーから取得されるBodySubscriber < Path > を返すBodyHandler<Path>を返します。
static HttpResponse.BodyHandler<InputStream>	ofInputStream()	BodySubscribers.ofInputStreamから取得されたBodySubscriber<InputStream>を返すBodyHandler<InputStream>を返します。
static HttpResponse.BodyHandler<Stream<String>>	ofLines()	BodySubscribers.ofLines(charset)から取得されたBodySubscriber<Stream<String>>を返すBodyHandler<Stream<String>>を返します。
static HttpResponse.BodyHandler<Flow.Publisher<List<ByteBuffer>>>	ofPublisher()	BodySubscribers.ofPublisher()から取得したBodySubscriber<Publisher<List<ByteBuffer>>>を作成するBodyHandler<Publisher<List<ByteBuffer>>>を返します。
static HttpResponse.BodyHandler<String>	ofString()	BodySubscribers.ofString(Charset)から取得されたBodySubscriber<String>を返すBodyHandler<String>を返します。
static HttpResponse.BodyHandler<String>	ofString(Charset charset)	BodySubscribers.ofString(Charset)から取得されたBodySubscriber<String>を返すBodyHandler<String>を返します。
static <U> HttpResponse.BodyHandler<U>	replacing(U value)	レスポンス本文を破棄した後、指定された置換値を返すレスポンス本文ハンドラを返します。

クラスjava.lang.Objectで宣言されたメソッド

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

メソッドの詳細

fromSubscriber

public static HttpResponse.BodyHandler<Void> fromSubscriber(Flow.Subscriber<? super List<ByteBuffer>> subscriber)

指定されたHttpResponse.BodySubscribers.fromSubscriber(Subscriber)から取得されたBodySubscriber<Void>を返すレスポンス本文ハンドラを返します。

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

APIのノート:

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

たとえば、

TextSubscriber subscriber = new TextSubscriber();
HttpResponse<Void> response = client.sendAsync(request,
    BodyHandlers.fromSubscriber(subscriber)).join();
System.out.println(response.statusCode());

パラメータ:

subscriber - サブスクライバ

戻り値:

レスポンス本文ハンドラ

fromSubscriber

public static <S extends Flow.Subscriber<? super List<ByteBuffer>>, T> HttpResponse.BodyHandler<T> fromSubscriber(S subscriber, Function<? super S,? extends T> finisher)

指定されたsubscriberおよびfinisher関数を使用して、HttpResponse.BodySubscribers.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,
    BodyHandlers.fromSubscriber(subscriber, TextSubscriber::getTextResult)).join();
String text = response.body();

型パラメータ:

S - サブスクライバのタイプ

T - レスポンス本文のタイプ

パラメータ:

subscriber - サブスクライバ

finisher - サブスクライバが完了した後に適用される機能

戻り値:

レスポンス本文ハンドラ

fromLineSubscriber

public static HttpResponse.BodyHandler<Void> fromLineSubscriber(Flow.Subscriber<? super String> subscriber)

指定されたBodySubscribers.fromLineSubscriber(subscriber, s -> null, charset, null)から取得されたBodySubscriber<Void>を返すレスポンス本文ハンドラを返します。 レスポンス本文バイトのデコードに使用されるcharsetはofString()で指定されたHTTPレスポンス・ヘッダーから取得され、行はBufferedReader.readLine()のように区切られます。

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

APIのノート:

このメソッドは、行ごとにテキスト行を解析する BodySubscriberとテキスト・ベースのFlow.Subscriberとの間のアダプタとして使用できます。

たとえば、

// A PrintSubscriber that implements Flow.Subscriber<String>
// and print lines received by onNext() on System.out
PrintSubscriber subscriber = new PrintSubscriber(System.out);
client.sendAsync(request, BodyHandlers.fromLineSubscriber(subscriber))
    .thenApply(HttpResponse::statusCode)
    .thenAccept((status) -> {
        if (status != 200) {
            System.err.printf("ERROR: %d status received%n", status);
        }
    });

パラメータ:

subscriber - サブスクライバ

戻り値:

レスポンス本文ハンドラ

fromLineSubscriber

public static <S extends Flow.Subscriber<? super String>, T> HttpResponse.BodyHandler<T> fromLineSubscriber(S subscriber, Function<? super S,? extends T> finisher, String lineSeparator)

BodySubscribers.fromLineSubscriber(subscriber, finisher, charset, lineSeparator)から取得したBodySubscriber<T>を返し、指定されたsubscriber、finisher関数および行セパレータを含むレスポンス本文ハンドラを返します。 レスポンス本文バイトのデコードに使用されるcharsetは、ofString()で指定されているHTTPレスポンス・ヘッダーから取得されます。

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

APIのノート:

このメソッドは、行ごとにテキスト行を解析する BodySubscriberとテキスト・ベースのFlow.Subscriberとの間のアダプタとして使用できます。

たとえば、

// A LineParserSubscriber that implements Flow.Subscriber<String>
// and accumulates lines that match a particular pattern
Pattern pattern = ...;
LineParserSubscriber subscriber = new LineParserSubscriber(pattern);
HttpResponse<List<String>> response = client.send(request,
    BodyHandlers.fromLineSubscriber(subscriber, s -> s.getMatchingLines(), "\n"));
if (response.statusCode() != 200) {
    System.err.printf("ERROR: %d status received%n", response.statusCode());
}

型パラメータ:

S - サブスクライバのタイプ

T - レスポンス本文のタイプ

パラメータ:

subscriber - サブスクライバ

finisher - サブスクライバが完了した後に適用される機能

lineSeparator - 行セパレータ(オプション): BufferedReader.readLine()のように線が区切られるnullにすることができます。

戻り値:

レスポンス本文ハンドラ

例外:

IllegalArgumentException - 指定されたlineSeparatorが空の文字列であるかどうか

discarding

public static HttpResponse.BodyHandler<Void> discarding()

レスポンス本文を破棄するレスポンス本文ハンドラを返します。

戻り値:

レスポンス本文ハンドラ

replacing

public static <U> HttpResponse.BodyHandler<U> replacing(U value)

レスポンス本文を破棄した後、指定された置換値を返すレスポンス本文ハンドラを返します。

型パラメータ:

U - レスポンス本文型

パラメータ:

value - 本文として返すUの値は、null

戻り値:

レスポンス本文ハンドラ

ofString

public static HttpResponse.BodyHandler<String> ofString(Charset charset)

BodySubscribers.ofString(Charset)から取得されたBodySubscriber<String>を返すBodyHandler<String>を返します。 本文は、指定された文字セットを使用してデコードされます。

パラメータ:

charset - 本文を変換する文字セット

戻り値:

レスポンス本文ハンドラ

ofFile

public static HttpResponse.BodyHandler<Path> ofFile(Path file, OpenOption... openOptions)

BodySubscribers.ofFile(Path,OpenOption...)から取得されたBodySubscriber<Path>を返すBodyHandler<Path>を返します。

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

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

パラメータ:

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

openOptions - ファイルのオープン/作成時に使用するオプション

戻り値:

レスポンス本文ハンドラ

例外:

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

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

ofFile

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

BodySubscriber<Path>を返すBodyHandler<Path>を返します。

同等: ofFile(file, CREATE, WRITE)

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

パラメータ:

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

戻り値:

レスポンス本文ハンドラ

例外:

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

ofFileDownload

public static HttpResponse.BodyHandler<Path> ofFileDownload(Path directory, OpenOption... openOptions)

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

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

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

パラメータ:

directory - ファイルを格納するディレクトリ

openOptions - ファイルを開くときに使用するオープン・オプション

戻り値:

レスポンス本文ハンドラ

例外:

IllegalArgumentException - 指定されたパスが存在しない場合、デフォルトのファイル・システムではない場合、ディレクトリではない場合、書込み不可の場合、または無効なオープン・オプションのセットが指定されている場合

SecurityException - デフォルトのファイル・システム・プロバイダおよびセキュリティ・マネージャがインストールされており、ディレクトリへの「読取りアクセス」を拒否するか、ディレクトリへの「書込みアクセス」を拒否するか、ディレクトリ内のファイルへの「書込みアクセス」を拒否する場合。

ofInputStream

public static HttpResponse.BodyHandler<InputStream> ofInputStream()

BodySubscribers.ofInputStreamから取得されたBodySubscriber<InputStream>を返すBodyHandler<InputStream>を返します。

HttpResponseオブジェクトが返されると、レスポンス・ヘッダーは完全に読み取られますが、本文がまだ完全に受信されていない可能性があります。 HttpResponse.body()メソッドはInputStreamを返します。InputStreamから本文を受信したときに読み取ることができます。

APIのノート:

詳細については、HttpResponse.BodySubscribers.ofInputStream()を参照してください。

戻り値:

レスポンス本文ハンドラ

ofLines

public static HttpResponse.BodyHandler<Stream<String>> ofLines()

BodySubscribers.ofLines(charset)から取得されたBodySubscriber<Stream<String>>を返すBodyHandler<Stream<String>>を返します。 レスポンス本文バイトのデコードに使用されるcharsetはofString()で指定されたHTTPレスポンス・ヘッダーから取得され、行はBufferedReader.readLine()のように区切られます。

HttpResponseオブジェクトが返されると、本文が完全に受け取られなかった可能性があります。

戻り値:

レスポンス本文ハンドラ

ofByteArrayConsumer

public static HttpResponse.BodyHandler<Void> ofByteArrayConsumer(Consumer<Optional<byte[]>> consumer)

BodySubscribers.ofByteArrayConsumer(Consumer)から取得されたBodySubscriber<Void>を返すBodyHandler<Void>を返します。

HttpResponseオブジェクトが返されると、本文はコンシューマに完全に書き込まれます。

APIのノート:

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

パラメータ:

consumer - レスポンス本文を受け入れるコンシューマ

戻り値:

レスポンス本文ハンドラ

ofByteArray

public static HttpResponse.BodyHandler<byte[]> ofByteArray()

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

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

戻り値:

レスポンス本文ハンドラ

ofString

public static HttpResponse.BodyHandler<String> ofString()

BodySubscribers.ofString(Charset)から取得されたBodySubscriber<String>を返すBodyHandler<String>を返します。 本文は、Content-Typeレスポンス・ヘッダーに指定されている文字セットを使用してデコードされます。 そのようなヘッダーがない場合、または文字セットがサポートされていない場合は、UTF_8が使用されます。

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

戻り値:

レスポンス本文ハンドラ

ofPublisher

public static HttpResponse.BodyHandler<Flow.Publisher<List<ByteBuffer>>> ofPublisher()

BodySubscribers.ofPublisher()から取得したBodySubscriber<Publisher<List<ByteBuffer>>>を作成するBodyHandler<Publisher<List<ByteBuffer>>>を返します。

HttpResponseオブジェクトが返されると、レスポンス・ヘッダーは完全に読み取られますが、本文がまだ完全に受信されていない可能性があります。 HttpResponse.body()メソッドは、受信時に本文レスポンスのバイトを取得できるPublisher<List<ByteBuffer>>を返します。 パブリッシャは、1回のみサブスクライブできます。

APIのノート:

詳細については、HttpResponse.BodySubscribers.ofPublisher()を参照してください。

戻り値:

レスポンス本文ハンドラ

buffering

public static <T> HttpResponse.BodyHandler<T> buffering(HttpResponse.BodyHandler<T> downstreamHandler, int bufferSize)

BodyHandlerを返します。BodyHandlerは、呼び出されるとデータをバッファリングして下流のサブスクライバに配信する「BodySubscriberをバッファリング」を返します。 これらのBodySubscriberインスタンスは、指定されたダウンストリーム・ハンドラおよびbufferSizeパラメータから取得されたサブスクライバを使用してBodySubscribers.bufferingをコールすることによって作成されます。

型パラメータ:

T - レスポンス本文型

パラメータ:

downstreamHandler - 下流のハンドラ

bufferSize - BodySubscribers.bufferingに渡されるバッファ・サイズ・パラメータ

戻り値:

本文ハンドラ

例外:

IllegalArgumentException - bufferSize <= 0の場合