[Cronet] Add error code and immediatelyRetryable() to UrlRequestException

components/cronet/android/api/src/org/chromium/net/UrlRequestException.java

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 package org.chromium.net;
 
 import java.io.IOException;
 
 /**
- * Exception after UrlRequest start. Could be reported by network stack, in
- * which case netError() will contain native error code.
+ * Exception passed to {@link UrlRequest.Callback#onFailed UrlRequest.Callback.onFailed()} when:
+ * <ul>
+ * <li>{@link UrlRequest.Callback} or {@link UploadDataProvider} method throws an exception. In this
+ *     case {@link IOException#getCause getCause()} can be used to find the thrown exception.
+ *     {@link #getErrorCode} will return {@link #ERROR_LISTENER_EXCEPTION_THROWN}.
+ * <li>Cronet fails to process a network request. In this case
+ *     {@link #getErrorCode} and {@link #getCronetInternalErrorCode} can be used to get more
+ *     information about the specific type of failure.
+ * </ul>
  */
 public class UrlRequestException extends IOException {
-    /** Net error code if exception is reported by native. */
-    final int mNetError;
+    /**
+     * Error code indicating this class wraps an exception thrown by {@link UrlRequest.Callback} or
+     * {@link UploadDataProvider}. Wrapped exception can be retrieved using
+     * {@link IOException#getCause}.
+     */
+    public static final int ERROR_LISTENER_EXCEPTION_THROWN = 0;
+    /**
+     * Error code indicating the host being sent the request could not be resolved to an IP address.
+     */
+    public static final int ERROR_HOSTNAME_NOT_RESOLVED = 1;
+    /**
+     * Error code indicating the device was not connected to any network.
+     */
+    public static final int ERROR_INTERNET_DISCONNECTED = 2;
+    /**
+     * Error code indicating that as the request was processed the network configuration changed.
+     */
+    public static final int ERROR_NETWORK_CHANGED = 3;
+    /**
+     * Error code indicating a timeout expired. Timeouts expiring while attempting to connect will
+     * be reported as the more specific {@link #ERROR_CONNECTION_TIMED_OUT}.
+     */
+    public static final int ERROR_TIMED_OUT = 4;
+    /**
+     * Error code indicating the connection was closed unexpectedly.
+     */
+    public static final int ERROR_CONNECTION_CLOSED = 5;
+    /**
+     * Error code indicating the connection attempt timed out.
+     */
+    public static final int ERROR_CONNECTION_TIMED_OUT = 6;
+    /**
+     * Error code indicating the connection attempt was refused.
+     */
+    public static final int ERROR_CONNECTION_REFUSED = 7;
+    /**
+     * Error code indicating the connection was unexpectedly reset.
+     */
+    public static final int ERROR_CONNECTION_RESET = 8;
+    /**
+     * Error code indicating the IP address being contacted is unreachable, meaning there is no
+     * route to the specified host or network.
+     */
+    public static final int ERROR_ADDRESS_UNREACHABLE = 9;
+    /**
+     * Error code indicating another type of error was encountered.
+     * {@link #getCronetInternalErrorCode} can be consulted to get a more specific cause.
+     */
+    public static final int ERROR_OTHER = 10;
 
-    UrlRequestException(String message, Throwable cause) {
-        super(message, cause);
-        mNetError = 0;
+    // Error code, one of ERROR_*
+    private final int mErrorCode;
+    // Cronet internal error code.
+    private final int mCronetInternalErrorCode;
+
+    /**
+     * Constructs an exception with a specific error.
+     *
+     * @param message explanation of failure.
+     * @param errorCode error code, one of {@link #ERROR_LISTENER_EXCEPTION_THROWN ERROR_*}.
+     * @param cronetInternalErrorCode Cronet internal error code, one of
+     * <a href=https://chromium.googlesource.com/chromium/src/+/master/net/base/net_error_list.h>
+     * these</a>.
+     */
+    public UrlRequestException(String message, int errorCode, int cronetInternalErrorCode) {
+        super(message, null);
+        // ERROR_* values cannot be directly initialized to UrlRequestError values because javadoc
+        // generation will fail because it is not passed the generated java constants.

[xunjieli, 2016/01/25 14:37:02]

Are we able to pass the generated java file to javadoc generator?  This
conversion seems an unnecessary step. (I looked up UrlRequest.Status, and that
is a subset of net::LoadState. But here these two sets are completely the same).

[pauljensen, 2016/02/02 18:45:45]

Done.

+        switch (errorCode) {
+            case UrlRequestError.LISTENER_EXCEPTION_THROWN:
+                mErrorCode = ERROR_LISTENER_EXCEPTION_THROWN;
+                break;
+            case UrlRequestError.HOSTNAME_NOT_RESOLVED:
+                mErrorCode = ERROR_HOSTNAME_NOT_RESOLVED;
+                break;
+            case UrlRequestError.INTERNET_DISCONNECTED:
+                mErrorCode = ERROR_INTERNET_DISCONNECTED;
+                break;
+            case UrlRequestError.NETWORK_CHANGED:
+                mErrorCode = ERROR_NETWORK_CHANGED;
+                break;
+            case UrlRequestError.TIMED_OUT:
+                mErrorCode = ERROR_TIMED_OUT;
+                break;
+            case UrlRequestError.CONNECTION_CLOSED:
+                mErrorCode = ERROR_CONNECTION_CLOSED;
+                break;
+            case UrlRequestError.CONNECTION_TIMED_OUT:
+                mErrorCode = ERROR_CONNECTION_TIMED_OUT;
+                break;
+            case UrlRequestError.CONNECTION_REFUSED:
+                mErrorCode = ERROR_CONNECTION_REFUSED;
+                break;
+            case UrlRequestError.CONNECTION_RESET:
+                mErrorCode = ERROR_CONNECTION_RESET;
+                break;
+            case UrlRequestError.ADDRESS_UNREACHABLE:
+                mErrorCode = ERROR_ADDRESS_UNREACHABLE;
+                break;
+            case UrlRequestError.OTHER:
+                mErrorCode = ERROR_OTHER;
+                break;
+            default:
+                throw new IllegalArgumentException("Unknown error code " + errorCode);
+        }
+        mCronetInternalErrorCode = cronetInternalErrorCode;
     }
 
-    UrlRequestException(String message, int netError) {
-        super(message, null);
-        mNetError = netError;
+    /**
+     * Constructs an exception that wraps {@code cause} thrown by a {@link UrlRequest.Callback}.
+     *
+     * @param message explanation of failure.
+     * @param cause exception thrown by {@link UrlRequest.Callback} that's being wrapped.
+     */
+    public UrlRequestException(String message, Throwable cause) {
+        super(message, cause);
+        mErrorCode = ERROR_LISTENER_EXCEPTION_THROWN;
+        mCronetInternalErrorCode = 0;
     }
 
-    /** @return Error code if exception is reported by native. */
-    public int netError() {
-        return mNetError;
+    /**
+     * Returns error code, one of {@link #ERROR_LISTENER_EXCEPTION_THROWN ERROR_*}.
+     *
+     * @return error code, one of {@link #ERROR_LISTENER_EXCEPTION_THROWN ERROR_*}.
+     */
+    public int getErrorCode() {
+        return mErrorCode;
+    }
+
+    /**
+     * Returns a Cronet internal error code. This may provide more specific error
+     * diagnosis than {@link #getErrorCode}, but the constant values are not exposed to Java and
+     * may change over time. See
+     * <a href=https://chromium.googlesource.com/chromium/src/+/master/net/base/net_error_list.h>
+     * here</a> for the lastest list of values.
+     *
+     * @return Cronet internal error code.
+     */
+    public int getCronetInternalErrorCode() {
+        return mCronetInternalErrorCode;
+    }
+
+    /**
+     * Returns {@code true} if retrying this request right away might succeed, {@code false}
+     * otherwise. For example returns {@code true} when {@link #getErrorCode} returns
+     * {@link #ERROR_NETWORK_CHANGED} because trying the request might succeed using the new
+     * network configuration, but {@code false} when {@code getErrorCode()} returns
+     * {@link #ERROR_INTERNET_DISCONNECTED} because retrying the request right away will
+     * encounter the same failure (instead retrying should be delayed until device regains
+     * network connectivity). Returns {@code false} when {@code getErrorCode()} returns
+     * {@link #ERROR_LISTENER_EXCEPTION_THROWN}.
+     *
+     * @return {@code true} if retrying this request right away might succeed, {@code false}
+     *         otherwise.
+     */
+    public boolean immediatelyRetryable() {
+        switch (mErrorCode) {
+            case ERROR_LISTENER_EXCEPTION_THROWN:
+            case ERROR_HOSTNAME_NOT_RESOLVED:
+            case ERROR_INTERNET_DISCONNECTED:
+            case ERROR_CONNECTION_REFUSED:
+            case ERROR_ADDRESS_UNREACHABLE:
+            case ERROR_OTHER:
+            default:
+                return false;
+            case ERROR_NETWORK_CHANGED:
+            case ERROR_TIMED_OUT:
+            case ERROR_CONNECTION_CLOSED:
+            case ERROR_CONNECTION_TIMED_OUT:
+            case ERROR_CONNECTION_RESET:
+                return true;
+        }
     }
 }