An engine to process UrlRequest
s, 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 CronetEngine s, which allows runtime configuration of
CronetEngine . |
Public Constructor Summary
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 | |
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
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.