[Cronet] Expose HttpURLConnection API from CronetEngine, not classes

components/cronet/android/java/src/org/chromium/net/CronetEngine.java

Index: components/cronet/android/java/src/org/chromium/net/CronetEngine.java
diff --git a/components/cronet/android/java/src/org/chromium/net/CronetEngine.java b/components/cronet/android/java/src/org/chromium/net/CronetEngine.java
index 2de7e8d001ef96e49d84d07f5305d474fdbcc03e..10f0a434afc09492368707c916de977f8695f4e3 100644
--- a/components/cronet/android/java/src/org/chromium/net/CronetEngine.java
+++ b/components/cronet/android/java/src/org/chromium/net/CronetEngine.java
@@ -13,6 +13,10 @@ import org.json.JSONObject;
 
 import java.io.File;
 import java.lang.reflect.Constructor;
+import java.net.Proxy;
+import java.net.URL;
+import java.net.URLConnection;
+import java.net.URLStreamHandlerFactory;
 import java.util.concurrent.Executor;
 
 /**
@@ -167,6 +171,8 @@ public abstract class CronetEngine {
          * proxy is allowed.
          * @return the builder to facilitate chaining.
          * @hide
+         * @deprecated Marked as deprecated because @hide doesn't properly hide but
+         *         javadocs are built with nodeprecated="yes".
          */
         public Builder setDataReductionProxyOptions(
                 String primaryProxy, String fallbackProxy, String secureProxyCheckUrl) {
@@ -517,6 +523,68 @@ public abstract class CronetEngine {
     public abstract void removeThroughputListener(NetworkQualityThroughputListener listener);
 
     /**
+     * Establishes a new connection to the resource specified by the {@link URL} {@code url}.
+     * <p>
+     * <b>Note:</b> Cronet's {@link java.net.HttpURLConnection} implementation is subject to certain
+     * limitations, see {@link #createURLStreamHandlerFactory} for details.
+     *
+     * @param url URL of resource to connect to.
+     * @return an {@link java.net.HttpURLConnection} instance implemented by this CronetEngine.
+     */
+    public abstract URLConnection openConnection(URL url);
+
+    /**
+     * Establishes a new connection to the resource specified by the {@link URL} {@code url}
+     * using the given proxy.
+     * <p>
+     * <b>Note:</b> Cronet's {@link java.net.HttpURLConnection} implementation is subject to certain
+     * limitations, see {@link #createURLStreamHandlerFactory} for details.
+     *
+     * @param url URL of resource to connect to.
+     * @param proxy proxy to use when establishing connection.
+     * @return an {@link java.net.HttpURLConnection} instance implemented by this CronetEngine.
+     * @hide
+     * @deprecated Marked as deprecated because @hide doesn't properly hide but
+     *         javadocs are built with nodeprecated="yes".
+     *         TODO(pauljensen): Expose once implemented, http://crbug.com/418111
+     */
+    public abstract URLConnection openConnection(URL url, Proxy proxy);
+
+    /**
+     * Creates a {@link URLStreamHandlerFactory} to handle HTTP and HTTPS
+     * traffic. An instance of this class can be installed via
+     * {@link java.net.URL#setURLStreamHandlerFactory} thus using this CronetEngine by default for

[xunjieli, 2015/10/08 14:17:56]

optional nit: Can use shorthand {@link URL#setURLStreamHandlerFactory} here and
on the next line.

[pauljensen, 2015/10/08 14:40:34]

Done.

+     * all requests created via {@link java.net.URL#openConnection}.
+     * <p>
+     * Cronet does not use certain HTTP features provided via the system:
+     * <ul>
+     * <li>the HTTP cache installed via
+     *     {@link android.net.http.HttpResponseCache#install(java.io.File, long)
+     *            HttpResponseCache.install()}</li>
+     * <li>the HTTP authentication method installed via
+     *     {@link java.net.Authenticator#setDefault}</li>
+     * <li>the HTTP cookie storage installed via {@link java.net.CookieHandler#setDefault}</li>
+     * </ul>
+     * <p>
+     * While Cronet supports and encourages requests using the HTTPS protocol,
+     * Cronet does not provide support for the
+     * {@link javax.net.ssl.HttpsURLConnection} API. This lack of support also
+     * includes not using certain HTTPS features provided via the system:
+     * <ul>
+     * <li>the HTTPS hostname verifier installed via {@link
+     *   javax.net.ssl.HttpsURLConnection#setDefaultHostnameVerifier(javax.net.ssl.HostnameVerifier)
+     *     HttpsURLConnection.setDefaultHostnameVerifier()}</li>
+     * <li>the HTTPS socket factory installed via {@link
+     *   javax.net.ssl.HttpsURLConnection#setDefaultSSLSocketFactory(javax.net.ssl.SSLSocketFactory)
+     *     HttpsURLConnection.setDefaultSSLSocketFactory()}</li>
+     * </ul>
+     *
+     * @return an {@link java.net.URLStreamHandlerFactory} instance implemented by this

[xunjieli, 2015/10/08 14:17:56]

optional nit: Since URLStreamHandlerFactory is imported, can use shorthand here
"{@link URLStreamHandlerFactory}". On line 554, the shorthand is used.

[pauljensen, 2015/10/08 14:40:34]

Done.

+     *         CronetEngine.
+     */
+    public abstract URLStreamHandlerFactory createURLStreamHandlerFactory();
+
+    /**
      * Creates a {@link CronetEngine} with the given {@link Builder}.
      * @param context Android {@link Context}.
      * @param config engine configuration.