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

Differentiate response and connect timeouts in HTTP Client API

    Details

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

      Description

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

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                chegar Chris Hegarty
                Reporter:
                michaelm Michael McMahon
                Reviewed By:
                Michael McMahon
              • Votes:
                0 Vote for this issue
                Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: