モジュール java.net.http
パッケージ 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()
        レスポンス本文を破棄するレスポンス本文ハンドラを返します。
        戻り値:
        レスポンス本文ハンドラ

      • replacing

        public static <U> HttpResponse.BodyHandler<U> replacing​(U value)
        レスポンス本文を破棄した後、指定された置換値を返すレスポンス本文ハンドラを返します。
        型パラメータ:
        U - レスポンス本文型
        パラメータ:
        value - 本文として返すUの値は、null
        戻り値:
        レスポンス本文ハンドラ

      • 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 - セキュリティ・マネージャがインストールされていて、ファイルに「書込みアクセス」が拒否されている場合。

      • ofFile

        public static HttpResponse.BodyHandler<Path> ofFile​(Path file)
        BodySubscriber<Path>を返すBodyHandler<Path>を返します。

        同等: ofFile(file, CREATE, WRITE)

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

        パラメータ:
        file - 本文を格納するファイル
        戻り値:
        レスポンス本文ハンドラ
        例外:
        SecurityException - セキュリティ・マネージャがインストールされていて、ファイルに「書込みアクセス」が拒否されている場合。

      • 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 - セキュリティ・マネージャがインストールされており、「読取りアクセス」をディレクトリに拒否するか、「書込みアクセス」をディレクトリに拒否するか、「書込みアクセス」をディレクトリ内のファイルに拒否します。

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