モジュール 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

  • メソッドの詳細

    • 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()
      レスポンス本文を破棄するレスポンス本文ハンドラを返します。
      戻り値:
      レスポンス本文ハンドラ

    • 置換

      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)
      ダウンロード・ディレクトリが指定されているBodySubscriber<Path>を返すBodyHandler<Path>を返しますが、ファイル名はContent-Dispositionレスポンス・ヘッダーから取得されます。 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()を参照してください。
      戻り値:
      レスポンス本文ハンドラ

    • バッファリング

      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の場合