模块  java.net.http
软件包  java.net.http

Class HttpResponse.BodySubscribers

  • Enclosing interface:
    HttpResponse < T > 
    public static class HttpResponse.BodySubscribersextends Object
    实现各种有用订户的BodySubscriber的实现，例如将响应主体字节转换为字符串，或将字节流式传输到文件。

    以下是使用预定义的主体订阅者将响应主体数据流转换为常见的高级Java对象的示例： 

       // Streams the response body to a File HttpResponse<byte[]> response = client .send(request, responseInfo -> BodySubscribers.ofByteArray()); // Accumulates the response body and returns it as a byte[] HttpResponse<byte[]> response = client .send(request, responseInfo -> BodySubscribers.ofByteArray()); // Discards the response body HttpResponse<Void> response = client .send(request, responseInfo -> BodySubscribers.discarding()); // Accumulates the response body as a String then maps it to its bytes HttpResponse<byte[]> response = client .send(request, responseInfo -> BodySubscribers.mapping(BodySubscribers.ofString(UTF_8), String::getBytes));
    从以下版本开始：
    11

    • 方法详细信息

      • fromSubscriber

        public static HttpResponse.BodySubscriber<Void> fromSubscriber​(Flow.Subscriber<? super List<ByteBuffer>> subscriber)
        返回一个主体订阅者，它将所有响应主体转发给给定的Flow.Subscriber 。 在调用给定订户之一onComplete或onError之后，返回的主体订户的completion stage完成。
        API Note:
        此方法可用作 BodySubscriber和 Flow.Subscriber之间的适配器。
        参数
        subscriber - 订户
        结果
        身体用户

      • fromSubscriber

        public static <S extends Flow.Subscriber<? super List<ByteBuffer>>,​T> HttpResponse.BodySubscriber<T> fromSubscriber​(S subscriber,                                                                                                                          Function<? super S,​? extends T> finisher)
        返回一个主体订阅者，它将所有响应主体转发给给定的Flow.Subscriber 。 在调用给定订户之一onComplete或onError之后，返回的正文订户的completion stage完成。

        在调用给定订户的onComplete之后应用给定的finisher函数。 使用给定订户调用finisher函数，并返回设置为响应正文的值。

        API Note:
        此方法可用作 BodySubscriber和 Flow.Subscriber之间的适配器。
        参数类型
        S - 订阅者的类型
        T - 响应正文的类型
        参数
        subscriber - 订户
        finisher - 订户完成后应用的功能
        结果
        身体用户

      • fromLineSubscriber

        public static HttpResponse.BodySubscriber<Void> fromLineSubscriber​(Flow.Subscriber<? super String> subscriber)
        返回一个主体订阅者，它Flow.Subscriber将所有响应主体转发给给定的Flow.Subscriber 。 该completion stage返回的身体用户的给定用户之一后完成onComplete或onError已被调用。 字节使用UTF-8字符集进行解码，行以BufferedReader.readLine()的方式分隔。
        API Note:
        此方法可用作 BodySubscriber和 Flow.Subscriber之间的适配器。
        Implementation Note:
        这相当于打电话 
           fromLineSubscriber(subscriber, s -> null, StandardCharsets.UTF_8, null)
        参数
        subscriber - 订户
        结果
        身体用户

      • fromLineSubscriber

        public static <S extends Flow.Subscriber<? super String>,​T> HttpResponse.BodySubscriber<T> fromLineSubscriber​(S subscriber,                                                                                                                    Function<? super S,​? extends T> finisher,                                                                                                                    Charset charset,                                                                                                                    String lineSeparator)
        返回一个主体订阅者，它Flow.Subscriber将所有响应主体转发给给定的Flow.Subscriber 。 在调用给定订户之一onComplete或onError之后，返回的正文订户的completion stage完成。

        在调用给定订户的onComplete之后应用给定的finisher功能。 使用给定订户调用finisher函数，并返回设置为响应正文的值。

        API Note:
        此方法可用作 BodySubscriber和 Flow.Subscriber之间的适配器。
        参数类型
        S - 订户的类型
        T - 响应正文的类型
        参数
        subscriber - 订户
        finisher - 订户完成后应用的功能
        charset - 用于解码字节的Charset
        lineSeparator - 可选的行分隔符：可以是 null ，在这种情况下，行将以 BufferedReader.readLine()的方式分隔。
        结果
        身体用户
        异常
        IllegalArgumentException - 如果提供的 lineSeparator是空字符串

      • ofString

        public static HttpResponse.BodySubscriber<String> ofString​(Charset charset)
        返回一个正文订阅者，它将响应正文存储为使用给定的String转换的Charset 。

        在读取完整个响应后，可以使用此订户的HttpResponse 。

        参数
        charset - 用于转换String的字符集
        结果
        身体用户

      • ofByteArray

        public static HttpResponse.BodySubscriber<byte[]> ofByteArray()
        返回BodySubscriber ，它将响应主体存储为字节数组。

        在读取完整个响应后，可以使用此订户的HttpResponse 。

        结果
        身体用户

      • ofFile

        public static HttpResponse.BodySubscriber<Path> ofFile​(Path file,                                                       OpenOption... openOptions)
        返回BodySubscriber ，它将响应正文存储在使用给定选项和名称打开的文件中。 在读取正文之前，将使用FileChannel.open使用给定选项打开文件。 抛出的任何异常将根据需要从HttpClient::send或HttpClient::sendAsync返回或抛出。

        在读取完整个响应后，可以使用使用此订户的HttpResponse 。

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

        参数
        file - 存储主体的文件
        openOptions - 用于打开文件的选项列表
        结果
        身体用户
        异常
        IllegalArgumentException - 如果指定了一组无效的打开选项
        SecurityException - 如果已安装安全管理器并且它拒绝该文件的 write access

      • ofFile

        public static HttpResponse.BodySubscriber<Path> ofFile​(Path file)
        返回BodySubscriber ，它将响应正文存储在使用给定名称打开的文件中。

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

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

        参数
        file - 存储主体的文件
        结果
        身体用户
        异常
        SecurityException - 如果已安装安全管理器并且它拒绝该文件的 write access

      • ofByteArrayConsumer

        public static HttpResponse.BodySubscriber<Void> ofByteArrayConsumer​(Consumer<Optional<byte[]>> consumer)
        返回BodySubscriber ，它向所提供的消费者提供传入的身体数据Optional<byte[]> 。 每次调用Consumer.accept()都将包含一个非空的Optional ，除了在读取所有正文数据后的最终调用时， Optional将为空。

        在读取完整个响应后，可以使用此订户的HttpResponse 。

        API Note:
        该订户不受流量控制。 因此，提供的消费者必须能够及时处理任何数量的数据。
        参数
        consumer - 字节数组的使用者
        结果
        一个BodySubscriber

      • ofInputStream

        public static HttpResponse.BodySubscriber<InputStream> ofInputStream()
        返回BodySubscriber ，它将响应正文流式传输为InputStream 。

        使用此订户的HttpResponse在读取响应标头后立即可用，无需等待处理整个主体。 然后可以直接从InputStream读取响应主体。

        API Note:
        为了确保与相应交换相关联的所有资源都被正确释放，调用者必须确保在达到EOF之前读取所有字节，或者如果不能或不愿意，则调用InputStream.close() 。 在耗尽流之前调用close可能导致底层HTTP连接被关闭并阻止它被重用于后续操作。
        结果
        将响应主体流式传输为InputStream的正文订阅者。

      • ofLines

        public static HttpResponse.BodySubscriber<Stream<String>> ofLines​(Charset charset)
        返回BodySubscriber ，它将响应主体流式传输为Stream ，其中流中的每个字符串对应于BufferedReader.lines()定义的行 。

        使用此订户的HttpResponse在读取响应标头后立即可用，无需等待处理整个主体。 然后可以直接从Stream读取响应主体。

        API Note:
        为确保与相应交换机关联的所有资源都已正确释放，呼叫者必须确保在流消耗之前读取所有线路，或者如果无法或不愿意，则调用BaseStream.close() 。 在耗尽流之前调用close可能导致底层HTTP连接被关闭并阻止它被重用于后续操作。
        参数
        charset - 将字节转换为字符时使用的字符集
        结果
        将响应主体流式传输为Stream 的正文订阅者。
        另请参见：
        BufferedReader.lines()

      • ofPublisher

        public static HttpResponse.BodySubscriber<Flow.Publisher<List<ByteBuffer>>> ofPublisher()
        返回通过Publisher<List<ByteBuffer>>发布响应正文的响应订阅者。

        使用此订户的HttpResponse在读取响应标头后立即可用，无需等待处理整个主体。 然后可以通过订阅HttpResponse body方法返回的发布者来获得响应主体字节。

        body方法返回的发布者只能订阅一次。 如果成功订阅，第一个订户将收到正文响应字节，否则将导致订阅被取消。 如果尝试更多订阅，则后续订阅者将立即订阅空订阅，并且将使用IllegalStateException调用其onError方法。

        API Note:
        为了确保与相应交换相关联的所有资源都被正确释放，调用者必须确保所提供的发布者订阅一次，并且调用requests所有字节直到onComplete或onError ，或者如果它不能或不愿意，则取消提供的subscription所以。 请注意，根据用于交换的实际HTTP协议version ，取消订阅而不是耗尽流量可能会导致底层HTTP连接被关闭，并阻止其重新用于后续操作。
        结果
        BodySubscriber ，通过 Publisher<List<ByteBuffer>>发布响应正文。

      • replacing

        public static <U> HttpResponse.BodySubscriber<U> replacing​(U value)
        返回一个丢弃响应主体的响应订阅者。 提供的值是将从HttpResponse.body()返回的值。
        参数类型
        U - 响应正文的类型
        参数
        value - 从HttpResponse.body（）返回的值，可能是 null
        结果
        BodySubscriber

      • buffering

        public static <T> HttpResponse.BodySubscriber<T> buffering​(HttpResponse.BodySubscriber<T> downstream,                                                           int bufferSize)
        返回BodySubscriber ，在将数据传递给给定的下游订户之前缓冲数据。 除最终调用之外，订户保证在每次调用下游的onNext方法时提供buffersize字节的数据，就在调用onComplete之前。 最终调用onNext可能包含少于bufferSize个字节。

        返回的订户将其getBody()方法委托给下游订户。

        参数类型
        T - 响应正文的类型
        参数
        downstream - 下游订户
        bufferSize - 缓冲区大小
        结果
        一个缓冲的身体用户
        异常
        IllegalArgumentException - 如果是 bufferSize <= 0

      • mapping

        public static <T,​U> HttpResponse.BodySubscriber<U> mapping​(HttpResponse.BodySubscriber<T> upstream,                                                                 Function<? super T,​? extends U> mapper)
        返回BodySubscriber其响应正文值是将给定函数应用于给定upstream BodySubscriber的正文对象的upstream BodySubscriber 。

        映射函数使用客户端executor执行，因此可用于映射任何响应体类型，包括阻止InputStream ，如以下示例所示，该示例使用着名的JSON解析器将InputStream转换为任何带注释的Java类型。

        例如： 

           public static <W> BodySubscriber<W> asJSON(Class<W> targetType) { BodySubscriber<InputStream> upstream = BodySubscribers.ofInputStream(); BodySubscriber<W> downstream = BodySubscribers.mapping( upstream, (InputStream is) -> { try (InputStream stream = is) { ObjectMapper objectMapper = new ObjectMapper(); return objectMapper.readValue(stream, targetType); } catch (IOException e) { throw new UncheckedIOException(e); } }); return downstream; }
        参数类型
        T - 上游体型
        U - 返回的正文订阅者的类型
        参数
        upstream - 要映射的正文订阅者
        mapper - 映射功能
        结果
        映射主体订户