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) { ... }
}