Summary

Change the HTTP BodyHandler API to use an extensible interface containing the required parameters rather than listing the parameters in the functional interface method directly, which is less extensible.

Problem

HttpResponse.BodyHandler is a functional interface defined as follows:

   /**
     * Returns a {@link BodySubscriber BodySubscriber} considering the
     * given response status code and headers. This method is invoked before
     * the actual response body bytes are read and its implementation must
     * return a {@link BodySubscriber BodySubscriber} to consume the response
     * body bytes.
     *
     * <p> The response body can be discarded using one of {@link
     * BodyHandlers#discarding() discarding} or {@link
     * BodyHandlers#replacing(Object) replacing}.
     *
     * @param statusCode the HTTP status code received
     * @param responseHeaders the response headers received
     * @return a body subscriber
     */
    public BodySubscriber<T> apply(int statusCode, HttpHeaders responseHeaders);

The parameters to the handler implementation are defined directly in the apply method. We need to add one new parameter to this list. So, we wish to replace the parameter list with a new interface type containing the two existing parameters and the new proposed one, so that further parameters could be added in the future.

Solution

Replace the existing BodyHandler.apply parameter list with a new interface type called HttpResponse.ResponseInfo containing the required parameters.

Specification

Add a new nested type of HttpResponse as follows:

/**
 * Initial response information supplied to a {@link BodyHandler} when a
 * response is initially received and before the body is processed.
 */
public interface ResponseInfo {
    /**
     * Provides the response status code
     * @return the response status code
     */
    public int statusCode();

    /**
     * Provides the response headers
     * @return the response headers
     */
    public HttpHeaders headers();

    /**
     * Provides the response protocol version
     * @return the response protocol version
     */
    public HttpClient.Version version();
}

Change the BodyHandler.apply() method to the following:

    /**
     * Returns a {@link BodySubscriber BodySubscriber} considering the
     * given response status code and headers. This method is invoked before
     * the actual response body bytes are read and its implementation must
     * return a {@link BodySubscriber BodySubscriber} to consume the response
     * body bytes.
     *
     * <p> The response body can be discarded using one of {@link
     * BodyHandlers#discarding() discarding} or {@link
     * BodyHandlers#replacing(Object) replacing}.
     *
     * @param responseInfo the response info.
     * @return a body subscriber
     */
    public BodySubscriber<T> apply(ResponseInfo responseInfo);