モジュール 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の注:
        このメソッドは、 BodySubscriberFlow.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の注:
        このメソッドは、 BodySubscriberFlow.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>を返すレスポンス本文ハンドラを返します。 レスポンス本文バイトのデコードに使用されるcharsetofString()で指定された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>を返し、指定されたsubscriberfinisher関数および行セパレータを含むレスポンス本文ハンドラを返します。 レスポンス本文バイトのデコードに使用される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 - セキュリティ・マネージャがインストールされていて、ファイルにwrite accessが拒否されている場合。
      • ofFile

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

        同等: ofFile(file, CREATE, WRITE)

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

        パラメータ:
        file - 本文を格納するファイル
        戻り値:
        レスポンス本文ハンドラ
        例外:
        SecurityException - セキュリティ・マネージャがインストールされていて、ファイルにwrite accessが拒否されている場合。
      • 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オブジェクトが返されると、本文は文字列に完全に書き込まれます。

        戻り値:
        レスポンス本文ハンドラ
      • 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の場合