[Cronet] Create Builders, rename UrlRequestContext to CronetEngine

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

Index: components/cronet/android/java/src/org/chromium/net/UrlRequest.java
diff --git a/components/cronet/android/java/src/org/chromium/net/UrlRequest.java b/components/cronet/android/java/src/org/chromium/net/UrlRequest.java
index 6a784c30dbe030b0032a877341523bf2d9830426..89d436d77eaefdca226b4b1ba47661dda5387e40 100644
--- a/components/cronet/android/java/src/org/chromium/net/UrlRequest.java
+++ b/components/cronet/android/java/src/org/chromium/net/UrlRequest.java
@@ -4,16 +4,162 @@
 
 package org.chromium.net;
 
+import android.util.Pair;
+
 import java.nio.ByteBuffer;
+import java.util.ArrayList;
 import java.util.concurrent.Executor;
 
 /**
  * Controls an HTTP request (GET, PUT, POST etc).
- * Created using {@link UrlRequestContext#createRequest UrlRequestContext.createRequest()}.
+ * Created using {@link CronetEngine#executeRequest CronetEngine.executeRequest()}.
  * Note: All methods must be called on the {@link Executor} passed in during creation.
  */
 public interface UrlRequest {
     /**
+     * Builder for {@link UrlRequest}s. Allows configuring requests before starting
+     * them via {@link CronetEngine#executeRequest}.
+     */
+    public static final class Builder {
+        // All fields are temporary storage of UrlRequest configuration to be
+        // copied to built UrlRequests.
+
+        // URL to request.
+        final String mUrl;
+        // Listener to receive progress callbacks.
+        final UrlRequestListener mListener;
+        // Executor to call listener on.
+        final Executor mExecutor;
+        // HTTP method (e.g. GET, POST etc).
+        String mMethod;
+        // List of request headers, stored as header field name and value pairs.
+        final ArrayList<Pair<String, String>> mRequestHeaders =
+                new ArrayList<Pair<String, String>>();
+        // Disable the cache for just this request.
+        boolean mDisableCache;

[mef, 2015/09/28 17:25:57]

should this have an explicit default?

[pauljensen, 2015/09/30 15:41:33]

Java initializes boolean's to false.  I think that should be enough, but I don't
feel strongly.  Do you think I should explicitly add " = false"?

+        // Priority of request.
+        int mPriority = REQUEST_PRIORITY_MEDIUM;
+        // If request is an upload, this provides the request body data.
+        UploadDataProvider mUploadDataProvider;
+        // Executor to call upload data provider back on.
+        Executor mUploadDataProviderExecutor;
+
+        /**
+         * Creates a builder for {@link UrlRequest} objects. All callbacks for
+         * generated {@link UrlRequest} objects 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 generated requests.
+         * @param listener callback class that gets called on different events.
+         * @param executor {@link Executor} on which all callbacks will be called.
+         */
+        public Builder(String url, UrlRequestListener listener, Executor executor) {

[mef, 2015/09/28 17:25:57]

given that all arguments are required, should we add null checks and throw
NullPointerException if they are not specified?

[pauljensen, 2015/09/30 15:41:33]

Done.

+            mUrl = url;
+            mListener = listener;
+            mExecutor = executor;
+        }
+
+        /**
+         * Sets the HTTP method verb to use for this request.
+         *
+         * <p>The default when this method is not called is "GET" if the request has
+         * no body or "POST" if it does.
+         *
+         * @param method "GET", "HEAD", "DELETE", "POST" or "PUT".
+         */
+        public void setHttpMethod(String method) {
+            if (method == null) {
+                throw new NullPointerException("Method is required.");
+            }
+            mMethod = method;
+        }
+
+        /**
+         * Adds a request header.
+         *
+         * @param header header name.
+         * @param value header value.
+         */
+        public void addHeader(String header, String value) {
+            if (header == null) {
+                throw new NullPointerException("Invalid header name.");
+            }
+            if (value == null) {
+                throw new NullPointerException("Invalid header value.");
+            }
+            mRequestHeaders.add(Pair.create(header, value));
+        }
+
+        /**
+         * Disables cache for the request. If context is not set up to use cache,
+         * this call has no effect.
+         */
+        public void disableCache() {
+            mDisableCache = true;
+        }
+
+        /**
+         * Lowest request priority. Passed to {@link #setPriority}.
+         */
+        public static final int REQUEST_PRIORITY_IDLE = 0;
+        /**
+         * Very low request priority. Passed to {@link #setPriority}.
+         */
+        public static final int REQUEST_PRIORITY_LOWEST = 1;
+        /**
+         * Low request priority. Passed to {@link #setPriority}.
+         */
+        public static final int REQUEST_PRIORITY_LOW = 2;
+        /**
+         * Medium request priority. Passed to {@link #setPriority}.
+         */
+        public static final int REQUEST_PRIORITY_MEDIUM = 3;
+        /**
+         * Highest request priority. Passed to {@link #setPriority}.
+         */
+        public static final int REQUEST_PRIORITY_HIGHEST = 4;
+
+        /**
+         * Sets priority of the request which should be one of the
+         * {@link #REQUEST_PRIORITY_IDLE REQUEST_PRIORITY_*} values.
+         * Defaults to {@link #REQUEST_PRIORITY_MEDIUM}
+         *
+         * @param priority priority of the request which should be one of the
+         *         {@link #REQUEST_PRIORITY_IDLE REQUEST_PRIORITY_*} values.
+         */
+        public void setPriority(int priority) {
+            mPriority = priority;
+        }
+
+        /**
+         * Sets upload data provider. Switches method to "POST" if not
+         * explicitly set. Starting the request will throw an exception if a
+         * Content-Type header is not set.
+         *
+         * @param uploadDataProvider responsible for providing the upload data.
+         * @param executor All {@code uploadDataProvider} methods will be called
+         *     using this {@code Executor}. May optionally be the same
+         *     {@code Executor} the request itself is using.
+         */
+        public void setUploadDataProvider(
+                UploadDataProvider uploadDataProvider, Executor executor) {
+            if (uploadDataProvider == null) {
+                throw new NullPointerException("Invalid UploadDataProvider.");
+            }
+            if (executor == null) {
+                throw new NullPointerException("Invalid UploadDataProvider Executor.");
+            }
+            if (mMethod == null) {
+                mMethod = "POST";
+            }
+            mUploadDataProvider = uploadDataProvider;
+            mUploadDataProviderExecutor = executor;
+        }
+    }
+
+    /**
      * Request status values returned by {@link #getStatus}.
      */
     public static class Status {
@@ -196,36 +342,6 @@ public interface UrlRequest {
     }
 
     /**
-     * Lowest request priority. Passed to {@link UrlRequestContext#createRequest(String,
-     * UrlRequestListener, Executor, int) UrlRequestContext.createRequest()}.
-     */
-    public static final int REQUEST_PRIORITY_IDLE = 0;
-    /**
-     * Very low request priority. Passed to {@link UrlRequestContext#createRequest(String,
-     * UrlRequestListener, Executor, int) UrlRequestContext.createRequest()}.
-     */
-    public static final int REQUEST_PRIORITY_LOWEST = 1;
-    /**
-     * Low request priority. Passed to {@link UrlRequestContext#createRequest(String,
-     * UrlRequestListener, Executor, int) UrlRequestContext.createRequest()}.
-     */
-    public static final int REQUEST_PRIORITY_LOW = 2;
-    /**
-     * Medium request priority. Passed to {@link UrlRequestContext#createRequest(String,
-     * UrlRequestListener, Executor, int) UrlRequestContext.createRequest()}.
-     */
-    public static final int REQUEST_PRIORITY_MEDIUM = 3;
-    /**
-     * Highest request priority. Passed to {@link UrlRequestContext#createRequest(String,
-     * UrlRequestListener, Executor, int) UrlRequestContext.createRequest()}.
-     */
-    public static final int REQUEST_PRIORITY_HIGHEST = 4;
-
-    // More setters go here. They may only be called before start (Maybe
-    // also allow during redirects). Could optionally instead use arguments
-    // to URLRequestFactory when creating the request.
-
-    /**
      * Sets the HTTP method verb to use for this request. Must be done before
      * request has started.
      *
@@ -233,16 +349,18 @@ public interface UrlRequest {
      * no body or "POST" if it does.
      *
      * @param method "GET", "HEAD", "DELETE", "POST" or "PUT".
+     * @deprecated Use {@link Builder#setHttpMethod}.
      */
-    public void setHttpMethod(String method);
+    @Deprecated public void setHttpMethod(String method);
 
     /**
      * Adds a request header. Must be done before request has started.
      *
      * @param header header name.
      * @param value header value.
+     * @deprecated Use {@link Builder#setPriority}.
      */
-    public void addHeader(String header, String value);
+    @Deprecated public void addHeader(String header, String value);
 
     /**
      * Sets upload data provider. Must be done before request has started. May only be
@@ -254,14 +372,17 @@ public interface UrlRequest {
      * @param executor All {@code uploadDataProvider} methods will be called
      *     using this {@code Executor}. May optionally be the same
      *     {@code Executor} the request itself is using.
+     * @deprecated Use {@link Builder#setUploadDataProvider}.
      */
+    @Deprecated
     public void setUploadDataProvider(UploadDataProvider uploadDataProvider, Executor executor);
 
     /**
      * Starts the request, all callbacks go to listener. May only be called
      * once. May not be called if {@link #cancel} has been called.
+     * @deprecated Use {@link CronetEngine#executeRequest}.
      */
-    public void start();
+    @Deprecated public void start();
 
     /**
      * Follows a pending redirect. Must only be called at most once for each
@@ -346,8 +467,9 @@ public interface UrlRequest {
     /**
      * Disables cache for the request. If context is not set up to use cache,
      * this call has no effect.
+     * @deprecated Use {@link Builder#disableCache}.
      */
-    public void disableCache();
+    @Deprecated public void disableCache();
 
     /**
      * Queries the status of the request.