Package com.linecorp.armeria.client.retrofit2

Class ArmeriaRetrofitBuilder

java.lang.Object

com.linecorp.armeria.client.AbstractClientOptionsBuilder

com.linecorp.armeria.client.retrofit2.ArmeriaRetrofitBuilder

public final class ArmeriaRetrofitBuilder
extends AbstractClientOptionsBuilder

A builder that creates a Retrofit which uses WebClient for sending requests.

See Also:

ArmeriaRetrofit

Method Summary

Modifier and Type	Method	Description
ArmeriaRetrofitBuilder	addCallAdapterFactory(CallAdapter.Factory factory)	Adds the specified call adapter factory for supporting service method return types other than Call.
ArmeriaRetrofitBuilder	addConverterFactory(Converter.Factory factory)	Adds the specified converter factory for serialization and deserialization of objects.
ArmeriaRetrofitBuilder	addHttpHeader(CharSequence name, Object value)	Adds the specified HTTP header.
ArmeriaRetrofitBuilder	addHttpHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> httpHeaders)	Adds the specified HTTP headers.
ArmeriaRetrofitBuilder	auth(BasicToken token)	Sets the HTTP basic access authentication header using HttpHeaderNames.AUTHORIZATION.
ArmeriaRetrofitBuilder	auth(OAuth1aToken token)	Sets the OAuth Core 1.0 Revision A header using HttpHeaderNames.AUTHORIZATION.
ArmeriaRetrofitBuilder	auth(OAuth2Token token)	Sets the OAuth 2.0 header using HttpHeaderNames.AUTHORIZATION.
Retrofit	build()	Returns a newly-created Retrofit based on the properties of this builder.
ArmeriaRetrofitBuilder	callbackExecutor(Executor executor)	Sets the Executor on which Callback methods are invoked when returning Call from your service method.
ArmeriaRetrofitBuilder	decorator(DecoratingHttpClientFunction decorator)	Adds the specified HTTP-level decorator.
ArmeriaRetrofitBuilder	decorator(Function<? super HttpClient,? extends HttpClient> decorator)	Adds the specified HTTP-level decorator.
ArmeriaRetrofitBuilder	endpointRemapper(Function<? super Endpoint,? extends EndpointGroup> endpointRemapper)	Sets a Function that remaps an Endpoint into an EndpointGroup.
ArmeriaRetrofitBuilder	factory(ClientFactory factory)	Sets the ClientFactory used for creating a client.
ArmeriaRetrofitBuilder	maxResponseLength(long maxResponseLength)	Sets the maximum allowed length of a server response in bytes.
ArmeriaRetrofitBuilder	nonBaseClientFactory(BiFunction<? super SessionProtocol,? super Endpoint,? extends WebClient> nonBaseClientFactory)	Specifies the BiFunction that creates a new non-base WebClient, which is used for sending requests to other authorities than that of base URL.
<T> ArmeriaRetrofitBuilder	option(ClientOption<T> option, T value)	Adds the specified ClientOption and its value.
<T> ArmeriaRetrofitBuilder	option(ClientOptionValue<T> optionValue)	Adds the specified ClientOptionValue.
ArmeriaRetrofitBuilder	options(ClientOptions options)	Adds the specified ClientOptions.
ArmeriaRetrofitBuilder	options(ClientOptionValue<?>... options)	Adds the specified ClientOptionValues.
ArmeriaRetrofitBuilder	options(Iterable<ClientOptionValue<?>> options)	Adds the specified ClientOptionValues.
ArmeriaRetrofitBuilder	requestIdGenerator(Supplier<RequestId> requestIdGenerator)	Sets the Supplier that generates a RequestId.
ArmeriaRetrofitBuilder	responseTimeout(Duration responseTimeout)	Sets the timeout of a response.
ArmeriaRetrofitBuilder	responseTimeoutMillis(long responseTimeoutMillis)	Sets the timeout of a response in milliseconds.
ArmeriaRetrofitBuilder	rpcDecorator(DecoratingRpcClientFunction decorator)	Adds the specified RPC-level decorator.
ArmeriaRetrofitBuilder	rpcDecorator(Function<? super RpcClient,? extends RpcClient> decorator)	Adds the specified RPC-level decorator.
ArmeriaRetrofitBuilder	setHttpHeader(CharSequence name, Object value)	Sets the specified HTTP header.
ArmeriaRetrofitBuilder	setHttpHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> httpHeaders)	Sets the specified HTTP headers.
ArmeriaRetrofitBuilder	streaming(boolean streaming)	Sets the streaming flag to make Armeria client fully support Streaming.
ArmeriaRetrofitBuilder	validateEagerly(boolean validateEagerly)	When calling Retrofit.create(java.lang.Class<T>) on the resulting Retrofit instance, eagerly validate the configuration of all methods in the supplied interface.
ArmeriaRetrofitBuilder	writeTimeout(Duration writeTimeout)	Sets the timeout of a socket write attempt.
ArmeriaRetrofitBuilder	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

nonBaseClientFactory

public ArmeriaRetrofitBuilder nonBaseClientFactory(BiFunction<? super SessionProtocol,? super Endpoint,? extends WebClient> nonBaseClientFactory)

Specifies the BiFunction that creates a new non-base WebClient, which is used for sending requests to other authorities than that of base URL. If not specified, the non-base WebClient will have the same options with the base WebClient, which was specified with ArmeriaRetrofit.of(WebClient) or ArmeriaRetrofit.builder(WebClient).

To avoid the overhead of repetitive instantiation of WebClients, the WebClients returned by the specified BiFunction will be cached for each combination of:

• Whether the connection is secured (HTTPS or HTTPS)
• Host name
• Port number

You can use this method to create a customized non-base WebClient, for example to send an additional header, override the timeout or enforce HTTP/1:

 ArmeriaRetrofit.builder("http://example.com/")
                .nonBaseClientFactory((protocol, endpoint) -> {
                    // Enforce HTTP/1.
                    final SessionProtocol actualProtocol =
                            protocol.isTls() ? SessionProtocol.H1 : SessionProtocol.H1C;

                    return WebClient.builder(actualProtocol, endpoint)
                                    // Derive most settings from 'defaultWebClient'.
                                    .factory(defaultWebClient.factory())
                                    .options(defaultWebClient.options())
                                    // Set a custom header.
                                    .setHttpHeader(HttpHeaderNames.AUTHORIZATION,
                                                   "bearer my-access-token")
                                    // Override the timeout.
                                    .responseTimeout(Duration.ofSeconds(30))
                                    .build();
                })
                .build();
 

Note that the specified BiFunction is not used for sending requests to the base URL's authority. The default WebClient specified with ArmeriaRetrofit.of(WebClient) or ArmeriaRetrofit.builder(WebClient) will be used instead for such requests:

 // No need to use 'nonBaseClientFactory()' method.
 ArmeriaRetrofit.of(WebClient.builder("http://example.com/")
                             .setHttpHeader(HttpHeaderNames.AUTHORIZATION,
                                            "bearer my-access-token")
                             .build());
 

addConverterFactory

public ArmeriaRetrofitBuilder addConverterFactory(Converter.Factory factory)

Adds the specified converter factory for serialization and deserialization of objects.

See Also:

Retrofit.Builder.addCallAdapterFactory(CallAdapter.Factory)

addCallAdapterFactory

public ArmeriaRetrofitBuilder addCallAdapterFactory(CallAdapter.Factory factory)

Adds the specified call adapter factory for supporting service method return types other than Call.

See Also:

Retrofit.Builder.addCallAdapterFactory(CallAdapter.Factory)

callbackExecutor

public ArmeriaRetrofitBuilder callbackExecutor(Executor executor)

Sets the Executor on which Callback methods are invoked when returning Call from your service method.

Note: executor is not used for custom method return types.

See Also:

Retrofit.Builder.callbackExecutor(Executor)

streaming

public ArmeriaRetrofitBuilder streaming(boolean streaming)

Sets the streaming flag to make Armeria client fully support Streaming. If this flag is false, Armeria client will buffer all data and call a callback after receiving the data completely, even if a service method was annotated with Streaming. By enabling this flag, Armeria client will use the Executor specified with callbackExecutor(Executor) to read the data in a blocking way.

Note: It is not recommended to have the service methods both with and without the Streaming annotation in the same interface. Consider separating them into different interfaces and using different builder to build the service.

See Also:

Streaming

validateEagerly

public ArmeriaRetrofitBuilder validateEagerly(boolean validateEagerly)

When calling Retrofit.create(java.lang.Class<T>) on the resulting Retrofit instance, eagerly validate the configuration of all methods in the supplied interface.

See Also:

Retrofit.Builder.validateEagerly(boolean)

build

public Retrofit build()

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

options

public ArmeriaRetrofitBuilder options(ClientOptions options)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOptions.

Overrides:

options in class AbstractClientOptionsBuilder

options

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

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOptionValues.

Overrides:

options in class AbstractClientOptionsBuilder

options

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

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOptionValues.

Overrides:

options in class AbstractClientOptionsBuilder

option

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

Description copied from class: AbstractClientOptionsBuilder

Adds the specified ClientOptionValue.

Overrides:

option in class AbstractClientOptionsBuilder

factory

public ArmeriaRetrofitBuilder 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 ArmeriaRetrofitBuilder 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 ArmeriaRetrofitBuilder 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 ArmeriaRetrofitBuilder 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 ArmeriaRetrofitBuilder 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 ArmeriaRetrofitBuilder 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 ArmeriaRetrofitBuilder requestIdGenerator(Supplier<RequestId> requestIdGenerator)

Description copied from class: AbstractClientOptionsBuilder

Sets the Supplier that generates a RequestId.

Overrides:

requestIdGenerator in class AbstractClientOptionsBuilder

endpointRemapper

public ArmeriaRetrofitBuilder 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:

ClientOption.ENDPOINT_REMAPPER, ClientOptions.endpointRemapper()

decorator

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

addHttpHeader

public ArmeriaRetrofitBuilder addHttpHeader(CharSequence name, Object value)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified HTTP header.

Overrides:

addHttpHeader in class AbstractClientOptionsBuilder

addHttpHeaders

public ArmeriaRetrofitBuilder addHttpHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> httpHeaders)

Description copied from class: AbstractClientOptionsBuilder

Adds the specified HTTP headers.

Overrides:

addHttpHeaders in class AbstractClientOptionsBuilder

setHttpHeader

public ArmeriaRetrofitBuilder setHttpHeader(CharSequence name, Object value)

Description copied from class: AbstractClientOptionsBuilder

Sets the specified HTTP header.

Overrides:

setHttpHeader in class AbstractClientOptionsBuilder

setHttpHeaders

public ArmeriaRetrofitBuilder setHttpHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> httpHeaders)

Description copied from class: AbstractClientOptionsBuilder

Sets the specified HTTP headers.

Overrides:

setHttpHeaders in class AbstractClientOptionsBuilder

auth

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

Description copied from class: AbstractClientOptionsBuilder

Sets the OAuth 2.0 header using HttpHeaderNames.AUTHORIZATION.

Overrides:

auth in class AbstractClientOptionsBuilder