CronetEngine

public abstract class CronetEngine extends Object

An engine to process UrlRequests, which uses the best HTTP stack available on the current platform. An instance of this class can be created using CronetEngine.Builder.

Nested Class Summary

class CronetEngine.Builder A builder for CronetEngines, which allows runtime configuration of CronetEngine.

Public Constructor Summary

CronetEngine()

Public Method Summary

abstract URLStreamHandlerFactory	createURLStreamHandlerFactory() Creates a `URLStreamHandlerFactory` to handle HTTP and HTTPS traffic.
abstract byte[]	getGlobalMetricsDeltas() Returns differences in metrics collected by Cronet since the last call to this method.
abstract String	getVersionString()
abstract UrlRequest.Builder	newUrlRequestBuilder(String url, UrlRequest.Callback callback, Executor executor) Creates a builder for `UrlRequest`.
abstract URLConnection	openConnection(URL url) Establishes a new connection to the resource specified by the `URL` `url`.
abstract void	shutdown() Shuts down the `CronetEngine` if there are no active requests, otherwise throws an exception.
abstract void	startNetLogToFile(String fileName, boolean logAll) Starts NetLog logging to a file.
abstract void	stopNetLog() Stops NetLog logging and flushes file to disk.

Inherited Method Summary

From class java.lang.Object

Object	clone()
boolean	equals(Object arg0)
void	finalize()
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

Public Constructors

public CronetEngine ()

Public Methods

public abstract URLStreamHandlerFactory createURLStreamHandlerFactory ()

Creates a URLStreamHandlerFactory to handle HTTP and HTTPS traffic. An instance of this class can be installed via URL.setURLStreamHandlerFactory(URLStreamHandlerFactory) thus using this CronetEngine by default for all requests created via URL.openConnection().

Cronet does not use certain HTTP features provided via the system:

the HTTP cache installed via HttpResponseCache.install()
the HTTP authentication method installed via Authenticator.setDefault(Authenticator)
the HTTP cookie storage installed via CookieHandler.setDefault(CookieHandler)

While Cronet supports and encourages requests using the HTTPS protocol, Cronet does not provide support for the HttpsURLConnection API. This lack of support also includes not using certain HTTPS features provided via the system:

the HTTPS hostname verifier installed via HttpsURLConnection.setDefaultHostnameVerifier()
the HTTPS socket factory installed via HttpsURLConnection.setDefaultSSLSocketFactory()

Returns

an URLStreamHandlerFactory instance implemented by this CronetEngine.

public abstract byte[] getGlobalMetricsDeltas ()

Returns differences in metrics collected by Cronet since the last call to this method.

Cronet collects these metrics globally. This means deltas returned by getGlobalMetricsDeltas() will include measurements of requests processed by other CronetEngine instances. Since this function returns differences in metrics collected since the last call, and these metrics are collected globally, a call to any CronetEngine instance's getGlobalMetricsDeltas() method will affect the deltas returned by any other CronetEngine instance's getGlobalMetricsDeltas().

Cronet starts collecting these metrics after the first call to getGlobalMetricsDeltras(), so the first call returns no useful data as no metrics have yet been collected.

Returns

differences in metrics collected by Cronet, since the last call to getGlobalMetricsDeltas(), serialized as a protobuf .

public abstract String getVersionString ()

Returns

a human-readable version string of the engine.

public abstract UrlRequest.Builder newUrlRequestBuilder (String url, UrlRequest.Callback callback, Executor executor)

Creates a builder for UrlRequest. All callbacks for generated UrlRequest objects will be invoked on executor's threads. executor must not run tasks on the thread calling Executor.execute(Runnable) to prevent blocking networking operations and causing exceptions during shutdown.

Parameters

url	URL for the generated requests.
callback	callback object that gets invoked on different events.
executor	`Executor` on which all callbacks will be invoked.

public abstract URLConnection openConnection (URL url)

Establishes a new connection to the resource specified by the URL url.

Note: Cronet's HttpURLConnection implementation is subject to certain limitations, see createURLStreamHandlerFactory() for details.

Parameters

url	URL of resource to connect to.

Returns

an HttpURLConnection instance implemented by this CronetEngine.

Throws

IOException	if an error occurs while opening the connection.

public abstract void shutdown ()

Shuts down the CronetEngine if there are no active requests, otherwise throws an exception. Cannot be called on network thread - the thread Cronet calls into Executor on (which is different from the thread the Executor invokes callbacks on). May block until all the CronetEngine's resources have been cleaned up.

public abstract void startNetLogToFile (String fileName, boolean logAll)

Starts NetLog logging to a file. The NetLog will contain events emitted by all live CronetEngines. The NetLog is useful for debugging. The file can be viewed using a Chrome browser navigated to chrome://net-internals/#import

Parameters

fileName	the complete file path. It must not be empty. If the file exists, it is truncated before starting. If actively logging, this method is ignored.
logAll	`true` to include basic events, user cookies, credentials and all transferred bytes in the log. This option presents a privacy risk, since it exposes the user's credentials, and should only be used with the user's consent and in situations where the log won't be public. `false` to just include basic events.

public abstract void stopNetLog ()

Stops NetLog logging and flushes file to disk. If a logging session is not in progress, this call is ignored.