HttpResponse.BodySubscriber (Java SE 10 & JDK 10 )
Keywords: jdk.incubator.http.HttpResponse.BodySubscriber interface

Module jdk.incubator.httpclient
Package jdk.incubator.http

## Interface HttpResponse.BodySubscriber<T>

- Type Parameters:
    `T` - the response body type
  All Superinterfaces:
    `Flow.Subscriber<List<ByteBuffer>>`
  Enclosing class:
    HttpResponse<T>

      public static interface HttpResponse.BodySubscriber<T>
      extends Flow.Subscriber<List<ByteBuffer>>

  A subscriber for response bodies.
  Incubating Feature. Will be removed in a future release.

  The object acts as a `Flow.Subscriber`<`List`<`ByteBuffer`>> to the HTTP client implementation, which publishes unmodifiable lists of ByteBuffers containing the response body. The Flow of data, as well as the order of ByteBuffers in the Flow lists, is a strictly ordered representation of the response body. Both the Lists and the ByteBuffers, once passed to the subscriber, are no longer used by the HTTP client. The subscriber converts the incoming buffers of data to some user-defined object type `T`.

  The `getBody()` method returns a `CompletionStage``<T>` that provides the response body object. The `CompletionStage` must be obtainable at any time. When it completes depends on the nature of type `T`. In many cases, when `T` represents the entire body after being read then it completes after the body has been read. If `T` is a streaming type such as `InputStream` then it completes before the body has been read, because the calling code uses it to consume the data.

  API Note:
    To ensure that all resources associated with the corresponding exchange are properly released, an implementation of `BodySubscriber` must ensure to request more data until `onComplete` or `onError` are signalled, or cancel its subscription if unable or unwilling to do so. Calling `cancel` before exhausting the data may cause the underlying HTTP connection to be closed and prevent it from being reused for subsequent operations.

- - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static HttpResponse.BodySubscriber<byte[]>` | `asByteArray()` | Returns a `BodySubscriber` which stores the response body as a byte array.
    `static HttpResponse.BodySubscriber<Void>` | `asByteArrayConsumer​(Consumer<Optional<byte[]>> consumer)` | Returns a `BodySubscriber` which provides the incoming body data to the provided Consumer of `Optional<byte[]>`.
    `static HttpResponse.BodySubscriber<Path>` | `asFile​(Path file)` | Returns a `BodySubscriber` which stores the response body in a file opened with the given name.
    `static HttpResponse.BodySubscriber<Path>` | `asFile​(Path file, OpenOption... openOptions)` | Returns a `BodySubscriber` which stores the response body in a file opened with the given options and name.
    `static HttpResponse.BodySubscriber<InputStream>` | `asInputStream()` | Returns a `BodySubscriber` which streams the response body as an `InputStream`.
    `static HttpResponse.BodySubscriber<String>` | `asString​(Charset charset)` | Returns a body subscriber which stores the response body as a `String` converted using the given `Charset`.
    `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.
    `static <U> HttpResponse.BodySubscriber<U>` | `discard​(U value)` | Returns a response subscriber which discards the response body.
    `static <S extends Flow.Subscriber<? super List<ByteBuffer>>> HttpResponse.BodySubscriber<Void>` | `fromSubscriber​(S subscriber)` | Returns a body subscriber that forwards all response body to the given `Flow.Subscriber`.
    `static <S extends Flow.Subscriber<? super List<ByteBuffer>>,T> HttpResponse.BodySubscriber<T>` | `fromSubscriber​(S subscriber, Function<S,T> finisher)` | Returns a body subscriber that forwards all response body to the given `Flow.Subscriber`.
    `CompletionStage<T>` | `getBody()` | Returns a `CompletionStage` which when completed will return the response body object.

    - ### Methods declared in interface java.util.concurrent.Flow.Subscriber

      `onComplete, onError, onNext, onSubscribe`

- - ### Method Detail

    - #### getBody

          CompletionStage<T> getBody()

      Returns a `CompletionStage` which when completed will return the response body object.
      Returns:
        a CompletionStage for the response body

    - #### fromSubscriber

          static <S extends Flow.Subscriber<? super List<ByteBuffer>>> HttpResponse.BodySubscriber<Void> fromSubscriber​(S subscriber)

      Returns a body subscriber that forwards all response body to the given `Flow.Subscriber`. The getBody() completion stage} of the returned body subscriber completes after one of the given subscribers `onComplete` or `onError` has been invoked.
      API Note:
        This method can be used as an adapter between `BodySubscriber` and `Flow.Subscriber`.
      Type Parameters:
        `S` - the type of the Subscriber
      Parameters:
        `subscriber` - the subscriber
      Returns:
        a body subscriber

    - #### fromSubscriber

          static <S extends Flow.Subscriber<? super List<ByteBuffer>>,T> HttpResponse.BodySubscriber<T> fromSubscriber​(S subscriber,
                                                                                                                       Function<S,T> finisher)

      Returns a body subscriber that forwards all response body to the given `Flow.Subscriber`. The getBody() 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.

      API Note:
        This method can be used as an adapter between `BodySubscriber` and `Flow.Subscriber`.
      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

    - #### asString

          static HttpResponse.BodySubscriber<String> asString​(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

    - #### asByteArray

          static HttpResponse.BodySubscriber<byte[]> asByteArray()

      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

    - #### asFile

          static HttpResponse.BodySubscriber<Path> asFile​(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:
        `SecurityException` - If a security manager has been installed and it denies `write access` to the file. The `checkDelete` method is invoked to check delete access if the file is opened with the `DELETE_ON_CLOSE` option.

    - #### asFile

          static HttpResponse.BodySubscriber<Path> asFile​(Path file)

      Returns a `BodySubscriber` which stores the response body in a file opened with the given name. Has the same effect as calling `asFile` with the standard open options `CREATE` and `WRITE`

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

      Parameters:
        `file` - the file to store the body in
      Returns:
        a body subscriber
      Throws:
        `SecurityException` - if a security manager has been installed and it denies `write access` to the file

    - #### asByteArrayConsumer

          static HttpResponse.BodySubscriber<Void> asByteArrayConsumer​(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 BodySubscriber

    - #### asInputStream

          static HttpResponse.BodySubscriber<InputStream> asInputStream()

      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`.

      API Note:
        To ensure that all resources associated with the corresponding exchange are properly released the caller must ensure to either read all bytes until EOF is reached, or call `InputStream.close()` if it is unable or unwilling to do so. Calling `close` before exhausting the stream may cause the underlying HTTP connection to be closed and prevent it from being reused for subsequent operations.
      Returns:
        a body subscriber that streams the response body as an `InputStream`.

    - #### discard

          static <U> HttpResponse.BodySubscriber<U> discard​(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 `BodySubscriber`

    - #### buffering

          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.

      Parameters:
        `downstream` - the downstream subscriber
        `bufferSize` - the buffer size
      Returns:
        a buffering body subscriber
      Throws:
        `IllegalArgumentException` - if `bufferSize <= 0`