io.servicetalk.http.api

Class PartitionedHttpClientBuilder<U,R>

Object

PartitionedHttpClientBuilder<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 PartitionedHttpClientBuilder<U,R>
extends Object

A builder of homogeneous StreamingHttpClient instances which call the server associated with a partition selected from a set of PartitionedServiceDiscovererEvents resolved from a single unresolved address.

Partition selection uses a function to infer PartitionAttributes from the HttpRequestMetaData. 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.

Constructor Summary

Constructors

Constructor and Description
PartitionedHttpClientBuilder()

Method Summary

Modifier and Type	Method and Description
abstract PartitionedHttpClientBuilder<U,R>	appendClientBuilderFilter(PartitionHttpClientBuilderConfigurator<U,R> clientFilterFunction) Sets a function that allows customizing the SingleAddressHttpClientBuilder used to create the client for a given partition based on its PartitionAttributes.
PartitionedHttpClientBuilder<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.
abstract PartitionedHttpClientBuilder<U,R>	appendClientFilter(StreamingHttpClientFilterFactory function) Appends the filter to the chain of filters used to decorate the HttpClient created by this builder.
abstract PartitionedHttpClientBuilder<U,R>	appendConnectionFactoryFilter(ConnectionFactoryFilter<R,FilterableStreamingHttpConnection> factory) Appends the filter to the chain of filters used to decorate the ConnectionFactory used by this builder.
PartitionedHttpClientBuilder<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.
abstract PartitionedHttpClientBuilder<U,R>	appendConnectionFilter(StreamingHttpConnectionFilterFactory factory) Appends the filter to the chain of filters used to decorate the StreamingHttpConnection created by this builder.
abstract PartitionedHttpClientBuilder<U,R>	autoRetryStrategy(AutoRetryStrategyProvider autoRetryStrategyProvider) Updates the automatic retry strategy for the clients generated by this builder.
abstract PartitionedHttpClientBuilder<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 PartitionedHttpClientBuilder<U,R>	disableHostHeaderFallback() Disables automatically setting Host headers by inferring from the address or HttpMetaData.
abstract PartitionedHttpClientBuilder<U,R>	enableWireLogging(String loggerName) Deprecated.
abstract PartitionedHttpClientBuilder<U,R>	enableWireLogging(String loggerName, LogLevel logLevel, BooleanSupplier logUserData) Enables wire-logging for connections created by this builder.
abstract PartitionedHttpClientBuilder<U,R>	executionStrategy(HttpExecutionStrategy strategy) Sets the HttpExecutionStrategy for all connections created from this builder.
abstract PartitionedHttpClientBuilder<U,R>	ioExecutor(IoExecutor ioExecutor) Sets the IoExecutor for all connections created from this builder.
abstract PartitionedHttpClientBuilder<U,R>	loadBalancerFactory(HttpLoadBalancerFactory<R> loadBalancerFactory) Sets a HttpLoadBalancerFactory to create LoadBalancer instances.
abstract PartitionedHttpClientBuilder<U,R>	partitionMapFactory(PartitionMapFactory partitionMapFactory) Sets PartitionMapFactory to use by all StreamingHttpClients created by this builder.
abstract PartitionedHttpClientBuilder<U,R>	protocols(HttpProtocolConfig... protocols) Configurations of various HTTP protocol versions.
abstract PartitionedHttpClientBuilder<U,R>	retryServiceDiscoveryErrors(ServiceDiscoveryRetryStrategy<R,PartitionedServiceDiscovererEvent<R>> retryStrategy) Sets a retry strategy to retry errors emitted by ServiceDiscoverer.
abstract PartitionedHttpClientSecurityConfigurator<U,R>	secure() Initiates security configuration for this client.
abstract PartitionedHttpClientBuilder<U,R>	serviceDiscoverer(ServiceDiscoverer<U,R,PartitionedServiceDiscovererEvent<R>> serviceDiscoverer) Sets a ServiceDiscoverer to resolve addresses of remote servers to connect to.
abstract PartitionedHttpClientBuilder<U,R>	serviceDiscoveryMaxQueueSize(int serviceDiscoveryMaxQueueSize) Sets the maximum amount of ServiceDiscovererEvent objects that will be queued for each partition.
abstract <T> PartitionedHttpClientBuilder<U,R>	socketOption(SocketOption<T> option, T value) Adds a SocketOption for all connections created by this builder.
abstract PartitionedHttpClientBuilder<U,R>	unresolvedAddressToHost(Function<U,CharSequence> unresolvedAddressToHostFunction) Provides a means to convert U unresolved address type into a CharSequence.

Methods inherited from class Object

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

Constructor Detail

PartitionedHttpClientBuilder

public PartitionedHttpClientBuilder()

Method Detail

ioExecutor

public abstract PartitionedHttpClientBuilder<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 PartitionedHttpClientBuilder<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 PartitionedHttpClientBuilder<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> PartitionedHttpClientBuilder<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

@Deprecated
public abstract PartitionedHttpClientBuilder<U,R> enableWireLogging(String loggerName)

Deprecated.

Enables wire-logging for connections created by this builder.

Parameters:

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

Returns:

this.

enableWireLogging

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

Returns:

this.

protocols

public abstract PartitionedHttpClientBuilder<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 are secured.

Parameters:

protocols - HttpProtocolConfig for each protocol that should be supported.

Returns:

this.

appendConnectionFilter

public abstract PartitionedHttpClientBuilder<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 PartitionedHttpClientBuilder<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.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 PartitionedHttpClientBuilder<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, 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.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

disableHostHeaderFallback

public abstract PartitionedHttpClientBuilder<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:

MultiAddressHttpClientBuilder.unresolvedAddressToHost(Function)

autoRetryStrategy

public abstract PartitionedHttpClientBuilder<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 PartitionedHttpClientBuilder<U,R> serviceDiscoverer(ServiceDiscoverer<U,R,PartitionedServiceDiscovererEvent<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

public abstract PartitionedHttpClientBuilder<U,R> retryServiceDiscoveryErrors(ServiceDiscoveryRetryStrategy<R,PartitionedServiceDiscovererEvent<R>> retryStrategy)

Sets a retry strategy to retry errors emitted by ServiceDiscoverer.

Parameters:

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

Returns:

this.

loadBalancerFactory

public abstract PartitionedHttpClientBuilder<U,R> loadBalancerFactory(HttpLoadBalancerFactory<R> loadBalancerFactory)

Sets a HttpLoadBalancerFactory to create LoadBalancer instances.

Parameters:

loadBalancerFactory - HttpLoadBalancerFactory to create LoadBalancer instances.

Returns:

this.

unresolvedAddressToHost

public abstract PartitionedHttpClientBuilder<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

appendClientFilter

public abstract PartitionedHttpClientBuilder<U,R> appendClientFilter(StreamingHttpClientFilterFactory function)

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:

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

Returns:

this

appendClientFilter

public PartitionedHttpClientBuilder<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.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

secure

public abstract PartitionedHttpClientSecurityConfigurator<U,R> secure()

Initiates security configuration for this client. Calling PartitionedHttpClientSecurityConfigurator.commit() on the returned PartitionedHttpClientSecurityConfigurator will commit the configuration.

Returns:

PartitionHttpClientBuilderConfigurator to configure security for this client. It is mandatory to call commit after all configuration is done.

serviceDiscoveryMaxQueueSize

public abstract PartitionedHttpClientBuilder<U,R> serviceDiscoveryMaxQueueSize(int serviceDiscoveryMaxQueueSize)

Sets the maximum amount of ServiceDiscovererEvent objects that will be queued for each partition.

It is assumed that the PublisherSource.Subscribers will process events in a timely manner (typically synchronously) so this typically doesn't need to be very large.

Parameters:

serviceDiscoveryMaxQueueSize - the maximum amount of ServiceDiscovererEvent objects that will be queued for each partition.

Returns:

this.

partitionMapFactory

public abstract PartitionedHttpClientBuilder<U,R> partitionMapFactory(PartitionMapFactory partitionMapFactory)

Sets PartitionMapFactory to use by all StreamingHttpClients created by this builder.

Parameters:

partitionMapFactory - PartitionMapFactory to use.

Returns:

this.

appendClientBuilderFilter

public abstract PartitionedHttpClientBuilder<U,R> appendClientBuilderFilter(PartitionHttpClientBuilderConfigurator<U,R> clientFilterFunction)

Sets a function that allows customizing the SingleAddressHttpClientBuilder used to create the client for a given partition based on its PartitionAttributes.

Parameters:

clientFilterFunction - BiFunction used to customize the SingleAddressHttpClientBuilder before creating the client for the partition

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