Package io.servicetalk.http.api

Class SingleAddressHttpClientBuilder<U,R>

java.lang.Object

io.servicetalk.http.api.SingleAddressHttpClientBuilder<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 SingleAddressHttpClientBuilder<U,R>
extends java.lang.Object

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.

Constructor Summary

Constructors

Constructor	Description
SingleAddressHttpClientBuilder()

Method Summary

Modifier and Type	Method	Description
abstract SingleAddressHttpClientBuilder<U,R>	allowDropResponseTrailers(boolean allowDrop)	Provide a hint if response trailers are allowed to be dropped.
abstract 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>	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 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.
abstract 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>	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 SingleAddressHttpClientBuilder<U,R>	autoRetryStrategy(AutoRetryStrategyProvider autoRetryStrategyProvider)	Updates the automatic retry strategy for the clients generated by this builder.
abstract SingleAddressHttpClientBuilder<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 SingleAddressHttpClientBuilder<U,R>	disableHostHeaderFallback()	Disables automatically setting Host headers by inferring from the address or HttpMetaData.
abstract SingleAddressHttpClientBuilder<U,R>	enableWireLogging(java.lang.String loggerName)	Deprecated.
abstract SingleAddressHttpClientBuilder<U,R>	enableWireLogging(java.lang.String loggerName, LogLevel logLevel, java.util.function.BooleanSupplier logUserData)	Enables wire-logging for connections created by this builder.
abstract SingleAddressHttpClientBuilder<U,R>	executionStrategy(HttpExecutionStrategy strategy)	Sets the HttpExecutionStrategy for all connections created from this builder.
abstract SingleAddressHttpClientBuilder<U,R>	ioExecutor(IoExecutor ioExecutor)	Sets the IoExecutor for all connections created from this builder.
abstract SingleAddressHttpClientBuilder<U,R>	loadBalancerFactory(HttpLoadBalancerFactory<R> loadBalancerFactory)	Sets a HttpLoadBalancerFactory to create LoadBalancer instances.
abstract SingleAddressHttpClientBuilder<U,R>	protocols(HttpProtocolConfig... protocols)	Configurations of various HTTP protocol versions.
abstract SingleAddressHttpClientBuilder<U,R>	retryServiceDiscoveryErrors(ServiceDiscoveryRetryStrategy<R,ServiceDiscovererEvent<R>> retryStrategy)	Sets a retry strategy to retry errors emitted by ServiceDiscoverer.
abstract SingleAddressHttpClientSecurityConfigurator<U,R>	secure()	Deprecated. Use sslConfig(ClientSslConfig).
abstract SingleAddressHttpClientBuilder<U,R>	serviceDiscoverer(ServiceDiscoverer<U,R,ServiceDiscovererEvent<R>> serviceDiscoverer)	Sets a ServiceDiscoverer to resolve addresses of remote servers to connect to.
abstract <T> SingleAddressHttpClientBuilder<U,R>	socketOption(java.net.SocketOption<T> option, T value)	Adds a SocketOption for all connections created by this builder.
abstract SingleAddressHttpClientBuilder<U,R>	sslConfig(ClientSslConfig sslConfig)	Set the SSL/TLS configuration.
abstract SingleAddressHttpClientBuilder<U,R>	unresolvedAddressToHost(java.util.function.Function<U,java.lang.CharSequence> unresolvedAddressToHostFunction)	Provides a means to convert SingleAddressHttpClientBuilder 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

SingleAddressHttpClientBuilder

public SingleAddressHttpClientBuilder()

Method Detail

ioExecutor

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

@Deprecated
public abstract SingleAddressHttpClientBuilder<U,R> enableWireLogging(java.lang.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 SingleAddressHttpClientBuilder<U,R> enableWireLogging(java.lang.String loggerName,
                                                                            LogLevel logLevel,
                                                                            java.util.function.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 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.

appendConnectionFilter

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

allowDropResponseTrailers

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

autoRetryStrategy

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

public abstract SingleAddressHttpClientBuilder<U,R> retryServiceDiscoveryErrors(ServiceDiscoveryRetryStrategy<R,ServiceDiscovererEvent<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 SingleAddressHttpClientBuilder<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 SingleAddressHttpClientBuilder<U,R> unresolvedAddressToHost(java.util.function.Function<U,java.lang.CharSequence> unresolvedAddressToHostFunction)

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

Parameters:

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

Returns:

this

appendClientFilter

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

secure

@Deprecated
public abstract SingleAddressHttpClientSecurityConfigurator<U,R> secure()

Deprecated.

Use sslConfig(ClientSslConfig).

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

Returns:

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

sslConfig

public abstract SingleAddressHttpClientBuilder<U,R> sslConfig(ClientSslConfig sslConfig)

Set the SSL/TLS configuration.

Parameters:

sslConfig - The configuration to use.

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