Package com.linecorp.armeria.client.websocket

Class WebSocketClientBuilder

java.lang.Object

com.linecorp.armeria.client.AbstractClientOptionsBuilder

com.linecorp.armeria.client.AbstractWebClientBuilder

com.linecorp.armeria.client.websocket.WebSocketClientBuilder

@UnstableApi
public final class WebSocketClientBuilder
extends AbstractWebClientBuilder

Builds a WebSocketClient. This client has the different default options from WebClient. Here are the differences:

• ClientOptions.RESPONSE_TIMEOUT_MILLIS is 0.
• ClientOptions.MAX_RESPONSE_LENGTH is 0.
• ClientOptions.REQUEST_AUTO_ABORT_DELAY_MILLIS is 5000.
• ClientOptions.AUTO_FILL_ORIGIN_HEADER is true.

Method Summary

Modifier and Type	Method	Description
WebSocketClientBuilder	addHeader(CharSequence name, Object value)	Adds the default HTTP header for an HttpRequest that will be sent by this Client.
WebSocketClientBuilder	addHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> headers)	Adds the default HTTP headers for an HttpRequest that will be sent by this Client.
WebSocketClientBuilder	aggregateContinuation(boolean aggregateContinuation)	Sets whether to aggregate the subsequent continuation frames of the incoming WebSocketFrameType.TEXT or WebSocketFrameType.BINARY frame into a single WebSocketFrameType.TEXT or WebSocketFrameType.BINARY frame.
WebSocketClientBuilder	allowMaskMismatch(boolean allowMaskMismatch)	Sets whether the decoder allows to loosen the masking requirement on received frames.
WebSocketClientBuilder	auth(AuthToken token)	Sets the AuthToken header using HttpHeaderNames.AUTHORIZATION.
WebSocketClientBuilder	auth(BasicToken token)	Sets the HTTP basic access authentication header using HttpHeaderNames.AUTHORIZATION.
WebSocketClientBuilder	auth(OAuth1aToken token)	Sets the OAuth Core 1.0 Revision A header using HttpHeaderNames.AUTHORIZATION.
WebSocketClientBuilder	auth(OAuth2Token token)	Sets the OAuth 2.0 header using HttpHeaderNames.AUTHORIZATION.
WebSocketClientBuilder	autoFillOriginHeader(boolean autoFillOriginHeader)	Sets whether to add an HttpHeaderNames.ORIGIN header automatically when sending an HttpRequest when the HttpRequest.headers() does not have it.
WebSocketClient	build()	Returns a newly-created WebSocketClient based on the properties of this builder.
WebSocketClientBuilder	clearDecorators()	Clears all HTTP-level and RPC-level decorators set so far.
WebSocketClientBuilder	contextCustomizer(Consumer<? super ClientRequestContext> contextCustomizer)	Adds the specified ClientRequestContext customizer function so that it customizes the context in the thread that initiated the client call.
WebSocketClientBuilder	contextHook(Supplier<? extends AutoCloseable> contextHook)	Sets the Supplier which provides an AutoCloseable and will be called whenever this RequestContext is popped from the RequestContextStorage.
WebSocketClientBuilder	decorator(DecoratingHttpClientFunction decorator)	Adds the specified HTTP-level decorator.
WebSocketClientBuilder	decorator(Function<? super HttpClient,? extends HttpClient> decorator)	Adds the specified HTTP-level decorator.
WebSocketClientBuilder	endpointRemapper(Function<? super Endpoint,? extends EndpointGroup> endpointRemapper)	Sets a Function that remaps an Endpoint into an EndpointGroup.
WebSocketClientBuilder	factory(ClientFactory factory)	Sets the ClientFactory used for creating a client.
WebSocketClientBuilder	followRedirects()	Enables automatic redirection.
WebSocketClientBuilder	followRedirects(RedirectConfig redirectConfig)	Sets the RedirectConfig to enable automatic redirection.
WebSocketClientBuilder	maxFramePayloadLength(int maxFramePayloadLength)	Sets the maximum length of a frame's payload.
WebSocketClientBuilder	maxResponseLength(long maxResponseLength)	Sets the maximum allowed length of a server response in bytes.
<T> WebSocketClientBuilder	option(ClientOption<T> option, T value)	Adds the specified ClientOption and its value.
<T> WebSocketClientBuilder	option(ClientOptionValue<T> optionValue)	Adds the specified ClientOptionValue.
WebSocketClientBuilder	options(ClientOptions options)	Adds the specified ClientOptions.
WebSocketClientBuilder	options(ClientOptionValue<?>... options)	Adds the specified ClientOptionValues.
WebSocketClientBuilder	options(Iterable<ClientOptionValue<?>> options)	Adds the specified ClientOptionValues.
WebSocketClientBuilder	requestAutoAbortDelay(Duration delay)	Sets the amount of time to wait before aborting an HttpRequest when its corresponding HttpResponse is complete.
WebSocketClientBuilder	requestAutoAbortDelayMillis(long delayMillis)	Sets the amount of time in millis to wait before aborting an HttpRequest when its corresponding HttpResponse is complete.
WebSocketClientBuilder	requestIdGenerator(Supplier<RequestId> requestIdGenerator)	Sets the Supplier that generates a RequestId.
WebSocketClientBuilder	responseTimeout(Duration responseTimeout)	Sets the timeout of a response.
WebSocketClientBuilder	responseTimeoutMillis(long responseTimeoutMillis)	Sets the timeout of a response in milliseconds.
WebSocketClientBuilder	rpcDecorator(DecoratingRpcClientFunction decorator)	Deprecated.
WebSocketClientBuilder	rpcDecorator(Function<? super RpcClient,? extends RpcClient> decorator)	Deprecated.
WebSocketClientBuilder	setHeader(CharSequence name, Object value)	Sets the default HTTP header for an HttpRequest that will be sent by this Client.
WebSocketClientBuilder	setHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> headers)	Sets the default HTTP headers for an HttpRequest that will be sent by this Client.
WebSocketClientBuilder	subprotocols(Iterable<String> subprotocols)	Sets the subprotocols to use with the WebSocket Protocol.
WebSocketClientBuilder	subprotocols(String... subprotocols)	Sets the subprotocols to use with the WebSocket Protocol.
WebSocketClientBuilder	successFunction(SuccessFunction successFunction)	Sets a SuccessFunction that determines whether a request was handled successfully or not.
WebSocketClientBuilder	writeTimeout(Duration writeTimeout)	Sets the timeout of a socket write attempt.
WebSocketClientBuilder	writeTimeoutMillis(long writeTimeoutMillis)	Sets the timeout of a socket write attempt in milliseconds.

Methods inherited from class com.linecorp.armeria.client.AbstractWebClientBuilder

buildWebClient, clientBuilderParams

Methods inherited from class com.linecorp.armeria.client.AbstractClientOptionsBuilder

buildOptions, buildOptions

Methods inherited from class java.lang.Object

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

Method Details

maxFramePayloadLength

public WebSocketClientBuilder maxFramePayloadLength(int maxFramePayloadLength)

Sets the maximum length of a frame's payload. 65535 is used by default.

allowMaskMismatch

public WebSocketClientBuilder allowMaskMismatch(boolean allowMaskMismatch)

Sets whether the decoder allows to loosen the masking requirement on received frames. It's not allowed by default.

subprotocols

public WebSocketClientBuilder subprotocols(String... subprotocols)

Sets the subprotocols to use with the WebSocket Protocol.

See Also:

• Subprotocols Using the WebSocket Protocol

subprotocols

public WebSocketClientBuilder subprotocols(Iterable<String> subprotocols)

Sets the subprotocols to use with the WebSocket Protocol.

See Also:

• Subprotocols Using the WebSocket Protocol

aggregateContinuation

public WebSocketClientBuilder aggregateContinuation(boolean aggregateContinuation)

Sets whether to aggregate the subsequent continuation frames of the incoming WebSocketFrameType.TEXT or WebSocketFrameType.BINARY frame into a single WebSocketFrameType.TEXT or WebSocketFrameType.BINARY frame. Note that enabling this feature may lead to increased memory usage, so use it with caution.

autoFillOriginHeader

public WebSocketClientBuilder autoFillOriginHeader(boolean autoFillOriginHeader)

Sets whether to add an HttpHeaderNames.ORIGIN header automatically when sending an HttpRequest when the HttpRequest.headers() does not have it. It's true by default.

build

public WebSocketClient build()

Returns a newly-created WebSocketClient based on the properties of this builder.

rpcDecorator

@Deprecated
public WebSocketClientBuilder rpcDecorator(Function<? super RpcClient,? extends RpcClient> decorator)

Deprecated.

Description copied from class: AbstractWebClientBuilder

Raises an UnsupportedOperationException because this builder doesn't support RPC-level but only HTTP-level decorators.

Overrides:

rpcDecorator in class AbstractWebClientBuilder

Parameters:

decorator - the Function that transforms an RpcClient to another

rpcDecorator

@Deprecated
public WebSocketClientBuilder rpcDecorator(DecoratingRpcClientFunction decorator)

Deprecated.

Description copied from class: AbstractWebClientBuilder

Raises an UnsupportedOperationException because this builder doesn't support RPC-level but only HTTP-level decorators.

Overrides:

rpcDecorator in class AbstractWebClientBuilder

Parameters:

decorator - the DecoratingRpcClientFunction that intercepts an invocation

options

public WebSocketClientBuilder options(ClientOptions options)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOptions.

Overrides:

options in class AbstractClientOptionsBuilder

options

public WebSocketClientBuilder options(ClientOptionValue<?>... options)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOptionValues.

Overrides:

options in class AbstractClientOptionsBuilder

options

public WebSocketClientBuilder options(Iterable<ClientOptionValue<?>> options)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOptionValues.

Overrides:

options in class AbstractClientOptionsBuilder

option

public <T> WebSocketClientBuilder option(ClientOption<T> option,
 T value)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOption and its value.

Overrides:

option in class AbstractClientOptionsBuilder

option

public <T> WebSocketClientBuilder option(ClientOptionValue<T> optionValue)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOptionValue.

Overrides:

option in class AbstractClientOptionsBuilder

factory

public WebSocketClientBuilder factory(ClientFactory factory)

Description copied from class: AbstractClientOptionsBuilder

Sets the ClientFactory used for creating a client. The default is ClientFactory.ofDefault().

Overrides:

factory in class AbstractClientOptionsBuilder

writeTimeout

public WebSocketClientBuilder writeTimeout(Duration writeTimeout)

Description copied from class: AbstractClientOptionsBuilder

Sets the timeout of a socket write attempt.

Overrides:

writeTimeout in class AbstractClientOptionsBuilder

Parameters:

writeTimeout - the timeout. 0 disables the timeout.

writeTimeoutMillis

public WebSocketClientBuilder writeTimeoutMillis(long writeTimeoutMillis)

Description copied from class: AbstractClientOptionsBuilder

Sets the timeout of a socket write attempt in milliseconds.

Overrides:

writeTimeoutMillis in class AbstractClientOptionsBuilder

Parameters:

writeTimeoutMillis - the timeout in milliseconds. 0 disables the timeout.

responseTimeout

public WebSocketClientBuilder responseTimeout(Duration responseTimeout)

Description copied from class: AbstractClientOptionsBuilder

Sets the timeout of a response.

Overrides:

responseTimeout in class AbstractClientOptionsBuilder

Parameters:

responseTimeout - the timeout. 0 disables the timeout.

responseTimeoutMillis

public WebSocketClientBuilder responseTimeoutMillis(long responseTimeoutMillis)

Description copied from class: AbstractClientOptionsBuilder

Sets the timeout of a response in milliseconds.

Overrides:

responseTimeoutMillis in class AbstractClientOptionsBuilder

Parameters:

responseTimeoutMillis - the timeout in milliseconds. 0 disables the timeout.

maxResponseLength

public WebSocketClientBuilder maxResponseLength(long maxResponseLength)

Description copied from class: AbstractClientOptionsBuilder

Sets the maximum allowed length of a server response in bytes.

Overrides:

maxResponseLength in class AbstractClientOptionsBuilder

Parameters:

maxResponseLength - the maximum length in bytes. 0 disables the limit.

requestAutoAbortDelay

public WebSocketClientBuilder requestAutoAbortDelay(Duration delay)

Description copied from class: AbstractClientOptionsBuilder

Sets the amount of time to wait before aborting an HttpRequest when its corresponding HttpResponse is complete. This may be useful when you want to send additional data even after the response is complete. Specify Duration.ZERO to abort the HttpRequest immediately. Any negative value will not abort the request automatically. There is no delay by default.

Overrides:

requestAutoAbortDelay in class AbstractClientOptionsBuilder

requestAutoAbortDelayMillis

public WebSocketClientBuilder requestAutoAbortDelayMillis(long delayMillis)

Description copied from class: AbstractClientOptionsBuilder

Sets the amount of time in millis to wait before aborting an HttpRequest when its corresponding HttpResponse is complete. This may be useful when you want to send additional data even after the response is complete. Specify 0 to abort the HttpRequest immediately. Any negative value will not abort the request automatically. There is no delay by default.

Overrides:

requestAutoAbortDelayMillis in class AbstractClientOptionsBuilder

requestIdGenerator

public WebSocketClientBuilder requestIdGenerator(Supplier<RequestId> requestIdGenerator)

Description copied from class: AbstractClientOptionsBuilder

Sets the Supplier that generates a RequestId.

Overrides:

requestIdGenerator in class AbstractClientOptionsBuilder

successFunction

public WebSocketClientBuilder successFunction(SuccessFunction successFunction)

Description copied from class: AbstractClientOptionsBuilder

Sets a SuccessFunction that determines whether a request was handled successfully or not. If unspecified, SuccessFunction.ofDefault() is used.

Overrides:

successFunction in class AbstractClientOptionsBuilder

endpointRemapper

public WebSocketClientBuilder endpointRemapper(Function<? super Endpoint,? extends EndpointGroup> endpointRemapper)

Description copied from class: AbstractClientOptionsBuilder

Sets a Function that remaps an Endpoint into an EndpointGroup. This ClientOption is useful when you need to override a single target host into a group of hosts to enable client-side load-balancing, e.g.

 MyService.Iface client =
     Clients.newClient("tbinary+http://example.com/api",
                       MyService.Iface.class);

 EndpointGroup myGroup = EndpointGroup.of(Endpoint.of("node-1.example.com")),
                                          Endpoint.of("node-2.example.com")));

 MyService.Iface derivedClient =
     Clients.newDerivedClient(client, options -> {
         return options.toBuilder()
                       .endpointRemapper(endpoint -> {
                           if (endpoint.host().equals("example.com")) {
                               return myGroup;
                           } else {
                               return endpoint;
                           }
                       })
                       .build();
     });

 // This request goes to 'node-1.example.com' or 'node-2.example.com'.
 derivedClient.call();
 

Note that the remapping does not occur recursively but only once.

Overrides:

endpointRemapper in class AbstractClientOptionsBuilder

See Also:

• ClientOptions.ENDPOINT_REMAPPER
• ClientOptions.endpointRemapper()

decorator

public WebSocketClientBuilder decorator(Function<? super HttpClient,? extends HttpClient> decorator)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified HTTP-level decorator.

Overrides:

decorator in class AbstractClientOptionsBuilder

Parameters:

decorator - the Function that transforms an HttpClient to another

decorator

public WebSocketClientBuilder decorator(DecoratingHttpClientFunction decorator)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified HTTP-level decorator.

Overrides:

decorator in class AbstractClientOptionsBuilder

Parameters:

decorator - the DecoratingHttpClientFunction that intercepts an invocation

clearDecorators

public WebSocketClientBuilder clearDecorators()

Description copied from class: AbstractClientOptionsBuilder

Clears all HTTP-level and RPC-level decorators set so far.

Overrides:

clearDecorators in class AbstractClientOptionsBuilder

addHeader

public WebSocketClientBuilder addHeader(CharSequence name,
 Object value)

Description copied from class: AbstractClientOptionsBuilder

Adds the default HTTP header for an HttpRequest that will be sent by this Client.

Note that the values of the default HTTP headers could be overridden if the same HttpHeaderNames are defined in the HttpRequest.headers() or ClientRequestContext.additionalRequestHeaders().

Overrides:

addHeader in class AbstractClientOptionsBuilder

addHeaders

public WebSocketClientBuilder addHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> headers)

Description copied from class: AbstractClientOptionsBuilder

Adds the default HTTP headers for an HttpRequest that will be sent by this Client.

Note that the values of the default HTTP headers could be overridden if the same HttpHeaderNames are defined in the HttpRequest.headers() or ClientRequestContext.additionalRequestHeaders().

Overrides:

addHeaders in class AbstractClientOptionsBuilder

setHeader

public WebSocketClientBuilder setHeader(CharSequence name,
 Object value)

Description copied from class: AbstractClientOptionsBuilder

Sets the default HTTP header for an HttpRequest that will be sent by this Client.

Note that the default HTTP header could be overridden if the same HttpHeaderNames are defined in HttpRequest.headers() or ClientRequestContext.additionalRequestHeaders().

Overrides:

setHeader in class AbstractClientOptionsBuilder

setHeaders

public WebSocketClientBuilder setHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> headers)

Description copied from class: AbstractClientOptionsBuilder

Sets the default HTTP headers for an HttpRequest that will be sent by this Client.

Note that the values of the default HTTP headers could be overridden if the same HttpHeaderNames are defined in HttpRequest.headers() or ClientRequestContext.additionalRequestHeaders().

Overrides:

setHeaders in class AbstractClientOptionsBuilder

auth

public WebSocketClientBuilder auth(BasicToken token)

Description copied from class: AbstractClientOptionsBuilder

Sets the HTTP basic access authentication header using HttpHeaderNames.AUTHORIZATION.

Overrides:

auth in class AbstractClientOptionsBuilder

auth

public WebSocketClientBuilder auth(OAuth1aToken token)

Description copied from class: AbstractClientOptionsBuilder

Sets the OAuth Core 1.0 Revision A header using HttpHeaderNames.AUTHORIZATION.

Overrides:

auth in class AbstractClientOptionsBuilder

auth

public WebSocketClientBuilder auth(OAuth2Token token)

Description copied from class: AbstractClientOptionsBuilder

Sets the OAuth 2.0 header using HttpHeaderNames.AUTHORIZATION.

Overrides:

auth in class AbstractClientOptionsBuilder

auth

public WebSocketClientBuilder auth(AuthToken token)

Description copied from class: AbstractClientOptionsBuilder

Sets the AuthToken header using HttpHeaderNames.AUTHORIZATION.

Overrides:

auth in class AbstractClientOptionsBuilder

followRedirects

public WebSocketClientBuilder followRedirects()

Description copied from class: AbstractClientOptionsBuilder

Enables automatic redirection.

Overrides:

followRedirects in class AbstractClientOptionsBuilder

followRedirects

public WebSocketClientBuilder followRedirects(RedirectConfig redirectConfig)

Description copied from class: AbstractClientOptionsBuilder

Sets the RedirectConfig to enable automatic redirection.

Overrides:

followRedirects in class AbstractClientOptionsBuilder

contextCustomizer

public WebSocketClientBuilder contextCustomizer(Consumer<? super ClientRequestContext> contextCustomizer)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientRequestContext customizer function so that it customizes the context in the thread that initiated the client call. The given customizer function is evaluated before the customizer function specified by Clients.withContextCustomizer(Consumer).

 static final ThreadLocal<String> USER_ID = new ThreadLocal<>();
 static final AttributeKey<String> USER_ID_ATTR = AttributeKey.valueOf("USER_ID");
 ...
 MyClientStub client =
     Clients.builder(...)
            .contextCustomizer(ctx -> {
                // This customizer will be invoked from the thread that initiates a client call.
                ctx.setAttr(USER_ID_ATTR, USER_ID.get());
            })
            .build(MyClientStub.class);

 // Good:
 // The context data is set by the thread that initiates the client call.
 USER_ID.set("user1");
 try {
     client.executeSomething1(..);
     ...
     client.executeSomethingN(..);
 } finally {
     // Should clean up the thread local storage.
     USER_ID.remove();
 }

 // Bad:
 USER_ID.set("user1");
 executor.execute(() -> {
     // The variable in USER_ID won't be propagated to the context.
     // The variable is not valid at the moment client.executeSomething1() is called.
      client.executeSomething1(..);
 });
 

Note that certain properties of ClientRequestContext, such as:

• ClientRequestContext.endpoint()
• RequestContext.localAddress()
• RequestContext.remoteAddress()

may be null while the customizer function runs, because the target host of the Request is not determined yet.

Overrides:

contextCustomizer in class AbstractClientOptionsBuilder

See Also:

• Clients.withContextCustomizer(Consumer)

contextHook

public WebSocketClientBuilder contextHook(Supplier<? extends AutoCloseable> contextHook)

Description copied from class: AbstractClientOptionsBuilder

Sets the Supplier which provides an AutoCloseable and will be called whenever this RequestContext is popped from the RequestContextStorage.

Overrides:

contextHook in class AbstractClientOptionsBuilder

Parameters:

contextHook - the Supplier that provides an AutoCloseable