com.linecorp.armeria.client

Class Clients

java.lang.Object

com.linecorp.armeria.client.Clients

public final class Clients
extends Object

Creates a new client that connects to a specified URI. If you are creating an WebClient, it is recommended to use the factory methods in WebClient.

Method Summary

Modifier and Type	Method and Description
static ClientBuilder	builder(Scheme scheme, EndpointGroup endpointGroup) Returns a new ClientBuilder that builds the client that connects to the specified EndpointGroup with the Scheme.
static ClientBuilder	builder(SessionProtocol protocol, EndpointGroup endpointGroup) Returns a new ClientBuilder that builds the client that connects to the specified EndpointGroup with the SessionProtocol.
static ClientBuilder	builder(String uri) Returns a new ClientBuilder that builds the client that connects to the specified uri.
static ClientBuilder	builder(String scheme, EndpointGroup endpointGroup) Returns a new ClientBuilder that builds the client that connects to the specified EndpointGroup with the scheme.
static ClientBuilder	builder(URI uri) Returns a new ClientBuilder that builds the client that connects to the specified URI.
static boolean	isUndefinedUri(URI uri) Returns true if the specified uri is an undefined URI, which signifies that a Client, was created without a URI or EndpointGroup.
static <T> T	newClient(ClientFactory factory, Scheme scheme, EndpointGroup endpointGroup, Class<T> clientType, ClientOptions options) Deprecated. Use builder(Scheme, EndpointGroup), ClientBuilder.factory(ClientFactory) and ClientBuilder.options(ClientOptions).
static <T> T	newClient(ClientFactory factory, Scheme scheme, EndpointGroup endpointGroup, Class<T> clientType, ClientOptionValue<?>... options) Deprecated. Use builder(Scheme, EndpointGroup), ClientBuilder.factory(ClientFactory) and ClientBuilder.options(ClientOptionValue[]).
static <T> T	newClient(ClientFactory factory, SessionProtocol protocol, SerializationFormat format, EndpointGroup endpointGroup, Class<T> clientType, ClientOptions options) Deprecated. Use builder(Scheme, EndpointGroup), ClientBuilder.factory(ClientFactory) and ClientBuilder.options(ClientOptions).
static <T> T	newClient(ClientFactory factory, SessionProtocol protocol, SerializationFormat format, EndpointGroup endpointGroup, Class<T> clientType, ClientOptionValue<?>... options) Deprecated. Use builder(Scheme, EndpointGroup), ClientBuilder.factory(ClientFactory) and ClientBuilder.options(ClientOptionValue[]).
static <T> T	newClient(ClientFactory factory, String uri, Class<T> clientType, ClientOptions options) Deprecated. Use builder(String), ClientBuilder.factory(ClientFactory) and ClientBuilder.options(ClientOptions).
static <T> T	newClient(ClientFactory factory, String uri, Class<T> clientType, ClientOptionValue<?>... options) Deprecated. Use builder(String), ClientBuilder.factory(ClientFactory) and ClientBuilder.options(ClientOptionValue[]).
static <T> T	newClient(ClientFactory factory, URI uri, Class<T> clientType, ClientOptions options) Deprecated. Use builder(URI), ClientBuilder.factory(ClientFactory) and ClientBuilder.options(ClientOptions).
static <T> T	newClient(ClientFactory factory, URI uri, Class<T> clientType, ClientOptionValue<?>... options) Deprecated. Use builder(URI), ClientBuilder.factory(ClientFactory) and ClientBuilder.options(ClientOptionValue[]).
static <T> T	newClient(Scheme scheme, EndpointGroup endpointGroup, Class<T> clientType) Creates a new client that connects to the specified EndpointGroup with the Scheme using the default ClientFactory.
static <T> T	newClient(Scheme scheme, EndpointGroup endpointGroup, Class<T> clientType, ClientOptions options) Deprecated. Use builder(Scheme, EndpointGroup) and ClientBuilder.options(ClientOptions).
static <T> T	newClient(Scheme scheme, EndpointGroup endpointGroup, Class<T> clientType, ClientOptionValue<?>... options) Deprecated. Use builder(Scheme, EndpointGroup) and ClientBuilder.options(ClientOptionValue[]).
static <T> T	newClient(SessionProtocol protocol, EndpointGroup endpointGroup, Class<T> clientType) Creates a new client that connects to the specified EndpointGroup with the SessionProtocol using the default ClientFactory.
static <T> T	newClient(SessionProtocol protocol, SerializationFormat format, EndpointGroup endpointGroup, Class<T> clientType, ClientOptions options) Deprecated. Use builder(Scheme, EndpointGroup) and ClientBuilder.options(ClientOptions).
static <T> T	newClient(SessionProtocol protocol, SerializationFormat format, EndpointGroup endpointGroup, Class<T> clientType, ClientOptionValue<?>... options) Deprecated. Use builder(Scheme, EndpointGroup) and ClientBuilder.options(ClientOptionValue[]).
static <T> T	newClient(String uri, Class<T> clientType) Creates a new client that connects to the specified uri using the default ClientFactory.
static <T> T	newClient(String uri, Class<T> clientType, ClientOptions options) Deprecated. Use builder(String) and ClientBuilder.options(ClientOptions).
static <T> T	newClient(String uri, Class<T> clientType, ClientOptionValue<?>... options) Deprecated. Use builder(String) and ClientBuilder.options(ClientOptionValue[]).
static <T> T	newClient(String scheme, EndpointGroup endpointGroup, Class<T> clientType) Creates a new client that connects to the specified EndpointGroup with the scheme using the default ClientFactory.
static <T> T	newClient(URI uri, Class<T> clientType) Creates a new client that connects to the specified URI using the default ClientFactory.
static <T> T	newClient(URI uri, Class<T> clientType, ClientOptions options) Deprecated. Use builder(URI) and ClientBuilder.options(ClientOptions).
static <T> T	newClient(URI uri, Class<T> clientType, ClientOptionValue<?>... options) Deprecated. Use builder(URI) and ClientBuilder.options(ClientOptionValue[]).
static ClientRequestContextCaptor	newContextCaptor() Prepare to capture the ClientRequestContext of the next request sent from the current thread.
static <T> T	newDerivedClient(T client, ClientOptionValue<?>... additionalOptions) Creates a new derived client that connects to the same URI with the specified client and the specified additionalOptions.
static <T> T	newDerivedClient(T client, Function<? super ClientOptions,ClientOptions> configurator) Creates a new derived client that connects to the same URI with the specified client but with different ClientOptions.
static <T> T	newDerivedClient(T client, Iterable<ClientOptionValue<?>> additionalOptions) Creates a new derived client that connects to the same URI with the specified client and the specified additionalOptions.
static <T> T	unwrap(Object client, Class<T> type) Unwraps the specified client into the object of the specified type.
static SafeCloseable	withContextCustomizer(Consumer<? super ClientRequestContext> contextCustomizer) Sets the specified ClientRequestContext customization function in a thread-local variable so that the customized context is used when the client invokes a request from the current thread.
static SafeCloseable	withHttpHeader(CharSequence name, Object value) Sets the specified HTTP header in a thread-local variable so that the header is sent by the client call made from the current thread.
static SafeCloseable	withHttpHeader(CharSequence name, String value) Sets the specified HTTP header in a thread-local variable so that the header is sent by the client call made from the current thread.
static SafeCloseable	withHttpHeaders(Function<? super HttpHeaders,? extends HttpHeaders> headerManipulator) Sets the specified HTTP header manipulating function in a thread-local variable so that the manipulated headers are sent by the client call made from the current thread.

Methods inherited from class java.lang.Object

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

Method Detail

newClient

public static <T> T newClient(String uri,
                              Class<T> clientType)

Creates a new client that connects to the specified uri using the default ClientFactory.

Parameters:

uri - the URI of the server endpoint

clientType - the type of the new client

Throws:

IllegalArgumentException - if the scheme of the specified uri is invalid or the specified clientType is unsupported for the scheme

newClient

public static <T> T newClient(URI uri,
                              Class<T> clientType)

Creates a new client that connects to the specified URI using the default ClientFactory.

Parameters:

uri - the URI of the server endpoint

clientType - the type of the new client

Throws:

IllegalArgumentException - if the scheme of the specified URI is invalid or the specified clientType is unsupported for the scheme

newClient

public static <T> T newClient(String scheme,
                              EndpointGroup endpointGroup,
                              Class<T> clientType)

Creates a new client that connects to the specified EndpointGroup with the scheme using the default ClientFactory.

Parameters:

scheme - the Scheme represented as a String

endpointGroup - the server EndpointGroup

clientType - the type of the new client

Throws:

IllegalArgumentException - if the specified scheme is invalid or the specified clientType is unsupported for the specified scheme.

newClient

public static <T> T newClient(Scheme scheme,
                              EndpointGroup endpointGroup,
                              Class<T> clientType)

Creates a new client that connects to the specified EndpointGroup with the Scheme using the default ClientFactory.

Parameters:

scheme - the Scheme

endpointGroup - the server EndpointGroup

clientType - the type of the new client

Throws:

IllegalArgumentException - if the specified clientType is unsupported for the specified Scheme.

newClient

public static <T> T newClient(SessionProtocol protocol,
                              EndpointGroup endpointGroup,
                              Class<T> clientType)

Creates a new client that connects to the specified EndpointGroup with the SessionProtocol using the default ClientFactory.

Parameters:

protocol - the SessionProtocol

endpointGroup - the server EndpointGroup

clientType - the type of the new client

Throws:

IllegalArgumentException - if the specified clientType is unsupported for the specified SessionProtocol or SerializationFormat is required.

newClient

@Deprecated
public static <T> T newClient(String uri,
                                          Class<T> clientType,
                                          ClientOptionValue<?>... options)

Deprecated. Use builder(String) and ClientBuilder.options(ClientOptionValue[]).

Creates a new client that connects to the specified uri using the default ClientFactory.

Parameters:

uri - the URI of the server endpoint

clientType - the type of the new client

options - the ClientOptionValues

Throws:

IllegalArgumentException - if the scheme of the specified uri or the specified clientType is unsupported for the scheme

newClient

@Deprecated
public static <T> T newClient(String uri,
                                          Class<T> clientType,
                                          ClientOptions options)

Deprecated. Use builder(String) and ClientBuilder.options(ClientOptions).

Creates a new client that connects to the specified uri using the default ClientFactory.

Parameters:

uri - the URI of the server endpoint

clientType - the type of the new client

options - the ClientOptions

Throws:

IllegalArgumentException - if the scheme of the specified uri or the specified clientType is unsupported for the scheme

newClient

@Deprecated
public static <T> T newClient(ClientFactory factory,
                                          String uri,
                                          Class<T> clientType,
                                          ClientOptionValue<?>... options)

Deprecated. Use builder(String), ClientBuilder.factory(ClientFactory) and ClientBuilder.options(ClientOptionValue[]).

Creates a new client that connects to the specified uri using the specified ClientFactory.

Parameters:

factory - an alternative ClientFactory

uri - the URI of the server endpoint

clientType - the type of the new client

options - the ClientOptionValues

Throws:

IllegalArgumentException - if the scheme of the specified uri or the specified clientType is unsupported for the scheme

newClient

@Deprecated
public static <T> T newClient(ClientFactory factory,
                                          String uri,
                                          Class<T> clientType,
                                          ClientOptions options)

Deprecated. Use builder(String), ClientBuilder.factory(ClientFactory) and ClientBuilder.options(ClientOptions).

Creates a new client that connects to the specified uri using the specified ClientFactory.

Parameters:

factory - an alternative ClientFactory

uri - the URI of the server endpoint

clientType - the type of the new client

options - the ClientOptions

Throws:

IllegalArgumentException - if the scheme of the specified uri or the specified clientType is unsupported for the scheme

newClient

@Deprecated
public static <T> T newClient(URI uri,
                                          Class<T> clientType,
                                          ClientOptionValue<?>... options)

Deprecated. Use builder(URI) and ClientBuilder.options(ClientOptionValue[]).

Creates a new client that connects to the specified URI using the default ClientFactory.

Parameters:

uri - the URI of the server endpoint

clientType - the type of the new client

options - the ClientOptionValues

Throws:

IllegalArgumentException - if the scheme of the specified uri or the specified clientType is unsupported for the scheme

newClient

@Deprecated
public static <T> T newClient(URI uri,
                                          Class<T> clientType,
                                          ClientOptions options)

Deprecated. Use builder(URI) and ClientBuilder.options(ClientOptions).

Creates a new client that connects to the specified URI using the default ClientFactory.

Parameters:

uri - the URI of the server endpoint

clientType - the type of the new client

options - the ClientOptions

Throws:

IllegalArgumentException - if the scheme of the specified uri or the specified clientType is unsupported for the scheme

newClient

@Deprecated
public static <T> T newClient(ClientFactory factory,
                                          URI uri,
                                          Class<T> clientType,
                                          ClientOptionValue<?>... options)

Deprecated. Use builder(URI), ClientBuilder.factory(ClientFactory) and ClientBuilder.options(ClientOptionValue[]).

Creates a new client that connects to the specified URI using the specified ClientFactory.

Parameters:

factory - an alternative ClientFactory

uri - the URI of the server endpoint

clientType - the type of the new client

options - the ClientOptionValues

Throws:

IllegalArgumentException - if the scheme of the specified uri or the specified clientType is unsupported for the scheme

newClient

@Deprecated
public static <T> T newClient(ClientFactory factory,
                                          URI uri,
                                          Class<T> clientType,
                                          ClientOptions options)

Deprecated. Use builder(URI), ClientBuilder.factory(ClientFactory) and ClientBuilder.options(ClientOptions).

Creates a new client that connects to the specified URI using the specified ClientFactory.

Parameters:

factory - an alternative ClientFactory

uri - the URI of the server endpoint

clientType - the type of the new client

options - the ClientOptions

Throws:

IllegalArgumentException - if the scheme of the specified uri or the specified clientType is unsupported for the scheme

newClient

@Deprecated
public static <T> T newClient(SessionProtocol protocol,
                                          SerializationFormat format,
                                          EndpointGroup endpointGroup,
                                          Class<T> clientType,
                                          ClientOptionValue<?>... options)

Deprecated. Use builder(Scheme, EndpointGroup) and ClientBuilder.options(ClientOptionValue[]).

Creates a new client that connects to the specified EndpointGroup with the SessionProtocol and the SerializationFormat using the default ClientFactory.

Parameters:

protocol - the session protocol

format - the SerializationFormat for remote procedure call

endpointGroup - the server EndpointGroup

clientType - the type of the new client

options - the ClientOptionValues

Throws:

IllegalArgumentException - if the scheme of the specified SessionProtocol and SerializationFormat, or the specified clientType is unsupported for the scheme

newClient

@Deprecated
public static <T> T newClient(SessionProtocol protocol,
                                          SerializationFormat format,
                                          EndpointGroup endpointGroup,
                                          Class<T> clientType,
                                          ClientOptions options)

Deprecated. Use builder(Scheme, EndpointGroup) and ClientBuilder.options(ClientOptions).

Creates a new client that connects to the specified EndpointGroup with the SessionProtocol and the SerializationFormat using the default ClientFactory.

Parameters:

protocol - the session protocol

format - the SerializationFormat for remote procedure call

endpointGroup - the server EndpointGroup

clientType - the type of the new client

options - the ClientOptions

Throws:

IllegalArgumentException - if the scheme of the specified SessionProtocol and SerializationFormat, or the specified clientType is unsupported for the scheme

newClient

@Deprecated
public static <T> T newClient(ClientFactory factory,
                                          SessionProtocol protocol,
                                          SerializationFormat format,
                                          EndpointGroup endpointGroup,
                                          Class<T> clientType,
                                          ClientOptionValue<?>... options)

Deprecated. Use builder(Scheme, EndpointGroup), ClientBuilder.factory(ClientFactory) and ClientBuilder.options(ClientOptionValue[]).

Creates a new client that connects to the specified EndpointGroup with the SessionProtocol and the SerializationFormat using the specified ClientFactory.

Parameters:

factory - an alternative ClientFactory

protocol - the session protocol

format - the SerializationFormat for remote procedure call

endpointGroup - the server EndpointGroup

clientType - the type of the new client

options - the ClientOptionValues

Throws:

IllegalArgumentException - if the scheme of the specified SessionProtocol and SerializationFormat, or the specified clientType is unsupported for the scheme

newClient

@Deprecated
public static <T> T newClient(ClientFactory factory,
                                          SessionProtocol protocol,
                                          SerializationFormat format,
                                          EndpointGroup endpointGroup,
                                          Class<T> clientType,
                                          ClientOptions options)

Deprecated. Use builder(Scheme, EndpointGroup), ClientBuilder.factory(ClientFactory) and ClientBuilder.options(ClientOptions).

Creates a new client that connects to the specified EndpointGroup with the SessionProtocol and the SerializationFormat using the specified ClientFactory.

Parameters:

factory - an alternative ClientFactory

protocol - the session protocol

format - the SerializationFormat for remote procedure call

endpointGroup - the server EndpointGroup

clientType - the type of the new client

options - the ClientOptions

Throws:

IllegalArgumentException - if the scheme of the specified SessionProtocol and SerializationFormat, or the specified clientType is unsupported for the scheme

newClient

@Deprecated
public static <T> T newClient(Scheme scheme,
                                          EndpointGroup endpointGroup,
                                          Class<T> clientType,
                                          ClientOptionValue<?>... options)

Deprecated. Use builder(Scheme, EndpointGroup) and ClientBuilder.options(ClientOptionValue[]).

Creates a new client that connects to the specified EndpointGroup with the Scheme using the default ClientFactory.

Parameters:

scheme - the Scheme

endpointGroup - the server EndpointGroup

clientType - the type of the new client

options - the ClientOptionValues

Throws:

IllegalArgumentException - if the specified Scheme or the specified clientType is unsupported for the scheme

newClient

@Deprecated
public static <T> T newClient(Scheme scheme,
                                          EndpointGroup endpointGroup,
                                          Class<T> clientType,
                                          ClientOptions options)

Deprecated. Use builder(Scheme, EndpointGroup) and ClientBuilder.options(ClientOptions).

Creates a new client that connects to the specified EndpointGroup with the Scheme using the default ClientFactory.

Parameters:

scheme - the Scheme

endpointGroup - the server EndpointGroup

clientType - the type of the new client

options - the ClientOptions

Throws:

IllegalArgumentException - if the specified Scheme or the specified clientType is unsupported for the scheme

newClient

@Deprecated
public static <T> T newClient(ClientFactory factory,
                                          Scheme scheme,
                                          EndpointGroup endpointGroup,
                                          Class<T> clientType,
                                          ClientOptionValue<?>... options)

Deprecated. Use builder(Scheme, EndpointGroup), ClientBuilder.factory(ClientFactory) and ClientBuilder.options(ClientOptionValue[]).

Creates a new client that connects to the specified EndpointGroup with the Scheme using the specified ClientFactory.

Parameters:

factory - an alternative ClientFactory

scheme - the Scheme

endpointGroup - the server EndpointGroup

clientType - the type of the new client

options - the ClientOptionValues

Throws:

IllegalArgumentException - if the specified Scheme or the specified clientType is unsupported for the scheme

newClient

@Deprecated
public static <T> T newClient(ClientFactory factory,
                                          Scheme scheme,
                                          EndpointGroup endpointGroup,
                                          Class<T> clientType,
                                          ClientOptions options)

Deprecated. Use builder(Scheme, EndpointGroup), ClientBuilder.factory(ClientFactory) and ClientBuilder.options(ClientOptions).

Creates a new client that connects to the specified EndpointGroup with the Scheme using the specified ClientFactory.

Parameters:

factory - an alternative ClientFactory

scheme - the Scheme

endpointGroup - the server EndpointGroup

clientType - the type of the new client

options - the ClientOptions

Throws:

IllegalArgumentException - if the specified Scheme or the specified clientType is unsupported for the scheme

builder

public static ClientBuilder builder(String uri)

Returns a new ClientBuilder that builds the client that connects to the specified uri.

builder

public static ClientBuilder builder(URI uri)

Returns a new ClientBuilder that builds the client that connects to the specified URI.

builder

public static ClientBuilder builder(String scheme,
                                    EndpointGroup endpointGroup)

Returns a new ClientBuilder that builds the client that connects to the specified EndpointGroup with the scheme.

builder

public static ClientBuilder builder(Scheme scheme,
                                    EndpointGroup endpointGroup)

Returns a new ClientBuilder that builds the client that connects to the specified EndpointGroup with the Scheme.

builder

public static ClientBuilder builder(SessionProtocol protocol,
                                    EndpointGroup endpointGroup)

Returns a new ClientBuilder that builds the client that connects to the specified EndpointGroup with the SessionProtocol.

newDerivedClient

public static <T> T newDerivedClient(T client,
                                     ClientOptionValue<?>... additionalOptions)

Creates a new derived client that connects to the same URI with the specified client and the specified additionalOptions.

See Also:

ClientBuilder, for more information about how the base options and additional options are merged when a derived client is created.

newDerivedClient

public static <T> T newDerivedClient(T client,
                                     Iterable<ClientOptionValue<?>> additionalOptions)

Creates a new derived client that connects to the same URI with the specified client and the specified additionalOptions.

See Also:

ClientBuilder, for more information about how the base options and additional options are merged when a derived client is created.

newDerivedClient

public static <T> T newDerivedClient(T client,
                                     Function<? super ClientOptions,ClientOptions> configurator)

Creates a new derived client that connects to the same URI with the specified client but with different ClientOptions. For example:

 WebClient derivedWebClient = Clients.newDerivedClient(webClient, options -> {
     ClientOptionsBuilder builder = options.toBuilder();
     builder.decorator(...);     // Add a decorator.
     builder.addHttpHeader(...); // Add an HTTP header.
     return builder.build();
 });
 

Parameters:

configurator - a Function whose input is the original ClientOptions of the client being derived from and whose output is the ClientOptions of the new derived client

See Also:

ClientBuilder, for more information about how the base options and additional options are merged when a derived client is created., ClientOptionsBuilder

unwrap

public static <T> T unwrap(Object client,
                           Class<T> type)

Unwraps the specified client into the object of the specified type. Use this method instead of an explicit downcast. For example:

 WebClient client = WebClient.builder(...)
                             .decorator(LoggingClient.newDecorator())
                             .build();

 LoggingClient unwrapped = Clients.unwrap(client, LoggingClient.class);

 // If the client implements Unwrappable, you can just use the 'as()' method.
 LoggingClient unwrapped2 = client.as(LoggingClient.class);
 

Parameters:

type - the type of the object to return

Returns:

the object of the specified type if found, or null if not found.

See Also:

Client.as(Class), ClientFactory.unwrap(Object, Class), Unwrappable

withHttpHeader

public static SafeCloseable withHttpHeader(CharSequence name,
                                           String value)

Sets the specified HTTP header in a thread-local variable so that the header is sent by the client call made from the current thread. Use the try-with-resources block with the returned SafeCloseable to unset the thread-local variable automatically:

 import static com.linecorp.armeria.common.HttpHeaderNames.AUTHORIZATION;

 try (SafeCloseable ignored = withHttpHeader(AUTHORIZATION, myCredential)) {
     client.executeSomething(..);
 }
 

You can also nest the header manipulation:

 import static com.linecorp.armeria.common.HttpHeaderNames.AUTHORIZATION;
 import static com.linecorp.armeria.common.HttpHeaderNames.USER_AGENT;

 try (SafeCloseable ignored = withHttpHeader(USER_AGENT, myAgent)) {
     for (String secret : secrets) {
         try (SafeCloseable ignored2 = withHttpHeader(AUTHORIZATION, secret)) {
             // Both USER_AGENT and AUTHORIZATION will be set.
             client.executeSomething(..);
         }
     }
 }
 

See Also:

withHttpHeaders(Function)

withHttpHeader

public static SafeCloseable withHttpHeader(CharSequence name,
                                           Object value)

Sets the specified HTTP header in a thread-local variable so that the header is sent by the client call made from the current thread. Use the try-with-resources block with the returned SafeCloseable to unset the thread-local variable automatically:

 import static com.linecorp.armeria.common.HttpHeaderNames.CONTENT_TYPE;
 import static com.linecorp.armeria.common.MediaType.JSON_UTF_8;

 try (SafeCloseable ignored = withHttpHeader(CONTENT_TYPE, JSON_UTF_8)) {
     client.executeSomething(..);
 }
 

You can also nest the header manipulation:

 import static com.linecorp.armeria.common.HttpHeaderNames.AUTHORIZATION;
 import static com.linecorp.armeria.common.HttpHeaderNames.CONTENT_TYPE;
 import static com.linecorp.armeria.common.MediaType.JSON_UTF_8;

 try (SafeCloseable ignored = withHttpHeader(CONTENT_TYPE, JSON_UTF_8)) {
     for (String secret : secrets) {
         try (SafeCloseable ignored2 = withHttpHeader(AUTHORIZATION, secret)) {
             // Both CONTENT_TYPE and AUTHORIZATION will be set.
             client.executeSomething(..);
         }
     }
 }
 

See Also:

withHttpHeaders(Function)

withHttpHeaders

public static SafeCloseable withHttpHeaders(Function<? super HttpHeaders,? extends HttpHeaders> headerManipulator)

Sets the specified HTTP header manipulating function in a thread-local variable so that the manipulated headers are sent by the client call made from the current thread. Use the try-with-resources block with the returned SafeCloseable to unset the thread-local variable automatically:

 import static com.linecorp.armeria.common.HttpHeaderNames.AUTHORIZATION;
 import static com.linecorp.armeria.common.HttpHeaderNames.USER_AGENT;

 try (SafeCloseable ignored = withHttpHeaders(headers -> {
     return headers.toBuilder()
                   .set(HttpHeaders.AUTHORIZATION, myCredential)
                   .set(HttpHeaders.USER_AGENT, myAgent)
                   .build();
 })) {
     client.executeSomething(..);
 }
 

You can also nest the header manipulation:

 import static com.linecorp.armeria.common.HttpHeaderNames.AUTHORIZATION;
 import static com.linecorp.armeria.common.HttpHeaderNames.USER_AGENT;

 try (SafeCloseable ignored = withHttpHeaders(h -> {
          return h.toBuilder()
                  .set(USER_AGENT, myAgent)
                  .build();
      })) {
     for (String secret : secrets) {
         try (SafeCloseable ignored2 = withHttpHeaders(h -> {
                  return h.toBuilder()
                          .set(AUTHORIZATION, secret)
                          .build();
              })) {
             // Both USER_AGENT and AUTHORIZATION will be set.
             client.executeSomething(..);
         }
     }
 }
 

See Also:

withHttpHeader(CharSequence, String)

withContextCustomizer

public static SafeCloseable withContextCustomizer(Consumer<? super ClientRequestContext> contextCustomizer)

Sets the specified ClientRequestContext customization function in a thread-local variable so that the customized context is used when the client invokes a request from the current thread. Use the try-with-resources block with the returned SafeCloseable to unset the thread-local variable automatically:

 try (SafeCloseable ignored = withContextCustomizer(ctx -> {
     ctx.setAttr(USER_ID, userId);
     ctx.setAttr(USER_SECRET, secret);
 })) {
     client.executeSomething(..);
 }
 

You can also nest the request context customization:

 try (SafeCloseable ignored = withContextCustomizer(ctx -> ctx.setAttr(USER_ID, userId))) {
     String secret = client.getSecret();
     try (SafeCloseable ignored2 = withContextCustomizer(ctx -> ctx.setAttr(USER_SECRET, secret))) {
         // Both USER_ID and USER_SECRET will be set.
         client.executeSomething(..);
     }
 }
 

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:

withHttpHeaders(Function)

newContextCaptor

public static ClientRequestContextCaptor newContextCaptor()

Prepare to capture the ClientRequestContext of the next request sent from the current thread. Use the try-with-resources block with the returned ClientRequestContextCaptor to retrieve the captured ClientRequestContext and to unset the thread-local variable automatically.

 try (ClientRequestContextCaptor captor = Clients.newContextCaptor()) {
     WebClient.of().get("https://www.example.com/hello");
     ClientRequestContext ctx = captor.get();
     assert ctx.path().equals("/hello");
 }

Note that you can also capture more than one ClientRequestContext:

 try (ClientRequestContextCaptor captor = Clients.newContextCaptor()) {
     WebClient.of().get("https://www.example.com/foo");
     WebClient.of().get("https://www.example.com/bar");
     List<ClientRequestContext> contexts = captor.getAll();
     assert contexts.get(0).path().equals("/foo");
     assert contexts.get(1).path().equals("/bar");
 }

isUndefinedUri

public static boolean isUndefinedUri(URI uri)

Returns true if the specified uri is an undefined URI, which signifies that a Client, was created without a URI or EndpointGroup. For example, isUndefinedUri(WebClient.of().uri()) will return true.