Module inet.ipaddr
Package inet.ipaddr

Class HostName

java.lang.Object
inet.ipaddr.HostName
All Implemented Interfaces:
HostIdentifierString, Serializable, Comparable<HostName>

public class HostName extends Object implements HostIdentifierString, Comparable<HostName>
An internet host name. Can be a fully qualified domain name, a simple host name, or an ip address string. Can also include a port number or service name (which maps to a port). Can include a prefix length or mask for either an ipaddress or host name string. An IPv6 address can have an IPv6 zone.

Supported formats

You can use all host or address formats supported by nmap and all address formats supported by IPAddressString. All manners of domain names are supported. When adding a prefix length or mask to a host name string, it is to denote the subnet of the resolved address.

Validation is done separately from DNS resolution to avoid unnecessary DNS lookups.

See rfc 3513, 2181, 952, 1035, 1034, 1123, 5890 or the list of rfcs for IPAddress. For IPv6 addresses in host, see rfc 2732 specifying [] notation and 3986 and 4038 (combining IPv6 [] with prefix or zone) and SMTP rfc 2821 for alternative uses of [] for both IPv4 and IPv6

Author:
sfoley
See Also:
  • Field Details

  • Constructor Details

    • HostName

      public HostName(IPAddress addr)
      Constructs a host name from an IP address.
      Parameters:
      addr -
    • HostName

      public HostName(IPAddress addr, int port)
      Constructs a host name from an IP address and a port.
      Parameters:
      addr -
    • HostName

      public HostName(InetSocketAddress inetSocketAddr)
      Constructs a host name from an InetSocketAddress.
      Parameters:
      inetSocketAddr -
    • HostName

      public HostName(InetAddress inetAddr, Integer prefixLength)
      Constructs a host name from an address with prefix length, which can be null.
      Parameters:
      inetAddr -
    • HostName

      public HostName(InterfaceAddress interfaceAddr)
      Constructs a host name from an InterfaceAddress.
      Parameters:
      interfaceAddr -
    • HostName

      public HostName(InetAddress inetAddr)
      Constructs a host name from an IP address.
      Parameters:
      inetAddr -
    • HostName

      public HostName(InetAddress inetAddr, IPAddressStringParameters addressOptions)
      Constructs a host name from an IP address, allowing control over conversion to an IPAddress instance.
      Parameters:
      inetAddr -
    • HostName

      public HostName(String host)
      Constructs a host name instance from the given string. Supports string host names and ip addresses. Also allows masks, ports, service name strings, and prefix lengths, both with addresses and host name strings. Any IPAddressString format is supported.
      Parameters:
      host -
    • HostName

      public HostName(String host, HostNameParameters options)
      Similar to HostName(String), but allows you to control which elements are allowed and which are not, using the given options. The default options used by HostName(String) are permissive.
      Parameters:
      host -
      options -
  • Method Details

    • getValidationOptions

      public HostNameParameters getValidationOptions()
      Supplies the validation options used to validate this host name, whether the default or the one supplied with HostName(String, HostNameParameters)
      Returns:
    • validate

      public void validate() throws HostNameException
      Validates that this string is a valid host name or IP address, and if not, throws an exception with a descriptive message indicating why it is not.
      Specified by:
      validate in interface HostIdentifierString
      Throws:
      HostNameException
    • isValid

      public boolean isValid()
      Returns whether this represents a valid host name or address format.
      Returns:
    • resolvesToSelf

      public boolean resolvesToSelf()
      Returns whether this represents, or resolves to, a host or address representing the same host.
      Returns:
      whether this represents or resolves to the localhost host or a loopback address
    • isSelf

      public boolean isSelf()
      Returns whether this represents a host or address representing the same host. Also see isLocalHost() and isLoopback()
      Returns:
      whether this is the localhost host or a loopback address
    • isLocalHost

      public boolean isLocalHost()
      Returns whether this host is "localhost"
      Returns:
    • isLoopback

      public boolean isLoopback()
      Returns whether this host has the loopback address, such as [::1] (aka [0:0:0:0:0:0:0:1]) or 127.0.0.1 Also see isSelf()
    • toInetAddress

      public InetAddress toInetAddress() throws HostNameException, UnknownHostException
      Returns the InetAddress associated with this host. This will attempt to resolve a host name string if the string is not already an IP address.
      Returns:
      Throws:
      HostNameException - when validation fails
      UnknownHostException - when resolve fails
    • toNormalizedString

      public String toNormalizedString()
      Provides a normalized string which is lowercase for host strings, and which is a normalized string for addresses.
      Specified by:
      toNormalizedString in interface HostIdentifierString
      Returns:
    • equals

      public boolean equals(Object o)
      Returns true if the given object is a host name and matches(HostName) this one.
      Overrides:
      equals in class Object
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
    • getNormalizedLabels

      public String[] getNormalizedLabels()
      Returns an array of normalized strings for this host name instance. If this represents an IP address, the address segments are separated into the returned array. If this represents a host name string, the domain name segments are separated into the returned array, with the top-level domain name (right-most segment) as the last array element. The individual segment strings are normalized in the same way as toNormalizedString() Ports, service name strings, prefix lengths, and masks are all omitted from the returned array.
      Returns:
    • getHost

      public String getHost()
      Returns the host string normalized but without port, service, prefix or mask. If an address, returns the address string normalized, but without port, service, prefix, mask, or brackets for IPv6. To get a normalized string encompassing all details, use toNormalizedString() If not a valid host, returns null
      Returns:
    • matches

      public boolean matches(HostName host)
      Returns whether the given host matches this one. For hosts to match, they must represent the same addresses or have the same host names. Hosts are not resolved when matching. Also, hosts must have the same port and service. They must have the same masks if they are host names. Even if two hosts are invalid, they match if they have the same invalid string.
      Parameters:
      host -
      Returns:
    • compareTo

      public int compareTo(HostName other)
      Specified by:
      compareTo in interface Comparable<HostName>
    • isAddress

      public boolean isAddress(IPAddress.IPVersion version)
    • isAddress

      public boolean isAddress()
      Returns whether this host name is a string representing an valid specific IP address or subnet.
      Returns:
    • isAddressString

      public boolean isAddressString()
      Returns whether this host name is a string representing an IP address or subnet.
      Returns:
    • isAllAddresses

      public boolean isAllAddresses()
      Whether the address represents the set all all valid IP addresses (as opposed to an empty string, a specific address, a prefix length, or an invalid format).
      Returns:
      whether the address represents the set all all valid IP addresses
    • isPrefixOnly

      public boolean isPrefixOnly()
      Whether the address represents a valid IP address network prefix (as opposed to an empty string, an address with or without a prefix, or an invalid format).
      Returns:
      whether the address represents a valid IP address network prefix
    • isEmpty

      public boolean isEmpty()
      Returns true if the address is empty (zero-length).
      Returns:
    • getPort

      public Integer getPort()
      If a port was supplied, returns the port, otherwise returns null
      Returns:
    • getService

      public String getService()
      If a service name was supplied, returns the service name, otherwise returns null
      Returns:
    • getAddressStringException

      public AddressStringException getAddressStringException()
      Returns the exception thrown for invalid ipv6 literal or invalid reverse DNS hosts. This method will return non-null when this host is valid, so no HostException is thrown, but a secondary address within the host is not valid.
      Returns:
    • isUNCIPv6Literal

      public boolean isUNCIPv6Literal()
      Returns whether this host name is an Uniform Naming Convention IPv6 literal host name.
      Returns:
    • isReverseDNS

      public boolean isReverseDNS()
      Returns whether this host name is a reverse DNS string host name.
      Returns:
    • asAddressString

      public IPAddressString asAddressString()
      If this represents an ip address or represents any valid IPAddressString, returns the corresponding address string. Otherwise, returns null. Note that translation includes prefix lengths and IPv6 zones. This does not resolve addresses. Call toAddress() or getAddress() to get the resolved address.
      Returns:
    • asAddress

      public IPAddress asAddress()
      If this represents an ip address, returns that address. Otherwise, returns null. Note that translation includes prefix lengths and IPv6 zones. This does not resolve addresses or return resolved addresses. Call toAddress() or getAddress() to get the resolved address.

      In cases such as IPv6 literals and reverse DNS hosts, you can check the relevant methods isIpv6Literal or isReverseDNS, in which case this method should return the associated address. If this method returns null then an exception occurred when producing the associated address, and that exception is available from getAddressStringException.

      Returns:
    • asAddress

      public IPAddress asAddress(IPAddress.IPVersion version)
      If this represents an ip address, returns that address. Otherwise, returns null. Call toAddress() or getAddress() to get the resolved address.
      Returns:
    • getNetworkPrefixLength

      public Integer getNetworkPrefixLength()
      If a prefix length was supplied, either as part of an address or as part of a domain (in which case the prefix applies to any resolved address), then returns that prefix length. Otherwise, returns null.
    • getMask

      public IPAddress getMask()
      If a mask was provided with this host name, this returns the resulting mask value.
      Returns:
    • asInetAddress

      public InetAddress asInetAddress()
      Similar to toInetAddress() but does not throw, instead returns null whenever not a valid address. This method does not resolve hosts. For that, call toAddress() and then IPAddress.toInetAddress()
      Returns:
    • asInetSocketAddress

      public InetSocketAddress asInetSocketAddress(Function<String,Integer> serviceMapper)
      Returns the InetSocketAddress for this host. A host must have an associated port, or a service name string that is mapped to a port using the provided service mapper, to have a corresponding InetSocketAddress.

      If there is on associated port, then this returns null.

      Note that host name strings are not resolved when using this method.

      Parameters:
      serviceMapper - maps service name strings to ports. Returns null when a service string has no mapping, otherwise returns the port for a given service. You can use a project like netdb to provide a service mapper lambda, https://github.com/jnr/jnr-netdb
      Returns:
      the socket address, or null if no such address.
    • asInetSocketAddress

      public InetSocketAddress asInetSocketAddress()
      Returns the InetSocketAddress for this host. A host must have an associated port to have a corresponding InetSocketAddress.

      If there is on associated port, then this returns null.

      Note that host name strings are not resolved when using this method.

      Returns:
      the socket address, or null if no such address.
    • toAddress

      public IPAddress toAddress() throws UnknownHostException, HostNameException
      If this represents an ip address, returns that address. If this represents a host, returns the resolved ip address of that host. Otherwise, returns null, but only for strings that are considered valid address strings but cannot be converted to address objects. This method will throw exceptions for invalid formats and failures to resolve the address. The equivalent method getAddress() will simply return null rather than throw those exceptions. If you wish to get the represented address and avoid DNS resolution, use asAddress() or asAddressString()
      Specified by:
      toAddress in interface HostIdentifierString
      Returns:
      Throws:
      UnknownHostException
      HostNameException
    • getAddress

      public IPAddress getAddress()
      If this represents an ip address, returns that address. If this represents a host, returns the resolved ip address of that host. Otherwise, returns null. If you wish to get the represented address and avoid DNS resolution, use asAddress() or asAddressString()
      Specified by:
      getAddress in interface HostIdentifierString
      Returns:
    • toString

      public String toString()
      Returns the string used to construct the object.
      Specified by:
      toString in interface HostIdentifierString
      Overrides:
      toString in class Object
      Returns: