[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 b338775fdcba74a4f0e707f2d51182726421d1b7..14c01d78426e389190932623a6568d8b4d55578f 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".

[xunjieli, 2015/10/02 15:49:06]

This is a little hacky to use @deprecated to hide the javadoc. I wonder whether
we can make use of Doclava (https://code.google.com/p/doclava/), which is used
to generate the android references. It works with ant as well. It has an
internal site.

I don't think it'll be straight-forward. Maybe we can make it work?

[pauljensen, 2015/10/02 23:39:43]

I looked into doclava before uploading this CL (see note in commit description).
 I don't think it'll be trivial to add (it's not small and I couldn't seem to
find a pre-existing copy in the Chromium repository) so I'd say do this in
another CL.  Perhaps after we finish the API work.

          */
         public Builder setDataReductionProxyOptions(
                 String primaryProxy, String fallbackProxy, String secureProxyCheckUrl) {
@@ -441,6 +447,64 @@ public abstract class CronetEngine {
     public abstract void stopNetLog();
 
     /**
+     * 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.
+     */
+    public abstract URLConnection openConnection(URL url, Proxy proxy);

[xunjieli, 2015/10/02 15:49:06]

Maybe add in the javadoc that this method is not implemented, and optionally a
link to the crbug.com/418111

[pauljensen, 2015/10/02 23:39:43]

I hid it like I did setDataReductionProxyOptions() as there's no point in
exposing an API that isn't implemented.  I also added a note to expose once
implemented with bug link.

+
+    /**
+     * 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
+     * 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
+     *         CronetEngine.
+     */
+    public abstract URLStreamHandlerFactory createURLStreamHandlerFactory();
+
+    /**
      * Creates a {@link CronetEngine} with the given {@link Builder}.
      * @param context Android {@link Context}.
      * @param config engine configuration.