Differentiate response and connect timeouts in HTTP Client API

Summary

Add connection specific timeout support to the HTTP Client.

Problem

The Java 11 HTTP Client API supports setting an overall request timeout through HttpRequest.Builder::timeout. A connect specific timeout is also desirable, so that the connection phase can be timed with a much smaller timeout than the overall response ( which is typically done to mitigate against potentially long connection delays when the network does not response to TCP SYN requests for some domains).

Solution

Add a new method to the HttpClient.Builder that allows setting of a connect timeout duration for all new connections established by clients built from that builder. Add a new accessor to HttpClient to retrieve said connect timeout duration.

Add a new public exception type, HttpConnectTimeoutException that is thrown when a connection times out. This exception type is a subtype of the existing HttpTimeoutException, thus allowing for more fine grained exception handling to discern connection timeouts from response timeouts, where desired. The use of a subtype reduces the exception handling overhead for those that do not wish to take that burden, a timeout is just a timeout.

Specification

Specification changes to the java.net.http package:

To HttpClient.Builder add:

/**
 * Sets the connect timeout duration for this client.
 *
 * <p> In the case where a new connection needs to be established, if
 * the connection cannot be established within the given {@code
 * duration}, then {@link HttpClient#send(HttpRequest,BodyHandler)
 * HttpClient::send} throws an {@link HttpConnectTimeoutException}, or
 * {@link HttpClient#sendAsync(HttpRequest,BodyHandler)
 * HttpClient::sendAsync} completes exceptionally with an
 * {@code HttpConnectTimeoutException}. If a new connection does not
 * need to be established, for example if a connection can be reused
 * from a previous request, then this timeout duration has no effect.
 *
 * @param duration the duration to allow the underlying connection to be
 *                 established
 * @return this builder
 * @throws IllegalArgumentException if the duration is non-positive
 */
public Builder connectTimeout(Duration duration);

To HttpClient add an accessor:

/**
 * Returns an {@code Optional} containing the <i>connect timeout duration</i>
 * for this client. If the {@linkplain Builder#connectTimeout(Duration)
 * connect timeout duration} was not set in the client's builder, then the
 * {@code Optional} is empty.
 *
 * @return an {@code Optional} containing this client's connect timeout
 *         duration
 */
public abstract Optional<Duration> connectTimeout();

Add new Exception type:

/**
 * Thrown when a connection, over which an {@code HttpRequest} is intended to be
 * sent, is not successfully established within a specified time period.
 *
 * @since 11
 */
public class HttpConnectTimeoutException extends HttpTimeoutException {

    private static final long serialVersionUID = 321L + 11L;

    /**
     * Constructs an {@code HttpConnectTimeoutException} with the given detail
     * message.
     *
     * @param message
     *        The detail message; can be {@code null}
     */
    public HttpConnectTimeoutException(String message) { ... }
}