[Cronet] Expose HttpURLConnection API from CronetEngine, not classes

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

 // Copyright 2015 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 android.content.Context;
 import android.util.Log;
 
 import org.json.JSONArray;
 import org.json.JSONException;
 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;
 
 /**
  * An engine to process {@link UrlRequest}s, which uses the best HTTP stack
  * available on the current platform.
  */
 public abstract class CronetEngine {
     /**
      * A builder for {@link CronetEngine}s, which allows runtime configuration of
      * {@code CronetEngine}. Configuration options are set on the builder and
@@ skipping 134 matching lines @@
          * <a href="https://developer.chrome.com/multidevice/data-compression">
          * Data Reduction Proxy</a> configuration parameters with a primary
          * proxy name, fallback proxy name, and a secure proxy check URL. Proxies
          * are specified as [scheme://]host[:port]. Used for testing.
          * @param primaryProxy the primary data reduction proxy to use.
          * @param fallbackProxy a fallback data reduction proxy to use.
          * @param secureProxyCheckUrl a URL to fetch to determine if using a secure
          * 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) {
             if (primaryProxy.isEmpty() || fallbackProxy.isEmpty()
                     || secureProxyCheckUrl.isEmpty()) {
                 throw new IllegalArgumentException(
                         "Primary and fallback proxies and check url must be set");
             }
             putString(CronetEngineBuilderList.DATA_REDUCTION_PRIMARY_PROXY, primaryProxy);
             putString(CronetEngineBuilderList.DATA_REDUCTION_FALLBACK_PROXY, fallbackProxy);
@@ skipping 254 matching lines @@
      */
     public abstract void startNetLogToFile(String fileName, boolean logAll);
 
     /**
      * Stops NetLog logging and flushes file to disk. If a logging session is
      * not in progress, this call is ignored.
      */
     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.
      * @deprecated Use {@link CronetEngine.Builder}.
      */
     @Deprecated
     public static CronetEngine createContext(Builder config) {
         CronetEngine cronetEngine = null;
         if (config.userAgent().isEmpty()) {
             config.setUserAgent(UserAgent.from(config.getContext()));
@@ skipping 24 matching lines @@
                 cronetEngine = possibleEngine;
             }
         } catch (ClassNotFoundException e) {
             // Leave as null.
         } catch (Exception e) {
             throw new IllegalStateException("Cannot instantiate: " + CRONET_URL_REQUEST_CONTEXT, e);
         }
         return cronetEngine;
     }
 }