Package com.linecorp.armeria.client.endpoint.healthcheck

Class HealthCheckedEndpointGroupBuilder

java.lang.Object

com.linecorp.armeria.client.endpoint.AbstractDynamicEndpointGroupBuilder

com.linecorp.armeria.client.endpoint.healthcheck.AbstractHealthCheckedEndpointGroupBuilder

com.linecorp.armeria.client.endpoint.healthcheck.HealthCheckedEndpointGroupBuilder

All Implemented Interfaces:

DynamicEndpointGroupSetters

public final class HealthCheckedEndpointGroupBuilder
extends AbstractHealthCheckedEndpointGroupBuilder

A builder for creating a new HealthCheckedEndpointGroup that sends HTTP health check requests.

Method Summary

Modifier and Type	Method	Description
HealthCheckedEndpointGroupBuilder	allowEmptyEndpoints(boolean allowEmptyEndpoints)	Sets whether to allow an empty Endpoint list.
HealthCheckedEndpointGroupBuilder	auth(AuthToken token)	Sets the AuthToken header using HttpHeaderNames.AUTHORIZATION.
HealthCheckedEndpointGroupBuilder	clientFactory(ClientFactory clientFactory)	Sets the ClientFactory to use when making health check requests.
HealthCheckedEndpointGroupBuilder	clientOptions(ClientOptions options)	Sets the ClientOptions of the Client that sends health check requests.
HealthCheckedEndpointGroupBuilder	maxEndpointCount(int maxEndpointCount)	Sets the maximum endpoint count of target selected candidates.
HealthCheckedEndpointGroupBuilder	maxEndpointRatio(double maxEndpointRatio)	Sets the maximum endpoint ratio of target selected candidates.
protected Function<? super HealthCheckerContext,? extends AsyncCloseable>	newCheckerFactory()	Returns the Function that starts to send health check requests to the Endpoint specified in a given HealthCheckerContext when invoked.
HealthCheckedEndpointGroupBuilder	port(int port)	Sets the port where a health check request will be sent instead of the original port number specified by EndpointGroup's Endpoints.
HealthCheckedEndpointGroupBuilder	protocol(SessionProtocol protocol)	Sets the SessionProtocol to be used when making health check requests.
HealthCheckedEndpointGroupBuilder	retryBackoff(Backoff retryBackoff)	Sets the backoff between health check requests.
HealthCheckedEndpointGroupBuilder	retryInterval(Duration retryInterval)	Sets the interval between health check requests.
HealthCheckedEndpointGroupBuilder	retryIntervalMillis(long retryIntervalMillis)	Sets the interval between health check requests in milliseconds.
HealthCheckedEndpointGroupBuilder	selectionTimeout(Duration selectionTimeout)	Sets the timeout to wait until a successful Endpoint selection.
HealthCheckedEndpointGroupBuilder	selectionTimeout(Duration initialSelectionTimeout, Duration selectionTimeout)	Sets the timeouts to wait until a successful Endpoint selection.
HealthCheckedEndpointGroupBuilder	selectionTimeoutMillis(long selectionTimeoutMillis)	Sets the timeout to wait until a successful Endpoint selection.
HealthCheckedEndpointGroupBuilder	selectionTimeoutMillis(long initialSelectionTimeoutMillis, long selectionTimeoutMillis)	Sets the timeouts to wait until a successful Endpoint selection.
HealthCheckedEndpointGroupBuilder	useGet(boolean useGet)	Sets whether to use HTTP GET method instead of HEAD when sending a health check request.
HealthCheckedEndpointGroupBuilder	withClientOptions(Function<? super ClientOptionsBuilder,ClientOptionsBuilder> configurator)	Sets the Function that customizes a Client that sends health check requests.

Methods inherited from class com.linecorp.armeria.client.endpoint.healthcheck.AbstractHealthCheckedEndpointGroupBuilder

build

Methods inherited from class com.linecorp.armeria.client.endpoint.AbstractDynamicEndpointGroupBuilder

selectionTimeoutMillis, shouldAllowEmptyEndpoints

Methods inherited from class java.lang.Object

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

Method Details

useGet

public HealthCheckedEndpointGroupBuilder useGet(boolean useGet)

Sets whether to use HTTP GET method instead of HEAD when sending a health check request. By default, HEAD method is used. This can be useful when the health check requests are failing due to a bad request or an authorization failure and you want to learn why.

clientFactory

public HealthCheckedEndpointGroupBuilder clientFactory(ClientFactory clientFactory)

Description copied from class: AbstractHealthCheckedEndpointGroupBuilder

Sets the ClientFactory to use when making health check requests. This should generally be the same as the ClientFactory used when creating a Client stub using the EndpointGroup.

Overrides:

clientFactory in class AbstractHealthCheckedEndpointGroupBuilder

protocol

public HealthCheckedEndpointGroupBuilder protocol(SessionProtocol protocol)

Description copied from class: AbstractHealthCheckedEndpointGroupBuilder

Sets the SessionProtocol to be used when making health check requests.

Overrides:

protocol in class AbstractHealthCheckedEndpointGroupBuilder

port

public HealthCheckedEndpointGroupBuilder port(int port)

Description copied from class: AbstractHealthCheckedEndpointGroupBuilder

Sets the port where a health check request will be sent instead of the original port number specified by EndpointGroup's Endpoints. This property is useful when your server listens to health check requests on a different port.

Overrides:

port in class AbstractHealthCheckedEndpointGroupBuilder

retryInterval

public HealthCheckedEndpointGroupBuilder retryInterval(Duration retryInterval)

Description copied from class: AbstractHealthCheckedEndpointGroupBuilder

Sets the interval between health check requests. Must be positive.

Overrides:

retryInterval in class AbstractHealthCheckedEndpointGroupBuilder

retryIntervalMillis

public HealthCheckedEndpointGroupBuilder retryIntervalMillis(long retryIntervalMillis)

Description copied from class: AbstractHealthCheckedEndpointGroupBuilder

Sets the interval between health check requests in milliseconds. Must be positive.

Overrides:

retryIntervalMillis in class AbstractHealthCheckedEndpointGroupBuilder

retryBackoff

public HealthCheckedEndpointGroupBuilder retryBackoff(Backoff retryBackoff)

Description copied from class: AbstractHealthCheckedEndpointGroupBuilder

Sets the backoff between health check requests.

Overrides:

retryBackoff in class AbstractHealthCheckedEndpointGroupBuilder

clientOptions

public HealthCheckedEndpointGroupBuilder clientOptions(ClientOptions options)

Description copied from class: AbstractHealthCheckedEndpointGroupBuilder

Sets the ClientOptions of the Client that sends health check requests. This method can be useful if you already have an Armeria client and want to reuse its configuration, such as using the same decorators.

 WebClient myClient = ...;
 // Use the same settings and decorators with `myClient` when sending health check requests.
 builder.clientOptions(myClient.options());
 

Overrides:

clientOptions in class AbstractHealthCheckedEndpointGroupBuilder

withClientOptions

public HealthCheckedEndpointGroupBuilder withClientOptions(Function<? super ClientOptionsBuilder,ClientOptionsBuilder> configurator)

Description copied from class: AbstractHealthCheckedEndpointGroupBuilder

Sets the Function that customizes a Client that sends health check requests.

 builder.withClientOptions(b -> {
     return b.setHeader(HttpHeaders.AUTHORIZATION,
                        "bearer my-access-token")
             .responseTimeout(Duration.ofSeconds(3));
 });
 

Overrides:

withClientOptions in class AbstractHealthCheckedEndpointGroupBuilder

newCheckerFactory

protected Function<? super HealthCheckerContext,? extends AsyncCloseable> newCheckerFactory()

Description copied from class: AbstractHealthCheckedEndpointGroupBuilder

Returns the Function that starts to send health check requests to the Endpoint specified in a given HealthCheckerContext when invoked. The Function must update the health of the Endpoint with a value between [0, 1] via HealthCheckerContext.updateHealth(double, ClientRequestContext, ResponseHeaders, Throwable). HealthCheckedEndpointGroup will call AsyncCloseable.closeAsync() on the AsyncCloseable returned by the Function when it needs to stop sending health check requests.

Specified by:

newCheckerFactory in class AbstractHealthCheckedEndpointGroupBuilder

maxEndpointRatio

public HealthCheckedEndpointGroupBuilder maxEndpointRatio(double maxEndpointRatio)

Description copied from class: AbstractHealthCheckedEndpointGroupBuilder

Sets the maximum endpoint ratio of target selected candidates.

Overrides:

maxEndpointRatio in class AbstractHealthCheckedEndpointGroupBuilder

maxEndpointCount

public HealthCheckedEndpointGroupBuilder maxEndpointCount(int maxEndpointCount)

Description copied from class: AbstractHealthCheckedEndpointGroupBuilder

Sets the maximum endpoint count of target selected candidates.

Overrides:

maxEndpointCount in class AbstractHealthCheckedEndpointGroupBuilder

auth

public HealthCheckedEndpointGroupBuilder auth(AuthToken token)

Description copied from class: AbstractHealthCheckedEndpointGroupBuilder

Sets the AuthToken header using HttpHeaderNames.AUTHORIZATION.

Overrides:

auth in class AbstractHealthCheckedEndpointGroupBuilder

allowEmptyEndpoints

public HealthCheckedEndpointGroupBuilder allowEmptyEndpoints(boolean allowEmptyEndpoints)

Description copied from interface: DynamicEndpointGroupSetters

Sets whether to allow an empty Endpoint list. If unspecified, an empty Endpoint list is allowed.

Specified by:

allowEmptyEndpoints in interface DynamicEndpointGroupSetters

Overrides:

allowEmptyEndpoints in class AbstractHealthCheckedEndpointGroupBuilder

selectionTimeout

public HealthCheckedEndpointGroupBuilder selectionTimeout(Duration selectionTimeout)

Description copied from class: AbstractHealthCheckedEndpointGroupBuilder

Sets the timeout to wait until a successful Endpoint selection. This method is shortcut for selectionTimeout(selectionTimeout, selectionTimeout). Duration.ZERO disables the timeout. If unspecified, Flags.defaultResponseTimeoutMillis() is used to wait for the initial endpoints, and Flags.defaultConnectTimeoutMillis()} is used after the initial endpoints are resolved by default.

Note that the specified selectionTimeout and the delegate's selectionTimeout are added and set to this HealthCheckedEndpointGroup. For example:

 DnsAddressEndpointGroup delegate = DnsAddressEndpointGroup.builder("armeria.dev")
                                                           .selectionTimeout(Duration.ofSeconds(3))
                                                           ...
                                                           .build();
 HealthCheckedEndpointGroup endpointGroup =
     HealthCheckedEndpointGroup.builder(delegate, "/health")
                               // Sets the same timeout to both initialSelectionTimeout
                               // and selectionTimeout
                               .selectionTimeout(Duration.ofSeconds(10))
                               ...
                               .build();
 // The selection timeout of `delegate` is added into `endpointGroup`.
 assert endpointGroup.selectionTimeoutMillis() == 13000; // 10000 (health) + 3000 (dns)
 endpointGroup.whenReady.join();
 // The selection timeout won't be changed even after the endpoint initialization.
 assert endpointGroup.selectionTimeoutMillis() == 13000; // 10000 (health) + 3000 (dns)
 

Specified by:

selectionTimeout in interface DynamicEndpointGroupSetters

Overrides:

selectionTimeout in class AbstractHealthCheckedEndpointGroupBuilder

selectionTimeout

public HealthCheckedEndpointGroupBuilder selectionTimeout(Duration initialSelectionTimeout,
 Duration selectionTimeout)

Description copied from class: AbstractHealthCheckedEndpointGroupBuilder

Sets the timeouts to wait until a successful Endpoint selection. Duration.ZERO disables the timeout.

The final timeout is calculated by adding the HealthCheckedEndpointGroup.selectionTimeoutMillis() and the selection timeout of the delegate specified when creating this builder. For example:

 DnsAddressEndpointGroup delegate = DnsAddressEndpointGroup.builder("armeria.dev")
                                                           .selectionTimeout(Duration.ofSeconds(3))
                                                           ...
                                                           .build();
 HealthCheckedEndpointGroup endpointGroup =
     HealthCheckedEndpointGroup.builder(delegate, "/health")
                               .selectionTimeout(Duration.ofSeconds(10), Duration.ofSeconds(5))
                               ...
                               .build();
 assert endpointGroup.selectionTimeoutMillis() == 13000; // 10000 (health) + 3000 (dns)

 // Wait for the initial endpoints.
 endpointGroup.whenReady().join();
 assert endpointGroup.selectionTimeoutMillis() == 8000; // 5000 (health) + 3000 (dns)
 

Overrides:

selectionTimeout in class AbstractHealthCheckedEndpointGroupBuilder

Parameters:

initialSelectionTimeout - the initial selection timeout to wait for the initial endpoints. If unspecified, Flags.defaultResponseTimeoutMillis() is used by default.

selectionTimeout - the selection timeout to wait for an Endpoint after the initial endpoints are resolved. If unspecified, Flags.defaultConnectTimeoutMillis()} is used by default.

selectionTimeoutMillis

public HealthCheckedEndpointGroupBuilder selectionTimeoutMillis(long selectionTimeoutMillis)

Description copied from class: AbstractHealthCheckedEndpointGroupBuilder

Sets the timeout to wait until a successful Endpoint selection. This method is shortcut for selectionTimeoutMillis(selectionTimeout, selectionTimeout). Duration.ZERO disables the timeout. If unspecified, Flags.defaultResponseTimeoutMillis() is used to wait for the initial endpoints, and Flags.defaultConnectTimeoutMillis()} is used after the initial endpoints are resolved by default.

Note that the specified selectionTimeoutMillis and the delegate's selectionTimeoutMillis are added and set to this HealthCheckedEndpointGroup. For example:

 DnsAddressEndpointGroup delegate = DnsAddressEndpointGroup.builder("armeria.dev")
                                                           .selectionTimeoutMillis(3000)
                                                           ...
                                                           .build();
 HealthCheckedEndpointGroup endpointGroup =
     HealthCheckedEndpointGroup.builder(delegate, "/health")
                               // Sets the same timeout to both initialSelectionTimeoutMills
                               // and selectionTimeoutMillis
                               .selectionTimeoutMillis(10000)
                               ...
                               .build();

 // The selection timeout of `delegate` is added into `endpointGroup`.
 assert endpointGroup.selectionTimeoutMillis() == 13000; // 10000 (health) + 3000 (dns)
 endpointGroup.whenReady.join();
 // The selection timeout won't be changed even after the endpoint initialization.
 assert endpointGroup.selectionTimeoutMillis() == 13000; // 10000 (health) + 3000 (dns)
 

Specified by:

selectionTimeoutMillis in interface DynamicEndpointGroupSetters

Overrides:

selectionTimeoutMillis in class AbstractHealthCheckedEndpointGroupBuilder

selectionTimeoutMillis

public HealthCheckedEndpointGroupBuilder selectionTimeoutMillis(long initialSelectionTimeoutMillis,
 long selectionTimeoutMillis)

Description copied from class: AbstractHealthCheckedEndpointGroupBuilder

Sets the timeouts to wait until a successful Endpoint selection. 0 disables the timeout.

The final timeout is calculated by adding the HealthCheckedEndpointGroup.selectionTimeoutMillis() and the selection timeout of the delegate specified when creating this builder. For example:

 DnsAddressEndpointGroup delegate = DnsAddressEndpointGroup.builder("armeria.dev")
                                                           .selectionTimeoutMillis(3000)
                                                           ...
                                                           .build();
 HealthCheckedEndpointGroup endpointGroup =
     HealthCheckedEndpointGroup.builder(delegate, "/health")
                               .selectionTimeoutMillis(10000, 5000)
                               ...
                               .build();
 assert endpointGroup.selectionTimeoutMillis() == 13000; // 10000 (health) + 3000 (dns)

 // Wait for the initial endpoints.
 endpointGroup.whenReady().join();
 assert endpointGroup.selectionTimeoutMillis() == 8000;  // 5000 (health) + 3000 (dns)
 

Overrides:

selectionTimeoutMillis in class AbstractHealthCheckedEndpointGroupBuilder

Parameters:

initialSelectionTimeoutMillis - the initial selection timeout to wait for the initial endpoints. If unspecified, Flags.defaultResponseTimeoutMillis() is used by default.

selectionTimeoutMillis - the selection timeout to wait for an Endpoint after the initial endpoints are resolved. If unspecified, Flags.defaultConnectTimeoutMillis()} is used by default.