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

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

      io.micrometer.core.instrument.MeterRegistry meterRegistry()
      Returns the MeterRegistry that collects various stats.

    • setMeterRegistry

      @Deprecated void setMeterRegistry(io.micrometer.core.instrument.MeterRegistry meterRegistry)
      Deprecated.
      Use FlagsProvider SPI to override the default 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:

    • 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

    • closeOnJvmShutdown

      default CompletableFuture<Void> closeOnJvmShutdown()
      Registers a JVM shutdown hook that closes this ClientFactory when the current JVM terminates.

    • closeOnJvmShutdown

      CompletableFuture<Void> closeOnJvmShutdown(Runnable whenClosing)
      Registers a JVM shutdown hook that closes this ClientFactory when the current JVM terminates.
      Parameters:
      whenClosing - the Runnable will be run before closing this ClientFactory