Document the effect on timeouts of having both IPv4 and IPv6 addresses

Bug: http://b/3441111

Change-Id: Ib4c2e3e0d8d86eb5eb77cf92a0814c7444fd153f

4 files changed, 47 insertions, 44 deletions

diff --git a/luni/src/main/java/java/net/HttpURLConnection.java b/luni/src/main/java/java/net/HttpURLConnection.java
index 5bfdd2e..c5b4f7c 100644
--- a/luni/src/main/java/java/net/HttpURLConnection.java
+++ b/luni/src/main/java/java/net/HttpURLConnection.java
@@ -130,9 +130,9 @@ import libcore.net.http.HttpEngine;
  * for multiple request/response pairs. As a result, HTTP connections may be
  * held open longer than necessary. Calls to {@link #disconnect()} may return
  * the socket to a pool of connected sockets. This behavior can be disabled by
- * setting the "http.keepAlive" system property to "false" before issuing any
- * HTTP requests. The "http.maxConnections" property may be used to control how
- * many idle connections to each server will be held.
+ * setting the {@code http.keepAlive} system property to {@code false} before
+ * issuing any HTTP requests. The {@code http.maxConnections} property may be
+ * used to control how many idle connections to each server will be held.
  *
  * <p>By default, this implementation of {@code HttpURLConnection} requests that
  * servers use gzip compression. Since {@link #getContentLength()} returns the
@@ -518,8 +518,8 @@ public abstract class HttpURLConnection extends URLConnection {
      *
      * <p>Unlike other Java implementations, this will not necessarily close
      * socket connections that can be reused. You can disable all connection
-     * reuse by setting the "http.keepAlive" system property to "false" before
-     * issuing any HTTP requests.
+     * reuse by setting the {@code http.keepAlive} system property to {@code
+     * false} before issuing any HTTP requests.
      */
     public abstract void disconnect();
 
diff --git a/luni/src/main/java/java/net/URLConnection.java b/luni/src/main/java/java/net/URLConnection.java
index a8d967c..5e2b0c4 100644
--- a/luni/src/main/java/java/net/URLConnection.java
+++ b/luni/src/main/java/java/net/URLConnection.java
@@ -972,57 +972,52 @@ public abstract class URLConnection {
     }
 
     /**
-     * Sets the timeout value in milliseconds for establishing the connection to
-     * the resource pointed by this {@code URLConnection} instance. A {@code
-     * SocketTimeoutException} is thrown if the connection could not be
-     * established in this time. Default is {@code 0} which stands for an
-     * infinite timeout.
+     * Sets the maximum time to wait for a connect to complete before giving up.
+     * Connecting to a server will fail with a {@link SocketTimeoutException} if
+     * the timeout elapses before a connection is established. The default value
+     * of {@code 0} disables connect timeouts; connect attempts may wait
+     * indefinitely.
      *
-     * @param timeout
-     *            the connecting timeout in milliseconds.
-     * @throws IllegalArgumentException
-     *             if the parameter {@code timeout} is less than zero.
+     * <p><strong>Warning:</strong> if the server has both IPv6 and IPv4
+     * addresses, this client will try each in its preferred order. Should the
+     * server not respond on either address, two timeouts will elapse before the
+     * connect attempt fails.
+     *
+     * @param timeoutMillis the connect timeout in milliseconds. Non-negative.
      */
-    public void setConnectTimeout(int timeout) {
-        if (timeout < 0) {
-            throw new IllegalArgumentException("timeout < 0");
+    public void setConnectTimeout(int timeoutMillis) {
+        if (timeoutMillis < 0) {
+            throw new IllegalArgumentException("timeoutMillis < 0");
         }
-        this.connectTimeout = timeout;
+        this.connectTimeout = timeoutMillis;
     }
 
     /**
-     * Returns the configured connecting timeout.
-     *
-     * @return the connecting timeout value in milliseconds.
+     * Returns the connect timeout in milliseconds, or {@code 0} if connect
+     * attempts never timeout.
      */
     public int getConnectTimeout() {
         return connectTimeout;
     }
 
     /**
-     * Sets the timeout value in milliseconds for reading from the input stream
-     * of an established connection to the resource. A {@code
-     * SocketTimeoutException} is thrown if the connection could not be
-     * established in this time. Default is {@code 0} which stands for an
-     * infinite timeout.
+     * Sets the maximum time to wait for an input stream read to complete before
+     * giving up. Reading will fail with a {@link SocketTimeoutException} if the
+     * timeout elapses before data becomes available. The default value of
+     * {@code 0} disables read timeouts; read attempts will block indefinitely.
      *
-     * @param timeout
-     *            the reading timeout in milliseconds.
-     * @throws IllegalArgumentException
-     *             if the parameter {@code timeout} is less than zero.
+     * @param timeoutMillis the read timeout in milliseconds. Non-negative.
      */
-    public void setReadTimeout(int timeout) {
-        if (timeout < 0) {
-            throw new IllegalArgumentException("timeout < 0");
+    public void setReadTimeout(int timeoutMillis) {
+        if (timeoutMillis < 0) {
+            throw new IllegalArgumentException("timeoutMillis < 0");
         }
-        this.readTimeout = timeout;
+        this.readTimeout = timeoutMillis;
     }
 
     /**
-     * Returns the configured timeout for reading from the input stream of an
-     * established connection to the resource.
-     *
-     * @return the reading timeout value in milliseconds.
+     * Returns the read timeout in milliseconds, or {@code 0} if reads never
+     * timeout.
      */
     public int getReadTimeout() {
         return readTimeout;
diff --git a/luni/src/main/java/libcore/net/http/HttpsURLConnectionImpl.java b/luni/src/main/java/libcore/net/http/HttpsURLConnectionImpl.java
index ae5e7c1..e213706 100644
--- a/luni/src/main/java/libcore/net/http/HttpsURLConnectionImpl.java
+++ b/luni/src/main/java/libcore/net/http/HttpsURLConnectionImpl.java
@@ -336,8 +336,8 @@ final class HttpsURLConnectionImpl extends HttpsURLConnection {
     }
 
     @Override
-    public void setConnectTimeout(int timeout) {
-        delegate.setConnectTimeout(timeout);
+    public void setConnectTimeout(int timeoutMillis) {
+        delegate.setConnectTimeout(timeoutMillis);
     }
 
     @Override
@@ -346,8 +346,8 @@ final class HttpsURLConnectionImpl extends HttpsURLConnection {
     }
 
     @Override
-    public void setReadTimeout(int timeout) {
-        delegate.setReadTimeout(timeout);
+    public void setReadTimeout(int timeoutMillis) {
+        delegate.setReadTimeout(timeoutMillis);
     }
 
     @Override
diff --git a/luni/src/test/java/libcore/java/net/URLConnectionTest.java b/luni/src/test/java/libcore/java/net/URLConnectionTest.java
index 5d1c6fa..a37c126 100644
--- a/luni/src/test/java/libcore/java/net/URLConnectionTest.java
+++ b/luni/src/test/java/libcore/java/net/URLConnectionTest.java
@@ -34,6 +34,7 @@ import java.net.CacheResponse;
 import java.net.ConnectException;
 import java.net.HttpRetryException;
 import java.net.HttpURLConnection;
+import java.net.InetAddress;
 import java.net.PasswordAuthentication;
 import java.net.ProtocolException;
 import java.net.Proxy;
@@ -1396,6 +1397,11 @@ public final class URLConnectionTest extends TestCase {
         }
     }
 
+    /**
+     * Test that the timeout period is honored. The timeout may be doubled!
+     * HttpURLConnection will wait the full timeout for each of the server's IP
+     * addresses. This is typically one IPv4 address and one IPv6 address.
+     */
     public void testConnectTimeouts() throws IOException {
         StuckServer ss = new StuckServer();
         int serverPort = ss.getLocalPort();
@@ -1407,8 +1413,10 @@ public final class URLConnectionTest extends TestCase {
             urlConnection.getInputStream();
             fail();
         } catch (SocketTimeoutException expected) {
-            long actual = System.currentTimeMillis() - start;
-            assertTrue(Math.abs(timeout - actual) < 500);
+            long elapsed = System.currentTimeMillis() - start;
+            int attempts = InetAddress.getAllByName("localhost").length; // one per IP address
+            assertTrue("timeout=" +timeout + ", elapsed=" + elapsed + ", attempts=" + attempts,
+                    Math.abs((attempts * timeout) - elapsed) < 500);
         } finally {
             ss.close();
         }