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 Summary

Modifier and Type	Method and Description
Publisher<Object>	eventStream() A Publisher of events provided by this LoadBalancer.
default Single<C>	newConnection(ContextMap context) Opens a new connection for a request instead of potentially reusing one.
default Single<C>	selectConnection(Predicate<C> selector) Deprecated. Use selectConnection(Predicate, ContextMap).
default Single<C>	selectConnection(Predicate<C> selector, ContextMap context) Select the most appropriate connection for a request.

Methods inherited from interface ListenableAsyncCloseable

onClose, onClosing

Methods inherited from interface AsyncCloseable

closeAsync, closeAsyncGracefully

Method Detail

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.