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 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
      • "<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

    • 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

    • select

      public Endpoint select​(ClientRequestContext ctx)
      Description copied from interface: EndpointGroup
      Selects an Endpoint from this EndpointGroup.
      Specified by:
      select in interface EndpointGroup
      Specified by:
      select in interface EndpointSelector
      Returns:
      the Endpoint selected by the EndpointSelectionStrategy, which was specified when constructing this EndpointGroup, or null if this EndpointGroup is empty.

    • 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.
      Throws:
      IllegalStateException - if this endpoint is not a host but a group

    • ipAddr

      @Nullable public String ipAddr()
      Returns the IP address of this endpoint.
      Returns:
      the IP address, or null if the host name is not resolved yet
      Throws:
      IllegalStateException - if this endpoint is not a host but a group

    • 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.
      Throws:
      IllegalStateException - if this endpoint is not a host but a group

    • 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
      Throws:
      IllegalStateException - if this endpoint is not a host but a group

    • ipFamily

      @Nullable public 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
      Throws:
      IllegalStateException - if this endpoint is not a host but a group

    • port

      public int port()
      Returns the port number of this endpoint.
      Throws:
      IllegalStateException - if this endpoint is not a host but a group, or 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
      Throws:
      IllegalStateException - if this endpoint is not a host but a group

    • 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.
      Throws:
      IllegalStateException - if this endpoint is not a host but a group

    • 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.
      Throws:
      IllegalStateException - if this endpoint is not a host but a group

    • 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.
      Throws:
      IllegalStateException - if this endpoint is not a host but a group

    • 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.
      Throws:
      IllegalStateException - if this endpoint is not a host but a group

    • withIpAddr

      public Endpoint withIpAddr​(@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:
      IllegalStateException - if this endpoint is not a host but a group

    • 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.
      Throws:
      IllegalStateException - if this endpoint is not a host but a group

    • 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

    • 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 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 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 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

    • 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

    • equals

      public boolean equals​(@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