[Cronet] Create Builders, rename UrlRequestContext to CronetEngine

components/cronet/README.md

 # Quick Start Guide to Using Cronet
 Cronet is the networking stack of Chromium put into a library for use on
 mobile. This is the same networking stack that is used in the Chrome browser
 by over a billion people. It offers an easy-to-use, high performance,
 standards-compliant, and secure way to perform HTTP requests. Cronet has support
 for both Android and iOS. On Android, Cronet offers its own Java asynchronous
 API as well as support for the [java.net.HttpURLConnection] API.
 This document gives a brief introduction to using these two Java APIs.
 
 ### Basics
@@ skipping 50 matching lines @@
                 ResponseInfo responseInfo, UrlRequestException error) {
              // Request has failed. responseInfo might be null.
              Log.e("MyListener", "Request failed. " + error.getMessage());
              // Maybe handle error here. Typical errors include hostname
              // not resolved, connection to server refused, etc.
         }
     }
 
 Make a request like this:
 
-    UrlRequestContextConfig myConfig = new UrlRequestContextConfig();
-    CronetUrlRequestContext myRequestContext =
-            new CronetUrlRequestContext(getContext(), myConfig);
+    CronetEngine.Builder engineBuilder = new CronetEngine.Builder();
+    CronetEngine engine = engineBuilder.build(getContext());

[xunjieli, 2015/09/28 14:57:05]

I usually see build method with 0 argument. Should we move the app context
parameter to the builder's constructor or use a setter?

[mef, 2015/09/28 16:31:38]

My concern with having setter is that it is not apparent that it must be set. I
have no problem with passing it to builder's constructor.

     Executor executor = Executors.newSingleThreadExecutor();
     MyListener listener = new MyListener();
-    UrlRequest request = myRequestContext.createRequest(
+    UrlRequest.Builder requestBuilder = new UrlRequest.Builder(
             "https://www.example.com", listener, executor);

[xunjieli, 2015/09/28 14:57:05]

Why doesn't the UrlRequest.Builder have a build method? It seems unintuitive
that we have a builder but don't build it.

I would expect executeRequest takes in a request or requestBuilder.build():

UrlRequest.Builder requestBuilder = new UrlRequest.Builder();
UrlRequest request = requestBuilder.build();
engine.executeRequest(request);

[mef, 2015/09/28 16:31:38]

I see your point, but what would somebody do with built, but not executing
request?

[mef, 2015/09/28 17:13:37]

I take it back. Looking at
http://cr.openjdk.java.net/~michaelm/httpclient.old/CCCv1.1/javadoc/ it seems to
make sense to separate building from execution.

-    request.start();
+    UrlRequest request = engine.executeRequest(requestBuilder);
 
 In the above example, `MyListener` extends `UrlRequestListener`. The request
 is started asynchronously. When the response is ready (fully or partially), and
 in the event of failures or redirects, `listener`'s methods will be invoked on
 `executor`'s thread to inform the client of the request state and/or response
 information.
 
 ### Downloading Data
 When Cronet fetches response headers from the server or gets them from the
 cache, `UrlRequestListener.onResponseStarted` will be invoked. To read the
 response body, the client should call `UrlRequest.read` and supply a
 [ByteBuffer] for Cronet to fill. Once a portion or all of
 the response body is read, `UrlRequestListener.onReadCompleted` will be invoked.
 The client may then read and consume the data within `byteBuffer`.
 Once the client is ready to consume more data, the client should call
 `UrlRequest.read` again. The process continues until
 `UrlRequestListener.onSucceeded` or `UrlRequestListener.onFailed` is invoked,
 which signals the completion of the request.
 
 ### Uploading Data
     MyUploadDataProvider myUploadDataProvider = new MyUploadDataProvider();
-    request.setHttpMethod("POST");
-    request.setUploadDataProvider(myUploadDataProvider, executor);
-    request.start();
+    requestBuilder.setHttpMethod("POST");
+    requestBuilder.setUploadDataProvider(myUploadDataProvider, executor);
 
 In the above example, `MyUploadDataProvider` extends `UploadDataProvider`.
 When Cronet is ready to send the request body,
 `myUploadDataProvider.read(UploadDataSink uploadDataSink,
 ByteBuffer byteBuffer)` will be invoked. The client will need to write the
 request body into `byteBuffer`. Once the client is done writing into
 `byteBuffer`, the client can let Cronet know by calling
 `uploadDataSink.onReadSucceeded`. If the request body doesn't fit into
 `byteBuffer`, the client can continue writing when `UploadDataProvider.read` is
 invoked again. For more details, please see the API reference.
 
 ### <a id=configuring-cronet></a> Configuring Cronet
-Various configuration options are available via the `UrlRequestContextConfig`
+Various configuration options are available via the `CronetEngine.Builder`
 object.
 
 Enabling HTTP/2, QUIC, or SDCH:
 
 - For Example:
 
-        myConfig.enableSPDY(true).enableQUIC(true).enableSDCH(true);
+        engineBuilder.enableSPDY(true).enableQUIC(true).enableSDCH(true);
 
 Controlling the cache:
 
 - Use a 100KiB in-memory cache:
 
-        myConfig.enableHttpCache(
-                UrlRequestContextConfig.HttpCache.IN_MEMORY, 100 * 1024);
+        engineBuilder.enableHttpCache(
+                CronetEngine.Builder.HttpCache.IN_MEMORY, 100 * 1024);
 
 - or use a 1MiB disk cache:
 
-        myConfig.setStoragePath(storagePathString);
-        myConfig.enableHttpCache(UrlRequestContextConfig.HttpCache.DISK,
+        engineBuilder.setStoragePath(storagePathString);
+        engineBuilder.enableHttpCache(CronetEngine.Builder.HttpCache.DISK,
                 1024 * 1024);
 
 ### Debugging
 To get more information about how Cronet is processing network
 requests, you can start and stop **NetLog** logging by calling
-`UrlRequestContext.startNetLogToFile` and `UrlRequestContext.stopNetLog`.
+`CronetEngine.startNetLogToFile` and `CronetEngine.stopNetLog`.
 Bear in mind that logs may contain sensitive data. You may analyze the
 generated log by navigating to [chrome://net-internals#import] using a
 Chrome browser.
 
 # Using the java.net.HttpURLConnection API
 Cronet offers an implementation of the [java.net.HttpURLConnection] API to make
 it easier for apps which rely on this API to use Cronet.
 To use Cronet's implementation instead of the system's default implementation,
 simply do the following:
 
     CronetURLStreamHandlerFactory streamHandlerFactory =
-            new CronetURLStreamHandlerFactory(getContext(), myConfig);
+            new CronetURLStreamHandlerFactory(getContext(), engineBuilder);
     URL.setURLStreamHandlerFactory(streamHandlerFactory);
 
 Cronet's
 HttpURLConnection implementation has some limitations as compared to the system
 implementation, including not utilizing the default system HTTP cache (Please
 see {@link org.chromium.net.urlconnection.CronetURLStreamHandlerFactory} for
 more information).
 You can configure Cronet and control caching through the
-`UrlRequestContextConfig` instance, `myConfig`
+`CronetEngine.Builder` instance, `engineBuilder`
 (See [Configuring Cronet](#configuring-cronet) section), before you pass it
 into the `CronetURLStreamHandlerFactory` constructor.
 
 [ByteBuffer]: https://developer.android.com/reference/java/nio/ByteBuffer.html
 [chrome://net-internals#import]: chrome://net-internals#import
 [java.net.HttpURLConnection]: https://developer.android.com/reference/java/net/HttpURLConnection.html