Package com.linecorp.armeria.client

Interface ClientFactory

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

AbstractClientFactory, DecoratingClientFactory

public interface ClientFactory
extends AutoCloseable

Creates and manages clients.

Life cycle of the default ClientFactory

Clients or ClientBuilder uses DEFAULT, the default ClientFactory, unless you specified a ClientFactory explicitly. Calling 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	Description
static ClientFactory	DEFAULT	The default ClientFactory implementation.

Method Summary

Modifier and Type	Method	Description
ReleasableHolder<EventLoop>	acquireEventLoop(Endpoint endpoint, SessionProtocol sessionProtocol)	Acquires an EventLoop that is expected to handle a connection to the specified Endpoint.
default <T> Optional<ClientBuilderParams>	clientBuilderParams(T client)	Returns the ClientBuilderParams held in client.
void	close()	Closes all clients managed by this factory and shuts down the EventLoopGroup created implicitly by this factory.
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.
MeterRegistry	meterRegistry()	Returns the MeterRegistry that collects various stats.
<T> T	newClient(Scheme scheme, Endpoint endpoint, Class<T> clientType, ClientOptions options)	Creates a new client that connects to the specified Endpoint with the Scheme.
<T> T	newClient(Scheme scheme, Endpoint endpoint, Class<T> clientType, ClientOptionValue<?>... options)	Creates a new client that connects to the specified Endpoint with the Scheme.
<T> T	newClient(Scheme scheme, Endpoint endpoint, String path, Class<T> clientType, ClientOptions options)	Creates a new client that connects to the specified Endpoint with the Scheme and path.
<T> T	newClient(Scheme scheme, Endpoint endpoint, String path, Class<T> clientType, ClientOptionValue<?>... options)	Creates a new client that connects to the specified Endpoint with the Scheme and path.
<T> T	newClient(String uri, Class<T> clientType, ClientOptions options)	Creates a new client that connects to the specified uri.
<T> T	newClient(String uri, Class<T> clientType, ClientOptionValue<?>... options)	Creates a new client that connects to the specified uri.
<T> T	newClient(URI uri, Class<T> clientType, ClientOptions options)	Creates a new client that connects to the specified URI.
<T> T	newClient(URI uri, Class<T> clientType, ClientOptionValue<?>... options)	Creates a new client that connects to the specified URI.
void	setMeterRegistry(MeterRegistry meterRegistry)	Sets the MeterRegistry that collects various stats.
Set<Scheme>	supportedSchemes()	Returns the Schemes supported by this ClientFactory.
default <T> Optional<T>	unwrap(Object client, Class<T> type)	Unwraps the specified client object into the object of the specified type.

Field Detail

DEFAULT

static final ClientFactory DEFAULT

The default ClientFactory implementation.

Method Detail

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

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

newClient

<T> T newClient(String uri,
                Class<T> clientType,
                ClientOptionValue<?>... options)

Creates a new client that connects to the specified uri.

Parameters:

uri - the URI of the server endpoint

clientType - the type of the new client

options - the ClientOptionValues

newClient

<T> T newClient(String uri,
                Class<T> clientType,
                ClientOptions options)

Creates a new client that connects to the specified uri.

Parameters:

uri - the URI of the server endpoint

clientType - the type of the new client

options - the ClientOptions

newClient

<T> T newClient(URI uri,
                Class<T> clientType,
                ClientOptionValue<?>... options)

Creates a new client that connects to the specified URI.

Parameters:

uri - the URI of the server endpoint

clientType - the type of the new client

options - the ClientOptionValues

newClient

<T> T newClient(URI uri,
                Class<T> clientType,
                ClientOptions options)

Creates a new client that connects to the specified URI.

Parameters:

uri - the URI of the server endpoint

clientType - the type of the new client

options - the ClientOptions

newClient

<T> T newClient(Scheme scheme,
                Endpoint endpoint,
                Class<T> clientType,
                ClientOptionValue<?>... options)

Creates a new client that connects to the specified Endpoint with the Scheme.

Parameters:

scheme - the Scheme for the endpoint

endpoint - the server Endpoint

clientType - the type of the new client

options - the ClientOptionValues

newClient

<T> T newClient(Scheme scheme,
                Endpoint endpoint,
                Class<T> clientType,
                ClientOptions options)

Creates a new client that connects to the specified Endpoint with the Scheme.

Parameters:

scheme - the Scheme for the endpoint

endpoint - the server Endpoint

clientType - the type of the new client

options - the ClientOptions

newClient

<T> T newClient(Scheme scheme,
                Endpoint endpoint,
                @Nullable
                String path,
                Class<T> clientType,
                ClientOptionValue<?>... options)

Creates a new client that connects to the specified Endpoint with the Scheme and path.

Parameters:

scheme - the Scheme for the endpoint

endpoint - the server Endpoint

path - the service path

clientType - the type of the new client

options - the ClientOptionValues

newClient

<T> T newClient(Scheme scheme,
                Endpoint endpoint,
                @Nullable
                String path,
                Class<T> clientType,
                ClientOptions options)

Creates a new client that connects to the specified Endpoint with the Scheme and path.

Parameters:

scheme - the Scheme for the endpoint

endpoint - the server Endpoint

path - the service path

clientType - the type of the new client

options - the ClientOptions

clientBuilderParams

default <T> Optional<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 Optional.empty().

unwrap

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

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

 ClientFactory clientFactory = ...;
 HttpClient client = new HttpClientBuilder()
     .factory(clientFactory)
     .decorator(LoggingClient.newDecorator())
     .build();

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

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

Parameters:

client - the client object

type - the type of the object to return

Returns:

the object of the specified type if found. Optional.empty() if not found.

See Also:

Client.as(Class), Clients.unwrap(Object, Class), Unwrappable

close

void close()

Closes all clients managed by this factory and shuts down the EventLoopGroup created implicitly by this factory.

Specified by:

close in interface AutoCloseable