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

  • Method Details

    • 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 specified uri is invalid, or the specified clientType is unsupported for the uri's 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 specified URI is invalid, or the specified clientType is unsupported for the URI's 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 specified 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​(String scheme, EndpointGroup endpointGroup, String path, Class<T> clientType)
      Creates a new client that connects to the specified EndpointGroup with the specified scheme and path using the default ClientFactory.
      Parameters:
      scheme - the Scheme represented as a String
      endpointGroup - the server EndpointGroup
      path - the path to the endpoint
      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 specified 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​(Scheme scheme, EndpointGroup endpointGroup, String path, Class<T> clientType)
      Creates a new client that connects to the specified EndpointGroup with the specified Scheme and path using the default ClientFactory.
      Parameters:
      scheme - the Scheme
      endpointGroup - the server EndpointGroup
      path - the path to the endpoint
      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 specified 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

      public static <T> T newClient​(SessionProtocol protocol, EndpointGroup endpointGroup, String path, Class<T> clientType)
      Creates a new client that connects to the specified EndpointGroup with the specified SessionProtocol and path using the default ClientFactory.
      Parameters:
      protocol - the SessionProtocol
      endpointGroup - the server EndpointGroup
      path - the path to the endpoint
      clientType - the type of the new client
      Throws:
      IllegalArgumentException - if the specified clientType is unsupported for the specified SessionProtocol or SerializationFormat is required.

    • builder

      public static ClientBuilder builder​(String uri)
      Returns a new ClientBuilder that builds the client that connects to the specified uri.
      Throws:
      IllegalArgumentException - if the specified uri is invalid, or the specified clientType is unsupported for the uri's scheme

    • builder

      public static ClientBuilder builder​(URI uri)
      Returns a new ClientBuilder that builds the client that connects to the specified URI.
      Throws:
      IllegalArgumentException - if the specified URI is invalid, or the specified clientType is unsupported for the URI's scheme

    • 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 specified scheme.
      Throws:
      IllegalArgumentException - if the scheme is invalid.

    • builder

      public static ClientBuilder builder​(String scheme, EndpointGroup endpointGroup, String path)
      Returns a new ClientBuilder that builds the client that connects to the specified EndpointGroup with the specified scheme and path.
      Throws:
      IllegalArgumentException - if the scheme is invalid.

    • 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 specified SessionProtocol.

    • builder

      public static ClientBuilder builder​(SessionProtocol protocol, EndpointGroup endpointGroup, String path)
      Returns a new ClientBuilder that builds the client that connects to the specified EndpointGroup with the specified SessionProtocol and path.

    • 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 specified Scheme.

    • builder

      public static ClientBuilder builder​(Scheme scheme, EndpointGroup endpointGroup, String path)
      Returns a new ClientBuilder that builds the client that connects to the specified EndpointGroup with the specified Scheme and path.

    • 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

      @Nullable 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(Consumer)

    • 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(Consumer)

    • withHttpHeaders

      @Deprecated public static SafeCloseable withHttpHeaders​(Function<? super HttpHeaders,​? extends HttpHeaders> headerManipulator)
      Deprecated.
      Use withHttpHeaders(Consumer).
      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:
      withHttpHeaders(Consumer)

    • withHttpHeaders

      public static SafeCloseable withHttpHeaders​(Consumer<HttpHeadersBuilder> headerMutator)
      Sets the specified Consumer, which mutates HTTP headers, in a thread-local variable so that the mutated 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(builder -> {
     builder.set(HttpHeaders.AUTHORIZATION, myCredential)
            .set(HttpHeaders.USER_AGENT, myAgent);
 })) {
     client.executeSomething(..);
 }
      You can also nest the header mutation: 
      
 import static com.linecorp.armeria.common.HttpHeaderNames.AUTHORIZATION;
 import static com.linecorp.armeria.common.HttpHeaderNames.USER_AGENT;

 try (SafeCloseable ignored = withHttpHeaders(builder -> {
          builder.set(USER_AGENT, myAgent);
      })) {
     for (String secret : secrets) {
         try (SafeCloseable ignored2 = withHttpHeaders(builder -> {
                  builder.set(AUTHORIZATION, secret);
              })) {
             // 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: may be null while the customizer function runs, because the target host of the Request is not determined yet.
      See Also:
      withHttpHeaders(Consumer)

    • 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.