HttpEngine.Builder
public
static
class
HttpEngine.Builder
extends Object
java.lang.Object | |
↳ | android.net.http.HttpEngine.Builder |
A builder for HttpEngine
s, which allows runtime configuration of
HttpEngine
. Configuration options are set on the builder and
then build()
is called to create the HttpEngine
.
Summary
Constants | |
---|---|
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 constructors | |
---|---|
Builder(Context context)
Constructs a |
Public methods | |
---|---|
HttpEngine.Builder
|
addPublicKeyPins(String hostName, Set<byte[]> pinsSha256, boolean includeSubdomains, Instant expirationInstant)
Pins a set of public keys for a given host. |
HttpEngine.Builder
|
addQuicHint(String host, int port, int alternatePort)
Adds hint that |
HttpEngine
|
build()
Build a |
String
|
getDefaultUserAgent()
Constructs a default User-Agent string including the system build version, model and id, and the HTTP stack version. |
HttpEngine.Builder
|
setConnectionMigrationOptions(ConnectionMigrationOptions connectionMigrationOptions)
Configures the behavior of connection migration. |
HttpEngine.Builder
|
setDnsOptions(DnsOptions dnsOptions)
Configures the behavior of hostname lookup. |
HttpEngine.Builder
|
setEnableBrotli(boolean value)
Sets whether Brotli compression is enabled. |
HttpEngine.Builder
|
setEnableHttp2(boolean value)
Sets whether HTTP/2 protocol is enabled. |
HttpEngine.Builder
|
setEnableHttpCache(int cacheMode, long maxSize)
Enables or disables caching of HTTP data and other information like QUIC server information. |
HttpEngine.Builder
|
setEnablePublicKeyPinningBypassForLocalTrustAnchors(boolean value)
Enables or disables public key pinning bypass for local trust anchors. |
HttpEngine.Builder
|
setEnableQuic(boolean value)
Sets whether QUIC protocol is enabled. |
HttpEngine.Builder
|
setQuicOptions(QuicOptions quicOptions)
Configures the behavior of the HTTP stack when using QUIC. |
HttpEngine.Builder
|
setStoragePath(String value)
Sets directory for HTTP Cache and Cookie Storage. |
HttpEngine.Builder
|
setUserAgent(String userAgent)
Overrides the User-Agent header for all requests. |
Inherited methods | |
---|---|
Constants
HTTP_CACHE_DISABLED
public static final int HTTP_CACHE_DISABLED
Setting to disable HTTP cache. Some data may still be temporarily stored in memory.
Passed to setEnableHttpCache(int, long)
.
Constant Value: 0 (0x00000000)
HTTP_CACHE_DISK
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
setEnableHttpCache(int, long)
.
Constant Value: 3 (0x00000003)
HTTP_CACHE_DISK_NO_HTTP
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
setEnableHttpCache(int, long)
.
Constant Value: 2 (0x00000002)
HTTP_CACHE_IN_MEMORY
public static final int HTTP_CACHE_IN_MEMORY
Setting to enable in-memory HTTP cache, including HTTP data.
Passed to setEnableHttpCache(int, long)
.
Constant Value: 1 (0x00000001)
Public constructors
Builder
public Builder (Context context)
Constructs a Builder
object that facilitates creating a
HttpEngine
. The default configuration enables HTTP/2 and
QUIC, but disables the HTTP cache.
Parameters | |
---|---|
context |
Context : Android Context , which is used by 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.
This value cannot be null . |
Public methods
addPublicKeyPins
public HttpEngine.Builder addPublicKeyPins (String hostName, Set<byte[]> pinsSha256, boolean includeSubdomains, Instant expirationInstant)
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 |
String : 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.
This value cannot be null . |
pinsSha256 |
Set : 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.
This value cannot be null . |
includeSubdomains |
boolean : indicates whether the pinning policy should be applied to
subdomains of hostName . |
expirationInstant |
Instant : specifies the expiration instant for the pins.
This value cannot be null . |
Returns | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining.
This value cannot be null . |
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. |
addQuicHint
public HttpEngine.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 |
String : hostname of the server that supports QUIC.
This value cannot be null . |
port |
int : host of the server that supports QUIC. |
alternatePort |
int : alternate port to use for QUIC. |
Returns | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining.
This value cannot be null . |
build
public HttpEngine build ()
Build a HttpEngine
using this builder's configuration.
Returns | |
---|---|
HttpEngine |
constructed HttpEngine .
This value cannot be null . |
getDefaultUserAgent
public String getDefaultUserAgent ()
Constructs a default User-Agent string including the system build version, model and id, and the HTTP stack version.
Returns | |
---|---|
String |
User-Agent string.
This value cannot be null . |
setConnectionMigrationOptions
public HttpEngine.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 setEnableQuic(boolean)
is enabled.
Parameters | |
---|---|
connectionMigrationOptions |
ConnectionMigrationOptions : This value cannot be null . |
Returns | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining.
This value cannot be null . |
setDnsOptions
public HttpEngine.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 setEnableQuic(boolean)
is enabled.
Parameters | |
---|---|
dnsOptions |
DnsOptions : This value cannot be null . |
Returns | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining.
This value cannot be null . |
setEnableBrotli
public HttpEngine.Builder setEnableBrotli (boolean value)
Sets whether Brotli compression is enabled. If enabled, Brotli will be advertised in Accept-Encoding request headers. Defaults to disabled.
Parameters | |
---|---|
value |
boolean : true to enable Brotli, false to disable. |
Returns | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining.
This value cannot be null . |
setEnableHttp2
public HttpEngine.Builder setEnableHttp2 (boolean value)
Sets whether HTTP/2 protocol is enabled. Defaults to enabled.
Parameters | |
---|---|
value |
boolean : true to enable HTTP/2, false to disable. |
Returns | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining.
This value cannot be null . |
setEnableHttpCache
public HttpEngine.Builder setEnableHttpCache (int cacheMode, long maxSize)
Enables or disables caching of HTTP data and other information like QUIC server information.
Parameters | |
---|---|
cacheMode |
int : control location and type of cached data. Must be one of HTTP_CACHE_* . |
maxSize |
long : maximum size in bytes used to cache data (advisory and maybe exceeded at
times). |
Returns | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining.
This value cannot be null . |
setEnablePublicKeyPinningBypassForLocalTrustAnchors
public HttpEngine.Builder setEnablePublicKeyPinningBypassForLocalTrustAnchors (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 |
boolean : true to enable the bypass, false to disable. |
Returns | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining.
This value cannot be null . |
setEnableQuic
public HttpEngine.Builder setEnableQuic (boolean value)
Sets whether QUIC protocol is enabled. Defaults to enabled.
Parameters | |
---|---|
value |
boolean : true to enable QUIC, false to disable. |
Returns | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining.
This value cannot be null . |
setQuicOptions
public HttpEngine.Builder setQuicOptions (QuicOptions quicOptions)
Configures the behavior of the HTTP stack when using QUIC. For more details, see
documentation of QuicOptions
and the individual methods
of QuicOptions.Builder
.
Only relevant if setEnableQuic(boolean)
is enabled.
Parameters | |
---|---|
quicOptions |
QuicOptions : This value cannot be null . |
Returns | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining.
This value cannot be null . |
setStoragePath
public HttpEngine.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
HttpEngine
at a time. Access to the storage directory does
not support concurrent access by multiple HttpEngine
instances.
Parameters | |
---|---|
value |
String : path to existing directory.
This value cannot be null . |
Returns | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining.
This value cannot be null . |
setUserAgent
public HttpEngine.Builder setUserAgent (String userAgent)
Overrides the User-Agent header for all requests. An explicitly set User-Agent header
(set using UrlRequest.Builder#addHeader
) will override a value set using this
function.
Parameters | |
---|---|
userAgent |
String : the User-Agent string to use for all requests.
This value cannot be null . |
Returns | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining.
This value cannot be null . |