io.servicetalk.http.api

Class MultiAddressHttpClientBuilder<U,R>

java.lang.Object

io.servicetalk.http.api.MultiAddressHttpClientBuilder<U,R>

Type Parameters:

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

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

public abstract class MultiAddressHttpClientBuilder<U,R>
extends java.lang.Object

A builder of StreamingHttpClient instances which have a capacity to call any server based on the parsed absolute-form URL address information from each StreamingHttpRequest.

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.

See Also:

absolute-form rfc7230#section-5.3.2

Constructor Summary

Constructors

Constructor and Description
MultiAddressHttpClientBuilder()

Method Summary

Modifier and Type	Method and Description
abstract MultiAddressHttpClientBuilder<U,R>	appendClientFilter(MultiAddressHttpClientFilterFactory<U> factory) Appends the filter to the chain of filters used to decorate the StreamingHttpClient created by this builder for a given UnresolvedAddress.
MultiAddressHttpClientBuilder<U,R>	appendClientFilter(java.util.function.Predicate<StreamingHttpRequest> predicate, MultiAddressHttpClientFilterFactory<U> factory) Appends the filter to the chain of filters used to decorate the StreamingHttpClient created by this builder for a given UnresolvedAddress, for every request that passes the provided Predicate.
MultiAddressHttpClientBuilder<U,R>	appendClientFilter(java.util.function.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.
abstract MultiAddressHttpClientBuilder<U,R>	appendClientFilter(StreamingHttpClientFilterFactory factory) Appends the filter to the chain of filters used to decorate the HttpClient created by this builder.
abstract MultiAddressHttpClientBuilder<U,R>	appendConnectionFactoryFilter(ConnectionFactoryFilter<R,FilterableStreamingHttpConnection> factory) Appends the filter to the chain of filters used to decorate the ConnectionFactory used by this builder.
MultiAddressHttpClientBuilder<U,R>	appendConnectionFilter(java.util.function.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.
abstract MultiAddressHttpClientBuilder<U,R>	appendConnectionFilter(StreamingHttpConnectionFilterFactory factory) Appends the filter to the chain of filters used to decorate the StreamingHttpConnection created by this builder.
abstract MultiAddressHttpClientBuilder<U,R>	autoRetryStrategy(AutoRetryStrategyProvider autoRetryStrategyProvider) Updates the automatic retry strategy for the clients generated by this builder.
abstract MultiAddressHttpClientBuilder<U,R>	bufferAllocator(BufferAllocator allocator) Sets the BufferAllocator for all connections created from this builder.
HttpClient	build() Builds a new HttpClient, using a default ExecutionContext.
BlockingHttpClient	buildBlocking() Creates a new BlockingHttpClient, using a default ExecutionContext.
BlockingStreamingHttpClient	buildBlockingStreaming() Creates a new BlockingStreamingHttpClient, using a default ExecutionContext.
abstract StreamingHttpClient	buildStreaming() Builds a new StreamingHttpClient, using a default ExecutionContext.
abstract MultiAddressHttpClientBuilder<U,R>	disableHostHeaderFallback() Disables automatically setting Host headers by inferring from the address or HttpMetaData.
abstract MultiAddressHttpClientBuilder<U,R>	enableWireLogging(java.lang.String loggerName) Enables wire-logging for connections created by this builder.
abstract MultiAddressHttpClientBuilder<U,R>	executionStrategy(HttpExecutionStrategy strategy) Sets the HttpExecutionStrategy for all connections created from this builder.
abstract MultiAddressHttpClientBuilder<U,R>	ioExecutor(IoExecutor ioExecutor) Sets the IoExecutor for all connections created from this builder.
abstract MultiAddressHttpClientBuilder<U,R>	loadBalancerFactory(LoadBalancerFactory<R,FilterableStreamingHttpLoadBalancedConnection> loadBalancerFactory, java.util.function.Function<FilterableStreamingHttpConnection,FilterableStreamingHttpLoadBalancedConnection> protocolBinding) Sets a LoadBalancerFactory to generate LoadBalancer objects.
abstract MultiAddressHttpClientBuilder<U,R>	maxRedirects(int maxRedirects) Sets a maximum number of redirects to follow.
abstract io.servicetalk.http.api.HttpClientBuilder<U,R,SDE>	protocols(HttpProtocolConfig... protocols) Configurations of various HTTP protocol versions.
abstract MultiAddressHttpClientBuilder<U,R>	secure(java.util.function.BiConsumer<HostAndPort,ClientSecurityConfigurator> sslConfigFunction) Sets a function that is used for configuring SSL/TLS for https requests.
abstract MultiAddressHttpClientBuilder<U,R>	serviceDiscoverer(ServiceDiscoverer<U,R,? extends ServiceDiscovererEvent<R>> serviceDiscoverer) Sets a ServiceDiscoverer to resolve addresses of remote servers to connect to.
abstract <T> MultiAddressHttpClientBuilder<U,R>	socketOption(java.net.SocketOption<T> option, T value) Adds a SocketOption for all connections created by this builder.
abstract MultiAddressHttpClientBuilder<U,R>	unresolvedAddressToHost(java.util.function.Function<U,java.lang.CharSequence> unresolvedAddressToHostFunction) Provides a means to convert U unresolved address type into a CharSequence.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MultiAddressHttpClientBuilder

public MultiAddressHttpClientBuilder()

Method Detail

ioExecutor

public abstract MultiAddressHttpClientBuilder<U,R> ioExecutor(IoExecutor ioExecutor)

Sets the IoExecutor for all connections created from this builder.

Parameters:

ioExecutor - IoExecutor to use.

Returns:

this.

executionStrategy

public abstract MultiAddressHttpClientBuilder<U,R> executionStrategy(HttpExecutionStrategy strategy)

Sets the HttpExecutionStrategy for all connections created from this builder.

Parameters:

strategy - HttpExecutionStrategy to use.

Returns:

this.

bufferAllocator

public abstract MultiAddressHttpClientBuilder<U,R> bufferAllocator(BufferAllocator allocator)

Sets the BufferAllocator for all connections created from this builder.

Parameters:

allocator - BufferAllocator to use.

Returns:

this.

socketOption

public abstract <T> MultiAddressHttpClientBuilder<U,R> socketOption(java.net.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

public abstract MultiAddressHttpClientBuilder<U,R> enableWireLogging(java.lang.String loggerName)

Enables wire-logging for connections created by this builder.

All wire events will be logged at TRACE level.

Parameters:

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

Returns:

this.

disableHostHeaderFallback

public abstract MultiAddressHttpClientBuilder<U,R> disableHostHeaderFallback()

Disables automatically setting Host headers by inferring from the address or HttpMetaData.

This setting disables the default filter such that no Host header will be manipulated.

Returns:

this

See Also:

unresolvedAddressToHost(Function)

secure

public abstract MultiAddressHttpClientBuilder<U,R> secure(java.util.function.BiConsumer<HostAndPort,ClientSecurityConfigurator> sslConfigFunction)

Sets a function that is used for configuring SSL/TLS for https requests.

Parameters:

sslConfigFunction - The function to use for configuring SSL/TLS for https requests.

Returns:

this

appendConnectionFilter

public abstract MultiAddressHttpClientBuilder<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.append(filter1).append(filter2).append(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

public MultiAddressHttpClientBuilder<U,R> appendConnectionFilter(java.util.function.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.append(filter1).append(filter2).append(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:

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

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

Returns:

this

appendConnectionFactoryFilter

public abstract MultiAddressHttpClientBuilder<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). 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.append(filter1).append(filter2).append(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

autoRetryStrategy

public abstract MultiAddressHttpClientBuilder<U,R> autoRetryStrategy(AutoRetryStrategyProvider autoRetryStrategyProvider)

Updates the automatic retry strategy for the clients generated by this builder. Automatic retries are done by the clients automatically when allowed by the passed AutoRetryStrategyProvider. These retries are not a substitute for user level retries which are designed to infer retry decisions based on request/error information. Typically such user level retries are done using filters (eg: appendClientFilter(StreamingHttpClientFilterFactory)) but can also be done differently per request (eg: by using Single.retry(BiIntPredicate)).

Parameters:

autoRetryStrategyProvider - AutoRetryStrategyProvider for the automatic retry strategy.

Returns:

this

serviceDiscoverer

public abstract MultiAddressHttpClientBuilder<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.

loadBalancerFactory

public abstract MultiAddressHttpClientBuilder<U,R> loadBalancerFactory(LoadBalancerFactory<R,FilterableStreamingHttpLoadBalancedConnection> loadBalancerFactory,
                                                                       java.util.function.Function<FilterableStreamingHttpConnection,FilterableStreamingHttpLoadBalancedConnection> protocolBinding)

Sets a LoadBalancerFactory to generate LoadBalancer objects.

Parameters:

loadBalancerFactory - The LoadBalancerFactory which generates LoadBalancer objects.

protocolBinding - The Function that bridges the HTTP protocol to the FilterableStreamingHttpLoadBalancedConnection which exposes a ScoreSupplier.score() function which may inform the LoadBalancer created from the provided loadBalancerFactory while making connection selection decisions.

Returns:

this.

unresolvedAddressToHost

public abstract MultiAddressHttpClientBuilder<U,R> unresolvedAddressToHost(java.util.function.Function<U,java.lang.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

appendClientFilter

public abstract MultiAddressHttpClientBuilder<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.append(filter1).append(filter2).append(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

public MultiAddressHttpClientBuilder<U,R> appendClientFilter(java.util.function.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.append(filter1).append(filter2).append(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

appendClientFilter

public abstract MultiAddressHttpClientBuilder<U,R> appendClientFilter(MultiAddressHttpClientFilterFactory<U> factory)

Appends the filter to the chain of filters used to decorate the StreamingHttpClient created by this builder for a given UnresolvedAddress.

Note this method will be used to decorate the result of buildStreaming() 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.append(filter1).append(filter2).append(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 - MultiAddressHttpClientFilterFactory to decorate a StreamingHttpClient for the purpose of filtering.

Returns:

this

appendClientFilter

public MultiAddressHttpClientBuilder<U,R> appendClientFilter(java.util.function.Predicate<StreamingHttpRequest> predicate,
                                                             MultiAddressHttpClientFilterFactory<U> factory)

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

Note this method will be used to decorate the result of buildStreaming() 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.append(filter1).append(filter2).append(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 - MultiAddressHttpClientFilterFactory to decorate a StreamingHttpClient for the purpose of filtering.

Returns:

this

maxRedirects

public abstract MultiAddressHttpClientBuilder<U,R> maxRedirects(int maxRedirects)

Sets a maximum number of redirects to follow.

Parameters:

maxRedirects - A maximum number of redirects to follow. 0 disables redirects.

Returns:

this.

protocols

public abstract io.servicetalk.http.api.HttpClientBuilder<U,R,SDE> 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 are secured.

Parameters:

protocols - HttpProtocolConfig for each protocol that should be supported.

Returns:

this.

buildStreaming

public abstract StreamingHttpClient buildStreaming()

Builds a new StreamingHttpClient, using a default ExecutionContext.

Returns:

A new StreamingHttpClient

build

public final HttpClient build()

Builds a new HttpClient, using a default ExecutionContext.

Returns:

A new HttpClient

buildBlockingStreaming

public final BlockingStreamingHttpClient buildBlockingStreaming()

Creates a new BlockingStreamingHttpClient, using a default ExecutionContext.

Returns:

BlockingStreamingHttpClient

buildBlocking

public final BlockingHttpClient buildBlocking()

Creates a new BlockingHttpClient, using a default ExecutionContext.

Returns:

BlockingHttpClient