components/cronet/getting_started.md - chromium/src - Git at Google

 # Quick Start Guide to Using Cronet
 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.

 ## Using Cronet's Java asynchronous API
 First you will need to extend `UrlRequest.Callback` to handle
 events during the lifetime of a request. For example:

     class MyCallback extends UrlRequest.Callback {
         @Override
         public void onRedirectReceived(UrlRequest request,
                 UrlResponseInfo responseInfo, String newLocationUrl) {
             if (followRedirect) {
                 // Let's tell Cronet to follow the redirect!
                 request.followRedirect();
             } else {
                 // Not worth following the redirect? Abandon the request.
                 request.cancel();
             }
         }

         @Override
         public void onResponseStarted(UrlRequest request,
                 UrlResponseInfo responseInfo) {
              // Now we have response headers!
              int httpStatusCode = responseInfo.getHttpStatusCode();
              if (httpStatusCode == 200) {
                  // Success! Let's tell Cronet to read the response body.
                  request.read(myBuffer);
              } else if (httpStatusCode == 503) {
                  // Do something. Note that 4XX and 5XX are not considered
                  // errors from Cronet's perspective since the response is
                  // successfully read.
              }
              mResponseHeaders = responseInfo.getAllHeaders();
         }

         @Override
         public void onReadCompleted(UrlRequest request,
                 UrlResponseInfo responseInfo, ByteBuffer byteBuffer) {
              // Response body is available.
              doSomethingWithResponseData(byteBuffer);
              // Let's tell Cronet to continue reading the response body or
              // inform us that the response is complete!
              request.read(mBuffer);
         }

         @Override
         public void onSucceeded(UrlRequest request,
                 UrlResponseInfo responseInfo) {
              // Request has completed successfully!
         }

         @Override
         public void onFailed(UrlRequest request,
                 UrlResponseInfo responseInfo, CronetException error) {
              // Request has failed. responseInfo might be null.
              Log.e("MyCallback", "Request failed. " + error.getMessage());
              // Maybe handle error here. Typical errors include hostname
              // not resolved, connection to server refused, etc.
         }
     }

 Make a request like this:

     CronetEngine.Builder engineBuilder = new CronetEngine.Builder(getContext());
     CronetEngine engine = engineBuilder.build();
     Executor executor = Executors.newSingleThreadExecutor();
     MyCallback callback = new MyCallback();
     UrlRequest.Builder requestBuilder = engine.newUrlRequestBuilder(
             "https://www.example.com", callback, executor);
     UrlRequest request = requestBuilder.build();
     request.start();

 In the above example, `MyCallback` extends `UrlRequest.Callback`. The request
 is started asynchronously. When the response is ready (fully or partially), and
 in the event of failures or redirects, `callback`'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, `UrlRequest.Callback.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, `UrlRequest.Callback.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
 `UrlRequest.Callback.onSucceeded` or `UrlRequest.Callback.onFailed` is invoked,
 which signals the completion of the request.

 ### Uploading Data
     MyUploadDataProvider myUploadDataProvider = new MyUploadDataProvider();
     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 `CronetEngine.Builder`
 object.

 Enabling HTTP/2 and QUIC:

 - For Example:

         engineBuilder.enableHttp2(true).enableQuic(true);

 Controlling the cache:

 - Use a 100KiB in-memory cache:

         engineBuilder.enableHttpCache(
                 CronetEngine.Builder.HttpCache.IN_MEMORY, 100 * 1024);

 - or use a 1MiB disk cache:

         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
 `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 open individual connections using Cronet's implementation, do the following:

     HttpURLConnection connection =
             (HttpURLConnection)engine.openConnection(url);

 To use Cronet's implementation instead of the system's default implementation
 for all connections established using `URL.openConnection()` do the following:

     URL.setURLStreamHandlerFactory(engine.createURLStreamHandlerFactory());

 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.CronetEngine#createURLStreamHandlerFactory} for
 more information).
 You can configure Cronet and control caching through the
 `CronetEngine.Builder` instance, `engineBuilder`
 (See [Configuring Cronet](#configuring-cronet) section), before you build the
 `CronetEngine` and then call `CronetEngine.createURLStreamHandlerFactory()`.

 [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
	# Quick Start Guide to Using Cronet
	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.

	## Using Cronet's Java asynchronous API
	First you will need to extend `UrlRequest.Callback` to handle
	events during the lifetime of a request. For example:

	class MyCallback extends UrlRequest.Callback {
	@Override
	public void onRedirectReceived(UrlRequest request,
	UrlResponseInfo responseInfo, String newLocationUrl) {
	if (followRedirect) {
	// Let's tell Cronet to follow the redirect!
	request.followRedirect();
	} else {
	// Not worth following the redirect? Abandon the request.
	request.cancel();
	}
	}

	@Override
	public void onResponseStarted(UrlRequest request,
	UrlResponseInfo responseInfo) {
	// Now we have response headers!
	int httpStatusCode = responseInfo.getHttpStatusCode();
	if (httpStatusCode == 200) {
	// Success! Let's tell Cronet to read the response body.
	request.read(myBuffer);
	} else if (httpStatusCode == 503) {
	// Do something. Note that 4XX and 5XX are not considered
	// errors from Cronet's perspective since the response is
	// successfully read.
	}
	mResponseHeaders = responseInfo.getAllHeaders();
	}

	@Override
	public void onReadCompleted(UrlRequest request,
	UrlResponseInfo responseInfo, ByteBuffer byteBuffer) {
	// Response body is available.
	doSomethingWithResponseData(byteBuffer);
	// Let's tell Cronet to continue reading the response body or
	// inform us that the response is complete!
	request.read(mBuffer);
	}

	@Override
	public void onSucceeded(UrlRequest request,
	UrlResponseInfo responseInfo) {
	// Request has completed successfully!
	}

	@Override
	public void onFailed(UrlRequest request,
	UrlResponseInfo responseInfo, CronetException error) {
	// Request has failed. responseInfo might be null.
	Log.e("MyCallback", "Request failed. " + error.getMessage());
	// Maybe handle error here. Typical errors include hostname
	// not resolved, connection to server refused, etc.
	}
	}

	Make a request like this:

	CronetEngine.Builder engineBuilder = new CronetEngine.Builder(getContext());
	CronetEngine engine = engineBuilder.build();
	Executor executor = Executors.newSingleThreadExecutor();
	MyCallback callback = new MyCallback();
	UrlRequest.Builder requestBuilder = engine.newUrlRequestBuilder(
	"https://www.example.com", callback, executor);
	UrlRequest request = requestBuilder.build();
	request.start();

	In the above example, `MyCallback` extends `UrlRequest.Callback`. The request
	is started asynchronously. When the response is ready (fully or partially), and
	in the event of failures or redirects, `callback`'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, `UrlRequest.Callback.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, `UrlRequest.Callback.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
	`UrlRequest.Callback.onSucceeded` or `UrlRequest.Callback.onFailed` is invoked,
	which signals the completion of the request.

	### Uploading Data
	MyUploadDataProvider myUploadDataProvider = new MyUploadDataProvider();
	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 `CronetEngine.Builder`
	object.

	Enabling HTTP/2 and QUIC:

	- For Example:

	engineBuilder.enableHttp2(true).enableQuic(true);

	Controlling the cache:

	- Use a 100KiB in-memory cache:

	engineBuilder.enableHttpCache(
	CronetEngine.Builder.HttpCache.IN_MEMORY, 100 * 1024);

	- or use a 1MiB disk cache:

	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
	`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 open individual connections using Cronet's implementation, do the following:

	HttpURLConnection connection =
	(HttpURLConnection)engine.openConnection(url);

	To use Cronet's implementation instead of the system's default implementation
	for all connections established using `URL.openConnection()` do the following:

	URL.setURLStreamHandlerFactory(engine.createURLStreamHandlerFactory());

	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.CronetEngine#createURLStreamHandlerFactory} for
	more information).
	You can configure Cronet and control caching through the
	`CronetEngine.Builder` instance, `engineBuilder`
	(See [Configuring Cronet](#configuring-cronet) section), before you build the
	`CronetEngine` and then call `CronetEngine.createURLStreamHandlerFactory()`.

	[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