Package com.linecorp.armeria.client

Class Endpoint

java.lang.Object

com.linecorp.armeria.client.Endpoint

All Implemented Interfaces:

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

public final class Endpoint
extends Object
implements Comparable<Endpoint>, EndpointGroup

A remote endpoint that refers to a single host.

An endpoint has host(), optional ipAddr() and optional port(). It can be represented as "<host>" or "<host>:<port>" in the authority part of a URI. It can have an IP address if the host name has been resolved and thus there's no need to query a DNS server.

Method Summary

Modifier and Type	Method	Description
void	addListener(Consumer<? super List<Endpoint>> listener, boolean notifyLatestEndpoints)	Adds a Consumer that will be invoked when this EndpointGroup changes its value.
<T> T	attr(AttributeKey<T> key)	Returns the attribute value associated with the given AttributeKey of this endpoint, or null if there's no value associated with this key.
Attributes	attrs()	Returns the Attributes of this endpoint, or an empty Attributes if this endpoint does not have any attributes.
String	authority()	Converts this endpoint into the authority part of a URI.
void	close()	This method does nothing.
CompletableFuture<?>	closeAsync()	This method does nothing but returning an immediately complete future.
int	compareTo(Endpoint that)
List<Endpoint>	endpoints()	Returns the endpoints held by this EndpointGroup.
boolean	equals(@Nullable Object obj)
int	hashCode()
boolean	hasIpAddr()	Returns whether this endpoint has an IP address resolved.
boolean	hasPort()	Returns whether this endpoint has a port number specified.
String	host()	Returns the host name of this endpoint.
@Nullable String	ipAddr()	Returns the IP address of this endpoint.
@Nullable StandardProtocolFamily	ipFamily()	Returns the StandardProtocolFamily of this endpoint's IP address.
boolean	isDomainSocket()	Returns whether this endpoint connects to a domain socket.
boolean	isIpAddrOnly()	Returns whether this endpoint's host name is an IP address.
static Endpoint	of(String host)	Creates a new host Endpoint with unspecified port number.
static Endpoint	of(String host, int port)	Creates a new host Endpoint.
static Endpoint	of(SocketAddress addr)	Creates a new Endpoint from the specified SocketAddress.
static Endpoint	parse(String authority)	Parse the authority part of a URI.
int	port()	Returns the port number of this endpoint.
int	port(int defaultValue)	Returns the port number of this endpoint.
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)	Deprecated.
EndpointSelectionStrategy	selectionStrategy()	Returns the EndpointSelectionStrategy of this EndpointGroup.
long	selectionTimeoutMillis()	Returns the timeout to wait until a successful Endpoint selection.
Endpoint	selectNow(ClientRequestContext ctx)	Selects an Endpoint from this EndpointGroup.
InetSocketAddress	toSocketAddress(int defaultPort)	Converts this endpoint into an InetSocketAddress.
String	toString()
URI	toUri(Scheme scheme)	Converts this endpoint into a URI using the Scheme.
URI	toUri(Scheme scheme, @Nullable String path)	Converts this endpoint into a URI using the Scheme and the path.
URI	toUri(SessionProtocol sessionProtocol)	Converts this endpoint into a URI using the SessionProtocol.
URI	toUri(SessionProtocol sessionProtocol, @Nullable String path)	Converts this endpoint into a URI using the SessionProtocol and path.
URI	toUri(String scheme)	Converts this endpoint into a URI using the scheme.
URI	toUri(String scheme, @Nullable String path)	Converts this endpoint into a URI using the scheme and path.
static Endpoint	unsafeCreate(String host, int port)	Creates a new host Endpoint without validation.
int	weight()	Returns the weight of this endpoint.
CompletableFuture<List<Endpoint>>	whenReady()	Returns a CompletableFuture which is completed when the initial Endpoints are ready.
<T> Endpoint	withAttr(AttributeKey<T> key, T value)	Returns a new host endpoint with the specified AttributeKey and value.
Endpoint	withAttrs(Attributes newAttributes)	Returns a new Endpoint with the specified Attributes.
Endpoint	withDefaultPort(int defaultPort)	Returns a new host endpoint with the specified default port number.
Endpoint	withDefaultPort(SessionProtocol protocol)	Returns a new host endpoint with the default port number of the specified SessionProtocol.
Endpoint	withHost(String host)	Returns a new endpoint with the specified host.
Endpoint	withInetAddress(InetAddress address)	Returns a new host endpoint with the IP address of the specified InetAddress.
Endpoint	withIpAddr(@Nullable String ipAddr)	Returns a new host endpoint with the specified IP address.
Endpoint	withoutDefaultPort(int defaultPort)	Returns a new host endpoint with the default port number removed.
Endpoint	withoutDefaultPort(SessionProtocol protocol)	Returns a new host endpoint with the default port number of the specified SessionProtocol removed.
Endpoint	withoutPort()	Returns a new host endpoint with its port number unspecified.
Endpoint	withPort(int port)	Returns a new host endpoint with the specified port number.
Endpoint	withWeight(int weight)	Returns a new host endpoint with the specified weight.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

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

addListener, orElse, removeListener

Method Details

parse

public static Endpoint parse(String authority)

Parse the authority part of a URI. The authority part may have one of the following formats:

• "<host>:<port>" for a host endpoint (The userinfo part will be ignored.)
• "<host>" for a host endpoint with no port number specified

An IPv4 or IPv6 address can be specified in lieu of a host name, e.g. "127.0.0.1:8080" and "[::1]:8080".

of

public static Endpoint of(String host,
 int port)

Creates a new host Endpoint.

Throws:

IllegalArgumentException - if host is not a valid host name or port is not a valid port number

of

public static Endpoint of(String host)

Creates a new host Endpoint with unspecified port number.

Throws:

IllegalArgumentException - if host is not a valid host name

of

@UnstableApi
public static Endpoint of(SocketAddress addr)

Creates a new Endpoint from the specified SocketAddress. This method converts the following address types into an endpoint:

• InetSocketAddress
• DomainSocketAddress
• DomainSocketAddress

Throws:

IllegalArgumentException - if the specified SocketAddress is not supported

unsafeCreate

@UnstableApi
public static Endpoint unsafeCreate(String host,
 int port)

Creates a new host Endpoint without validation.

Note that you should carefully use this method only when both host and port are already valid.

endpoints

public List<Endpoint> endpoints()

Description copied from interface: EndpointGroup

Returns the endpoints held by this EndpointGroup.

Specified by:

endpoints in interface EndpointGroup

addListener

public void addListener(Consumer<? super List<Endpoint>> listener,
 boolean notifyLatestEndpoints)

Description copied from interface: EndpointGroup

Adds a Consumer that will be invoked when this EndpointGroup changes its value. If notifyLatestEndpoints is set to true and the EndpointGroup.whenReady() is completed already, the Consumer will be invoked immediately with the current EndpointGroup.endpoints().

Specified by:

addListener 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

public 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

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

Deprecated.

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

host

public String host()

Returns the host name of this endpoint.

withHost

@UnstableApi
public Endpoint withHost(String host)

Returns a new endpoint with the specified host.

ipAddr

@Nullable
public @Nullable String ipAddr()

Returns the IP address of this endpoint.

Returns:

the IP address, or null if the host name is not resolved yet

hasIpAddr

public boolean hasIpAddr()

Returns whether this endpoint has an IP address resolved. This method is a shortcut for ipAddr() != null.

Returns:

true if and only if this endpoint has an IP address.

isIpAddrOnly

public boolean isIpAddrOnly()

Returns whether this endpoint's host name is an IP address.

Returns:

true if and only if this endpoint's host name is an IP address

ipFamily

@Nullable
public @Nullable StandardProtocolFamily ipFamily()

Returns the StandardProtocolFamily of this endpoint's IP address.

Returns:

the StandardProtocolFamily of this endpoint's IP address, or null if the host name is not resolved yet.

isDomainSocket

@UnstableApi
public boolean isDomainSocket()

Returns whether this endpoint connects to a domain socket.

port

public int port()

Returns the port number of this endpoint.

Throws:

IllegalStateException - this endpoint does not have its port specified.

port

public int port(int defaultValue)

Returns the port number of this endpoint.

Parameters:

defaultValue - the default value to return when this endpoint does not have its port specified

hasPort

public boolean hasPort()

Returns whether this endpoint has a port number specified.

Returns:

true if and only if this endpoint has a port number.

withPort

public Endpoint withPort(int port)

Returns a new host endpoint with the specified port number.

Parameters:

port - the new port number

Returns:

the new endpoint with the specified port number if this endpoint does not have a port or it has a different port number than what's specified. this if this endpoint has the same port number with the specified one.

withoutPort

public Endpoint withoutPort()

Returns a new host endpoint with its port number unspecified.

Returns:

the new endpoint whose port is unspecified if this endpoint has its port. this if this endpoint does not have a port already.

Throws:

IllegalStateException - if this endpoint is not a host but a group

withDefaultPort

public Endpoint withDefaultPort(int defaultPort)

Returns a new host endpoint with the specified default port number.

Parameters:

defaultPort - the default port number

Returns:

the new endpoint whose port is defaultPort if this endpoint does not have its port specified. this if this endpoint already has its port specified.

withDefaultPort

@UnstableApi
public Endpoint withDefaultPort(SessionProtocol protocol)

Returns a new host endpoint with the default port number of the specified SessionProtocol.

Parameters:

protocol - the SessionProtocol that will provide the default port number

Returns:

the new endpoint whose port is the default port number of the specified SessionProtocol if this endpoint does not have its port specified. this if this endpoint already has its port specified.

withoutDefaultPort

public Endpoint withoutDefaultPort(int defaultPort)

Returns a new host endpoint with the default port number removed.

Parameters:

defaultPort - the default port number

Returns:

the new endpoint without a port number if this endpoint had the same port number with the specified default port number. this if this endpoint had a different port number than the specified default port number or this endpoint already does not have a port number.

withoutDefaultPort

@UnstableApi
public Endpoint withoutDefaultPort(SessionProtocol protocol)

Returns a new host endpoint with the default port number of the specified SessionProtocol removed.

Parameters:

protocol - the SessionProtocol that will provide the default port number

Returns:

the new endpoint without a port number if this endpoint had the same port number with the default port number provided by the specified SessionProtocol. this if this endpoint had a different port number than the default port number or this endpoint already does not have a port number.

withIpAddr

public Endpoint withIpAddr(@Nullable
 @Nullable String ipAddr)

Returns a new host endpoint with the specified IP address.

Returns:

the new endpoint with the specified IP address. this if this endpoint has the same IP address.

Throws:

IllegalArgumentException - if the specified IP address is invalid

withInetAddress

public Endpoint withInetAddress(InetAddress address)

Returns a new host endpoint with the IP address of the specified InetAddress.

Returns:

the new endpoint with the specified InetAddress. this if this endpoint has the same IP address.

withWeight

public Endpoint withWeight(int weight)

Returns a new host endpoint with the specified weight.

Returns:

the new endpoint with the specified weight. this if this endpoint has the same weight.

weight

public int weight()

Returns the weight of this endpoint.

authority

public String authority()

Converts this endpoint into the authority part of a URI.

Returns:

the authority string

attr

@UnstableApi
@Nullable
public <T> T attr(AttributeKey<T> key)

Returns the attribute value associated with the given AttributeKey of this endpoint, or null if there's no value associated with this key.

withAttr

@UnstableApi
public <T> Endpoint withAttr(AttributeKey<T> key,
 @Nullable
 T value)

Returns a new host endpoint with the specified AttributeKey and value.

Returns:

the new endpoint with the specified AttributeKey and value. this if this endpoint has the same value with the specified AttributeKey.

withAttrs

@UnstableApi
public Endpoint withAttrs(Attributes newAttributes)

Returns a new Endpoint with the specified Attributes. Note that the attrs() of this Endpoint is replaced with the specified Attributes.

attrs

@UnstableApi
public Attributes attrs()

Returns the Attributes of this endpoint, or an empty Attributes if this endpoint does not have any attributes.

toUri

public URI toUri(String scheme)

Converts this endpoint into a URI using the scheme.

Parameters:

scheme - the scheme for URI.

Returns:

the URI

toUri

public URI toUri(String scheme,
 @Nullable
 @Nullable String path)

Converts this endpoint into a URI using the scheme and path.

Parameters:

scheme - the scheme for URI.

path - the path for URI.

Returns:

the URI

toUri

public URI toUri(SessionProtocol sessionProtocol)

Converts this endpoint into a URI using the SessionProtocol.

Parameters:

sessionProtocol - the SessionProtocol for URI.

Returns:

the URI

toUri

public URI toUri(SessionProtocol sessionProtocol,
 @Nullable
 @Nullable String path)

Converts this endpoint into a URI using the SessionProtocol and path.

Parameters:

sessionProtocol - the SessionProtocol for URI.

path - the path for URI.

Returns:

the URI

toUri

public URI toUri(Scheme scheme)

Converts this endpoint into a URI using the Scheme.

Parameters:

scheme - the Scheme for URI.

Returns:

the URI

toUri

public URI toUri(Scheme scheme,
 @Nullable
 @Nullable String path)

Converts this endpoint into a URI using the Scheme and the path.

Parameters:

scheme - the Scheme for URI.

path - the path for URI.

Returns:

the URI

toSocketAddress

@UnstableApi
public InetSocketAddress toSocketAddress(int defaultPort)

Converts this endpoint into an InetSocketAddress. The specified defaultPort is used if this endpoint does not have a port number. A DomainSocketAddress is returned if this endpoint refers to a Unix domain socket.

See Also:

• hasPort()
• isDomainSocket()

closeAsync

public CompletableFuture<?> closeAsync()

This method does nothing but returning an immediately complete future.

Specified by:

closeAsync in interface AsyncCloseable

Returns:

the CompletableFuture which is completed after the resources are released

close

public void close()

This method does nothing.

Specified by:

close in interface AsyncCloseable

Specified by:

close in interface AutoCloseable

equals

public boolean equals(@Nullable
 @Nullable Object obj)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

compareTo

public int compareTo(Endpoint that)

Specified by:

compareTo in interface Comparable<Endpoint>

toString

public String toString()

Overrides:

toString in class Object