Package io.servicetalk.http.api

Interface MultiAddressHttpClientBuilder<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:

DelegatingMultiAddressHttpClientBuilder

public interface MultiAddressHttpClientBuilder<U,R>

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

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	MultiAddressHttpClientBuilder.SingleAddressInitializer<U,R>	Initializes the SingleAddressHttpClientBuilder for each new client.

Method Summary

Modifier and Type	Method	Description
default MultiAddressHttpClientBuilder<U,R>	appendClientFilter(StreamingHttpClientFilterFactory factory)	Appends the filter to the chain of filters used to decorate the HttpClient created by this builder.
default MultiAddressHttpClientBuilder<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.
MultiAddressHttpClientBuilder<U,R>	bufferAllocator(BufferAllocator allocator)
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.
default MultiAddressHttpClientBuilder<U,R>	defaultHttpPort(int port)	Configures the default port for the HTTP scheme if not explicitly provided as part of the HttpRequestMetaData.requestTarget().
default MultiAddressHttpClientBuilder<U,R>	defaultHttpsPort(int port)	Configures the default port for the HTTPS scheme if not explicitly provided as part of the HttpRequestMetaData.requestTarget().
MultiAddressHttpClientBuilder<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.
MultiAddressHttpClientBuilder<U,R>	executor(Executor executor)
MultiAddressHttpClientBuilder<U,R>	followRedirects(RedirectConfig config)	Configures redirection behavior.
default MultiAddressHttpClientBuilder<U,R>	headersFactory(HttpHeadersFactory headersFactory)	Sets the HttpHeadersFactory to be used for creating HttpHeaders for new requests.
MultiAddressHttpClientBuilder<U,R>	initializer(MultiAddressHttpClientBuilder.SingleAddressInitializer<U,R> initializer)	Set a function which can customize options for each StreamingHttpClient that is built.
MultiAddressHttpClientBuilder<U,R>	ioExecutor(IoExecutor ioExecutor)

Method Details

ioExecutor

MultiAddressHttpClientBuilder<U,R> ioExecutor(IoExecutor ioExecutor)

executor

MultiAddressHttpClientBuilder<U,R> executor(Executor executor)

executionStrategy

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

Provides the base execution strategy for all clients created from this builder and the default strategy for the SingleAddressHttpClientBuilder used to construct client instances. The initializer(SingleAddressInitializer) may be used for some customization of the execution strategy for a specific single address client instance, but may not reduce the offloading to be performed. Specifically, the initializer may introduce additional offloading via SingleAddressHttpClientBuilder.executionStrategy(HttpExecutionStrategy) and may add filters which influence the computed execution strategy.

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

Unspecified or HttpExecutionStrategies.defaultStrategy()

The resulting client instances will use the default safe strategy for each API variant and SingleAddressHttpClientBuilder instances generated will also have default strategy.

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

SingleAddressHttpClientBuilder instances created by the client will have a strategy of HttpExecutionStrategies.offloadNone(). HttpExecutionStrategies.offloadNone() execution strategy requires that filters and asynchronous callbacks must not ever block during the execution of client requests. An initializer may override to add offloads using SingleAddressHttpClientBuilder.executionStrategy(HttpExecutionStrategy).

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

SingleAddressHttpClientBuilder instances created by the client will start with the provided strategy and may add additional offloading as required by added filters.

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

MultiAddressHttpClientBuilder<U,R> bufferAllocator(BufferAllocator allocator)

headersFactory

default MultiAddressHttpClientBuilder<U,R> headersFactory(HttpHeadersFactory headersFactory)

Sets the HttpHeadersFactory to be used for creating HttpHeaders for new requests.

Parameters:

headersFactory - HttpHeadersFactory to be used for creating HttpHeaders for new requests

Returns:

this

initializer

MultiAddressHttpClientBuilder<U,R> initializer(MultiAddressHttpClientBuilder.SingleAddressInitializer<U,R> initializer)

Set a function which can customize options for each StreamingHttpClient that is built.

Parameters:

initializer - Initializes the SingleAddressHttpClientBuilder used to build new StreamingHttpClients. See executionStrategy(HttpExecutionStrategy) for discussion of restrictions on the use of SingleAddressHttpClientBuilder.executionStrategy(HttpExecutionStrategy) within an initializer.

Returns:

this

followRedirects

MultiAddressHttpClientBuilder<U,R> followRedirects(@Nullable
 RedirectConfig config)

Configures redirection behavior.

Parameters:

config - RedirectConfig to configure redirection behavior. It can be used to tune what requests should follow redirects and which parts of the original request (headers/payload body/trailers) should be redirected to non-relative locations. Use null to disable redirects.

Note that this filters location is last, or as if it had been appended right before building the client. If that is not the desired position you can disable redirects and use appendClientFilter(StreamingHttpClientFilterFactory) to place the RedirectingHttpRequesterFilter in the position of your choice.

Returns:

this.

See Also:

• RedirectConfigBuilder

defaultHttpPort

default MultiAddressHttpClientBuilder<U,R> defaultHttpPort(int port)

Configures the default port for the HTTP scheme if not explicitly provided as part of the HttpRequestMetaData.requestTarget().

Parameters:

port - the port that should be used if not explicitly provided for HTTP requests.

Returns:

this.

defaultHttpsPort

default MultiAddressHttpClientBuilder<U,R> defaultHttpsPort(int port)

Configures the default port for the HTTPS scheme if not explicitly provided as part of the HttpRequestMetaData.requestTarget().

Parameters:

port - the port that should be used if not explicitly provided for HTTPS requests.

Returns:

this.

appendClientFilter

default 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 but will always be before any filters applied to the underlying single address clients. 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

See Also:

• for adding filters to the underlying clients.

appendClientFilter

default MultiAddressHttpClientBuilder<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 but will always be before any filters applied to the underlying single address clients. 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

See Also:

• for adding filters to the underlying clients.

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