Package io.servicetalk.http.netty

Enum Class HttpClients.DiscoveryStrategy

java.lang.Object

java.lang.Enum<HttpClients.DiscoveryStrategy>

io.servicetalk.http.netty.HttpClients.DiscoveryStrategy

All Implemented Interfaces:

Serializable, Comparable<HttpClients.DiscoveryStrategy>, Constable

Enclosing class:

HttpClients

public static enum HttpClients.DiscoveryStrategy
extends Enum<HttpClients.DiscoveryStrategy>

Defines ServiceDiscoverer will be used.

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Enum

Enum.EnumDesc<E extends Enum<E>>

Enum Constant Summary

Enum Constants

Enum Constant	Description
BACKGROUND	Resolves an address in a background.
ON_NEW_CONNECTION	Resolves an address every time a new connection is required.

Method Summary

Modifier and Type	Method	Description
static HttpClients.DiscoveryStrategy	valueOf(String name)	Returns the enum constant of this class with the specified name.
static HttpClients.DiscoveryStrategy[]	values()	Returns an array containing the constants of this enum class, in the order they are declared.

Methods inherited from class java.lang.Enum

clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Enum Constant Details

BACKGROUND

public static final HttpClients.DiscoveryStrategy BACKGROUND

Resolves an address in a background.

The LoadBalancer subscribes to the stream of events from ServiceDiscoverer and listens for updates in a background. All changes propagated by a discovery system will be available to the LoadBalancer. When a new connection is required, the resolved address will already be available.

This is the recommended default strategy that allows a client to:

1. Perform client-side load balancing.
2. Remove the cost (latency) required for resolving an address from the hot path of request processing.
3. Move/shift traffic immediately based on updates from the ServiceDiscoverer.

use client-side load balancing and removes the cost (latency) required for resolving an address from the hot execution path.

ON_NEW_CONNECTION

public static final HttpClients.DiscoveryStrategy ON_NEW_CONNECTION

Resolves an address every time a new connection is required.

Client holds the unresolved address internally and uses ServiceDiscoverer to resolve it only when a new connection is required. This behavior may be beneficial for the following scenarios:

1. Client has a low rate of opening new connections.
2. Application creates many clients (or uses a multi-address client) that talk to many different hosts. the default BACKGROUND strategy introduces a risk to overload the discovery system. The impact might be more visible when ServiceDiscoverer uses polling to receive updated, like DNS.
3. To mimic behavior of other HTTP client implementations, like default Java HttpClient or HttpURLConnection.

Important side effects of this strategy to take into account:

1. The total latency for opening a new connection will be increased by a latency of the first ServiceDiscoverer answer.
2. If the target host has more than one resolved address, created clients loose ability to perform client-side load balancing for each request. Instead, the client will connect to any random resolved address returned by a ServiceDiscoverer. This approach introduces randomness at connect time but doesn't guarantee balancing for every request.
3. Created clients won't be able to move/shift traffic based on changes observed by a ServiceDiscoverer until the remote server closes existing connections.
4. The only way to change or customize a ServiceDiscoverer for this strategy is to use HttpClients.forSingleAddress(ServiceDiscoverer, Object, DiscoveryStrategy) client factory. Setting a different ServiceDiscoverer instance via SingleAddressHttpClientBuilder.serviceDiscoverer(ServiceDiscoverer) method later will throw an exception.
5. Currently, TransportObserver won't be able to take ServiceDiscoverer latency into account because onNewConnection callback is invoked later. Users need to use observability features provided by a ServiceDiscoverer implementation or intercept its ServiceDiscoverer.discover(Object) publisher to track this latency. Correlation between that tracking logic and TransportObserver.onNewConnection(Object, Object) (if desired) can be achieved using a state propagated via AsyncContext. Observability features for this strategy will be improved in the future releases.

Method Details

values

public static HttpClients.DiscoveryStrategy[] values()

Returns an array containing the constants of this enum class, in the order they are declared.

Returns:

an array containing the constants of this enum class, in the order they are declared

valueOf

public static HttpClients.DiscoveryStrategy valueOf(String name)

Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)

Parameters:

name - the name of the enum constant to be returned.

Returns:

the enum constant with the specified name

Throws:

IllegalArgumentException - if this enum class has no constant with the specified name

NullPointerException - if the argument is null