CronetEngine.Builder

public static class CronetEngine.Builder extends Object

A builder for CronetEngines, which allows runtime configuration of CronetEngine. Configuration options are set on the builder and then build() is called to create the CronetEngine.

Nested Class Summary

class

CronetEngine.Builder.LibraryLoader

A class which provides a method for loading the cronet native library.

Constant Summary

int	HTTP_CACHE_DISABLED	Setting to disable HTTP cache.
int	HTTP_CACHE_DISK	Setting to enable on-disk cache, including HTTP data.
int	HTTP_CACHE_DISK_NO_HTTP	Setting to enable on-disk cache, excluding HTTP data.
int	HTTP_CACHE_IN_MEMORY	Setting to enable in-memory HTTP cache, including HTTP data.

Public Constructor Summary

Builder(Context context) Constructs a CronetEngine.Builder object that facilitates creating a CronetEngine.

Public Method Summary

CronetEngine.Builder	addPublicKeyPins(String hostName, Set<byte[]> pinsSha256, boolean includeSubdomains, Date expirationDate) Pins a set of public keys for a given host.
CronetEngine.Builder	addQuicHint(String host, int port, int alternatePort) Adds hint that host supports QUIC.
CronetEngine	build() Build a CronetEngine using this builder's configuration.
CronetEngine.Builder	enableBrotli(boolean value) Sets whether Brotli compression is enabled.
CronetEngine.Builder	enableHttp2(boolean value) Sets whether HTTP/2 protocol is enabled.
CronetEngine.Builder	enableHttpCache(int cacheMode, long maxSize) Enables or disables caching of HTTP data and other information like QUIC server information.
CronetEngine.Builder	enableNetworkQualityEstimator(boolean value) Enables the network quality estimator, which collects and reports measurements of round trip time (RTT) and downstream throughput at various layers of the network stack.
CronetEngine.Builder	enablePublicKeyPinningBypassForLocalTrustAnchors(boolean value) Enables or disables public key pinning bypass for local trust anchors.
CronetEngine.Builder	enableQuic(boolean value) Sets whether QUIC protocol is enabled.
String	getDefaultUserAgent() Constructs a User-Agent string including application name and version, system build version, model and id, and Cronet version.
CronetEngine.Builder	setConnectionMigrationOptions(ConnectionMigrationOptions connectionMigrationOptions) Configures the behavior of connection migration.
CronetEngine.Builder	setConnectionMigrationOptions(ConnectionMigrationOptions.Builder connectionMigrationOptionsBuilder)
CronetEngine.Builder	setDnsOptions(DnsOptions.Builder dnsOptions)
CronetEngine.Builder	setDnsOptions(DnsOptions dnsOptions) Configures the behavior of hostname lookup.
CronetEngine.Builder	setLibraryLoader(CronetEngine.Builder.LibraryLoader loader) Sets a CronetEngine.Builder.LibraryLoader to be used to load the native library.
CronetEngine.Builder	setQuicOptions(QuicOptions.Builder quicOptionsBuilder)
CronetEngine.Builder	setQuicOptions(QuicOptions quicOptions) Configures the behavior of Cronet when using QUIC.
CronetEngine.Builder	setStoragePath(String value) Sets directory for HTTP Cache and Cookie Storage.
CronetEngine.Builder	setThreadPriority(int priority) Sets the thread priority of Cronet's internal thread.
CronetEngine.Builder	setUserAgent(String userAgent) Overrides the User-Agent header for all requests.

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()

Constants

public static final int HTTP_CACHE_DISABLED

Setting to disable HTTP cache. Some data may still be temporarily stored in memory. Passed to enableHttpCache(int, long).

Constant Value: 0

public static final int HTTP_CACHE_DISK

Setting to enable on-disk cache, including HTTP data. setStoragePath(String) must be called prior to passing this constant to enableHttpCache(int, long).

Constant Value: 3

public static final int HTTP_CACHE_DISK_NO_HTTP

Setting to enable on-disk cache, excluding HTTP data. setStoragePath(String) must be called prior to passing this constant to enableHttpCache(int, long).

Constant Value: 2

public static final int HTTP_CACHE_IN_MEMORY

Setting to enable in-memory HTTP cache, including HTTP data. Passed to enableHttpCache(int, long).

Constant Value: 1

Public Constructors

public Builder (Context context)

Constructs a CronetEngine.Builder object that facilitates creating a CronetEngine. The default configuration enables HTTP/2 and QUIC, but disables the HTTP cache.

Parameters

context	Android Context, which is used by CronetEngine.Builder to retrieve the application context. A reference to only the application context will be kept, so as to avoid extending the lifetime of context unnecessarily.

Public Methods

public CronetEngine.Builder addPublicKeyPins (String hostName, Set<byte[]> pinsSha256, boolean includeSubdomains, Date expirationDate)

Pins a set of public keys for a given host. By pinning a set of public keys, pinsSha256, communication with hostName is required to authenticate with a certificate with a public key from the set of pinned ones. An app can pin the public key of the root certificate, any of the intermediate certificates or the end-entry certificate. Authentication will fail and secure communication will not be established if none of the public keys is present in the host's certificate chain, even if the host attempts to authenticate with a certificate allowed by the device's trusted store of certificates.

Calling this method multiple times with the same host name overrides the previously set pins for the host.

More information about the public key pinning can be found in RFC 7469.

Parameters

hostName	name of the host to which the public keys should be pinned. A host that consists only of digits and the dot character is treated as invalid.
pinsSha256	a set of pins. Each pin is the SHA-256 cryptographic hash of the DER-encoded ASN.1 representation of the Subject Public Key Info (SPKI) of the host's X.509 certificate. Use Certificate.getPublicKey() and Key.getEncoded() to obtain DER-encoded ASN.1 representation of the SPKI. Although, the method does not mandate the presence of the backup pin that can be used if the control of the primary private key has been lost, it is highly recommended to supply one.
includeSubdomains	indicates whether the pinning policy should be applied to subdomains of hostName.
expirationDate	specifies the expiration date for the pins.

Returns

• the builder to facilitate chaining.

Throws

NullPointerException	if any of the input parameters are null.
IllegalArgumentException	if the given host name is invalid or pinsSha256 contains a byte array that does not represent a valid SHA-256 hash.

public CronetEngine.Builder addQuicHint (String host, int port, int alternatePort)

Adds hint that host supports QUIC. Note that enableHttpCache (HTTP_CACHE_DISK) is needed to take advantage of 0-RTT connection establishment between sessions.

Parameters

host	hostname of the server that supports QUIC.
port	host of the server that supports QUIC.
alternatePort	alternate port to use for QUIC.

Returns

• the builder to facilitate chaining.

public CronetEngine build ()

Build a CronetEngine using this builder's configuration.

Returns

• constructed CronetEngine.

public CronetEngine.Builder enableBrotli (boolean value)

Sets whether Brotli compression is enabled. If enabled, Brotli will be advertised in Accept-Encoding request headers. Defaults to disabled.

Parameters

value	true to enable Brotli, false to disable.

Returns

• the builder to facilitate chaining.

public CronetEngine.Builder enableHttp2 (boolean value)

Sets whether HTTP/2 protocol is enabled. Defaults to enabled.

Parameters

value	true to enable HTTP/2, false to disable.

Returns

• the builder to facilitate chaining.

public CronetEngine.Builder enableHttpCache (int cacheMode, long maxSize)

Enables or disables caching of HTTP data and other information like QUIC server information.

Parameters

cacheMode	control location and type of cached data. Must be one of HTTP_CACHE_*.
maxSize	maximum size in bytes used to cache data (advisory and maybe exceeded at times).

Returns

• the builder to facilitate chaining.

public CronetEngine.Builder enableNetworkQualityEstimator (boolean value)

Enables the network quality estimator, which collects and reports measurements of round trip time (RTT) and downstream throughput at various layers of the network stack. After enabling the estimator, listeners of RTT and throughput can be added with CronetEngine.addRttListener(NetworkQualityRttListener) and CronetEngine.addThroughputListener(NetworkQualityThroughputListener) and removed with CronetEngine.removeRttListener(NetworkQualityRttListener) and CronetEngine.removeThroughputListener(NetworkQualityThroughputListener). The estimator uses memory and CPU only when enabled.

Parameters

value	true to enable network quality estimator, false to disable.

Returns

• the builder to facilitate chaining.

public CronetEngine.Builder enablePublicKeyPinningBypassForLocalTrustAnchors (boolean value)

Enables or disables public key pinning bypass for local trust anchors. Disabling the bypass for local trust anchors is highly discouraged since it may prohibit the app from communicating with the pinned hosts. E.g., a user may want to send all traffic through an SSL enabled proxy by changing the device proxy settings and adding the proxy certificate to the list of local trust anchor. Disabling the bypass will most likely prevent the app from sending any traffic to the pinned hosts. For more information see 'How does key pinning interact with local proxies and filters?' at https://www.chromium.org/Home/chromium-security/security-faq

Parameters

value	true to enable the bypass, false to disable.

Returns

• the builder to facilitate chaining.

public CronetEngine.Builder enableQuic (boolean value)

Sets whether QUIC protocol is enabled. Defaults to enabled. If QUIC is enabled, then QUIC User Agent Id containing application name and Cronet version is sent to the server.

Parameters

value	true to enable QUIC, false to disable.

Returns

• the builder to facilitate chaining.

public String getDefaultUserAgent ()

Constructs a User-Agent string including application name and version, system build version, model and id, and Cronet version.

Returns

• User-Agent string.

public CronetEngine.Builder setConnectionMigrationOptions (ConnectionMigrationOptions connectionMigrationOptions)

Configures the behavior of connection migration. For more details, see documentation of ConnectionMigrationOptions and the individual methods of ConnectionMigrationOptions.Builder.

Only relevant if enableQuic(boolean) is enabled.

Parameters

connectionMigrationOptions

Returns

• the builder to facilitate chaining.

public CronetEngine.Builder setConnectionMigrationOptions (ConnectionMigrationOptions.Builder connectionMigrationOptionsBuilder)

Parameters

connectionMigrationOptionsBuilder

See Also

• setConnectionMigrationOptions(ConnectionMigrationOptions)

public CronetEngine.Builder setDnsOptions (DnsOptions.Builder dnsOptions)

Parameters

dnsOptions

See Also

• setDnsOptions(DnsOptions)

public CronetEngine.Builder setDnsOptions (DnsOptions dnsOptions)

Configures the behavior of hostname lookup. For more details, see documentation of DnsOptions and the individual methods of DnsOptions.Builder.

Only relevant if enableQuic(boolean) is enabled.

Parameters

dnsOptions

Returns

• the builder to facilitate chaining.

public CronetEngine.Builder setLibraryLoader (CronetEngine.Builder.LibraryLoader loader)

Sets a CronetEngine.Builder.LibraryLoader to be used to load the native library. If not set, the library will be loaded using System.loadLibrary(String).

Parameters

loader	LibraryLoader to be used to load the native library.

Returns

• the builder to facilitate chaining.

public CronetEngine.Builder setQuicOptions (QuicOptions.Builder quicOptionsBuilder)

Parameters

quicOptionsBuilder

See Also

• setQuicOptions(QuicOptions)

public CronetEngine.Builder setQuicOptions (QuicOptions quicOptions)

Configures the behavior of Cronet when using QUIC. For more details, see documentation of QuicOptions and the individual methods of QuicOptions.Builder.

Only relevant if enableQuic(boolean) is enabled.

Parameters

quicOptions

Returns

• the builder to facilitate chaining.

public CronetEngine.Builder setStoragePath (String value)

Sets directory for HTTP Cache and Cookie Storage. The directory must exist.

NOTE: Do not use the same storage directory with more than one CronetEngine at a time. Access to the storage directory does not support concurrent access by multiple CronetEngines.

Parameters

value	path to existing directory.

Returns

• the builder to facilitate chaining.

public CronetEngine.Builder setThreadPriority (int priority)

Sets the thread priority of Cronet's internal thread.

Parameters

priority	the thread priority of Cronet's internal thread. A Linux priority level, from -20 for highest scheduling priority to 19 for lowest scheduling priority. For more information on values, see Process.setThreadPriority(int, int) and THREAD_PRIORITY_* values.

Returns

• the builder to facilitate chaining.

public CronetEngine.Builder setUserAgent (String userAgent)

Overrides the User-Agent header for all requests. An explicitly set User-Agent header (set using UrlRequest.Builder.addHeader(String, String)) will override a value set using this function.

Parameters

userAgent	the User-Agent string to use for all requests.

Returns

• the builder to facilitate chaining.