模块 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>，具有给定的 subscriber。

      响应主体无法通过此或 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)
      返回一个响应主体处理程序，该处理程序返回从 HttpResponse.BodySubscribers.fromSubscriber(Subscriber, Function) 获得的 BodySubscriber <T>，具有给定的 subscriber 和 finisher 函数。

      给定的 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>，具有给定的 subscriber。用于解码响应体字节的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 - 可选的行分隔符：可以是 null ，在这种情况下，行将以 BufferedReader.readLine() 的方式分隔。
      返回：
      响应主体处理程序
      抛出：
      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)
      返回一个 BodyHandler<String>，它返回一个从 BodySubscribers.ofString(Charset) 获得的 BodySubscriber <String>。使用给定的字符集对正文进行解码。
      参数：
      charset - 用于转换正文的字符集
      返回：
      响应主体处理程序

    • ofFile

      public static HttpResponse.BodyHandler <Path > ofFile(Path  file, OpenOption ... openOptions)
      返回一个 BodyHandler<Path>，它返回一个从 BodySubscribers.ofFile(Path,OpenOption...) 获得的 BodySubscriber <Path>。

      当返回 HttpResponse 对象时，主体已完全写入文件，HttpResponse.body() 返回对其 Path 的引用。

      对于默认文件系统提供程序，安全管理器权限检查是在创建 BodyHandler 时在此工厂方法中执行的。否则，权限检查 可能会在文件访问时针对调用者的上下文异步执行。必须注意不要与不受信任的代码共享 BodyHandler。

      参数：
      file - 存储正文的文件
      openOptions - 打开/创建文件时使用的任何选项
      返回：
      响应主体处理程序
      抛出：
      IllegalArgumentException - 如果指定了一组无效的打开选项
      SecurityException - 在默认文件系统提供程序的情况下，安装了安全管理器，调用 checkWrite 来检查对给定文件的写访问

    • ofFile

      public static HttpResponse.BodyHandler <Path > ofFile(Path  file)
      返回一个 BodyHandler<Path>，它返回一个 BodySubscriber <Path>。

      相当于：ofFile(file, CREATE, WRITE)

      对于默认文件系统提供程序，安全管理器权限检查是在创建 BodyHandler 时在此工厂方法中执行的。否则，权限检查 可能会在文件访问时针对调用者的上下文异步执行。必须注意不要与不受信任的代码共享 BodyHandler。

      参数：
      file - 存储正文的文件
      返回：
      响应主体处理程序
      抛出：
      SecurityException - 在默认文件系统提供程序的情况下，安装了安全管理器，调用 checkWrite 来检查对给定文件的写访问

    • ofFileDownload

      public static HttpResponse.BodyHandler <Path > ofFileDownload(Path  directory, OpenOption ... openOptions)
      返回一个 BodyHandler<Path>，返回一个 BodySubscriber <Path >，其中指定了下载目录，但文件名是从 Content-Disposition 响应标头中获取的。 Content-Disposition 标头必须指定attachment类型并且还必须包含文件名范围。如果文件名指定了多个路径组件，则只有最后一个组件用作文件名（具有给定的目录名称）。

      当 HttpResponse 对象返回时，正文已完全写入文件，HttpResponse.body() 返回文件的 Path 对象。返回的 Path 是提供的目录名和服务提供的文件名的组合。如果目标目录不存在或无法写入，则响应将失败并返回 IOException 。

      当创建 BodyHandler 时，安全管理器权限检查在此工厂方法中执行。必须注意不要与不受信任的代码共享 BodyHandler。

      参数：
      directory - 存储文件的目录
      openOptions - 打开文件时使用的打开选项
      返回：
      响应主体处理程序
      抛出：
      IllegalArgumentException - 如果给定路径不存在、不是默认文件系统、不是目录、不可写，或者指定了一组无效的打开选项
      SecurityException - 在默认文件系统提供程序和安全管理器已安装的情况下，它拒绝 读取权限 访问目录，或者拒绝 写权限 访问目录，或者拒绝 写权限 访问目录中的文件。

    • ofInputStream

      public static HttpResponse.BodyHandler <InputStream > ofInputStream()
      返回一个 BodyHandler<InputStream>，它返回一个从 BodySubscribers.ofInputStream 获得的 BodySubscriber <InputStream>。

      当 HttpResponse 对象返回时，响应头将被完全读取，但正文可能尚未完全接收。 HttpResponse.body() 方法返回一个 InputStream ，可以在接收到主体时从中读取主体。

      API 注意：
      有关详细信息，请参阅 HttpResponse.BodySubscribers.ofInputStream() 。
      返回：
      响应主体处理程序

    • ofLines

      public static HttpResponse.BodyHandler <Stream <String >> ofLines()
      返回一个 BodyHandler<Stream<String>>，它返回一个从 BodySubscribers.ofLines(charset) 获得的 BodySubscriber <Stream<String>>。用于解码响应体字节的charset 是从ofString() 指定的HTTP响应头中获取的，并且行以BufferedReader.readLine() 的方式分隔。

      当返回 HttpResponse 对象时，主体可能尚未完全接收。

      返回：
      响应主体处理程序

    • ofByteArrayConsumer

      public static HttpResponse.BodyHandler <Void > ofByteArrayConsumer(Consumer <Optional <byte[]>> consumer)
      返回一个 BodyHandler<Void>，它返回一个从 BodySubscribers.ofByteArrayConsumer(Consumer) 获得的 BodySubscriber <Void>。

      当返回HttpResponse对象时，主体已经完全写入消费者。

      API 注意：
      此处理程序返回的订户不受流量控制。因此，提供的消费者必须能够处理及时交付的任何数量的数据。
      参数：
      consumer - 消费者接受响应主体
      返回：
      响应主体处理程序

    • ofByteArray

      public static HttpResponse.BodyHandler <byte[]> ofByteArray()
      返回一个 BodyHandler<byte[]>，它返回一个从 BodySubscribers.ofByteArray() 获得的 BodySubscriber <byte[]>。

      当返回HttpResponse对象时，主体已经完全写入字节数组。

      返回：
      响应主体处理程序

    • ofString

      public static HttpResponse.BodyHandler <String > ofString()
      返回一个 BodyHandler<String>，它返回一个从 BodySubscribers.ofString(Charset) 获得的 BodySubscriber <String>。使用 Content-Type 响应标头中指定的字符集对正文进行解码。如果没有这样的标头，或者不支持字符集，则使用 UTF_8 。

      当 HttpResponse 对象返回时，正文已完全写入字符串。

      返回：
      响应主体处理程序

    • ofPublisher

      public static HttpResponse.BodyHandler <Flow.Publisher <List <ByteBuffer >>> ofPublisher()
      返回一个 BodyHandler<Publisher<List<ByteBuffer>>>，它创建一个从 BodySubscribers.ofPublisher() 获得的 BodySubscriber <Publisher<List<ByteBuffer>>>。

      当 HttpResponse 对象返回时，响应头将被完全读取，但正文可能尚未完全接收。 HttpResponse.body() 方法返回一个 Publisher <List<ByteBuffer>>，在接收到主体响应字节时可以从中获取它们。发布者可以而且必须只被订阅一次。

      API 注意：
      有关详细信息，请参阅 HttpResponse.BodySubscribers.ofPublisher() 。
      返回：
      响应主体处理程序

    • buffering

      public static <T> HttpResponse.BodyHandler <T> buffering(HttpResponse.BodyHandler <T> downstreamHandler, int bufferSize)
      返回一个 BodyHandler，它在被调用时返回一个 缓冲 BodySubscriber，它在将数据传递给下游订阅者之前缓冲数据。这些 BodySubscriber 实例是通过使用从给定下游处理程序和 bufferSize 参数获得的订阅者调用 BodySubscribers.buffering 创建的。
      类型参数：
      T - 响应主体类型
      参数：
      downstreamHandler - 下游处理程序
      bufferSize - 传递给 BodySubscribers.buffering 的缓冲区大小参数
      返回：
      身体处理程序
      抛出：
      IllegalArgumentException - 如果 bufferSize <= 0