Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8209075

Differentiate response and connect timeouts in HTTP Client API



    • Type: CSR
    • Status: Closed
    • Priority: P2
    • Resolution: Approved
    • Fix Version/s: 11
    • Component/s: core-libs
    • Labels:
    • Subcomponent:
    • Compatibility Risk:
    • Compatibility Risk Description:
      New API in Java 11
    • Interface Kind:
      Java API
    • Scope:



      Add connection specific timeout support to the HTTP Client.


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


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


          Issue Links



              chegar Chris Hegarty
              michaelm Michael McMahon
              Reviewed By:
              Michael McMahon
              0 Vote for this issue
              2 Start watching this issue