Package com.linecorp.armeria.client

Class HttpClientBuilder

java.lang.Object

com.linecorp.armeria.client.HttpClientBuilder

public final class HttpClientBuilder
extends Object

Creates a new HTTP client that connects to the specified URI using the builder pattern. Use the factory methods in HttpClient if you do not have many options to override. Please refer to ClientBuilder for how decorators and HTTP headers are configured

Constructor Summary

Constructors

Constructor	Description
HttpClientBuilder(SessionProtocol sessionProtocol, Endpoint endpoint)	Creates a new instance.
HttpClientBuilder(String uri)	Creates a new instance.
HttpClientBuilder(URI uri)	Creates a new instance.

Method Summary

Modifier and Type	Method	Description
B	addHttpHeader(CharSequence name, Object value)	Adds the specified HTTP header.
B	addHttpHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> httpHeaders)	Adds the specified HTTP headers.
HttpClient	build()	Returns a newly-created HTTP client based on the properties of this builder.
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.
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.
B	contentPreviewerFactory(ContentPreviewerFactory factory)	Sets the ContentPreviewerFactory for a request and a response.
<I extends HttpRequest,O extends HttpResponse> B	decorator(DecoratingClientFunction<I,O> decorator)	Adds the specified HTTP-level decorator.
<I extends Request,O extends Response> B	decorator(Class<I> requestType, Class<O> responseType, DecoratingClientFunction<I,O> decorator)	Deprecated. Use decorator(DecoratingClientFunction) or rpcDecorator(DecoratingClientFunction).
<T extends Client<I,O>,R extends Client<I,O>,I extends Request,O extends Response> B	decorator(Class<I> requestType, Class<O> responseType, Function<T,R> decorator)	Deprecated. Use decorator(Function) or rpcDecorator(Function).
<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.
B	defaultMaxResponseLength(long maxResponseLength)	Deprecated. Use maxResponseLength(long).
B	defaultResponseTimeout(Duration responseTimeout)	Deprecated. Use responseTimeout(Duration).
B	defaultResponseTimeoutMillis(long responseTimeoutMillis)	Deprecated. Use responseTimeoutMillis(long).
B	defaultWriteTimeout(Duration writeTimeout)	Deprecated. Use writeTimeout(Duration).
B	defaultWriteTimeoutMillis(long writeTimeoutMillis)	Deprecated. Use writeTimeoutMillis(long).
HttpClientBuilder	factory(ClientFactory factory)	Sets the ClientFactory of the client.
B	maxResponseLength(long maxResponseLength)	Sets the maximum allowed length of a server response in bytes.
<T> B	option(ClientOption<T> option, T value)	Adds the specified ClientOption and its value.
<T> B	option(ClientOptionValue<T> optionValue)	Adds the specified ClientOptionValue.
B	options(ClientOptions options)	Adds the specified ClientOptions.
B	options(ClientOptionValue<?>... options)	Adds the specified ClientOptionValues.
B	options(Iterable<ClientOptionValue<?>> options)	Adds the specified ClientOptionValues.
HttpClientBuilder	path(String path)	Sets the path of the client.
B	requestContentPreviewerFactory(ContentPreviewerFactory factory)	Sets the ContentPreviewerFactory for a request.
B	responseContentPreviewerFactory(ContentPreviewerFactory factory)	Sets the ContentPreviewerFactory for a response.
B	responseTimeout(Duration responseTimeout)	Sets the timeout of a response.
B	responseTimeoutMillis(long responseTimeoutMillis)	Sets the timeout of a response in milliseconds.
<I extends RpcRequest,O extends RpcResponse> B	rpcDecorator(DecoratingClientFunction<I,O> decorator)	Adds the specified RPC-level decorator.
<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.
B	setHttpHeader(CharSequence name, Object value)	Sets the specified HTTP header.
B	setHttpHeaders(Iterable<? extends Map.Entry<? extends CharSequence,?>> httpHeaders)	Sets the specified HTTP headers.
B	writeTimeout(Duration writeTimeout)	Sets the timeout of a socket write attempt.
B	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

HttpClientBuilder

public HttpClientBuilder(String uri)

Creates a new instance.

Throws:

IllegalArgumentException - if the scheme of the uri is not one of the fields in SessionProtocol or the uri violates RFC 2396

HttpClientBuilder

public HttpClientBuilder(URI uri)

Creates a new instance.

Throws:

IllegalArgumentException - if the scheme of the uri is not one of the fields in SessionProtocol

HttpClientBuilder

public HttpClientBuilder(SessionProtocol sessionProtocol,
                         Endpoint endpoint)

Creates a new instance.

Throws:

IllegalArgumentException - if the sessionProtocol is not one of the fields in SessionProtocol

Method Detail

factory

public HttpClientBuilder factory(ClientFactory factory)

Sets the ClientFactory of the client. The default is ClientFactory.DEFAULT.

path

public HttpClientBuilder path(String path)

Sets the path of the client.

build

public HttpClient build()

Returns a newly-created HTTP client based on the properties of this builder.

Throws:

IllegalArgumentException - if the scheme of the uri specified in HttpClientBuilder(String) or HttpClientBuilder(URI) is not an HTTP scheme

options

public B options(ClientOptions options)

Adds the specified ClientOptions.

options

public B options(ClientOptionValue<?>... options)

Adds the specified ClientOptionValues.

options

public B options(Iterable<ClientOptionValue<?>> options)

Adds the specified ClientOptionValues.

option

public <T> B option(ClientOption<T> option,
                    T value)

Adds the specified ClientOption and its value.

option

public <T> B option(ClientOptionValue<T> optionValue)

Adds the specified ClientOptionValue.

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.

requestContentPreviewerFactory

public B requestContentPreviewerFactory(ContentPreviewerFactory factory)

Sets the ContentPreviewerFactory for a request.

responseContentPreviewerFactory

public B responseContentPreviewerFactory(ContentPreviewerFactory factory)

Sets the ContentPreviewerFactory for a response.

contentPreviewerFactory

public B contentPreviewerFactory(ContentPreviewerFactory factory)

Sets the ContentPreviewerFactory for a request and a response.

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

@Deprecated
public <T extends Client<I,O>,R extends Client<I,O>,I extends Request,O extends Response> B decorator(Class<I> requestType,
                                                                                                                                    Class<O> responseType,
                                                                                                                                    Function<T,R> decorator)

Deprecated.

Use decorator(Function) or rpcDecorator(Function).

Adds the specified 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:

requestType - the type of the Request that the decorator is interested in

responseType - the type of the Response that the decorator is interested in

decorator - the Function that transforms a Client to another

decorator

@Deprecated
public <I extends Request,O extends Response> B decorator(Class<I> requestType,
                                                                Class<O> responseType,
                                                                DecoratingClientFunction<I,O> decorator)

Deprecated.

Use decorator(DecoratingClientFunction) or rpcDecorator(DecoratingClientFunction).

Adds the specified decorator.

Type Parameters:

I - the Request type of the Client being decorated

O - the Response type of the Client being decorated

Parameters:

requestType - the type of the Request that the decorator is interested in

responseType - the type of the Response that the decorator is interested in

decorator - the DecoratingClientFunction that intercepts an invocation

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

decorator

public <I extends HttpRequest,O extends HttpResponse> B decorator(DecoratingClientFunction<I,O> decorator)

Adds the specified HTTP-level decorator.

Type Parameters:

I - the Request type of the Client being decorated

O - the Response type of the Client being decorated

Parameters:

decorator - the DecoratingClientFunction that intercepts an invocation

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

rpcDecorator

public <I extends RpcRequest,O extends RpcResponse> B rpcDecorator(DecoratingClientFunction<I,O> decorator)

Adds the specified RPC-level decorator.

Type Parameters:

I - the Request type of the Client being decorated

O - the Response type of the Client being decorated

Parameters:

decorator - the DecoratingClientFunction that intercepts an invocation

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.