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

*** 32,41 ****
--- 32,42 ----
  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,102 ****
   *
   * <p><b>Synchronous Example</b>
   * <pre>{@code    HttpClient client = HttpClient.newBuilder()
   *        .version(Version.HTTP_1_1)
   *        .followRedirects(Redirect.NORMAL)
   *        .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))
   *        .header("Content-Type", "application/json")
   *        .POST(BodyPublishers.ofFile(Paths.get("file.json")))
   *        .build();
   *   client.sendAsync(request, BodyHandlers.ofString())
   *        .thenApply(HttpResponse::body)
--- 83,104 ----
   *
   * <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(2))
   *        .header("Content-Type", "application/json")
   *        .POST(BodyPublishers.ofFile(Paths.get("file.json")))
   *        .build();
   *   client.sendAsync(request, BodyHandlers.ofString())
   *        .thenApply(HttpResponse::body)
*** 195,204 ****
--- 197,226 ----
           * @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,352 ****
--- 365,385 ----
       * @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