com.linecorp.armeria.client

Interface ClientFactory

All Superinterfaces:

AsyncCloseable, AutoCloseable, ListenableAsyncCloseable

All Known Implementing Classes:

DecoratingClientFactory

public interface ClientFactory
extends ListenableAsyncCloseable

Creates and manages clients.

Life cycle of the default ClientFactory

Clients or ClientBuilder uses the default ClientFactory returned by ofDefault(), unless you specified a ClientFactory explicitly. Calling AsyncCloseable.close() on the default ClientFactory will neither terminate its I/O threads nor release other related resources unlike other ClientFactory to protect itself from accidental premature termination.

Instead, when the current ClassLoader is the system class loader, a shutdown hook is registered so that they are released when the JVM exits.

If you are in a multi-classloader environment or you desire an early/explicit termination of the default ClientFactory, use closeDefault().

Field Summary

Fields

Modifier and Type	Field and Description
static ClientFactory	DEFAULT Deprecated. Use ofDefault().

Method Summary

Modifier and Type	Method and Description
ReleasableHolder<io.netty.channel.EventLoop>	acquireEventLoop(Endpoint endpoint, SessionProtocol sessionProtocol) Acquires an EventLoop that is expected to handle a connection to the specified Endpoint.
static ClientFactoryBuilder	builder() Returns a newly created ClientFactoryBuilder.
default <T> ClientBuilderParams	clientBuilderParams(T client) Returns the ClientBuilderParams held in client.
static void	closeDefault() Closes the default ClientFactory.
static void	disableShutdownHook() Disables the shutdown hook which closes the default ClientFactory.
io.netty.channel.EventLoopGroup	eventLoopGroup() Returns the EventLoopGroup being used by this ClientFactory.
Supplier<io.netty.channel.EventLoop>	eventLoopSupplier() Returns a Supplier that provides one of the EventLoops being used by this ClientFactory.
static ClientFactory	insecure() Returns the insecure default ClientFactory implementation which does not verify server's TLS certificate chain.
MeterRegistry	meterRegistry() Returns the MeterRegistry that collects various stats.
Object	newClient(ClientBuilderParams params) Creates a new client with the specified ClientBuilderParams.
static ClientFactory	ofDefault() Returns the default ClientFactory implementation.
ClientFactoryOptions	options() Returns the ClientFactoryOptions that has been used to create this ClientFactory.
void	setMeterRegistry(MeterRegistry meterRegistry) Sets the MeterRegistry that collects various stats.
Set<Scheme>	supportedSchemes() Returns the Schemes supported by this ClientFactory.
default <T> T	unwrap(Object client, Class<T> type) Unwraps the specified client object into the object of the specified type.
default ClientBuilderParams	validateParams(ClientBuilderParams params) Makes sure the specified ClientBuilderParams has the Scheme supported by this ClientFactory.
default Scheme	validateScheme(Scheme scheme) Makes sure the specified Scheme is supported by this ClientFactory.
default URI	validateUri(URI uri) Makes sure the specified URI is supported by this ClientFactory.

Methods inherited from interface com.linecorp.armeria.common.util.ListenableAsyncCloseable

isClosed, isClosing, whenClosed

Methods inherited from interface com.linecorp.armeria.common.util.AsyncCloseable

close, closeAsync

Field Detail

DEFAULT

@Deprecated
static final ClientFactory DEFAULT

Deprecated. Use ofDefault().

The default ClientFactory implementation.

Method Detail

ofDefault

static ClientFactory ofDefault()

Returns the default ClientFactory implementation.

insecure

static ClientFactory insecure()

Returns the insecure default ClientFactory implementation which does not verify server's TLS certificate chain.

builder

static ClientFactoryBuilder builder()

Returns a newly created ClientFactoryBuilder.

closeDefault

static void closeDefault()

Closes the default ClientFactory.

disableShutdownHook

static void disableShutdownHook()

Disables the shutdown hook which closes the default ClientFactory. This method is useful when you need full control over the life cycle of the default ClientFactory.

supportedSchemes

Set<Scheme> supportedSchemes()

Returns the Schemes supported by this ClientFactory.

eventLoopGroup

io.netty.channel.EventLoopGroup eventLoopGroup()

Returns the EventLoopGroup being used by this ClientFactory. Can be used to, e.g., schedule a periodic task without creating a separate event loop. Use eventLoopSupplier() instead if what you need is an EventLoop rather than an EventLoopGroup.

eventLoopSupplier

Supplier<io.netty.channel.EventLoop> eventLoopSupplier()

Returns a Supplier that provides one of the EventLoops being used by this ClientFactory.

acquireEventLoop

ReleasableHolder<io.netty.channel.EventLoop> acquireEventLoop(Endpoint endpoint,
                                                              SessionProtocol sessionProtocol)

Acquires an EventLoop that is expected to handle a connection to the specified Endpoint. The caller must release the returned EventLoop back by calling ReleasableHolder.release() so that ClientFactory utilizes EventLoops efficiently.

meterRegistry

MeterRegistry meterRegistry()

Returns the MeterRegistry that collects various stats.

setMeterRegistry

void setMeterRegistry(MeterRegistry meterRegistry)

Sets the MeterRegistry that collects various stats. Note that this method is intended to be used during the initialization phase of an application, so that the application gets a chance to switch to the preferred MeterRegistry implementation. Invoking this method after this factory started to export stats to the old MeterRegistry may result in undocumented behavior.

options

ClientFactoryOptions options()

Returns the ClientFactoryOptions that has been used to create this ClientFactory.

newClient

Object newClient(ClientBuilderParams params)

Creates a new client with the specified ClientBuilderParams. The client instance returned by this method must be an instance of ClientBuilderParams.clientType().

clientBuilderParams

default <T> ClientBuilderParams clientBuilderParams(T client)

Returns the ClientBuilderParams held in client. This is used when creating a new derived Client which inherits ClientBuilderParams from client. If this ClientFactory does not know how to handle the ClientBuilderParams for the provided client, it should return null.

unwrap

default <T> T unwrap(Object client,
                     Class<T> type)

Unwraps the specified client object into the object of the specified type. For example,

 ClientFactory clientFactory = ...;
 WebClient client = WebClient.builder(...)
                             .factory(clientFactory)
                             .decorator(LoggingClient.newDecorator())
                             .build();

 LoggingClient unwrapped = clientFactory.unwrap(client, LoggingClient.class);

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

Parameters:

client - the client object

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), Clients.unwrap(Object, Class), Unwrappable

validateUri

default URI validateUri(URI uri)

Makes sure the specified URI is supported by this ClientFactory.

Parameters:

uri - the URI of the server endpoint

Returns:

the validated and normalized URI which always has a non-empty path.

Throws:

IllegalArgumentException - if the scheme of the specified URI is not supported by this ClientFactory

validateScheme

default Scheme validateScheme(Scheme scheme)

Makes sure the specified Scheme is supported by this ClientFactory.

Parameters:

scheme - the Scheme of the server endpoint

Returns:

the specified Scheme

Throws:

IllegalArgumentException - if the Scheme is not supported by this ClientFactory

validateParams

default ClientBuilderParams validateParams(ClientBuilderParams params)

Makes sure the specified ClientBuilderParams has the Scheme supported by this ClientFactory.

Returns:

the specified ClientBuilderParams