Package com.linecorp.armeria.xds.client.endpoint

Class XdsEndpointGroup

java.lang.Object

com.linecorp.armeria.common.util.AbstractListenable<List<Endpoint>>

com.linecorp.armeria.xds.client.endpoint.XdsEndpointGroup

All Implemented Interfaces:

EndpointGroup, EndpointSelector, AsyncCloseable, Listenable<List<Endpoint>>, AutoCloseable

@UnstableApi
public final class XdsEndpointGroup
extends AbstractListenable<List<Endpoint>>
implements EndpointGroup

Provides a simple EndpointGroup which listens to an xDS cluster to select endpoints. Listening to EDS can be done like the following:

 XdsBootstrap watchersStorage = XdsBootstrap.of(...);
 EndpointGroup endpointGroup = XdsEndpointGroup.of(watchersStorage, "my-cluster");
 WebClient client = WebClient.of(SessionProtocol.HTTP, endpointGroup);
 

Currently, all SocketAddresses of a ClusterLoadAssignment are aggregated to a list and added to this EndpointGroup. Features such as automatic TLS detection or locality based load balancing are not supported yet. Note that it is important to shut down the endpoint group to clean up resources for the provided XdsBootstrap.

Method Summary

Modifier and Type	Method	Description
void	close()	Releases any underlying resources held by this object synchronously.
CompletableFuture<?>	closeAsync()	Releases any underlying resources held by this object asynchronously.
List<Endpoint>	endpoints()	Returns the endpoints held by this EndpointGroup.
protected @Nullable List<Endpoint>	latestValue()	Returns the latest value notified before.
static XdsEndpointGroup	of(ClusterSnapshot clusterSnapshot)	Creates a XdsEndpointGroup based on the specified ClusterSnapshot.
static XdsEndpointGroup	of(String listenerName, XdsBootstrap xdsBootstrap)	Creates a XdsEndpointGroup which listens to the specified listener.
static XdsEndpointGroup	of(String listenerName, XdsBootstrap xdsBootstrap, boolean allowEmptyEndpoints)	Creates a XdsEndpointGroup which listens to the specified listener.
CompletableFuture<Endpoint>	select(ClientRequestContext ctx, ScheduledExecutorService executor)	Selects an Endpoint asynchronously from the EndpointGroup associated with the specified ClientRequestContext, waiting up to the specified timeoutMillis.
CompletableFuture<Endpoint>	select(ClientRequestContext ctx, ScheduledExecutorService executor, long timeoutMillis)	Selects an Endpoint asynchronously from the EndpointGroup associated with the specified ClientRequestContext, waiting up to the specified timeoutMillis.
EndpointSelectionStrategy	selectionStrategy()	Returns the EndpointSelectionStrategy of this EndpointGroup.
long	selectionTimeoutMillis()	Returns the timeout to wait until a successful Endpoint selection.
@Nullable Endpoint	selectNow(ClientRequestContext ctx)	Selects an Endpoint from this EndpointGroup.
String	toString()
CompletableFuture<List<Endpoint>>	whenReady()	Returns a CompletableFuture which is completed when the initial Endpoints are ready.

Methods inherited from class com.linecorp.armeria.common.util.AbstractListenable

addListener, addListener, notifyListeners, removeListener

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.linecorp.armeria.client.endpoint.EndpointGroup

addListener, addListener, orElse, removeListener

Method Details

of

public static XdsEndpointGroup of(String listenerName,
 XdsBootstrap xdsBootstrap)

Creates a XdsEndpointGroup which listens to the specified listener.

of

public static XdsEndpointGroup of(String listenerName,
 XdsBootstrap xdsBootstrap,
 boolean allowEmptyEndpoints)

Creates a XdsEndpointGroup which listens to the specified listener.

of

@UnstableApi
public static XdsEndpointGroup of(ClusterSnapshot clusterSnapshot)

Creates a XdsEndpointGroup based on the specified ClusterSnapshot. This may be useful if one would like to create an EndpointGroup based on a GrpcService.

latestValue

@Nullable
protected @Nullable List<Endpoint> latestValue()

Description copied from class: AbstractListenable

Returns the latest value notified before. null if the value has not been initialized yet or the implementation of this class cannot cache it.

Overrides:

latestValue in class AbstractListenable<List<Endpoint>>

endpoints

public List<Endpoint> endpoints()

Description copied from interface: EndpointGroup

Returns the endpoints held by this EndpointGroup.

Specified by:

endpoints in interface EndpointGroup

selectionStrategy

public EndpointSelectionStrategy selectionStrategy()

Description copied from interface: EndpointGroup

Returns the EndpointSelectionStrategy of this EndpointGroup.

Specified by:

selectionStrategy in interface EndpointGroup

selectNow

@Nullable
public @Nullable Endpoint selectNow(ClientRequestContext ctx)

Description copied from interface: EndpointGroup

Selects an Endpoint from this EndpointGroup.

Specified by:

selectNow in interface EndpointGroup

Specified by:

selectNow in interface EndpointSelector

Returns:

the Endpoint selected by the EndpointSelectionStrategy, which was specified when constructing this EndpointGroup, or null if this EndpointGroup is empty.

select

public CompletableFuture<Endpoint> select(ClientRequestContext ctx,
 ScheduledExecutorService executor,
 long timeoutMillis)

Description copied from interface: EndpointSelector

Selects an Endpoint asynchronously from the EndpointGroup associated with the specified ClientRequestContext, waiting up to the specified timeoutMillis.

Specified by:

select in interface EndpointSelector

Parameters:

ctx - the ClientRequestContext of the Request being handled.

executor - the ScheduledExecutorService used for notifying the CompletableFuture being returned and scheduling timeout tasks.

timeoutMillis - the amount of milliseconds to wait until a successful Endpoint selection.

Returns:

the CompletableFuture that will be completed with the Endpoint selected by this EndpointSelector's selection strategy, or completed with null if no Endpoint was selected within the specified timeoutMillis, which can happen if the EndpointGroup is empty.

select

public CompletableFuture<Endpoint> select(ClientRequestContext ctx,
 ScheduledExecutorService executor)

Description copied from interface: EndpointSelector

Selects an Endpoint asynchronously from the EndpointGroup associated with the specified ClientRequestContext, waiting up to the specified timeoutMillis.

Specified by:

select in interface EndpointSelector

Parameters:

ctx - the ClientRequestContext of the Request being handled.

executor - the ScheduledExecutorService used for notifying the CompletableFuture being returned and scheduling timeout tasks.

Returns:

the CompletableFuture that will be completed with the Endpoint selected by this EndpointSelector's selection strategy, or completed with null if no Endpoint was selected within the specified timeoutMillis, which can happen if the EndpointGroup is empty.

selectionTimeoutMillis

public long selectionTimeoutMillis()

Description copied from interface: EndpointGroup

Returns the timeout to wait until a successful Endpoint selection. If an Endpoint is not resolved by this EndpointGroup within the timeout, a null value will be returned by EndpointSelector.select(ClientRequestContext, ScheduledExecutorService). The null Endpoint may cause a client request end with an EndpointSelectionTimeoutException if no RetryingClient is configured.

0 means EndpointGroup.selectNow(ClientRequestContext) should always return an Endpoint.

Specified by:

selectionTimeoutMillis in interface EndpointGroup

whenReady

public CompletableFuture<List<Endpoint>> whenReady()

Description copied from interface: EndpointGroup

Returns a CompletableFuture which is completed when the initial Endpoints are ready.

Specified by:

whenReady in interface EndpointGroup

closeAsync

public CompletableFuture<?> closeAsync()

Description copied from interface: AsyncCloseable

Releases any underlying resources held by this object asynchronously.

Specified by:

closeAsync in interface AsyncCloseable

Returns:

the CompletableFuture which is completed after the resources are released

close

public void close()

Description copied from interface: AsyncCloseable

Releases any underlying resources held by this object synchronously.

Specified by:

close in interface AsyncCloseable

Specified by:

close in interface AutoCloseable

toString

public String toString()

Overrides:

toString in class Object