Configuration Guide
The concept of HttpClient configuration APIs is closely aligned with its Architecture layering principles. Configuration parameters are grouped by the architecture layer they apply to. Those groups of configuration parameters are modelled as immutable bean classes referred to as config beans. Config beans are safe to pass around to different classes as those beans cannot be modified at runtime.
A config beans class always represents logically related properties of a single architecture layer. There can be however properties shared by multiple layers applicable to the underlying connection or ongoing message exchange at a different points of their life-cycle. Socket timeout is one of such parameters. For example, connections can start off with a default value of the socket timeout which can later be overridden at a higher level or at a specific phase of connection life-cycle such as TLS handshake.
Configuration Levels
Network I/O Level
-
SocketConfig: these parameters apply to the Classic Network I/O layer and define connection socket properties.
Socket configuration applies on a per-socket basis.
-
IOReactorConfig: these parameters apply to the Async Network I/O layer and define I/O reactor properties.
Protocol Transport Level
-
Http1Config: these parameters apply to the HTTP/1.1 protocol handlers and define common aspects of HTTP/1.1 message transmission.
HTTP/1.1 configuration applies on a per-connection basis.
-
H2Config: these parameters apply to the HTTP/2 protocol handlers and define common aspects of HTTP/2 message transmission and message multiplexing.
HTTP/2 configuration applies on a per-connection basis.
-
CharCodingConfig: these parameters apply to text based protocols such as HTTP/1.1 and define properties of binary to text coding.
Character coding configuration applies on a per-connection basis.
Connection Management Level
-
ConnectionConfig: these parameters apply to connections managed by connection managers. Connection configuration is expected to work consistently across all supported network I/O implementations.
Connection configuration applies on a per-route basis.
An example of per-route connection configuration for the classic transport can be found here: classic and async.
TLS Level
-
TlsConfig: these parameters apply to connections at the time of TLS handshake execution and session negotiation. TLS configuration is expected to work consistently across all supported network I/O implementations.
TLS configuration applies on a per-host basis.
An example of per-host TLS configuration for the classic transport can be found here: classic and async.
Message Exchange Protocol Level
-
RequestConfig: these parameters apply to individual HTTP message exchanges. Request execution parameters are generally expected to work consistently to all HTTP protocol versions with a few exceptions when certain functionality is not applicable due to differences in message transport between different HTTP protocol versions.
Request configuration applies on a per-request basis.
Caching Protocol Level
-
CacheConfig: these parameters apply to the caching protocol layer. They also define the most common properties shared by different cache storage implementations. Individual caching backends may still expose configuration options specific to those backends.
Cache configuration applies on a per-instance basis.