Package com.linecorp.armeria.client
Interface ClientFactory
- All Superinterfaces:
AsyncCloseable
,AutoCloseable
,ListenableAsyncCloseable
,Unwrappable
- All Known Implementing Classes:
DecoratingClientFactory
Creates and manages clients.
Life cycle of the default
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 TypeMethodDescriptionacquireEventLoop
(SessionProtocol sessionProtocol, EndpointGroup endpointGroup, @Nullable Endpoint endpoint) static ClientFactoryBuilder
builder()
Returns a newly createdClientFactoryBuilder
.default <T> @Nullable ClientBuilderParams
clientBuilderParams
(T client) Returns theClientBuilderParams
held inclient
.static void
Closes the defaultClientFactory
.default CompletableFuture<Void>
Registers a JVM shutdown hook that closes thisClientFactory
when the current JVM terminates.closeOnJvmShutdown
(Runnable whenClosing) Registers a JVM shutdown hook that closes thisClientFactory
when the current JVM terminates.static void
Disables the shutdown hook which closes the defaultClientFactory
.Returns theEventLoopGroup
being used by thisClientFactory
.static ClientFactory
insecure()
Returns the insecure defaultClientFactory
implementation which does not verify server's TLS certificate chain.default boolean
isClientTypeSupported
(Class<?> clientType) Verifies that client typeClass
is supported by thisClientFactory
.Returns theMeterRegistry
that collects various stats.newClient
(ClientBuilderParams params) Creates a new client with the specifiedClientBuilderParams
.int
Returns the number of open connections managed by thisClientFactory
.static ClientFactory
Returns the defaultClientFactory
implementation.options()
Returns theClientFactoryOptions
that has been used to create thisClientFactory
.void
setMeterRegistry
(MeterRegistry meterRegistry) Sets theMeterRegistry
that collects various stats.Returns theScheme
s supported by thisClientFactory
.default ClientFactory
unwrap()
Unwraps this object and returns the object being decorated.default <T> T
Unwraps the specifiedclient
object into the object of the specifiedtype
.default ClientBuilderParams
validateParams
(ClientBuilderParams params) default Scheme
validateScheme
(Scheme scheme) Makes sure the specifiedScheme
is supported by thisClientFactory
.default URI
validateUri
(URI uri) Makes sure the specifiedURI
is supported by thisClientFactory
.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, equalsIgnoreWrapper, unwrapAll
-
Method Details
-
ofDefault
Returns the defaultClientFactory
implementation. -
insecure
Returns the insecure defaultClientFactory
implementation which does not verify server's TLS certificate chain. -
builder
Returns a newly createdClientFactoryBuilder
. -
closeDefault
static void closeDefault()Closes the defaultClientFactory
. -
disableShutdownHook
static void disableShutdownHook()Disables the shutdown hook which closes the defaultClientFactory
. This method is useful when you need full control over the life cycle of the defaultClientFactory
. -
supportedSchemes
Returns theScheme
s supported by thisClientFactory
. -
isClientTypeSupported
Verifies that client typeClass
is supported by thisClientFactory
. Can be used to support multipleClientFactory
s for a singleScheme
. -
eventLoopGroup
EventLoopGroup eventLoopGroup()Returns theEventLoopGroup
being used by thisClientFactory
. Can be used to, e.g., schedule a periodic task without creating a separate event loop. UseeventLoopSupplier()
instead if what you need is anEventLoop
rather than anEventLoopGroup
. -
eventLoopSupplier
-
acquireEventLoop
ReleasableHolder<EventLoop> acquireEventLoop(SessionProtocol sessionProtocol, EndpointGroup endpointGroup, @Nullable @Nullable Endpoint endpoint) Acquires anEventLoop
that is expected to handle a connection to the specifiedEndpoint
. The caller must release the returnedEventLoop
back by callingReleasableHolder.release()
so thatClientFactory
utilizesEventLoop
s efficiently.- Parameters:
sessionProtocol
- theSessionProtocol
of the connectionendpointGroup
- theEndpointGroup
whereendpoint
belongs to.endpoint
- theEndpoint
where a request is being sent.null
if theEndpoint
is not known yet.
-
meterRegistry
MeterRegistry meterRegistry()Returns theMeterRegistry
that collects various stats. -
setMeterRegistry
Sets theMeterRegistry
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 preferredMeterRegistry
implementation. Invoking this method after this factory started to export stats to the oldMeterRegistry
may result in undocumented behavior. -
options
ClientFactoryOptions options()Returns theClientFactoryOptions
that has been used to create thisClientFactory
. -
newClient
Creates a new client with the specifiedClientBuilderParams
. The client instance returned by this method must be an instance ofClientBuilderParams.clientType()
. -
numConnections
int numConnections()Returns the number of open connections managed by thisClientFactory
. -
clientBuilderParams
Returns theClientBuilderParams
held inclient
. This is used when creating a new derivedClient
which inheritsClientBuilderParams
fromclient
. If thisClientFactory
does not know how to handle theClientBuilderParams
for the providedclient
, it should returnnull
. -
unwrap
Unwraps the specifiedclient
object into the object of the specifiedtype
. 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 objecttype
- the type of the object to return- Returns:
- the object of the specified
type
if found, ornull
if not found. - See Also:
-
unwrap
Description copied from interface:Unwrappable
Unwraps this object and returns the object being decorated. If thisUnwrappable
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 interfaceUnwrappable
-
validateUri
Makes sure the specifiedURI
is supported by thisClientFactory
.- Parameters:
uri
- theURI
of the server endpoint- Returns:
- the validated and normalized
URI
which always has a non-empty path. - Throws:
IllegalArgumentException
- if the scheme of the specifiedURI
is not supported by thisClientFactory
-
validateScheme
Makes sure the specifiedScheme
is supported by thisClientFactory
.- Parameters:
scheme
- theScheme
of the server endpoint- Returns:
- the specified
Scheme
- Throws:
IllegalArgumentException
- if theScheme
is not supported by thisClientFactory
-
validateParams
- Returns:
- the specified
ClientBuilderParams
-
closeOnJvmShutdown
Registers a JVM shutdown hook that closes thisClientFactory
when the current JVM terminates. -
closeOnJvmShutdown
Registers a JVM shutdown hook that closes thisClientFactory
when the current JVM terminates.- Parameters:
whenClosing
- theRunnable
will be run before closing thisClientFactory
-