ClientBuilder (filter-service-metrics 1.13 1.13 API)

java.lang.Object
- com.linecorp.armeria.client.ClientBuilder

```
public final class ClientBuilder
extends Object
```
Creates a new client that connects to the specified URI using the builder pattern. Use the factory methods in Clients if you do not have many options to override. If you are creating an WebClient, it is recommended to use the WebClientBuilder or factory methods in WebClient.
How are decorators and HTTP headers configured?

Unlike other options, when a user calls option(ClientOption, Object) or options() with a ClientOption.DECORATION or a ClientOption.HTTP_HEADERS, this builder will not simply replace the old option but merge the specified option into the previous option value. For example:
```
 ClientOptionsBuilder b = ClientOptions.builder();
 b.option(ClientOption.HTTP_HEADERS, headersA);
 b.option(ClientOption.HTTP_HEADERS, headersB);
 b.option(ClientOption.DECORATION, decorationA);
 b.option(ClientOption.DECORATION, decorationB);

 ClientOptions opts = b.build();
 HttpHeaders httpHeaders = opts.httpHeaders();
 ClientDecoration decorations = opts.decoration();
 
```
httpHeaders will contain all HTTP headers of headersA and headersB. If headersA and headersB have the headers with the same name, the duplicate header in headerB will replace the one with the same name in headerA. Similarly, decorations will contain all decorators of decorationA and decorationB, but there will be no replacement but only addition.

Constructor Summary

Constructors
Constructor and Description
`ClientBuilder(Scheme scheme, Endpoint endpoint)` Deprecated. Use `Clients.builder(Scheme, EndpointGroup)`.
`ClientBuilder(SessionProtocol protocol, Endpoint endpoint)` Deprecated. Use `Clients.builder(SessionProtocol, EndpointGroup)`.
`ClientBuilder(String uri)` Deprecated. Use `Clients.builder(String)`.
`ClientBuilder(String scheme, Endpoint endpoint)` Deprecated. Use `Clients.builder(String, EndpointGroup)`.
`ClientBuilder(URI uri)` Deprecated. Use `Clients.builder(URI)`.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`ClientBuilder`	`addHttpHeader(CharSequence name, Object value)` Adds the specified HTTP header.
`ClientBuilder`	`addHttpHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> httpHeaders)` Adds the specified HTTP headers.
`<T> T`	`build(Class<T> clientType)` Returns a newly-created client which implements the specified `clientType`, based on the properties of this builder.
`ClientBuilder`	`decorator(DecoratingHttpClientFunction decorator)` Adds the specified HTTP-level `decorator`.
`ClientBuilder`	`decorator(Function<? super HttpClient,? extends HttpClient> decorator)` Adds the specified HTTP-level `decorator`.
`ClientBuilder`	`defaultMaxResponseLength(long maxResponseLength)` Deprecated.
`ClientBuilder`	`defaultResponseTimeout(Duration responseTimeout)` Deprecated.
`ClientBuilder`	`defaultResponseTimeoutMillis(long responseTimeoutMillis)` Deprecated.
`ClientBuilder`	`defaultWriteTimeout(Duration writeTimeout)` Deprecated.
`ClientBuilder`	`defaultWriteTimeoutMillis(long writeTimeoutMillis)` Deprecated.
`ClientBuilder`	`endpointRemapper(Function<? super Endpoint,? extends EndpointGroup> endpointRemapper)` Sets a `Function` that remaps an `Endpoint` into an `EndpointGroup`.
`ClientBuilder`	`factory(ClientFactory factory)` Sets the `ClientFactory` used for creating a client.
`ClientBuilder`	`maxResponseLength(long maxResponseLength)` Sets the maximum allowed length of a server response in bytes.
`<T> ClientBuilder`	`option(ClientOption<T> option, T value)` Adds the specified `ClientOption` and its `value`.
`<T> ClientBuilder`	`option(ClientOptionValue<T> optionValue)` Adds the specified `ClientOptionValue`.
`ClientBuilder`	`options(ClientOptions options)` Adds the specified `ClientOptions`.
`ClientBuilder`	`options(ClientOptionValue<?>... options)` Adds the specified `ClientOptionValue`s.
`ClientBuilder`	`options(Iterable<ClientOptionValue<?>> options)` Adds the specified `ClientOptionValue`s.
`ClientBuilder`	`path(String path)` Sets the `path` of the client.
`ClientBuilder`	`requestIdGenerator(Supplier<RequestId> requestIdGenerator)` Sets the `Supplier` that generates a `RequestId`.
`ClientBuilder`	`responseTimeout(Duration responseTimeout)` Sets the timeout of a response.
`ClientBuilder`	`responseTimeoutMillis(long responseTimeoutMillis)` Sets the timeout of a response in milliseconds.
`ClientBuilder`	`rpcDecorator(DecoratingRpcClientFunction decorator)` Adds the specified RPC-level `decorator`.
`ClientBuilder`	`rpcDecorator(Function<? super RpcClient,? extends RpcClient> decorator)` Adds the specified RPC-level `decorator`.
`ClientBuilder`	`serializationFormat(SerializationFormat format)` Sets the `SerializationFormat` of the client.
`ClientBuilder`	`setHttpHeader(CharSequence name, Object value)` Sets the specified HTTP header.
`ClientBuilder`	`setHttpHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> httpHeaders)` Sets the specified HTTP headers.
`ClientBuilder`	`writeTimeout(Duration writeTimeout)` Sets the timeout of a socket write attempt.
`ClientBuilder`	`writeTimeoutMillis(long writeTimeoutMillis)` Sets the timeout of a socket write attempt in milliseconds.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - ClientBuilder
```
@Deprecated
public ClientBuilder(String uri)
```
    Deprecated. Use Clients.builder(String).
    
    Creates a new ClientBuilder that builds the client that connects to the specified uri.
  - ClientBuilder
```
@Deprecated
public ClientBuilder(URI uri)
```
    Deprecated. Use Clients.builder(URI).
    
    Creates a new ClientBuilder that builds the client that connects to the specified URI.
  - ClientBuilder
```
@Deprecated
public ClientBuilder(String scheme,
                                 Endpoint endpoint)
```
    Deprecated. Use Clients.builder(String, EndpointGroup).
    
    Creates a new ClientBuilder that builds the client that connects to the specified Endpoint with the scheme.
  - ClientBuilder
```
@Deprecated
public ClientBuilder(Scheme scheme,
                                 Endpoint endpoint)
```
    Deprecated. Use Clients.builder(Scheme, EndpointGroup).
    
    Creates a new ClientBuilder that builds the client that connects to the specified Endpoint with the Scheme.
  - ClientBuilder
```
@Deprecated
public ClientBuilder(SessionProtocol protocol,
                                 Endpoint endpoint)
```
    Deprecated. Use Clients.builder(SessionProtocol, EndpointGroup).
    
    Creates a new ClientBuilder that builds the client that connects to the specified Endpoint with the SessionProtocol.
- Method Detail
  - path
```
public ClientBuilder path(String path)
```
    Sets the path of the client.
  - serializationFormat
```
public ClientBuilder serializationFormat(SerializationFormat format)
```
    Sets the SerializationFormat of the client. The default is SerializationFormat.NONE.
  - build
```
public <T> T build(Class<T> clientType)
```
    Returns a newly-created client which implements the specified clientType, based on the properties of this builder.
    
    Throws:
    
    IllegalArgumentException - if the scheme of the uri specified in Clients.builder(String) or the specified clientType is unsupported for the scheme
  - options
```
public ClientBuilder options(ClientOptions options)
```
    Adds the specified ClientOptions.
  - options
```
public ClientBuilder options(ClientOptionValue<?>... options)
```
    Adds the specified ClientOptionValues.
  - options
```
public ClientBuilder options(Iterable<ClientOptionValue<?>> options)
```
    Adds the specified ClientOptionValues.
  - option
```
public <T> ClientBuilder option(ClientOption<T> option,
                                T value)
```
    Adds the specified ClientOption and its value.
  - option
```
public <T> ClientBuilder option(ClientOptionValue<T> optionValue)
```
    Adds the specified ClientOptionValue.
  - factory
```
public ClientBuilder factory(ClientFactory factory)
```
    Sets the ClientFactory used for creating a client. The default is ClientFactory.ofDefault().
  - defaultWriteTimeout
```
@Deprecated
public ClientBuilder defaultWriteTimeout(Duration writeTimeout)
```
    Deprecated.
    
    Sets the timeout of a socket write attempt.
    
    Parameters:
    
    writeTimeout - the timeout. 0 disables the timeout.
  - defaultWriteTimeoutMillis
```
@Deprecated
public ClientBuilder defaultWriteTimeoutMillis(long writeTimeoutMillis)
```
    Deprecated.
    
    Sets the timeout of a socket write attempt in milliseconds.
    
    Parameters:
    
    writeTimeoutMillis - the timeout in milliseconds. 0 disables the timeout.
  - writeTimeout
```
public ClientBuilder writeTimeout(Duration writeTimeout)
```
    Sets the timeout of a socket write attempt.
    
    Parameters:
    
    writeTimeout - the timeout. 0 disables the timeout.
  - writeTimeoutMillis
```
public ClientBuilder writeTimeoutMillis(long writeTimeoutMillis)
```
    Sets the timeout of a socket write attempt in milliseconds.
    
    Parameters:
    
    writeTimeoutMillis - the timeout in milliseconds. 0 disables the timeout.
  - defaultResponseTimeout
```
@Deprecated
public ClientBuilder defaultResponseTimeout(Duration responseTimeout)
```
    Deprecated.
    
    Sets the timeout of a response.
    
    Parameters:
    
    responseTimeout - the timeout. 0 disables the timeout.
  - defaultResponseTimeoutMillis
```
@Deprecated
public ClientBuilder defaultResponseTimeoutMillis(long responseTimeoutMillis)
```
    Deprecated.
    
    Sets the timeout of a response in milliseconds.
    
    Parameters:
    
    responseTimeoutMillis - the timeout in milliseconds. 0 disables the timeout.
  - responseTimeout
```
public ClientBuilder responseTimeout(Duration responseTimeout)
```
    Sets the timeout of a response.
    
    Parameters:
    
    responseTimeout - the timeout. 0 disables the timeout.
  - responseTimeoutMillis
```
public ClientBuilder responseTimeoutMillis(long responseTimeoutMillis)
```
    Sets the timeout of a response in milliseconds.
    
    Parameters:
    
    responseTimeoutMillis - the timeout in milliseconds. 0 disables the timeout.
  - defaultMaxResponseLength
```
@Deprecated
public ClientBuilder defaultMaxResponseLength(long maxResponseLength)
```
    Deprecated.
    
    Sets the maximum allowed length of a server response in bytes.
    
    Parameters:
    
    maxResponseLength - the maximum length in bytes. 0 disables the limit.
  - maxResponseLength
```
public ClientBuilder maxResponseLength(long maxResponseLength)
```
    Sets the maximum allowed length of a server response in bytes.
    
    Parameters:
    
    maxResponseLength - the maximum length in bytes. 0 disables the limit.
  - requestIdGenerator
```
public ClientBuilder requestIdGenerator(Supplier<RequestId> requestIdGenerator)
```
    Sets the Supplier that generates a RequestId.
  - endpointRemapper
```
public ClientBuilder endpointRemapper(Function<? super Endpoint,? extends EndpointGroup> endpointRemapper)
```
    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.
    See Also:
    
    ClientOption.ENDPOINT_REMAPPER, ClientOptions.endpointRemapper()
  - decorator
```
public ClientBuilder decorator(Function<? super HttpClient,? extends HttpClient> decorator)
```
    Adds the specified HTTP-level decorator.
    
    Parameters:
    
    decorator - the Function that transforms an HttpClient to another
  - decorator
```
public ClientBuilder decorator(DecoratingHttpClientFunction decorator)
```
    Adds the specified HTTP-level decorator.
    
    Parameters:
    
    decorator - the DecoratingHttpClientFunction that intercepts an invocation
  - rpcDecorator
```
public ClientBuilder rpcDecorator(Function<? super RpcClient,? extends RpcClient> decorator)
```
    Adds the specified RPC-level decorator.
    
    Parameters:
    
    decorator - the Function that transforms an RpcClient to another
  - rpcDecorator
```
public ClientBuilder rpcDecorator(DecoratingRpcClientFunction decorator)
```
    Adds the specified RPC-level decorator.
    
    Parameters:
    
    decorator - the DecoratingRpcClientFunction that intercepts an invocation
  - addHttpHeader
```
public ClientBuilder addHttpHeader(CharSequence name,
                                   Object value)
```
    Adds the specified HTTP header.
  - addHttpHeaders
```
public ClientBuilder addHttpHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> httpHeaders)
```
    Adds the specified HTTP headers.
  - setHttpHeader
```
public ClientBuilder setHttpHeader(CharSequence name,
                                   Object value)
```
    Sets the specified HTTP header.
  - setHttpHeaders
```
public ClientBuilder setHttpHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> httpHeaders)
```
    Sets the specified HTTP headers.

Class ClientBuilder

How are decorators and HTTP headers configured?

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ClientBuilder

ClientBuilder

ClientBuilder

ClientBuilder

ClientBuilder

Method Detail

path

serializationFormat

build

options

options

options

option

option

factory

defaultWriteTimeout

defaultWriteTimeoutMillis

writeTimeout

writeTimeoutMillis

defaultResponseTimeout

defaultResponseTimeoutMillis

responseTimeout

responseTimeoutMillis

defaultMaxResponseLength

maxResponseLength

requestIdGenerator

endpointRemapper

decorator

decorator

rpcDecorator

rpcDecorator

addHttpHeader

addHttpHeaders

setHttpHeader

setHttpHeaders