Builder
open class Builder
kotlin.Any | |
↳ | 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 | |
---|---|
static Int |
Setting to disable HTTP cache. |
static Int |
Setting to enable on-disk cache, including HTTP data. |
static Int |
Setting to enable on-disk cache, excluding HTTP data. |
static Int |
Setting to enable in-memory HTTP cache, including HTTP data. |
Public constructors | |
---|---|
Constructs a |
Public methods | |
---|---|
open HttpEngine.Builder |
addPublicKeyPins(hostName: String, pinsSha256: MutableSet<ByteArray!>, includeSubdomains: Boolean, expirationInstant: Instant) Pins a set of public keys for a given host. |
open HttpEngine.Builder |
addQuicHint(host: String, port: Int, alternatePort: Int) Adds hint that |
open HttpEngine |
build() Build a |
open String |
Constructs a default User-Agent string including the system build version, model and id, and the HTTP stack version. |
open HttpEngine.Builder |
setConnectionMigrationOptions(connectionMigrationOptions: ConnectionMigrationOptions) Configures the behavior of connection migration. |
open HttpEngine.Builder |
setDnsOptions(dnsOptions: DnsOptions) Configures the behavior of hostname lookup. |
open HttpEngine.Builder |
setEnableBrotli(value: Boolean) Sets whether Brotli compression is enabled. |
open HttpEngine.Builder |
setEnableHttp2(value: Boolean) Sets whether HTTP/2 protocol is enabled. |
open HttpEngine.Builder |
setEnableHttpCache(cacheMode: Int, maxSize: Long) Enables or disables caching of HTTP data and other information like QUIC server information. |
open HttpEngine.Builder |
Enables or disables public key pinning bypass for local trust anchors. |
open HttpEngine.Builder |
setEnableQuic(value: Boolean) Sets whether QUIC protocol is enabled. |
open HttpEngine.Builder |
setQuicOptions(quicOptions: QuicOptions) Configures the behavior of the HTTP stack when using QUIC. |
open HttpEngine.Builder |
setStoragePath(value: String) Sets directory for HTTP Cache and Cookie Storage. |
open HttpEngine.Builder |
setUserAgent(userAgent: String) Overrides the User-Agent header for all requests. |
Constants
HTTP_CACHE_DISABLED
static val HTTP_CACHE_DISABLED: Int
Setting to disable HTTP cache. Some data may still be temporarily stored in memory. Passed to setEnableHttpCache
.
Value: 0
HTTP_CACHE_DISK
static val HTTP_CACHE_DISK: Int
Setting to enable on-disk cache, including HTTP data. setStoragePath
must be called prior to passing this constant to setEnableHttpCache
.
Value: 3
HTTP_CACHE_DISK_NO_HTTP
static val HTTP_CACHE_DISK_NO_HTTP: Int
Setting to enable on-disk cache, excluding HTTP data. setStoragePath
must be called prior to passing this constant to setEnableHttpCache
.
Value: 2
HTTP_CACHE_IN_MEMORY
static val HTTP_CACHE_IN_MEMORY: Int
Setting to enable in-memory HTTP cache, including HTTP data. Passed to setEnableHttpCache
.
Value: 1
Public constructors
Builder
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
open fun addPublicKeyPins(
hostName: String,
pinsSha256: MutableSet<ByteArray!>,
includeSubdomains: Boolean,
expirationInstant: Instant
): HttpEngine.Builder
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 |
MutableSet<ByteArray!>: 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 . |
Return | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining. This value cannot be null . |
Exceptions | |
---|---|
java.lang.NullPointerException |
if any of the input parameters are null . |
java.lang.IllegalArgumentException |
if the given host name is invalid or pinsSha256 contains a byte array that does not represent a valid SHA-256 hash. |
addQuicHint
open fun addQuicHint(
host: String,
port: Int,
alternatePort: Int
): HttpEngine.Builder
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. |
Return | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining. This value cannot be null . |
build
open fun build(): HttpEngine
Build a HttpEngine
using this builder's configuration.
Return | |
---|---|
HttpEngine |
constructed HttpEngine . This value cannot be null . |
getDefaultUserAgent
open fun getDefaultUserAgent(): String
Constructs a default User-Agent string including the system build version, model and id, and the HTTP stack version.
Return | |
---|---|
String |
User-Agent string. This value cannot be null . |
setConnectionMigrationOptions
open fun setConnectionMigrationOptions(connectionMigrationOptions: ConnectionMigrationOptions): HttpEngine.Builder
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 . |
Return | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining. This value cannot be null . |
setDnsOptions
open fun setDnsOptions(dnsOptions: DnsOptions): HttpEngine.Builder
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 . |
Return | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining. This value cannot be null . |
setEnableBrotli
open fun setEnableBrotli(value: Boolean): HttpEngine.Builder
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. |
Return | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining. This value cannot be null . |
setEnableHttp2
open fun setEnableHttp2(value: Boolean): HttpEngine.Builder
Sets whether HTTP/2 protocol is enabled. Defaults to enabled.
Parameters | |
---|---|
value |
Boolean: true to enable HTTP/2, false to disable. |
Return | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining. This value cannot be null . |
setEnableHttpCache
open fun setEnableHttpCache(
cacheMode: Int,
maxSize: Long
): HttpEngine.Builder
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). |
Return | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining. This value cannot be null . |
setEnablePublicKeyPinningBypassForLocalTrustAnchors
open fun setEnablePublicKeyPinningBypassForLocalTrustAnchors(value: Boolean): HttpEngine.Builder
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. |
Return | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining. This value cannot be null . |
setEnableQuic
open fun setEnableQuic(value: Boolean): HttpEngine.Builder
Sets whether QUIC protocol is enabled. Defaults to enabled.
Parameters | |
---|---|
value |
Boolean: true to enable QUIC, false to disable. |
Return | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining. This value cannot be null . |
setQuicOptions
open fun setQuicOptions(quicOptions: QuicOptions): HttpEngine.Builder
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 . |
Return | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining. This value cannot be null . |
setStoragePath
open fun setStoragePath(value: String): HttpEngine.Builder
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 . |
Return | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining. This value cannot be null . |
setUserAgent
open fun setUserAgent(userAgent: String): HttpEngine.Builder
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 . |
Return | |
---|---|
HttpEngine.Builder |
the builder to facilitate chaining. This value cannot be null . |