src/java.net.http/share/classes/java/net/http/HttpClient.java

@@ -32,10 +32,11 @@
 import java.net.Proxy;
 import java.net.ProxySelector;
 import java.net.URLPermission;
 import java.security.AccessController;
 import java.security.PrivilegedAction;
+import java.time.Duration;
 import java.util.Optional;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.Executor;
 import java.util.concurrent.Executors;
 import java.util.concurrent.ThreadFactory;

@@ -82,21 +83,22 @@
  *
  * <p><b>Synchronous Example</b>
  * <pre>{@code    HttpClient client = HttpClient.newBuilder()
  *        .version(Version.HTTP_1_1)
  *        .followRedirects(Redirect.NORMAL)
+ *        .connectTimeout(Duration.ofSeconds(20))
  *        .proxy(ProxySelector.of(new InetSocketAddress("proxy.example.com", 80)))
  *        .authenticator(Authenticator.getDefault())
  *        .build();
  *   HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
  *   System.out.println(response.statusCode());
  *   System.out.println(response.body());  }</pre>
  *
  * <p><b>Asynchronous Example</b>
  * <pre>{@code    HttpRequest request = HttpRequest.newBuilder()
  *        .uri(URI.create("https://foo.com/"))
- *        .timeout(Duration.ofMinutes(1))
+ *        .timeout(Duration.ofMinutes(2))
  *        .header("Content-Type", "application/json")
  *        .POST(BodyPublishers.ofFile(Paths.get("file.json")))
  *        .build();
  *   client.sendAsync(request, BodyHandlers.ofString())
  *        .thenApply(HttpResponse::body)

@@ -195,10 +197,30 @@
          * @return this builder
          */
         public Builder cookieHandler(CookieHandler cookieHandler);
 
         /**
+         * 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);
+
+        /**
          * Sets an {@code SSLContext}.
          *
          * <p> If this method is not invoked prior to {@linkplain #build()
          * building}, then newly built clients will use the {@linkplain
          * SSLContext#getDefault() default context}, which is normally adequate

@@ -343,10 +365,21 @@
      * @return an {@code Optional} containing this client's {@code CookieHandler}
      */
     public abstract Optional<CookieHandler> cookieHandler();
 
     /**
+     * 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();
+
+    /**
      * Returns the follow redirects policy for this client. The default value
      * for client's built by builders that do not specify a redirect policy is
      * {@link HttpClient.Redirect#NEVER NEVER}.
      *
      * @return this client's follow redirects setting