[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".
          */
         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 184 matching lines @@
 
     /**
      * Creates a {@link UrlRequest} object. All callbacks will
      * be called on {@code executor}'s thread. {@code executor} must not run
      * tasks on the current thread to prevent blocking networking operations
      * and causing exceptions during shutdown. Request is given medium priority,
      * see {@link UrlRequest#REQUEST_PRIORITY_MEDIUM}. To specify other
      * priorities see {@link #createRequest(String, UrlRequestListener,
      * Executor, int priority)}.
      *
-     * @param url {@link java.net.URL} for the request.
+     * @param url {@link URL} for the request.
      * @param listener callback class that gets called on different events.
      * @param executor {@link Executor} on which all callbacks will be called.
      * @return new request.
      * @deprecated Use {@link Builder#build}.
      */
     @Deprecated
     public abstract UrlRequest createRequest(
             String url, UrlRequestListener listener, Executor executor);
 
     /**
      * Creates a {@link UrlRequest} object. All callbacks will
      * be called on {@code executor}'s thread. {@code executor} must not run
      * tasks on the current thread to prevent blocking networking operations
      * and causing exceptions during shutdown.
      *
-     * @param url {@link java.net.URL} for the request.
+     * @param url {@link URL} for the request.
      * @param listener callback class that gets called on different events.
      * @param executor {@link Executor} on which all callbacks will be called.
      * @param priority priority of the request which should be one of the
      *         {@link UrlRequest#REQUEST_PRIORITY_IDLE REQUEST_PRIORITY_*}
      *         values.
      * @return new request.
      * @deprecated Use {@link Builder#build}.
      */
     @Deprecated
     public abstract UrlRequest createRequest(
@@ skipping 109 matching lines @@
      * Removes a listener of throughput. This should be called after a
      * {@link NetworkQualityThroughputListener} is added with
      * {@link #addThroughputListener} in order to stop receiving observations.
      * @param listener the listener of throughput.
      * @deprecated not really deprecated but hidden for now as it's a prototype.
      */
     @Deprecated
     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 URL#setURLStreamHandlerFactory} thus using this CronetEngine by default for
+     * all requests created via {@link 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 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;
     }
 }