Package 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 HttpClient, it is recommended to use the factory methods in HttpClient.

Method Summary

Modifier and Type	Method	Description
static <T> T	newClient(ClientFactory factory, Scheme scheme, Endpoint endpoint, Class<T> clientType, ClientOptions options)	Creates a new client that connects to the specified Endpoint with the Scheme using the specified ClientFactory.
static <T> T	newClient(ClientFactory factory, Scheme scheme, Endpoint endpoint, Class<T> clientType, ClientOptionValue<?>... options)	Creates a new client that connects to the specified Endpoint with the Scheme using the specified ClientFactory.
static <T> T	newClient(ClientFactory factory, SessionProtocol protocol, SerializationFormat format, Endpoint endpoint, Class<T> clientType, ClientOptions options)	Creates a new client that connects to the specified Endpoint with the SessionProtocol and the SerializationFormat using the specified ClientFactory.
static <T> T	newClient(ClientFactory factory, SessionProtocol protocol, SerializationFormat format, Endpoint endpoint, Class<T> clientType, ClientOptionValue<?>... options)	Creates a new client that connects to the specified Endpoint with the SessionProtocol and the SerializationFormat using the specified ClientFactory.
static <T> T	newClient(ClientFactory factory, String uri, Class<T> clientType, ClientOptions options)	Creates a new client that connects to the specified uri using the specified ClientFactory.
static <T> T	newClient(ClientFactory factory, String uri, Class<T> clientType, ClientOptionValue<?>... options)	Creates a new client that connects to the specified uri using the specified ClientFactory.
static <T> T	newClient(ClientFactory factory, URI uri, Class<T> clientType, ClientOptions options)	Creates a new client that connects to the specified URI using the specified ClientFactory.
static <T> T	newClient(ClientFactory factory, URI uri, Class<T> clientType, ClientOptionValue<?>... options)	Creates a new client that connects to the specified URI using the specified ClientFactory.
static <T> T	newClient(Scheme scheme, Endpoint endpoint, Class<T> clientType, ClientOptions options)	Creates a new client that connects to the specified Endpoint with the Scheme using the default ClientFactory.
static <T> T	newClient(Scheme scheme, Endpoint endpoint, Class<T> clientType, ClientOptionValue<?>... options)	Creates a new client that connects to the specified Endpoint with the Scheme using the default ClientFactory.
static <T> T	newClient(SessionProtocol protocol, SerializationFormat format, Endpoint endpoint, Class<T> clientType, ClientOptions options)	Creates a new client that connects to the specified Endpoint with the SessionProtocol and the SerializationFormat using the default ClientFactory.
static <T> T	newClient(SessionProtocol protocol, SerializationFormat format, Endpoint endpoint, Class<T> clientType, ClientOptionValue<?>... options)	Creates a new client that connects to the specified Endpoint with the SessionProtocol and the SerializationFormat using the default ClientFactory.
static <T> T	newClient(String uri, Class<T> clientType, ClientOptions options)	Creates a new client that connects to the specified uri using the default ClientFactory.
static <T> T	newClient(String uri, Class<T> clientType, ClientOptionValue<?>... options)	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)	Creates a new client that connects to the specified URI using the default ClientFactory.
static <T> T	newClient(URI uri, Class<T> clientType, ClientOptionValue<?>... options)	Creates a new client that connects to the specified URI using the default ClientFactory.
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, 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	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> Optional<T>	unwrap(Object client, Class<T> type)	Unwraps the specified client into the object of the specified type.
static SafeCloseable	withContextCustomizer(Consumer<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<HttpHeaders,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,
                              ClientOptionValue<?>... options)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

public static <T> T newClient(SessionProtocol protocol,
                              SerializationFormat format,
                              Endpoint endpoint,
                              Class<T> clientType,
                              ClientOptionValue<?>... options)

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

Parameters:

protocol - the session protocol

format - the SerializationFormat for remote procedure call

endpoint - the server Endpoint

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

public static <T> T newClient(SessionProtocol protocol,
                              SerializationFormat format,
                              Endpoint endpoint,
                              Class<T> clientType,
                              ClientOptions options)

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

Parameters:

protocol - the session protocol

format - the SerializationFormat for remote procedure call

endpoint - the server Endpoint

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

public static <T> T newClient(ClientFactory factory,
                              SessionProtocol protocol,
                              SerializationFormat format,
                              Endpoint endpoint,
                              Class<T> clientType,
                              ClientOptionValue<?>... options)

Creates a new client that connects to the specified Endpoint 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

endpoint - the server Endpoint

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

public static <T> T newClient(ClientFactory factory,
                              SessionProtocol protocol,
                              SerializationFormat format,
                              Endpoint endpoint,
                              Class<T> clientType,
                              ClientOptions options)

Creates a new client that connects to the specified Endpoint 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

endpoint - the server Endpoint

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

public static <T> T newClient(Scheme scheme,
                              Endpoint endpoint,
                              Class<T> clientType,
                              ClientOptionValue<?>... options)

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

Parameters:

scheme - the Scheme

endpoint - the server Endpoint

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

public static <T> T newClient(Scheme scheme,
                              Endpoint endpoint,
                              Class<T> clientType,
                              ClientOptions options)

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

Parameters:

scheme - the Scheme

endpoint - the server Endpoint

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

public static <T> T newClient(ClientFactory factory,
                              Scheme scheme,
                              Endpoint endpoint,
                              Class<T> clientType,
                              ClientOptionValue<?>... options)

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

Parameters:

factory - an alternative ClientFactory

scheme - the Scheme

endpoint - the server Endpoint

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

public static <T> T newClient(ClientFactory factory,
                              Scheme scheme,
                              Endpoint endpoint,
                              Class<T> clientType,
                              ClientOptions options)

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

Parameters:

factory - an alternative ClientFactory

scheme - the Scheme

endpoint - the server Endpoint

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

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:

 HttpClient derivedHttpClient = Clients.newDerivedClient(httpClient, options -> {
     ClientOptionsBuilder builder = new ClientOptionsBuilder(options);
     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> Optional<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:

 HttpClient client = new HttpClientBuilder()
     .decorator(LoggingClient.newDecorator())
     .build();

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

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

Parameters:

type - the type of the object to return

Returns:

the object of the specified type if found. Optional.empty() 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<HttpHeaders,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<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.attr(USER_ID).set(userId);
     ctx.attr(USER_SECRET).set(secret);
 })) {
     client.executeSomething(..);
 }
 

You can also nest the request context customization:

 try (SafeCloseable ignored = withContextCustomizer(ctx -> ctx.attr(USER_ID).set(userId))) {
     String secret = client.getSecret();
     try (SafeCloseable ignored2 = withContextCustomizer(ctx -> ctx.attr(USER_SECRET)
                                                                   .set(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)