org.apache.hc.client5.http.websocket.client

Class WebSocketClientBuilder

java.lang.Object

org.apache.hc.client5.http.websocket.client.WebSocketClientBuilder

public final class WebSocketClientBuilder
extends Object

Builder for CloseableWebSocketClient instances.

This builder assembles a WebSocket client on top of the asynchronous HTTP/1.1 requester and connection pool infrastructure provided by HttpComponents Core. Unless otherwise specified, sensible defaults are used for all components.

The resulting CloseableWebSocketClient manages its own I/O reactor and connection pool and must be closed when no longer needed.

Builders are mutable and not thread-safe. Configure the instance on a single thread and then call build().

Since:

5.7

Method Summary

Modifier and Type	Method and Description
CloseableWebSocketClient	build() Builds a new CloseableWebSocketClient instance using the current builder configuration.
static WebSocketClientBuilder	create() Creates a new WebSocketClientBuilder instance.
WebSocketClientBuilder	defaultConfig(WebSocketClientConfig defaultConfig) Sets the default configuration applied to WebSocket connections created by the resulting client.
WebSocketClientBuilder	setCharCodingConfig(CharCodingConfig charCodingConfig) Sets the character coding configuration for HTTP message processing.
WebSocketClientBuilder	setConnectionReuseStrategy(ConnectionReuseStrategy connStrategy) Sets the connection reuse strategy for persistent HTTP connections.
WebSocketClientBuilder	setConnPoolListener(ConnPoolListener<HttpHost> connPoolListener) Sets a listener for connection pool events.
WebSocketClientBuilder	setDefaultMaxPerRoute(int defaultMaxPerRoute) Sets the default maximum number of connections per route.
WebSocketClientBuilder	setExceptionCallback(Callback<Exception> exceptionCallback) Sets a callback to be notified of fatal I/O exceptions.
WebSocketClientBuilder	setH2Config(H2Config h2Config) Sets the HTTP/2 configuration for the underlying H2 requester.
WebSocketClientBuilder	setH2HttpProcessor(HttpProcessor h2HttpProcessor) Sets a custom HttpProcessor for the HTTP/2 requester.
WebSocketClientBuilder	setHttp1Config(Http1Config http1Config) Sets the HTTP/1.1 configuration for the underlying requester.
WebSocketClientBuilder	setHttpProcessor(HttpProcessor httpProcessor) Sets a custom HttpProcessor for HTTP/1.1 requests.
WebSocketClientBuilder	setIOReactorConfig(IOReactorConfig ioReactorConfig) Sets the I/O reactor configuration.
WebSocketClientBuilder	setIOSessionDecorator(Decorator<IOSession> ioSessionDecorator) Sets a decorator for low-level I/O sessions created by the reactor.
WebSocketClientBuilder	setIOSessionListener(IOSessionListener sessionListener) Sets a listener for I/O session lifecycle events.
WebSocketClientBuilder	setMaxPendingCommandsPerConnection(int maxPendingCommandsPerConnection) Sets the maximum number of pending commands per HTTP/1.1 connection.
WebSocketClientBuilder	setMaxTotal(int maxTotal) Sets the maximum total number of connections in the pool.
WebSocketClientBuilder	setPoolConcurrencyPolicy(PoolConcurrencyPolicy poolConcurrencyPolicy) Sets the concurrency policy for the connection pool.
WebSocketClientBuilder	setPoolReusePolicy(PoolReusePolicy poolReusePolicy) Sets the reuse policy for connections in the pool.
WebSocketClientBuilder	setReactorMetricsListener(IOReactorMetricsListener reactorMetricsListener) Sets a metrics listener for the I/O reactor.
WebSocketClientBuilder	setStreamListener(Http1StreamListener streamListener) Sets a listener for HTTP/1.1 stream events.
WebSocketClientBuilder	setThreadFactory(ThreadFactory threadFactory) Sets the thread factory used to create the main I/O reactor thread.
WebSocketClientBuilder	setTimeToLive(Timeout timeToLive) Sets the time-to-live for persistent connections in the pool.
WebSocketClientBuilder	setTlsHandshakeTimeout(Timeout handshakeTimeout) Sets the timeout for the TLS handshake.
WebSocketClientBuilder	setTlsStrategy(TlsStrategy tlsStrategy) Sets the TLS strategy used to establish HTTPS or WSS connections.

Methods inherited from class java.lang.Object

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

Method Detail

create

public static WebSocketClientBuilder create()

Creates a new WebSocketClientBuilder instance.

Returns:

a new builder.

defaultConfig

public WebSocketClientBuilder defaultConfig(WebSocketClientConfig defaultConfig)

Sets the default configuration applied to WebSocket connections created by the resulting client.

Parameters:

defaultConfig - default WebSocket configuration; if null the existing default is retained.

Returns:

this builder.

setIOReactorConfig

public WebSocketClientBuilder setIOReactorConfig(IOReactorConfig ioReactorConfig)

Sets the I/O reactor configuration.

Parameters:

ioReactorConfig - I/O reactor configuration, or null to use IOReactorConfig.DEFAULT.

Returns:

this builder.

setHttp1Config

public WebSocketClientBuilder setHttp1Config(Http1Config http1Config)

Sets the HTTP/1.1 configuration for the underlying requester.

Parameters:

http1Config - HTTP/1.1 configuration, or null to use Http1Config.DEFAULT.

Returns:

this builder.

setCharCodingConfig

public WebSocketClientBuilder setCharCodingConfig(CharCodingConfig charCodingConfig)

Sets the character coding configuration for HTTP message processing.

Parameters:

charCodingConfig - character coding configuration, or null to use CharCodingConfig.DEFAULT.

Returns:

this builder.

setHttpProcessor

public WebSocketClientBuilder setHttpProcessor(HttpProcessor httpProcessor)

Sets a custom HttpProcessor for HTTP/1.1 requests.

Parameters:

httpProcessor - HTTP processor, or null to use HttpProcessors.client().

Returns:

this builder.

setH2HttpProcessor

public WebSocketClientBuilder setH2HttpProcessor(HttpProcessor h2HttpProcessor)

Sets a custom HttpProcessor for the HTTP/2 requester.

Parameters:

h2HttpProcessor - HTTP/2 processor, or null to use H2Processors.client().

Returns:

this builder.

setConnectionReuseStrategy

public WebSocketClientBuilder setConnectionReuseStrategy(ConnectionReuseStrategy connStrategy)

Sets the connection reuse strategy for persistent HTTP connections.

Parameters:

connStrategy - connection reuse strategy, or null to use DefaultClientConnectionReuseStrategy.

Returns:

this builder.

setDefaultMaxPerRoute

public WebSocketClientBuilder setDefaultMaxPerRoute(int defaultMaxPerRoute)

Sets the default maximum number of connections per route.

Parameters:

defaultMaxPerRoute - maximum connections per route; values ≤ 0 cause the default of 20 to be used.

Returns:

this builder.

setMaxTotal

public WebSocketClientBuilder setMaxTotal(int maxTotal)

Sets the maximum total number of connections in the pool.

Parameters:

maxTotal - maximum total connections; values ≤ 0 cause the default of 50 to be used.

Returns:

this builder.

setTimeToLive

public WebSocketClientBuilder setTimeToLive(Timeout timeToLive)

Sets the time-to-live for persistent connections in the pool.

Parameters:

timeToLive - connection time-to-live, or null to use Timeout.DISABLED.

Returns:

this builder.

setPoolReusePolicy

public WebSocketClientBuilder setPoolReusePolicy(PoolReusePolicy poolReusePolicy)

Sets the reuse policy for connections in the pool.

Parameters:

poolReusePolicy - reuse policy, or null to use PoolReusePolicy.LIFO.

Returns:

this builder.

setPoolConcurrencyPolicy

public WebSocketClientBuilder setPoolConcurrencyPolicy(PoolConcurrencyPolicy poolConcurrencyPolicy)

Sets the concurrency policy for the connection pool.

Parameters:

poolConcurrencyPolicy - concurrency policy, or null to use PoolConcurrencyPolicy.STRICT.

Returns:

this builder.

setMaxPendingCommandsPerConnection

public WebSocketClientBuilder setMaxPendingCommandsPerConnection(int maxPendingCommandsPerConnection)

Sets the maximum number of pending commands per HTTP/1.1 connection.

This setting only applies to the HTTP/1.1 requester used for WebSocket upgrade handshakes. It has no effect on HTTP/2 streams.

Parameters:

maxPendingCommandsPerConnection - maximum pending commands; values < 0 cause the default of 0 to be used.

Returns:

this builder.

setTlsStrategy

public WebSocketClientBuilder setTlsStrategy(TlsStrategy tlsStrategy)

Sets the TLS strategy used to establish HTTPS or WSS connections.

Parameters:

tlsStrategy - TLS strategy, or null to use BasicClientTlsStrategy.

Returns:

this builder.

setTlsHandshakeTimeout

public WebSocketClientBuilder setTlsHandshakeTimeout(Timeout handshakeTimeout)

Sets the timeout for the TLS handshake.

Parameters:

handshakeTimeout - handshake timeout, or null for no specific timeout.

Returns:

this builder.

setIOSessionDecorator

public WebSocketClientBuilder setIOSessionDecorator(Decorator<IOSession> ioSessionDecorator)

Sets a decorator for low-level I/O sessions created by the reactor.

Parameters:

ioSessionDecorator - decorator, or null for none.

Returns:

this builder.

setExceptionCallback

public WebSocketClientBuilder setExceptionCallback(Callback<Exception> exceptionCallback)

Sets a callback to be notified of fatal I/O exceptions.

Parameters:

exceptionCallback - exception callback, or null to use WsLoggingExceptionCallback.INSTANCE.

Returns:

this builder.

setIOSessionListener

public WebSocketClientBuilder setIOSessionListener(IOSessionListener sessionListener)

Sets a listener for I/O session lifecycle events.

Parameters:

sessionListener - session listener, or null for none.

Returns:

this builder.

setH2Config

public WebSocketClientBuilder setH2Config(H2Config h2Config)

Sets the HTTP/2 configuration for the underlying H2 requester.

Parameters:

h2Config - HTTP/2 configuration, or null to use H2Config.DEFAULT.

Returns:

this builder.

setStreamListener

public WebSocketClientBuilder setStreamListener(Http1StreamListener streamListener)

Sets a listener for HTTP/1.1 stream events.

Parameters:

streamListener - stream listener, or null for none.

Returns:

this builder.

setConnPoolListener

public WebSocketClientBuilder setConnPoolListener(ConnPoolListener<HttpHost> connPoolListener)

Sets a listener for connection pool events.

Parameters:

connPoolListener - pool listener, or null for none.

Returns:

this builder.

setThreadFactory

public WebSocketClientBuilder setThreadFactory(ThreadFactory threadFactory)

Sets the thread factory used to create the main I/O reactor thread.

Parameters:

threadFactory - thread factory, or null to use a DefaultThreadFactory named "websocket-main".

Returns:

this builder.

setReactorMetricsListener

public WebSocketClientBuilder setReactorMetricsListener(IOReactorMetricsListener reactorMetricsListener)

Sets a metrics listener for the I/O reactor.

Parameters:

reactorMetricsListener - metrics listener, or null for none.

Returns:

this builder.

build

public CloseableWebSocketClient build()

Builds a new CloseableWebSocketClient instance using the current builder configuration.

The returned client owns its underlying I/O reactor and connection pool and must be closed to release system resources.

Returns:

a newly created CloseableWebSocketClient.