Package com.linecorp.armeria.client

Interface ClientFactory

All Superinterfaces:

AsyncCloseable, AutoCloseable, ListenableAsyncCloseable, Unwrappable

All Known Implementing Classes:

DecoratingClientFactory

public interface ClientFactory
extends Unwrappable, 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().

Method Summary

Modifier and Type	Method	Description
ReleasableHolder<EventLoop>	acquireEventLoop(SessionProtocol sessionProtocol, EndpointGroup endpointGroup, @Nullable Endpoint endpoint)	Acquires an EventLoop that is expected to handle a connection to the specified Endpoint.
static ClientFactoryBuilder	builder()	Returns a newly created ClientFactoryBuilder.
default <T> @Nullable 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.
EventLoopGroup	eventLoopGroup()	Returns the EventLoopGroup being used by this ClientFactory.
Supplier<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.
default boolean	isClientTypeSupported(Class<?> clientType)	Verifies that client type Class is supported by this ClientFactory.
MeterRegistry	meterRegistry()	Returns the MeterRegistry that collects various stats.
Object	newClient(ClientBuilderParams params)	Creates a new client with the specified ClientBuilderParams.
int	numConnections()	Returns the number of open connections managed by this ClientFactory.
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 ClientFactory	unwrap()	Unwraps this object and returns the object being decorated.
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.AsyncCloseable

close, closeAsync

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

isClosed, isClosing, whenClosed

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

as

Method Details

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.

isClientTypeSupported

default boolean isClientTypeSupported(Class<?> clientType)

Verifies that client type Class is supported by this ClientFactory. Can be used to support multiple ClientFactorys for a single Scheme.

eventLoopGroup

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<EventLoop> eventLoopSupplier()

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

acquireEventLoop

ReleasableHolder<EventLoop> acquireEventLoop(SessionProtocol sessionProtocol,
 EndpointGroup endpointGroup,
 @Nullable
 @Nullable Endpoint endpoint)

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.

Parameters:

sessionProtocol - the SessionProtocol of the connection

endpointGroup - the EndpointGroup where endpoint belongs to.

endpoint - the Endpoint where a request is being sent. null if the Endpoint is not known yet.

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().

numConnections

int numConnections()

Returns the number of open connections managed by this ClientFactory.

clientBuilderParams

@Nullable
default <T> @Nullable 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

@Nullable
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

unwrap

default ClientFactory unwrap()

Description copied from interface: Unwrappable

Unwraps this object and returns the object being decorated. If this Unwrappable is the innermost object, this method returns itself. For example:

 class Foo implements Unwrappable {}

 class Bar<T extends Unwrappable> extends AbstractUnwrappable<T> {
     Bar(T delegate) {
         super(delegate);
     }
 }

 class Qux<T extends Unwrappable> extends AbstractUnwrappable<T> {
     Qux(T delegate) {
         super(delegate);
     }
 }

 Foo foo = new Foo();
 assert foo.unwrap() == foo;

 Bar<Foo> bar = new Bar<>(foo);
 assert bar.unwrap() == foo;

 Qux<Bar<Foo>> qux = new Qux<>(bar);
 assert qux.unwrap() == bar;
 assert qux.unwrap().unwrap() == foo;
 

Specified by:

unwrap in interface 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