Package com.linecorp.armeria.client

Class AbstractClientOptionsBuilder

java.lang.Object

com.linecorp.armeria.client.AbstractClientOptionsBuilder

Direct Known Subclasses:

AbstractWebClientBuilder, ArmeriaRetrofitBuilder, ClientBuilder, ClientOptionsBuilder, GrpcClientBuilder, ThriftClientBuilder

public class AbstractClientOptionsBuilder
extends Object

A skeletal builder implementation for ClientOptions.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AbstractClientOptionsBuilder()	Creates a new instance.
protected	AbstractClientOptionsBuilder(ClientOptions options)	Creates a new instance with the specified base options.

Method Summary

Modifier and Type	Method	Description
AbstractClientOptionsBuilder	addHeader(CharSequence name, Object value)	Adds the default HTTP header for an HttpRequest that will be sent by this Client.
AbstractClientOptionsBuilder	addHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> headers)	Adds the default HTTP headers for an HttpRequest that will be sent by this Client.
AbstractClientOptionsBuilder	auth(AuthToken token)	Sets the AuthToken header using HttpHeaderNames.AUTHORIZATION.
AbstractClientOptionsBuilder	auth(BasicToken token)	Deprecated. Use auth(AuthToken) instead.
AbstractClientOptionsBuilder	auth(OAuth1aToken token)	Deprecated. Use auth(AuthToken) instead.
AbstractClientOptionsBuilder	auth(OAuth2Token token)	Deprecated. Use auth(AuthToken) instead.
protected final ClientOptions	buildOptions()	Builds ClientOptions with the given options and the default options.
protected final ClientOptions	buildOptions(@Nullable ClientOptions baseOptions)	Builds ClientOptions with the specified baseOptions and the options which were set to this builder.
AbstractClientOptionsBuilder	clearDecorators()	Clears all HTTP-level and RPC-level decorators set so far.
AbstractClientOptionsBuilder	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.
AbstractClientOptionsBuilder	contextHook(Supplier<? extends AutoCloseable> contextHook)	Sets the Supplier which provides an AutoCloseable and will be called whenever this RequestContext is popped from the RequestContextStorage.
AbstractClientOptionsBuilder	decorator(DecoratingHttpClientFunction decorator)	Adds the specified HTTP-level decorator.
AbstractClientOptionsBuilder	decorator(Function<? super HttpClient,? extends HttpClient> decorator)	Adds the specified HTTP-level decorator.
AbstractClientOptionsBuilder	endpointRemapper(Function<? super Endpoint,? extends EndpointGroup> endpointRemapper)	Sets a Function that remaps an Endpoint into an EndpointGroup.
AbstractClientOptionsBuilder	factory(ClientFactory factory)	Sets the ClientFactory used for creating a client.
AbstractClientOptionsBuilder	followRedirects()	Enables automatic redirection.
AbstractClientOptionsBuilder	followRedirects(RedirectConfig redirectConfig)	Sets the RedirectConfig to enable automatic redirection.
AbstractClientOptionsBuilder	maxResponseLength(long maxResponseLength)	Sets the maximum allowed length of a server response in bytes.
<T> AbstractClientOptionsBuilder	option(ClientOption<T> option, T value)	Adds the specified ClientOption and its value.
<T> AbstractClientOptionsBuilder	option(ClientOptionValue<T> optionValue)	Adds the specified ClientOptionValue.
AbstractClientOptionsBuilder	options(ClientOptions options)	Adds the specified ClientOptions.
AbstractClientOptionsBuilder	options(ClientOptionValue<?>... options)	Adds the specified ClientOptionValues.
AbstractClientOptionsBuilder	options(Iterable<ClientOptionValue<?>> options)	Adds the specified ClientOptionValues.
AbstractClientOptionsBuilder	requestAutoAbortDelay(Duration delay)	Sets the amount of time to wait before aborting an HttpRequest when its corresponding HttpResponse is complete.
AbstractClientOptionsBuilder	requestAutoAbortDelayMillis(long delayMillis)	Sets the amount of time in millis to wait before aborting an HttpRequest when its corresponding HttpResponse is complete.
AbstractClientOptionsBuilder	requestIdGenerator(Supplier<RequestId> requestIdGenerator)	Sets the Supplier that generates a RequestId.
AbstractClientOptionsBuilder	responseTimeout(Duration responseTimeout)	Sets the timeout of a response.
AbstractClientOptionsBuilder	responseTimeoutMillis(long responseTimeoutMillis)	Sets the timeout of a response in milliseconds.
AbstractClientOptionsBuilder	rpcDecorator(DecoratingRpcClientFunction decorator)	Adds the specified RPC-level decorator.
AbstractClientOptionsBuilder	rpcDecorator(Function<? super RpcClient,? extends RpcClient> decorator)	Adds the specified RPC-level decorator.
AbstractClientOptionsBuilder	setHeader(CharSequence name, Object value)	Sets the default HTTP header for an HttpRequest that will be sent by this Client.
AbstractClientOptionsBuilder	setHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> headers)	Sets the default HTTP headers for an HttpRequest that will be sent by this Client.
AbstractClientOptionsBuilder	successFunction(SuccessFunction successFunction)	Sets a SuccessFunction that determines whether a request was handled successfully or not.
AbstractClientOptionsBuilder	writeTimeout(Duration writeTimeout)	Sets the timeout of a socket write attempt.
AbstractClientOptionsBuilder	writeTimeoutMillis(long writeTimeoutMillis)	Sets the timeout of a socket write attempt in milliseconds.

Methods inherited from class java.lang.Object

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

Constructor Details

AbstractClientOptionsBuilder

protected AbstractClientOptionsBuilder()

Creates a new instance.

AbstractClientOptionsBuilder

protected AbstractClientOptionsBuilder(ClientOptions options)

Creates a new instance with the specified base options.

Method Details

options

public AbstractClientOptionsBuilder options(ClientOptions options)

Adds the specified ClientOptions.

options

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

Adds the specified ClientOptionValues.

options

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

Adds the specified ClientOptionValues.

option

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

Adds the specified ClientOption and its value.

option

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

Adds the specified ClientOptionValue.

factory

public AbstractClientOptionsBuilder factory(ClientFactory factory)

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

writeTimeout

public AbstractClientOptionsBuilder writeTimeout(Duration writeTimeout)

Sets the timeout of a socket write attempt.

Parameters:

writeTimeout - the timeout. 0 disables the timeout.

writeTimeoutMillis

public AbstractClientOptionsBuilder writeTimeoutMillis(long writeTimeoutMillis)

Sets the timeout of a socket write attempt in milliseconds.

Parameters:

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

responseTimeout

public AbstractClientOptionsBuilder responseTimeout(Duration responseTimeout)

Sets the timeout of a response.

Parameters:

responseTimeout - the timeout. 0 disables the timeout.

responseTimeoutMillis

public AbstractClientOptionsBuilder responseTimeoutMillis(long responseTimeoutMillis)

Sets the timeout of a response in milliseconds.

Parameters:

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

maxResponseLength

public AbstractClientOptionsBuilder maxResponseLength(long maxResponseLength)

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

Parameters:

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

requestAutoAbortDelay

@UnstableApi
public AbstractClientOptionsBuilder requestAutoAbortDelay(Duration delay)

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.

requestAutoAbortDelayMillis

@UnstableApi
public AbstractClientOptionsBuilder requestAutoAbortDelayMillis(long delayMillis)

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.

requestIdGenerator

public AbstractClientOptionsBuilder requestIdGenerator(Supplier<RequestId> requestIdGenerator)

Sets the Supplier that generates a RequestId.

successFunction

@UnstableApi
public AbstractClientOptionsBuilder successFunction(SuccessFunction successFunction)

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

endpointRemapper

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

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.

See Also:

• ClientOptions.ENDPOINT_REMAPPER
• ClientOptions.endpointRemapper()

contextHook

@UnstableApi
public AbstractClientOptionsBuilder contextHook(Supplier<? extends AutoCloseable> contextHook)

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

Parameters:

contextHook - the Supplier that provides an AutoCloseable

decorator

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

Adds the specified HTTP-level decorator.

Parameters:

decorator - the Function that transforms an HttpClient to another

decorator

public AbstractClientOptionsBuilder decorator(DecoratingHttpClientFunction decorator)

Adds the specified HTTP-level decorator.

Parameters:

decorator - the DecoratingHttpClientFunction that intercepts an invocation

clearDecorators

public AbstractClientOptionsBuilder clearDecorators()

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

rpcDecorator

public AbstractClientOptionsBuilder rpcDecorator(Function<? super RpcClient,? extends RpcClient> decorator)

Adds the specified RPC-level decorator.

Parameters:

decorator - the Function that transforms an RpcClient to another

rpcDecorator

public AbstractClientOptionsBuilder rpcDecorator(DecoratingRpcClientFunction decorator)

Adds the specified RPC-level decorator.

Parameters:

decorator - the DecoratingRpcClientFunction that intercepts an invocation

addHeader

public AbstractClientOptionsBuilder addHeader(CharSequence name,
 Object value)

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().

addHeaders

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

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().

setHeader

public AbstractClientOptionsBuilder setHeader(CharSequence name,
 Object value)

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().

setHeaders

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

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().

auth

@Deprecated
public AbstractClientOptionsBuilder auth(BasicToken token)

Deprecated.

Use auth(AuthToken) instead.

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

auth

@Deprecated
public AbstractClientOptionsBuilder auth(OAuth1aToken token)

Deprecated.

Use auth(AuthToken) instead.

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

auth

@Deprecated
public AbstractClientOptionsBuilder auth(OAuth2Token token)

Deprecated.

Use auth(AuthToken) instead.

Sets the OAuth 2.0 header using HttpHeaderNames.AUTHORIZATION.

auth

public AbstractClientOptionsBuilder auth(AuthToken token)

Sets the AuthToken header using HttpHeaderNames.AUTHORIZATION.

followRedirects

@UnstableApi
public AbstractClientOptionsBuilder followRedirects()

Enables automatic redirection.

followRedirects

@UnstableApi
public AbstractClientOptionsBuilder followRedirects(RedirectConfig redirectConfig)

Sets the RedirectConfig to enable automatic redirection.

contextCustomizer

@UnstableApi
public AbstractClientOptionsBuilder 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. 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.

See Also:

• Clients.withContextCustomizer(Consumer)

buildOptions

protected final ClientOptions buildOptions()

Builds ClientOptions with the given options and the default options.

buildOptions

protected final ClientOptions buildOptions(@Nullable
 @Nullable ClientOptions baseOptions)

Builds ClientOptions with the specified baseOptions and the options which were set to this builder.