Package com.linecorp.armeria.client.thrift

Class ThriftClientBuilder

java.lang.Object

com.linecorp.armeria.client.AbstractClientOptionsBuilder

com.linecorp.armeria.client.thrift.ThriftClientBuilder

@UnstableApi
public final class ThriftClientBuilder
extends AbstractClientOptionsBuilder

Creates a new Thrift client that connects to the specified URI using the builder pattern. Use the factory methods in ThriftClients if you do not have many options to override.

Method Summary

Modifier and Type	Method	Description
ThriftClientBuilder	addHeader(CharSequence name, Object value)	Adds the specified HTTP header.
ThriftClientBuilder	addHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> headers)	Adds the specified HTTP headers.
ThriftClientBuilder	auth(AuthToken token)	Sets the AuthToken header using HttpHeaderNames.AUTHORIZATION.
ThriftClientBuilder	auth(BasicToken token)	Sets the HTTP basic access authentication header using HttpHeaderNames.AUTHORIZATION.
ThriftClientBuilder	auth(OAuth1aToken token)	Sets the OAuth Core 1.0 Revision A header using HttpHeaderNames.AUTHORIZATION.
ThriftClientBuilder	auth(OAuth2Token token)	Sets the OAuth 2.0 header using HttpHeaderNames.AUTHORIZATION.
<T> T	build(Class<T> clientType)	Returns a newly-created Thrift client which implements the specified clientType, based on the properties of this builder.
ThriftClientBuilder	clearDecorators()	Clears all HTTP-level and RPC-level decorators set so far.
ThriftClientBuilder	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.
ThriftClientBuilder	decorator(DecoratingHttpClientFunction decorator)	Adds the specified HTTP-level decorator.
ThriftClientBuilder	decorator(Function<? super HttpClient,? extends HttpClient> decorator)	Adds the specified HTTP-level decorator.
ThriftClientBuilder	endpointRemapper(Function<? super Endpoint,? extends EndpointGroup> endpointRemapper)	Sets a Function that remaps an Endpoint into an EndpointGroup.
ThriftClientBuilder	factory(ClientFactory factory)	Sets the ClientFactory used for creating a client.
ThriftClientBuilder	followRedirects()	Enables automatic redirection.
ThriftClientBuilder	followRedirects(RedirectConfig redirectConfig)	Sets the RedirectConfig to enable automatic redirection.
ThriftClientBuilder	maxResponseContainerLength(int maxResponseContainerLength)	Sets the maximum allowed size of containers to read from the transport for maps, sets and lists.
ThriftClientBuilder	maxResponseLength(long maxResponseLength)	Sets the maximum allowed length of a server response in bytes.
ThriftClientBuilder	maxResponseStringLength(int maxResponseStringLength)	Sets the maximum allowed number of bytes to read from the transport for variable-length fields (such as strings or binary).
<T> ThriftClientBuilder	option(ClientOption<T> option, T value)	Adds the specified ClientOption and its value.
<T> ThriftClientBuilder	option(ClientOptionValue<T> optionValue)	Adds the specified ClientOptionValue.
ThriftClientBuilder	options(ClientOptions options)	Adds the specified ClientOptions.
ThriftClientBuilder	options(ClientOptionValue<?>... options)	Adds the specified ClientOptionValues.
ThriftClientBuilder	options(Iterable<ClientOptionValue<?>> options)	Adds the specified ClientOptionValues.
ThriftClientBuilder	path(String path)	Sets the path for the Thrift endpoint.
ThriftClientBuilder	requestIdGenerator(Supplier<RequestId> requestIdGenerator)	Sets the Supplier that generates a RequestId.
ThriftClientBuilder	responseTimeout(Duration responseTimeout)	Sets the timeout of a response.
ThriftClientBuilder	responseTimeoutMillis(long responseTimeoutMillis)	Sets the timeout of a response in milliseconds.
ThriftClientBuilder	rpcDecorator(DecoratingRpcClientFunction decorator)	Adds the specified RPC-level decorator.
ThriftClientBuilder	rpcDecorator(Function<? super RpcClient,? extends RpcClient> decorator)	Adds the specified RPC-level decorator.
ThriftClientBuilder	serializationFormat(SerializationFormat serializationFormat)	Sets the Thrift SerializationFormat.
ThriftClientBuilder	setHeader(CharSequence name, Object value)	Sets the specified HTTP header.
ThriftClientBuilder	setHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> headers)	Sets the specified HTTP headers.
ThriftClientBuilder	successFunction(SuccessFunction successFunction)	Sets a SuccessFunction that determines whether a request was handled successfully or not.
ThriftClientBuilder	writeTimeout(Duration writeTimeout)	Sets the timeout of a socket write attempt.
ThriftClientBuilder	writeTimeoutMillis(long writeTimeoutMillis)	Sets the timeout of a socket write attempt in milliseconds.

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

serializationFormat

public ThriftClientBuilder serializationFormat(SerializationFormat serializationFormat)

Sets the Thrift SerializationFormat. If not set, the Scheme.serializationFormat() specified when creating this builder will be used by default.

See Also:

• ThriftSerializationFormats

path

public ThriftClientBuilder path(String path)

Sets the path for the Thrift endpoint. This method will be useful if your Thrift service is bound to a path. For example:

 // A Thrift service is bound to "/thrift"
 Server.builder()
       .service("/thrift", THttpService.of(new MyThriftService()))
       .build();

 // Set "/thrift" to the Thrift service path.
 ThriftClients.builder("https://api.example.com")
              .path("/thrift")
              .build(MyThriftService.XXXIface.class)
 

maxResponseStringLength

public ThriftClientBuilder maxResponseStringLength(int maxResponseStringLength)

Sets the maximum allowed number of bytes to read from the transport for variable-length fields (such as strings or binary). If unspecified, the value of ClientOptions.maxResponseLength() will be used instead.

Note that this option is only valid for TBinaryProtocol and TCompactProtocol.

Parameters:

maxResponseStringLength - the maximum allowed string length. 0 disables the length limit.

maxResponseContainerLength

public ThriftClientBuilder maxResponseContainerLength(int maxResponseContainerLength)

Sets the maximum allowed size of containers to read from the transport for maps, sets and lists. If unspecified, the value of ClientOptions.maxResponseLength() will be used instead.

Note that this option is only valid for TBinaryProtocol and TCompactProtocol.

Parameters:

maxResponseContainerLength - the maximum allowed string length. 0 disables the length limit.

build

public <T> T build(Class<T> clientType)

Returns a newly-created Thrift client which implements the specified clientType, based on the properties of this builder.

options

public ThriftClientBuilder options(ClientOptions options)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOptions.

Overrides:

options in class AbstractClientOptionsBuilder

options

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

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOptionValues.

Overrides:

options in class AbstractClientOptionsBuilder

options

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

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOptionValues.

Overrides:

options in class AbstractClientOptionsBuilder

option

public <T> ThriftClientBuilder 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> ThriftClientBuilder option(ClientOptionValue<T> optionValue)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOptionValue.

Overrides:

option in class AbstractClientOptionsBuilder

factory

public ThriftClientBuilder 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 ThriftClientBuilder 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 ThriftClientBuilder 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 ThriftClientBuilder 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 ThriftClientBuilder 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 ThriftClientBuilder 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.

requestIdGenerator

public ThriftClientBuilder requestIdGenerator(Supplier<RequestId> requestIdGenerator)

Description copied from class: AbstractClientOptionsBuilder

Sets the Supplier that generates a RequestId.

Overrides:

requestIdGenerator in class AbstractClientOptionsBuilder

successFunction

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

rpcDecorator

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

Description copied from class: AbstractClientOptionsBuilder

Adds the specified RPC-level decorator.

Overrides:

rpcDecorator in class AbstractClientOptionsBuilder

Parameters:

decorator - the Function that transforms an RpcClient to another

rpcDecorator

public ThriftClientBuilder rpcDecorator(DecoratingRpcClientFunction decorator)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified RPC-level decorator.

Overrides:

rpcDecorator in class AbstractClientOptionsBuilder

Parameters:

decorator - the DecoratingRpcClientFunction that intercepts an invocation

clearDecorators

public ThriftClientBuilder clearDecorators()

Description copied from class: AbstractClientOptionsBuilder

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

Overrides:

clearDecorators in class AbstractClientOptionsBuilder

addHeader

public ThriftClientBuilder addHeader(CharSequence name,
 Object value)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified HTTP header.

Overrides:

addHeader in class AbstractClientOptionsBuilder

addHeaders

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

Description copied from class: AbstractClientOptionsBuilder

Adds the specified HTTP headers.

Overrides:

addHeaders in class AbstractClientOptionsBuilder

setHeader

public ThriftClientBuilder setHeader(CharSequence name,
 Object value)

Description copied from class: AbstractClientOptionsBuilder

Sets the specified HTTP header.

Overrides:

setHeader in class AbstractClientOptionsBuilder

setHeaders

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

Description copied from class: AbstractClientOptionsBuilder

Sets the specified HTTP headers.

Overrides:

setHeaders in class AbstractClientOptionsBuilder

auth

public ThriftClientBuilder 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 ThriftClientBuilder 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 ThriftClientBuilder auth(OAuth2Token token)

Description copied from class: AbstractClientOptionsBuilder

Sets the OAuth 2.0 header using HttpHeaderNames.AUTHORIZATION.

Overrides:

auth in class AbstractClientOptionsBuilder

auth

public ThriftClientBuilder auth(AuthToken token)

Description copied from class: AbstractClientOptionsBuilder

Sets the AuthToken header using HttpHeaderNames.AUTHORIZATION.

Overrides:

auth in class AbstractClientOptionsBuilder

followRedirects

public ThriftClientBuilder followRedirects()

Description copied from class: AbstractClientOptionsBuilder

Enables automatic redirection.

Overrides:

followRedirects in class AbstractClientOptionsBuilder

followRedirects

public ThriftClientBuilder followRedirects(RedirectConfig redirectConfig)

Description copied from class: AbstractClientOptionsBuilder

Sets the RedirectConfig to enable automatic redirection.

Overrides:

followRedirects in class AbstractClientOptionsBuilder

contextCustomizer

public ThriftClientBuilder 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)