Package io.servicetalk.client.api

Interface LoadBalancer<C extends LoadBalancedConnection>

Type Parameters:
C - The type of connection.
All Superinterfaces:
AsyncCloseable, ListenableAsyncCloseable
public interface LoadBalancer<C extends LoadBalancedConnection> extends ListenableAsyncCloseable
Given multiple SocketAddresses select the most desired SocketAddress to use. This is typically used to determine which connection to issue a request to.

  • Method Details

    • selectConnection

      @Deprecated default Single<C> selectConnection(Predicate<C> selector)
      Deprecated.
      Use selectConnection(Predicate, ContextMap).
      Select the most appropriate connection for a request. Returned connection may be used concurrently for other requests.
      Parameters:
      selector - A Function that evaluates a connection for selection. This selector should return null if the connection MUST not be selected. This selector is guaranteed to be called for any connection that is returned from this method.
      Returns:
      a Single that completes with the most appropriate connection to use. A failed Single with NoAvailableHostException can be returned if no connection can be selected at this time or with ConnectionRejectedException if a newly created connection was rejected by the selector or this load balancer.

    • selectConnection

      default Single<C> selectConnection(Predicate<C> selector, @Nullable ContextMap context)
      Select the most appropriate connection for a request. Returned connection may be used concurrently for other requests.
      Parameters:
      selector - A Function that evaluates a connection for selection. This selector should return null if the connection MUST not be selected. This selector is guaranteed to be called for any connection that is returned from this method.
      context - A context of the caller (e.g. request context) or null if no context provided.
      Returns:
      a Single that completes with the most appropriate connection to use. A failed Single with NoAvailableHostException can be returned if no connection can be selected at this time or with ConnectionRejectedException if a newly created connection was rejected by the selector or this load balancer.

    • newConnection

      default Single<C> newConnection(@Nullable ContextMap context)
      Opens a new connection for a request instead of potentially reusing one.

      If the returned connection is released, it is returned to the pool and made available for other connection requests sent via selectConnection(Predicate, ContextMap). If the connection should not be returned to the pool, it must be explicitly closed by the caller.

      Parameters:
      context - A context of the caller (e.g. request context) or null if no context provided.
      Returns:
      a Single that completes with a new connection to use. A failed Single with NoAvailableHostException can be returned if no connection can be created at this time or with ConnectionRejectedException if a newly created connection was rejected by this load balancer.

    • eventStream

      Publisher<Object> eventStream()
      A Publisher of events provided by this LoadBalancer. This maybe used to broadcast internal state of this LoadBalancer to provide hints/visibility for external usage.

      Note the Publisher maybe subscribed to multiple times. It is recommended that implementations use operators such as Publisher.replay(int) (or similar) to support this use case.

      Returns:
      A Publisher of events provided by this LoadBalancer.