Interface RoundRobinLoadBalancerBuilder<ResolvedAddress,C extends LoadBalancedConnection>
- Type Parameters:
ResolvedAddress
- The resolved address type.C
- The type of connection.
- All Known Implementing Classes:
DelegatingRoundRobinLoadBalancerBuilder
,RoundRobinLoadBalancerFactory.Builder
LoadBalancerFactory
that creates LoadBalancer
instances which use a round-robin strategy
for selecting connections from a pool of addresses.
The addresses are provided via the published
events
that signal the host's status
.
Instances returned handle ServiceDiscovererEvent.Status.AVAILABLE
,
ServiceDiscovererEvent.Status.EXPIRED
, and ServiceDiscovererEvent.Status.UNAVAILABLE
event statuses.
The created instances have the following behaviour:
- Round robining is done at address level.
- Connections are created lazily, without any concurrency control on their creation. This can lead to over-provisioning connections when dealing with a requests surge.
- Existing connections are reused unless a selector passed to
LoadBalancer.selectConnection(Predicate, ContextMap)
suggests otherwise. This can lead to situations where connections will be used to their maximum capacity (for example in the context of pipelining) before new connections are created. - Closed connections are automatically pruned.
- When
Publisher
<ServiceDiscovererEvent
> delivers events withServiceDiscovererEvent.status()
of valueServiceDiscovererEvent.Status.UNAVAILABLE
, connections are immediately closed for the associatedServiceDiscovererEvent.address()
. In case ofServiceDiscovererEvent.Status.EXPIRED
, already established connections toServiceDiscovererEvent.address()
are used for requests, but no new connections are created. In case the address' connections are busy, another host is tried. If all hosts are busy, selection fails with aConnectionRejectedException
. - For hosts to which consecutive connection attempts fail, a background health checking task is created and the
host is not considered for opening new connections until the background check succeeds to create a connection.
Upon such event, the connection can immediately be reused and future attempts will again consider this host. This
behaviour can be disabled using a negative argument for
healthCheckFailedConnectionsThreshold(int)
and the failing host will take part in the regular round robin cycle for trying to establish a connection on the request path.
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionbackgroundExecutor
(Executor backgroundExecutor) Deprecated.ThisLoadBalancer
may monitor hosts to which connection establishment has failed using health checks that run in the background.build()
Deprecated.Builds theLoadBalancerFactory
configured by this builder.healthCheckFailedConnectionsThreshold
(int threshold) Deprecated.Configure a threshold for consecutive connection failures to a host.healthCheckInterval
(Duration interval, Duration jitter) Deprecated.Configure an interval for health checking a host that failed to open connections.healthCheckResubscribeInterval
(Duration interval, Duration jitter) Deprecated.Configure an interval for re-subscribing to the original events stream in case all existing hosts become unhealthy.linearSearchSpace
(int linearSearchSpace) Deprecated.Sets the linear search space to find an available connection for the next host.
-
Method Details
-
linearSearchSpace
Deprecated.Sets the linear search space to find an available connection for the next host.When the next host has already opened connections, this
LoadBalancer
will perform a linear search for a connection that can serve the next request up to a specified number of attempts. If there are more open connections, selection of remaining connections will be attempted randomly.Higher linear search space may help to better identify excess connections in highly concurrent environments, but may result in slightly increased selection time.
- Parameters:
linearSearchSpace
- the number of attempts for a linear search space,0
enforces random selection all the time.- Returns:
this
.
-
backgroundExecutor
Deprecated.ThisLoadBalancer
may monitor hosts to which connection establishment has failed using health checks that run in the background. The health check tries to establish a new connection and if it succeeds, the host is returned to the load balancing pool. As long as the connection establishment fails, the host is not considered for opening new connections for processed requests. If anExecutor
is not provided using this method, a default shared instance is used for allLoadBalancers
created by this factory.healthCheckFailedConnectionsThreshold(int)
can be used to disable this mechanism and always consider all hosts for establishing new connections.- Parameters:
backgroundExecutor
-Executor
on which to schedule health checking.- Returns:
this
.- See Also:
-
healthCheckInterval
RoundRobinLoadBalancerBuilder<ResolvedAddress,C> healthCheckInterval(Duration interval, Duration jitter) Deprecated.Configure an interval for health checking a host that failed to open connections. If no interval is provided using this method, a default value will be used.healthCheckFailedConnectionsThreshold(int)
can be used to disable the health checking mechanism and always consider all hosts for establishing new connections.- Parameters:
interval
- interval at which a background health check will be scheduled.jitter
- the amount of jitter to apply to each retryinterval
.- Returns:
this
.- See Also:
-
healthCheckResubscribeInterval
RoundRobinLoadBalancerBuilder<ResolvedAddress,C> healthCheckResubscribeInterval(Duration interval, Duration jitter) Deprecated.Configure an interval for re-subscribing to the original events stream in case all existing hosts become unhealthy.In situations when there is a latency between
ServiceDiscoverer
propagating the updated state and all known hosts become unhealthy, which could happen due to intermediate caching layers, re-subscribe to the events stream can help to exit from a dead state.healthCheckFailedConnectionsThreshold(int)
can be used to disable the health checking mechanism and always consider all hosts for establishing new connections.- Parameters:
interval
- interval at which re-subscribes will be scheduled.jitter
- the amount of jitter to apply to each re-subscribeinterval
.- Returns:
this
.- See Also:
-
healthCheckFailedConnectionsThreshold
RoundRobinLoadBalancerBuilder<ResolvedAddress,C> healthCheckFailedConnectionsThreshold(int threshold) Deprecated.Configure a threshold for consecutive connection failures to a host. When theLoadBalancer
consecutively fails to open connections in the amount greater or equal to the specified value, the host will be marked as unhealthy and connection establishment will take place in the background repeatedly until a connection is established. During that time, the host will not take part in load balancing selection.Use a negative value of the argument to disable health checking.
- Parameters:
threshold
- number of consecutive connection failures to consider a host unhealthy and eligible for background health checking. Use negative value to disable the health checking mechanism.- Returns:
this
.- See Also:
-
build
LoadBalancerFactory<ResolvedAddress,C> build()Deprecated.Builds theLoadBalancerFactory
configured by this builder.- Returns:
- a new instance of
LoadBalancerFactory
with settings from this builder.
-
LoadBalancerBuilder
interfaces instead.