Class WebClientBuilder
URI
using the builder pattern.
Use the factory methods in WebClient
if you do not have many options to override.
Please refer to ClientBuilder
for how decorators and HTTP headers are configured-
Method Summary
Modifier and TypeMethodDescriptionaddHeader
(CharSequence name, Object value) Adds the default HTTP header for anHttpRequest
that will be sent by thisClient
.addHeaders
(Iterable<? extends Map.Entry<? extends CharSequence, ?>> headers) Adds the default HTTP headers for anHttpRequest
that will be sent by thisClient
.Sets theAuthToken
header usingHttpHeaderNames.AUTHORIZATION
.auth
(BasicToken token) Sets the HTTP basic access authentication header usingHttpHeaderNames.AUTHORIZATION
.auth
(OAuth1aToken token) Sets the OAuth Core 1.0 Revision A header usingHttpHeaderNames.AUTHORIZATION
.auth
(OAuth2Token token) Sets the OAuth 2.0 header usingHttpHeaderNames.AUTHORIZATION
.build()
Returns a newly-created web client based on the properties of this builder.Clears all HTTP-level and RPC-level decorators set so far.contextCustomizer
(Consumer<? super ClientRequestContext> contextCustomizer) Adds the specifiedClientRequestContext
customizer function so that it customizes the context in the thread that initiated the client call.contextHook
(Supplier<? extends AutoCloseable> contextHook) Sets theSupplier
which provides anAutoCloseable
and will be called whenever thisRequestContext
is popped from theRequestContextStorage
.decorator
(DecoratingHttpClientFunction decorator) Adds the specified HTTP-leveldecorator
.decorator
(Function<? super HttpClient, ? extends HttpClient> decorator) Adds the specified HTTP-leveldecorator
.endpointRemapper
(Function<? super Endpoint, ? extends EndpointGroup> endpointRemapper) factory
(ClientFactory factory) Sets theClientFactory
used for creating a client.Enables automatic redirection.followRedirects
(RedirectConfig redirectConfig) Sets theRedirectConfig
to enable automatic redirection.maxResponseLength
(long maxResponseLength) Sets the maximum allowed length of a server response in bytes.<T> WebClientBuilder
option
(ClientOption<T> option, T value) Adds the specifiedClientOption
and itsvalue
.<T> WebClientBuilder
option
(ClientOptionValue<T> optionValue) Adds the specifiedClientOptionValue
.options
(ClientOptions options) Adds the specifiedClientOptions
.options
(ClientOptionValue<?>... options) Adds the specifiedClientOptionValue
s.options
(Iterable<ClientOptionValue<?>> options) Adds the specifiedClientOptionValue
s.requestAutoAbortDelay
(Duration delay) Sets the amount of time to wait before aborting anHttpRequest
when its correspondingHttpResponse
is complete.requestAutoAbortDelayMillis
(long delayMillis) Sets the amount of time in millis to wait before aborting anHttpRequest
when its correspondingHttpResponse
is complete.requestIdGenerator
(Supplier<RequestId> requestIdGenerator) responseTimeout
(Duration responseTimeout) Sets the timeout of a response.responseTimeoutMillis
(long responseTimeoutMillis) Sets the timeout of a response in milliseconds.rpcDecorator
(DecoratingRpcClientFunction decorator) Deprecated.rpcDecorator
(Function<? super RpcClient, ? extends RpcClient> decorator) Deprecated.setHeader
(CharSequence name, Object value) Sets the default HTTP header for anHttpRequest
that will be sent by thisClient
.setHeaders
(Iterable<? extends Map.Entry<? extends CharSequence, ?>> headers) Sets the default HTTP headers for anHttpRequest
that will be sent by thisClient
.successFunction
(SuccessFunction successFunction) Sets aSuccessFunction
that determines whether a request was handled successfully or not.writeTimeout
(Duration writeTimeout) Sets the timeout of a socket write attempt.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
-
Method Details
-
build
Returns a newly-created web client based on the properties of this builder.- Throws:
IllegalArgumentException
- if the scheme of theuri
specified inWebClient.builder(String)
orWebClient.builder(URI)
is not an HTTP scheme
-
rpcDecorator
@Deprecated public WebClientBuilder rpcDecorator(Function<? super RpcClient, ? extends RpcClient> decorator) Deprecated.Description copied from class:AbstractWebClientBuilder
Raises anUnsupportedOperationException
because this builder doesn't support RPC-level but only HTTP-level decorators.- Overrides:
rpcDecorator
in classAbstractWebClientBuilder
- Parameters:
decorator
- theFunction
that transforms anRpcClient
to another
-
rpcDecorator
Deprecated.Description copied from class:AbstractWebClientBuilder
Raises anUnsupportedOperationException
because this builder doesn't support RPC-level but only HTTP-level decorators.- Overrides:
rpcDecorator
in classAbstractWebClientBuilder
- Parameters:
decorator
- theDecoratingRpcClientFunction
that intercepts an invocation
-
options
Description copied from class:AbstractClientOptionsBuilder
Adds the specifiedClientOptions
.- Overrides:
options
in classAbstractClientOptionsBuilder
-
options
Description copied from class:AbstractClientOptionsBuilder
Adds the specifiedClientOptionValue
s.- Overrides:
options
in classAbstractClientOptionsBuilder
-
options
Description copied from class:AbstractClientOptionsBuilder
Adds the specifiedClientOptionValue
s.- Overrides:
options
in classAbstractClientOptionsBuilder
-
option
Description copied from class:AbstractClientOptionsBuilder
Adds the specifiedClientOption
and itsvalue
.- Overrides:
option
in classAbstractClientOptionsBuilder
-
option
Description copied from class:AbstractClientOptionsBuilder
Adds the specifiedClientOptionValue
.- Overrides:
option
in classAbstractClientOptionsBuilder
-
factory
Description copied from class:AbstractClientOptionsBuilder
Sets theClientFactory
used for creating a client. The default isClientFactory.ofDefault()
.- Overrides:
factory
in classAbstractClientOptionsBuilder
-
writeTimeout
Description copied from class:AbstractClientOptionsBuilder
Sets the timeout of a socket write attempt.- Overrides:
writeTimeout
in classAbstractClientOptionsBuilder
- Parameters:
writeTimeout
- the timeout.0
disables the timeout.
-
writeTimeoutMillis
Description copied from class:AbstractClientOptionsBuilder
Sets the timeout of a socket write attempt in milliseconds.- Overrides:
writeTimeoutMillis
in classAbstractClientOptionsBuilder
- Parameters:
writeTimeoutMillis
- the timeout in milliseconds.0
disables the timeout.
-
responseTimeout
Description copied from class:AbstractClientOptionsBuilder
Sets the timeout of a response.- Overrides:
responseTimeout
in classAbstractClientOptionsBuilder
- Parameters:
responseTimeout
- the timeout.0
disables the timeout.
-
responseTimeoutMillis
Description copied from class:AbstractClientOptionsBuilder
Sets the timeout of a response in milliseconds.- Overrides:
responseTimeoutMillis
in classAbstractClientOptionsBuilder
- Parameters:
responseTimeoutMillis
- the timeout in milliseconds.0
disables the timeout.
-
maxResponseLength
Description copied from class:AbstractClientOptionsBuilder
Sets the maximum allowed length of a server response in bytes.- Overrides:
maxResponseLength
in classAbstractClientOptionsBuilder
- Parameters:
maxResponseLength
- the maximum length in bytes.0
disables the limit.
-
requestAutoAbortDelay
Description copied from class:AbstractClientOptionsBuilder
Sets the amount of time to wait before aborting anHttpRequest
when its correspondingHttpResponse
is complete. This may be useful when you want to send additional data even after the response is complete. SpecifyDuration.ZERO
to abort theHttpRequest
immediately. Any negative value will not abort the request automatically. There is no delay by default.- Overrides:
requestAutoAbortDelay
in classAbstractClientOptionsBuilder
-
requestAutoAbortDelayMillis
Description copied from class:AbstractClientOptionsBuilder
Sets the amount of time in millis to wait before aborting anHttpRequest
when its correspondingHttpResponse
is complete. This may be useful when you want to send additional data even after the response is complete. Specify0
to abort theHttpRequest
immediately. Any negative value will not abort the request automatically. There is no delay by default.- Overrides:
requestAutoAbortDelayMillis
in classAbstractClientOptionsBuilder
-
requestIdGenerator
Description copied from class:AbstractClientOptionsBuilder
- Overrides:
requestIdGenerator
in classAbstractClientOptionsBuilder
-
successFunction
Description copied from class:AbstractClientOptionsBuilder
Sets aSuccessFunction
that determines whether a request was handled successfully or not. If unspecified,SuccessFunction.ofDefault()
is used.- Overrides:
successFunction
in classAbstractClientOptionsBuilder
-
endpointRemapper
public WebClientBuilder endpointRemapper(Function<? super Endpoint, ? extends EndpointGroup> endpointRemapper) Description copied from class:AbstractClientOptionsBuilder
Sets aFunction
that remaps anEndpoint
into anEndpointGroup
. ThisClientOption
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 classAbstractClientOptionsBuilder
- See Also:
-
contextHook
Description copied from class:AbstractClientOptionsBuilder
Sets theSupplier
which provides anAutoCloseable
and will be called whenever thisRequestContext
is popped from theRequestContextStorage
.- Overrides:
contextHook
in classAbstractClientOptionsBuilder
- Parameters:
contextHook
- theSupplier
that provides anAutoCloseable
-
decorator
Description copied from class:AbstractClientOptionsBuilder
Adds the specified HTTP-leveldecorator
.- Overrides:
decorator
in classAbstractClientOptionsBuilder
- Parameters:
decorator
- theFunction
that transforms anHttpClient
to another
-
decorator
Description copied from class:AbstractClientOptionsBuilder
Adds the specified HTTP-leveldecorator
.- Overrides:
decorator
in classAbstractClientOptionsBuilder
- Parameters:
decorator
- theDecoratingHttpClientFunction
that intercepts an invocation
-
clearDecorators
Description copied from class:AbstractClientOptionsBuilder
Clears all HTTP-level and RPC-level decorators set so far.- Overrides:
clearDecorators
in classAbstractClientOptionsBuilder
-
addHeader
Description copied from class:AbstractClientOptionsBuilder
Adds the default HTTP header for anHttpRequest
that will be sent by thisClient
.Note that the values of the default HTTP headers could be overridden if the same
HttpHeaderNames
are defined in theHttpRequest.headers()
orClientRequestContext.additionalRequestHeaders()
.- Overrides:
addHeader
in classAbstractClientOptionsBuilder
-
addHeaders
Description copied from class:AbstractClientOptionsBuilder
Adds the default HTTP headers for anHttpRequest
that will be sent by thisClient
.Note that the values of the default HTTP headers could be overridden if the same
HttpHeaderNames
are defined in theHttpRequest.headers()
orClientRequestContext.additionalRequestHeaders()
.- Overrides:
addHeaders
in classAbstractClientOptionsBuilder
-
setHeader
Description copied from class:AbstractClientOptionsBuilder
Sets the default HTTP header for anHttpRequest
that will be sent by thisClient
.Note that the default HTTP header could be overridden if the same
HttpHeaderNames
are defined inHttpRequest.headers()
orClientRequestContext.additionalRequestHeaders()
.- Overrides:
setHeader
in classAbstractClientOptionsBuilder
-
setHeaders
Description copied from class:AbstractClientOptionsBuilder
Sets the default HTTP headers for anHttpRequest
that will be sent by thisClient
.Note that the values of the default HTTP headers could be overridden if the same
HttpHeaderNames
are defined inHttpRequest.headers()
orClientRequestContext.additionalRequestHeaders()
.- Overrides:
setHeaders
in classAbstractClientOptionsBuilder
-
auth
Description copied from class:AbstractClientOptionsBuilder
Sets the HTTP basic access authentication header usingHttpHeaderNames.AUTHORIZATION
.- Overrides:
auth
in classAbstractClientOptionsBuilder
-
auth
Description copied from class:AbstractClientOptionsBuilder
Sets the OAuth Core 1.0 Revision A header usingHttpHeaderNames.AUTHORIZATION
.- Overrides:
auth
in classAbstractClientOptionsBuilder
-
auth
Description copied from class:AbstractClientOptionsBuilder
Sets the OAuth 2.0 header usingHttpHeaderNames.AUTHORIZATION
.- Overrides:
auth
in classAbstractClientOptionsBuilder
-
auth
Description copied from class:AbstractClientOptionsBuilder
Sets theAuthToken
header usingHttpHeaderNames.AUTHORIZATION
.- Overrides:
auth
in classAbstractClientOptionsBuilder
-
followRedirects
Description copied from class:AbstractClientOptionsBuilder
Enables automatic redirection.- Overrides:
followRedirects
in classAbstractClientOptionsBuilder
-
followRedirects
Description copied from class:AbstractClientOptionsBuilder
Sets theRedirectConfig
to enable automatic redirection.- Overrides:
followRedirects
in classAbstractClientOptionsBuilder
-
contextCustomizer
Description copied from class:AbstractClientOptionsBuilder
Adds the specifiedClientRequestContext
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 byClients.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
may beClientRequestContext
, such as:null
while the customizer function runs, because the target host of theRequest
is not determined yet.- Overrides:
contextCustomizer
in classAbstractClientOptionsBuilder
- See Also:
-