Module java.httpclient
Package java.net.http

## Interface HttpResponse.BodyProcessor<T>

Type Parameters:
  `T` - the type of the response body

Enclosing class:
  HttpResponse

    public static interface HttpResponse.BodyProcessor<T>

A processor for response bodies, which determines the type of the response body returned from `HttpResponse`. Response processors can either return an object that represents the body itself (after it has been read) or else an object that is used to read the body (such as an `InputStream`). The parameterized type `<T>` is the type of the returned body object from `HttpResponse.body` and (indirectly) from `HttpResponse.bodyAsync`.

Implementations of this interface are provided in `HttpResponse` which write responses to `String, byte[], File, Consumer<byte[]>`. Custom implementations can also be used.

The methods of this interface may be called from multiple threads, but only one method is invoked at a time, and behaves as if called from one thread.

Since:
  9

### Method Summary

All Methods Instance Methods Abstract Methods
`void` `onResponseBodyChunk(ByteBuffer b)` Called for each buffer of data received for this response.
`T` `onResponseBodyStart(long contentLength, HttpHeaders responseHeaders, LongConsumer flowController)` Called immediately before the response body is read.
`T` `onResponseComplete()` Called after the last time `onResponseBodyChunk(java.nio.ByteBuffer)` has been called and returned indicating that the entire content has been read.
`void` `onResponseError(Throwable t)` Called if an error occurs while reading the response body.

### Method Detail

#### onResponseBodyStart

    T onResponseBodyStart(long contentLength,
                          HttpHeaders responseHeaders,
                          LongConsumer flowController)
                   throws IOException

Called immediately before the response body is read. If `<T>` is an object used to read or accept the response body, such as a `Consumer` or `InputStream` then it should be returned from this method, and the body object will be returned before any data is read. If `<T>` represents the body itself after being read, then this method must return `null` and the body will be returned from `onResponseComplete()`. In both cases, the actual body data is provided by the `onResponseBodyChunk` method in exactly the same way.

flowController is a consumer of long values and is used for updating a flow control window as follows. The window represents the number of times `onResponseBodyChunk` may be called before receiving further updates to the window. Each time it is called, the window is reduced by `1`. When the window reaches zero `onResponseBodyChunk()` will not be called again until the window has opened again with further calls to flowController.accept(). `flowcontroller.accept()` must be called to open (increase) the window by the specified amount. The initial value is zero. This implies that if `onResponseBodyStart()` does not call `flowController.accept()` with a positive value no data will ever be delivered.

Parameters:
  `contentLength` - `-1` signifies unknown content length. Otherwise, a positive integer, or zero.
  `responseHeaders` - the response headers
  `flowController` - a LongConsumer used to update the flow control window
Returns:
  `null` or an object that can be used to read the response body.
Throws:
  `IOException` - if an exception occurs starting the response body receive

#### onResponseError

    void onResponseError(Throwable t)

Called if an error occurs while reading the response body. This terminates the operation and no further calls will occur after this.

Parameters:
  `t` - the Throwable

#### onResponseBodyChunk

    void onResponseBodyChunk(ByteBuffer b)
                      throws IOException

Called for each buffer of data received for this response. ByteBuffers can be reused as soon as this method returns.

Parameters:
  `b` - a ByteBuffer whose position is at the first byte that can be read, and whose limit is after the last byte that can be read
Throws:
  `IOException` - in case of I/O error

#### onResponseComplete

    T onResponseComplete()
                  throws IOException

Called after the last time `onResponseBodyChunk(java.nio.ByteBuffer)` has been called and returned indicating that the entire content has been read. This method must return an object that represents or contains the response body just received, but only if an object was not returned from `onResponseBodyStart`.

Returns:
  a T, or `null` if an object was already returned
Throws:
  `IOException` - in case of I/O error