Package com.linecorp.armeria.client

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

    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 = new ClientOptionsBuilder();
 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.

    • Method Detail

      • 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 ClientBuilder(String) or the specified clientType is unsupported for the scheme

      • defaultWriteTimeout

        @Deprecated
public B defaultWriteTimeout​(Duration writeTimeout)
        Deprecated.
        Use writeTimeout(Duration).
        Sets the timeout of a socket write attempt.
        Parameters:
        writeTimeout - the timeout. 0 disables the timeout.

      • defaultWriteTimeoutMillis

        @Deprecated
public B defaultWriteTimeoutMillis​(long writeTimeoutMillis)
        Deprecated.
        Use writeTimeoutMillis(long).
        Sets the timeout of a socket write attempt in milliseconds.
        Parameters:
        writeTimeoutMillis - the timeout in milliseconds. 0 disables the timeout.

      • writeTimeout

        public B writeTimeout​(Duration writeTimeout)
        Sets the timeout of a socket write attempt.
        Parameters:
        writeTimeout - the timeout. 0 disables the timeout.

      • writeTimeoutMillis

        public B 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 B defaultResponseTimeout​(Duration responseTimeout)
        Deprecated.
        Use responseTimeout(Duration).
        Sets the timeout of a response.
        Parameters:
        responseTimeout - the timeout. 0 disables the timeout.

      • defaultResponseTimeoutMillis

        @Deprecated
public B defaultResponseTimeoutMillis​(long responseTimeoutMillis)
        Deprecated.
        Use responseTimeoutMillis(long).
        Sets the timeout of a response in milliseconds.
        Parameters:
        responseTimeoutMillis - the timeout in milliseconds. 0 disables the timeout.

      • responseTimeout

        public B responseTimeout​(Duration responseTimeout)
        Sets the timeout of a response.
        Parameters:
        responseTimeout - the timeout. 0 disables the timeout.

      • responseTimeoutMillis

        public B responseTimeoutMillis​(long responseTimeoutMillis)
        Sets the timeout of a response in milliseconds.
        Parameters:
        responseTimeoutMillis - the timeout in milliseconds. 0 disables the timeout.

      • defaultMaxResponseLength

        @Deprecated
public B defaultMaxResponseLength​(long maxResponseLength)
        Deprecated.
        Use maxResponseLength(long).
        Sets the maximum allowed length of a server response in bytes.
        Parameters:
        maxResponseLength - the maximum length in bytes. 0 disables the limit.

      • maxResponseLength

        public B 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.

      • contentPreview

        public B contentPreview​(int length,
                        Charset defaultCharset)
        Sets the ContentPreviewerFactory for creating a ContentPreviewer which produces the preview with the maximum length limit for a request and a response. The previewer is enabled only if the content type of a request/response meets any of the following conditions:
        • when it matches text/* or application/x-www-form-urlencoded
        • when its charset has been specified
        • when its subtype is "xml" or "json"
        • when its subtype ends with "+xml" or "+json"
        Parameters:
        length - the maximum length of the preview
        defaultCharset - the default charset used when a charset is not specified in the "content-type" header

      • contentPreview

        public B contentPreview​(int length)
        Sets the ContentPreviewerFactory for creating a ContentPreviewer which produces the preview with the maximum length limit for a request and a response. The previewer is enabled only if the content type of a request/response meets any of the following conditions:
        • when it matches text/* or application/x-www-form-urlencoded
        • when its charset has been specified
        • when its subtype is "xml" or "json"
        • when its subtype ends with "+xml" or "+json"
        Parameters:
        length - the maximum length of the preview.

      • decorator

        public <T extends Client<I,​O>,​R extends Client<I,​O>,​I extends HttpRequest,​O extends HttpResponse> B decorator​(Function<T,​R> decorator)
        Adds the specified HTTP-level decorator.
        Type Parameters:
        T - the type of the Client being decorated
        R - the type of the Client produced by the decorator
        I - the Request type of the Client being decorated
        O - the Response type of the Client being decorated
        Parameters:
        decorator - the Function that transforms a Client to another

      • rpcDecorator

        public <T extends Client<I,​O>,​R extends Client<I,​O>,​I extends RpcRequest,​O extends RpcResponse> B rpcDecorator​(Function<T,​R> decorator)
        Adds the specified RPC-level decorator.
        Type Parameters:
        T - the type of the Client being decorated
        R - the type of the Client produced by the decorator
        I - the Request type of the Client being decorated
        O - the Response type of the Client being decorated
        Parameters:
        decorator - the Function that transforms a Client to another

      • addHttpHeader

        public B addHttpHeader​(CharSequence name,
                       Object value)
        Adds the specified HTTP header.

      • addHttpHeaders

        public B addHttpHeaders​(Iterable<? extends Map.Entry<? extends CharSequence,​?>> httpHeaders)
        Adds the specified HTTP headers.

      • setHttpHeader

        public B setHttpHeader​(CharSequence name,
                       Object value)
        Sets the specified HTTP header.

      • setHttpHeaders

        public B setHttpHeaders​(Iterable<? extends Map.Entry<? extends CharSequence,​?>> httpHeaders)
        Sets the specified HTTP headers.