Class HttpResponse.BodySubscribers

java.lang.Object
java.net.http.HttpResponse.BodySubscribers
Enclosing interface:
HttpResponse<T>
public static class HttpResponse.BodySubscribers extends Object
Implementations of BodySubscriber that implement various useful subscribers, such as converting the response body bytes into a String, or streaming the bytes to a file.

The following are examples of using the predefined body subscribers to convert a flow of response body data into common high-level Java objects: 

// Streams the response body to a File
HttpResponse<Path> response = client
  .send(request, responseInfo -> BodySubscribers.ofFile(Paths.get("example.html"));
// 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));
Since:
11

  • Method Details

    • fromSubscriber

      public static HttpResponse.BodySubscriber<Void> fromSubscriber(Flow.Subscriber<? super List<ByteBuffer>> subscriber)
      Returns a body subscriber that forwards all response body to the given Flow.Subscriber. The completion stage of the returned body subscriber completes after one of the given subscribers onComplete or onError has been invoked.
      Parameters:
      subscriber - the subscriber
      Returns:
      a body subscriber

    • fromSubscriber

      public static <S extends Flow.Subscriber<? super List<ByteBuffer>>, T> HttpResponse.BodySubscriber<T> fromSubscriber(S subscriber, Function<? super S, ? extends T> finisher)
      Returns a body subscriber that forwards all response body to the given Flow.Subscriber. The completion stage of the returned body subscriber completes after one of the given subscribers onComplete or onError has been invoked.

      The given finisher function is applied after the given subscriber's onComplete has been invoked. The finisher function is invoked with the given subscriber, and returns a value that is set as the response's body.

      Type Parameters:
      S - the type of the Subscriber
      T - the type of the response body
      Parameters:
      subscriber - the subscriber
      finisher - a function to be applied after the subscriber has completed
      Returns:
      a body subscriber

    • fromLineSubscriber

      public static HttpResponse.BodySubscriber<Void> fromLineSubscriber(Flow.Subscriber<? super String> subscriber)
      Returns a body subscriber that forwards all response body to the given Flow.Subscriber, line by line. The completion stage of the returned body subscriber completes after one of the given subscribers onComplete or onError has been invoked. Bytes are decoded using the UTF-8 charset, and lines are delimited in the manner of BufferedReader.readLine().
      Parameters:
      subscriber - the subscriber
      Returns:
      a body 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)
      Returns a body subscriber that forwards all response body to the given Flow.Subscriber, line by line. The completion stage of the returned body subscriber completes after one of the given subscribers onComplete or onError has been invoked.

      The given finisher function is applied after the given subscriber's onComplete has been invoked. The finisher function is invoked with the given subscriber, and returns a value that is set as the response's body.

      Type Parameters:
      S - the type of the Subscriber
      T - the type of the response body
      Parameters:
      subscriber - the subscriber
      finisher - a function to be applied after the subscriber has completed
      charset - a Charset to decode the bytes
      lineSeparator - an optional line separator: can be null, in which case lines will be delimited in the manner of BufferedReader.readLine().
      Returns:
      a body subscriber
      Throws:
      IllegalArgumentException - if the supplied lineSeparator is the empty string

    • ofString

      public static HttpResponse.BodySubscriber<String> ofString(Charset charset)
      Returns a body subscriber which stores the response body as a String converted using the given Charset.

      The HttpResponse using this subscriber is available after the entire response has been read.

      Parameters:
      charset - the character set to convert the String with
      Returns:
      a body subscriber

    • ofByteArray

      public static HttpResponse.BodySubscriber<byte[]> ofByteArray()
      Returns a BodySubscriber which stores the response body as a byte array.

      The HttpResponse using this subscriber is available after the entire response has been read.

      Returns:
      a body subscriber

    • ofFile

      public static HttpResponse.BodySubscriber<Path> ofFile(Path file, OpenOption... openOptions)
      Returns a BodySubscriber which stores the response body in a file opened with the given options and name. The file will be opened with the given options using FileChannel.open just before the body is read. Any exception thrown will be returned or thrown from HttpClient::send or HttpClient::sendAsync as appropriate.

      The HttpResponse using this subscriber is available after the entire response has been read.

      Parameters:
      file - the file to store the body in
      openOptions - the list of options to open the file with
      Returns:
      a body subscriber
      Throws:
      IllegalArgumentException - if an invalid set of open options are specified

    • ofFile

      public static HttpResponse.BodySubscriber<Path> ofFile(Path file)
      Returns a BodySubscriber which stores the response body in a file opened with the given name.

      Equivalent to: ofFile(file, CREATE, WRITE)

      Parameters:
      file - the file to store the body in
      Returns:
      a body subscriber

    • ofByteArrayConsumer

      public static HttpResponse.BodySubscriber<Void> ofByteArrayConsumer(Consumer<Optional<byte[]>> consumer)
      Returns a BodySubscriber which provides the incoming body data to the provided Consumer of Optional<byte[]>. Each call to Consumer.accept() will contain a non-empty Optional, except for the final invocation after all body data has been read, when the Optional will be empty.

      The HttpResponse using this subscriber is available after the entire response has been read.

      Parameters:
      consumer - a Consumer of byte arrays
      Returns:
      a body subscriber

    • ofInputStream

      public static HttpResponse.BodySubscriber<InputStream> ofInputStream()
      Returns a BodySubscriber which streams the response body as an InputStream.

      The HttpResponse using this subscriber is available immediately after the response headers have been read, without requiring to wait for the entire body to be processed. The response body can then be read directly from the InputStream.

      Returns:
      a streaming body subscriber which streams the response body as an InputStream.

    • ofLines

      public static HttpResponse.BodySubscriber<Stream<String>> ofLines(Charset charset)
      Returns a BodySubscriber which streams the response body as a Stream<String>, where each string in the stream corresponds to a line as defined by BufferedReader.lines().

      The HttpResponse using this subscriber is available immediately after the response headers have been read, without requiring to wait for the entire body to be processed. The response body can then be read directly from the Stream.

      Parameters:
      charset - the character set to use when converting bytes to characters
      Returns:
      a streaming body subscriber which streams the response body as a Stream<String>.
      See Also:

    • ofPublisher

      public static HttpResponse.BodySubscriber<Flow.Publisher<List<ByteBuffer>>> ofPublisher()
      Returns a response subscriber which publishes the response body through a Publisher<List<ByteBuffer>>.

      The HttpResponse using this subscriber is available immediately after the response headers have been read, without requiring to wait for the entire body to be processed. The response body bytes can then be obtained by subscribing to the publisher returned by the HttpResponse body method.

      The publisher returned by the body method can be subscribed to only once. The first subscriber will receive the body response bytes if successfully subscribed, or will cause the subscription to be cancelled otherwise. If more subscriptions are attempted, the subsequent subscribers will be immediately subscribed with an empty subscription and their onError method will be invoked with an IllegalStateException.

      Returns:
      A publishing body subscriber which publishes the response body through a Publisher<List<ByteBuffer>>.

    • replacing

      public static <U> HttpResponse.BodySubscriber<U> replacing(U value)
      Returns a response subscriber which discards the response body. The supplied value is the value that will be returned from HttpResponse.body().
      Type Parameters:
      U - the type of the response body
      Parameters:
      value - the value to return from HttpResponse.body(), may be null
      Returns:
      a body subscriber

    • discarding

      public static HttpResponse.BodySubscriber<Void> discarding()
      Returns a response subscriber which discards the response body.
      Returns:
      a response body subscriber

    • buffering

      public static <T> HttpResponse.BodySubscriber<T> buffering(HttpResponse.BodySubscriber<T> downstream, int bufferSize)
      Returns a BodySubscriber which buffers data before delivering it to the given downstream subscriber. The subscriber guarantees to deliver bufferSize bytes of data to each invocation of the downstream's onNext method, except for the final invocation, just before onComplete is invoked. The final invocation of onNext may contain fewer than bufferSize bytes.

      The returned subscriber delegates its getBody() method to the downstream subscriber.

      Type Parameters:
      T - the type of the response body
      Parameters:
      downstream - the downstream subscriber
      bufferSize - the buffer size
      Returns:
      a buffering body subscriber
      Throws:
      IllegalArgumentException - if bufferSize <= 0

    • mapping

      public static <T,U> HttpResponse.BodySubscriber<U> mapping(HttpResponse.BodySubscriber<T> upstream, Function<? super T, ? extends U> mapper)
      Returns a BodySubscriber whose response body value is that of the result of applying the given function to the body object of the given upstream BodySubscriber.

      The mapping function is executed using the client's executor, and can therefore be used to map any response body type, including blocking InputStream. However, performing any blocking operation in the mapper function runs the risk of blocking the executor's thread for an unknown amount of time (at least until the blocking operation finishes), which may end up starving the executor of available threads. Therefore, in the case where mapping to the desired type might block (e.g. by reading on the InputStream), then mapping to a Supplier of the desired type and deferring the blocking operation until Supplier::get is invoked by the caller's thread should be preferred, as shown in the following example which uses a well-known JSON parser to convert an InputStream into any annotated Java type.

      For example: 

       public static <W> BodySubscriber<Supplier<W>> asJSON(Class<W> targetType) {
   BodySubscriber<InputStream> upstream = BodySubscribers.ofInputStream();

   BodySubscriber<Supplier<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;
}
      Type Parameters:
      T - the upstream body type
      U - the type of the body subscriber returned
      Parameters:
      upstream - the body subscriber to be mapped
      mapper - the mapping function
      Returns:
      a mapping body subscriber

    • limiting

      public static <T> HttpResponse.BodySubscriber<T> limiting(HttpResponse.BodySubscriber<T> downstreamSubscriber, long capacity)
      Returns a BodySubscriber that limits the number of body bytes that are delivered to the given downstreamSubscriber.

      If the number of body bytes received exceeds the given capacity, onError is called on the downstream BodySubscriber with an IOException indicating that the capacity is exceeded, and the upstream subscription is cancelled.

      Parameters:
      downstreamSubscriber - the downstream subscriber to pass received data to
      capacity - the maximum number of bytes that are allowed
      Returns:
      a BodySubscriber that limits the number of body bytes that are delivered to the given downstreamSubscriber
      Throws:
      IllegalArgumentException - if capacity is negative
      Since:
      25