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

    • 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

    • 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

      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.

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

    • 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

    • 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.
      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 @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 InetAddress.getHostAddress() 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.
      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 @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

    • 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