A builder for CronetEngine
s, 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 |
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 |
setLibraryLoader(CronetEngine.Builder.LibraryLoader loader)
Sets a
CronetEngine.Builder.LibraryLoader to be used to load the native library. |
CronetEngine.Builder |
setStoragePath(String value)
Sets directory for HTTP Cache and Cookie Storage.
|
CronetEngine.Builder |
setUserAgent(String userAgent)
Overrides the User-Agent header for all requests.
|
Inherited Method Summary
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)
.
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)
.
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)
.
public static final int HTTP_CACHE_IN_MEMORY
Setting to enable in-memory HTTP cache, including HTTP data.
Passed to enableHttpCache(int, long)
.
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 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 likly 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 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 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 CronetEngine
s.
Parameters
value | path to existing directory. |
---|
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.