Added in API level 34
Also in S Extensions 7

Summary: Constants | Ctors | Methods | Inherited Methods

HttpEngine.Builder

---

Kotlin |Java

public static class HttpEngine.Builder
extends Object

java.lang.Object
↳	android.net.http.HttpEngine.Builder

---

A builder for HttpEngines, 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 Builder object that facilitates creating a HttpEngine.

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 host supports QUIC.
HttpEngine	build() Build a HttpEngine using this builder's configuration.
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

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

HTTP_CACHE_DISABLED

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

public HttpEngine build ()

Build a HttpEngine using this builder's configuration.

Returns
HttpEngine	constructed HttpEngine. This value cannot be null.

getDefaultUserAgent

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

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

Added in API level 34
Also in S Extensions 7

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.