io.servicetalk.http.api

Interface SingleAddressHttpClientBuilder<U,R>

Type Parameters:

U - the type of address before resolution (unresolved address)

R - the type of address after resolution (resolved address)

All Known Implementing Classes:

DelegatingSingleAddressHttpClientBuilder

public interface SingleAddressHttpClientBuilder<U,R>

A builder of StreamingHttpClient instances which call a single server based on the provided unresolved address.

It also provides a good set of default settings and configurations, which could be used by most users as-is or could be overridden to address specific use cases.

Method Summary

Modifier and Type	Method and Description
SingleAddressHttpClientBuilder<U,R>	allowDropResponseTrailers(boolean allowDrop) Provide a hint if response trailers are allowed to be dropped.
SingleAddressHttpClientBuilder<U,R>	appendClientFilter(Predicate<StreamingHttpRequest> predicate, StreamingHttpClientFilterFactory factory) Appends the filter to the chain of filters used to decorate the HttpClient created by this builder, for every request that passes the provided Predicate.
SingleAddressHttpClientBuilder<U,R>	appendClientFilter(StreamingHttpClientFilterFactory factory) Appends the filter to the chain of filters used to decorate the HttpClient created by this builder.
SingleAddressHttpClientBuilder<U,R>	appendConnectionFactoryFilter(ConnectionFactoryFilter<R,FilterableStreamingHttpConnection> factory) Appends the filter to the chain of filters used to decorate the ConnectionFactory used by this builder.
SingleAddressHttpClientBuilder<U,R>	appendConnectionFilter(Predicate<StreamingHttpRequest> predicate, StreamingHttpConnectionFilterFactory factory) Appends the filter to the chain of filters used to decorate the StreamingHttpConnection created by this builder, for every request that passes the provided Predicate.
SingleAddressHttpClientBuilder<U,R>	appendConnectionFilter(StreamingHttpConnectionFilterFactory factory) Appends the filter to the chain of filters used to decorate the StreamingHttpConnection created by this builder.
SingleAddressHttpClientBuilder<U,R>	bufferAllocator(BufferAllocator allocator) Sets the BufferAllocator for all clients created from this builder.
default HttpClient	build() Builds a new HttpClient.
default BlockingHttpClient	buildBlocking() Creates a new BlockingHttpClient.
default BlockingStreamingHttpClient	buildBlockingStreaming() Creates a new BlockingStreamingHttpClient.
StreamingHttpClient	buildStreaming() Builds a new StreamingHttpClient.
SingleAddressHttpClientBuilder<U,R>	enableWireLogging(String loggerName, LogLevel logLevel, BooleanSupplier logUserData) Enables wire-logging for connections created by this builder.
SingleAddressHttpClientBuilder<U,R>	executionStrategy(HttpExecutionStrategy strategy) Sets the HttpExecutionStrategy to be used for client callbacks when executing client requests for all clients created from this builder.
SingleAddressHttpClientBuilder<U,R>	executor(Executor executor) Sets the Executor for all clients created from this builder.
SingleAddressHttpClientBuilder<U,R>	hostHeaderFallback(boolean enable) Configures automatically setting Host headers by inferring from the address.
SingleAddressHttpClientBuilder<U,R>	inferPeerHost(boolean shouldInfer) Toggle inference of value to use instead of ClientSslConfig.peerHost() from client's address when peer host is not specified.
SingleAddressHttpClientBuilder<U,R>	inferPeerPort(boolean shouldInfer) Toggle inference of value to use instead of ClientSslConfig.peerPort() from client's address when peer port is not specified (equals -1).
SingleAddressHttpClientBuilder<U,R>	inferSniHostname(boolean shouldInfer) Toggle SNI hostname inference from client's address if not explicitly specified via sslConfig(ClientSslConfig).
SingleAddressHttpClientBuilder<U,R>	ioExecutor(IoExecutor ioExecutor) Sets the IoExecutor for all clients created from this builder.
SingleAddressHttpClientBuilder<U,R>	loadBalancerFactory(HttpLoadBalancerFactory<R> loadBalancerFactory) Sets a HttpLoadBalancerFactory to create LoadBalancer instances.
SingleAddressHttpClientBuilder<U,R>	protocols(HttpProtocolConfig... protocols) Configurations of various HTTP protocol versions.
default SingleAddressHttpClientBuilder<U,R>	proxyAddress(U proxyAddress) Deprecated. Use proxyConfig(ProxyConfig) with ProxyConfig.forAddress(Object).
default SingleAddressHttpClientBuilder<U,R>	proxyConfig(ProxyConfig<U> proxyConfig) Configures a proxy to serve as an intermediary for requests.
SingleAddressHttpClientBuilder<U,R>	retryServiceDiscoveryErrors(BiIntFunction<Throwable,? extends Completable> retryStrategy) Sets a retry strategy to retry errors emitted by ServiceDiscoverer.
SingleAddressHttpClientBuilder<U,R>	serviceDiscoverer(ServiceDiscoverer<U,R,? extends ServiceDiscovererEvent<R>> serviceDiscoverer) Sets a ServiceDiscoverer to resolve addresses of remote servers to connect to.
<T> SingleAddressHttpClientBuilder<U,R>	socketOption(SocketOption<T> option, T value) Adds a SocketOption for all connections created by this builder.
SingleAddressHttpClientBuilder<U,R>	sslConfig(ClientSslConfig sslConfig) Set the SSL/TLS configuration.
SingleAddressHttpClientBuilder<U,R>	unresolvedAddressToHost(Function<U,CharSequence> unresolvedAddressToHostFunction) Provides a means to convert U unresolved address type into a CharSequence.

Method Detail

proxyAddress

@Deprecated
default SingleAddressHttpClientBuilder<U,R> proxyAddress(U proxyAddress)

Deprecated. Use proxyConfig(ProxyConfig) with ProxyConfig.forAddress(Object).

Configures a proxy to serve as an intermediary for requests.

If the client talks to a proxy over http (not https, ClientSslConfig is NOT configured), it will rewrite the request-target to absolute-form, as specified by the RFC.

For secure proxy tunnels (when ClientSslConfig is configured) the tunnel is always initialized using HTTP/1.1 CONNECT request. The actual protocol will be negotiated via ALPN extension of TLS protocol, taking into account HTTP protocols configured via protocols(HttpProtocolConfig...) method. In case of any error during CONNECT process, ProxyConnectException or ProxyConnectResponseException will be thrown when a request attempt is made through the constructed client instance.

Parameters:

proxyAddress - Unresolved address of the proxy. When used with a builder created for a resolved address, proxyAddress should also be already resolved – otherwise runtime exceptions may occur.

Returns:

this.

proxyConfig

default SingleAddressHttpClientBuilder<U,R> proxyConfig(ProxyConfig<U> proxyConfig)

Configures a proxy to serve as an intermediary for requests.

If the client talks to a proxy over http (not https, ClientSslConfig is NOT configured), it will rewrite the request-target to absolute-form, as specified by the RFC.

For secure proxy tunnels (when ClientSslConfig is configured) the tunnel is always initialized using HTTP/1.1 CONNECT request. The actual protocol will be negotiated via ALPN extension of TLS protocol, taking into account HTTP protocols configured via protocols(HttpProtocolConfig...) method. In case of any error during CONNECT process, ProxyConnectException or ProxyConnectResponseException will be thrown when a request attempt is made through the constructed client instance.

Parameters:

proxyConfig - Configuration for a proxy. When used with a builder created for a resolved address, ProxyConfig.address() must also be already resolved – otherwise runtime exceptions will occur.

Returns:

this.

See Also:

ProxyConfig.forAddress(Object), ProxyConfigBuilder

socketOption

<T> SingleAddressHttpClientBuilder<U,R> socketOption(SocketOption<T> option,
                                                     T value)

Adds a SocketOption for all connections created by this builder.

Type Parameters:

T - the type of the value.

Parameters:

option - the option to apply.

value - the value.

Returns:

this.

See Also:

StandardSocketOptions, ServiceTalkSocketOptions

enableWireLogging

SingleAddressHttpClientBuilder<U,R> enableWireLogging(String loggerName,
                                                      LogLevel logLevel,
                                                      BooleanSupplier logUserData)

Enables wire-logging for connections created by this builder.

Parameters:

loggerName - The name of the logger to log wire events.

logLevel - The level to log at.

logUserData - true to include user data (e.g. data, headers, etc.). false to exclude user data and log only network events. This method is invoked for each data object allowing for dynamic behavior.

Returns:

this.

protocols

SingleAddressHttpClientBuilder<U,R> protocols(HttpProtocolConfig... protocols)

Configurations of various HTTP protocol versions.

Note: the order of specified protocols will reflect on priorities for ALPN in case the connections use TLS.

Parameters:

protocols - HttpProtocolConfig for each protocol that should be supported.

Returns:

this.

hostHeaderFallback

SingleAddressHttpClientBuilder<U,R> hostHeaderFallback(boolean enable)

Configures automatically setting Host headers by inferring from the address.

When false is passed, this setting disables the default filter such that no Host header will be manipulated.

Parameters:

enable - Whether a default filter for inferring the Host headers should be added.

Returns:

this

See Also:

unresolvedAddressToHost(Function)

allowDropResponseTrailers

SingleAddressHttpClientBuilder<U,R> allowDropResponseTrailers(boolean allowDrop)

Provide a hint if response trailers are allowed to be dropped. This hint maybe ignored if the transport can otherwise infer that trailers should be preserved. For example, if the response headers contain Trailer then this hint maybe ignored.

Parameters:

allowDrop - true if response trailers are allowed to be dropped.

Returns:

this

appendConnectionFilter

SingleAddressHttpClientBuilder<U,R> appendConnectionFilter(StreamingHttpConnectionFilterFactory factory)

Appends the filter to the chain of filters used to decorate the StreamingHttpConnection created by this builder.

Filtering allows you to wrap a StreamingHttpConnection and modify behavior during request/response processing Some potential candidates for filtering include logging, metrics, and decorating responses.

The order of execution of these filters are in order of append. If 3 filters are added as follows:

     builder.appendConnectionFilter(filter1).appendConnectionFilter(filter2).appendConnectionFilter(filter3)
 

making a request to a connection wrapped by this filter chain the order of invocation of these filters will be:

     filter1 ⇒ filter2 ⇒ filter3 ⇒ connection
 

Parameters:

factory - StreamingHttpConnectionFilterFactory to decorate a StreamingHttpConnection for the purpose of filtering.

Returns:

this

appendConnectionFilter

SingleAddressHttpClientBuilder<U,R> appendConnectionFilter(Predicate<StreamingHttpRequest> predicate,
                                                           StreamingHttpConnectionFilterFactory factory)

Appends the filter to the chain of filters used to decorate the StreamingHttpConnection created by this builder, for every request that passes the provided Predicate.

Filtering allows you to wrap a StreamingHttpConnection and modify behavior during request/response processing Some potential candidates for filtering include logging, metrics, and decorating responses.

The order of execution of these filters are in order of append. If 3 filters are added as follows:

     builder.appendConnectionFilter(filter1).appendConnectionFilter(filter2).appendConnectionFilter(filter3)
 

making a request to a connection wrapped by this filter chain the order of invocation of these filters will be:

     filter1 ⇒ filter2 ⇒ filter3 ⇒ connection
 

When overriding this method, delegate to super as it uses internal utilities to provide a consistent execution flow.

Parameters:

predicate - the Predicate to test if the filter must be applied.

factory - StreamingHttpConnectionFilterFactory to decorate a StreamingHttpConnection for the purpose of filtering.

Returns:

this

ioExecutor

SingleAddressHttpClientBuilder<U,R> ioExecutor(IoExecutor ioExecutor)

Sets the IoExecutor for all clients created from this builder.

Parameters:

ioExecutor - IoExecutor to use.

Returns:

this.

executor

SingleAddressHttpClientBuilder<U,R> executor(Executor executor)

Sets the Executor for all clients created from this builder.

Parameters:

executor - IoExecutor to use.

Returns:

this.

executionStrategy

SingleAddressHttpClientBuilder<U,R> executionStrategy(HttpExecutionStrategy strategy)

Sets the HttpExecutionStrategy to be used for client callbacks when executing client requests for all clients created from this builder.

Specifying an execution strategy affects the offloading used during execution of client requests:

Unspecified or HttpExecutionStrategies.defaultStrategy()

Execution of client requests will use a safe (non-blocking) execution strategy appropriate for the client API used and the filters added. Blocking is always safe as all potentially blocking paths are offloaded. Each client API variant (async/blocking streaming/aggregate) requires a specific execution strategy to avoid blocking the event-loop and filters added via appendClientFilter(StreamingHttpClientFilterFactory), appendConnectionFilter(StreamingHttpConnectionFilterFactory), or appendConnectionFactoryFilter(ConnectionFactoryFilter), etc. may also require offloading. The execution strategy for execution of client requests will be computed based on the client API in use and HttpExecutionStrategyInfluencer.requiredOffloads() of added the filters.

HttpExecutionStrategies.offloadNone() (or deprecated HttpExecutionStrategies.offloadNever())

No offloading will be used during execution of client requests regardless of the client API used or the influence of added filters. Filters and asynchronous callbacks must not ever block during the execution of client requests.

A custom execution strategy (HttpExecutionStrategies.customStrategyBuilder()) or HttpExecutionStrategies.offloadAll()

The specified execution strategy will be used for executing client requests rather than the client API's default safe strategy. Like with the default strategy, the actual execution strategy used is computed from the provided strategy and the execution strategies required by added filters. Filters and asynchronous callbacks MAY only block during the offloaded portions of the client request execution.

Parameters:

strategy - HttpExecutionStrategy to use. If callbacks to the application code may block then those callbacks must request to be offloaded.

Returns:

this.

See Also:

HttpExecutionStrategies

bufferAllocator

SingleAddressHttpClientBuilder<U,R> bufferAllocator(BufferAllocator allocator)

Sets the BufferAllocator for all clients created from this builder.

Parameters:

allocator - BufferAllocator to use.

Returns:

this.

appendConnectionFactoryFilter

SingleAddressHttpClientBuilder<U,R> appendConnectionFactoryFilter(ConnectionFactoryFilter<R,FilterableStreamingHttpConnection> factory)

Appends the filter to the chain of filters used to decorate the ConnectionFactory used by this builder.

Filtering allows you to wrap a ConnectionFactory and modify behavior of ConnectionFactory.newConnection(Object, ContextMap, TransportObserver). Some potential candidates for filtering include logging and metrics.

The order of execution of these filters are in order of append. If 3 filters are added as follows:

     builder
         .appendConnectionFactoryFilter(filter1)
         .appendConnectionFactoryFilter(filter2)
         .appendConnectionFactoryFilter(filter3)
 

Calling ConnectionFactory wrapped by this filter chain, the order of invocation of these filters will be:

     filter1 ⇒ filter2 ⇒ filter3 ⇒ original connection factory
 

Parameters:

factory - ConnectionFactoryFilter to use.

Returns:

this

appendClientFilter

SingleAddressHttpClientBuilder<U,R> appendClientFilter(StreamingHttpClientFilterFactory factory)

Appends the filter to the chain of filters used to decorate the HttpClient created by this builder.

Note this method will be used to decorate the result of build() before it is returned to the user.

The order of execution of these filters are in order of append. If 3 filters are added as follows:

     builder.appendClientFilter(filter1).appendClientFilter(filter2).appendClientFilter(filter3)
 

making a request to a client wrapped by this filter chain the order of invocation of these filters will be:

     filter1 ⇒ filter2 ⇒ filter3 ⇒ client
 

Parameters:

factory - StreamingHttpClientFilterFactory to decorate a HttpClient for the purpose of filtering.

Returns:

this

appendClientFilter

SingleAddressHttpClientBuilder<U,R> appendClientFilter(Predicate<StreamingHttpRequest> predicate,
                                                       StreamingHttpClientFilterFactory factory)

Appends the filter to the chain of filters used to decorate the HttpClient created by this builder, for every request that passes the provided Predicate.

Note this method will be used to decorate the result of build() before it is returned to the user.

The order of execution of these filters are in order of append. If 3 filters are added as follows:

     builder.appendClientFilter(filter1).appendClientFilter(filter2).appendClientFilter(filter3)
 

making a request to a client wrapped by this filter chain the order of invocation of these filters will be:

     filter1 ⇒ filter2 ⇒ filter3 ⇒ client
 

Parameters:

predicate - the Predicate to test if the filter must be applied.

factory - StreamingHttpClientFilterFactory to decorate a HttpClient for the purpose of filtering.

Returns:

this

unresolvedAddressToHost

SingleAddressHttpClientBuilder<U,R> unresolvedAddressToHost(Function<U,CharSequence> unresolvedAddressToHostFunction)

Provides a means to convert U unresolved address type into a CharSequence. An example of where this maybe used is to convert the U to a default host header. It may also be used in the event of proxying.

Parameters:

unresolvedAddressToHostFunction - invoked to convert the U unresolved address type into a CharSequence suitable for use in Host Header format.

Returns:

this

serviceDiscoverer

SingleAddressHttpClientBuilder<U,R> serviceDiscoverer(ServiceDiscoverer<U,R,? extends ServiceDiscovererEvent<R>> serviceDiscoverer)

Sets a ServiceDiscoverer to resolve addresses of remote servers to connect to.

Parameters:

serviceDiscoverer - The ServiceDiscoverer to resolve addresses of remote servers to connect to. Lifecycle of the provided ServiceDiscoverer is managed externally and it should be closed after all built StreamingHttpClients will be closed and this ServiceDiscoverer is no longer needed.

Returns:

this.

retryServiceDiscoveryErrors

SingleAddressHttpClientBuilder<U,R> retryServiceDiscoveryErrors(BiIntFunction<Throwable,? extends Completable> retryStrategy)

Sets a retry strategy to retry errors emitted by ServiceDiscoverer.

Parameters:

retryStrategy - a retry strategy to retry errors emitted by ServiceDiscoverer.

Returns:

this.

See Also:

RetryStrategies

loadBalancerFactory

SingleAddressHttpClientBuilder<U,R> loadBalancerFactory(HttpLoadBalancerFactory<R> loadBalancerFactory)

Sets a HttpLoadBalancerFactory to create LoadBalancer instances.

Parameters:

loadBalancerFactory - HttpLoadBalancerFactory to create LoadBalancer instances.

Returns:

this.

sslConfig

SingleAddressHttpClientBuilder<U,R> sslConfig(ClientSslConfig sslConfig)

Set the SSL/TLS configuration.

Parameters:

sslConfig - The configuration to use.

Returns:

this.

See Also:

ClientSslConfigBuilder

inferPeerHost

SingleAddressHttpClientBuilder<U,R> inferPeerHost(boolean shouldInfer)

Toggle inference of value to use instead of ClientSslConfig.peerHost() from client's address when peer host is not specified. By default, inference is enabled.

Parameters:

shouldInfer - value indicating whether inference is on (true) or off (false).

Returns:

this

inferPeerPort

SingleAddressHttpClientBuilder<U,R> inferPeerPort(boolean shouldInfer)

Toggle inference of value to use instead of ClientSslConfig.peerPort() from client's address when peer port is not specified (equals -1). By default, inference is enabled.

Parameters:

shouldInfer - value indicating whether inference is on (true) or off (false).

Returns:

this

inferSniHostname

SingleAddressHttpClientBuilder<U,R> inferSniHostname(boolean shouldInfer)

Toggle SNI hostname inference from client's address if not explicitly specified via sslConfig(ClientSslConfig). By default, inference is enabled.

Parameters:

shouldInfer - value indicating whether inference is on (true) or off (false).

Returns:

this

buildStreaming

StreamingHttpClient buildStreaming()

Builds a new StreamingHttpClient.

Returns:

A new StreamingHttpClient

Throws:

IllegalArgumentException - for incomplete or illegal configurations

IllegalStateException - for unsupported configuration combinations

build

default HttpClient build()

Builds a new HttpClient.

Returns:

A new HttpClient

buildBlockingStreaming

default BlockingStreamingHttpClient buildBlockingStreaming()

Creates a new BlockingStreamingHttpClient.

Returns:

BlockingStreamingHttpClient

buildBlocking

default BlockingHttpClient buildBlocking()

Creates a new BlockingHttpClient.

Returns:

BlockingHttpClient