Module inet.ipaddr
Package inet.ipaddr

Class HostName

  • All Implemented Interfaces:
    HostIdentifierString, java.io.Serializable, java.lang.Comparable<HostName>

    public class HostName
    extends java.lang.Object
    implements HostIdentifierString, java.lang.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:
    Serialized Form
    • Constructor Summary

      Constructors 
      Constructor Description
      HostName​(IPAddress addr)
      Constructs a host name from an IP address.
      HostName​(IPAddress addr, int port)
      Constructs a host name from an IP address and a port.
      HostName​(java.lang.String host)
      Constructs a host name instance from the given string.
      HostName​(java.lang.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.
      HostName​(java.net.InetAddress inetAddr)
      Constructs a host name from an IP address.
      HostName​(java.net.InetAddress inetAddr, IPAddressStringParameters addressOptions)
      Constructs a host name from an IP address, allowing control over conversion to an IPAddress instance.
      HostName​(java.net.InetAddress inetAddr, java.lang.Integer prefixLength)
      Constructs a host name from an address with prefix length, which can be null.
      HostName​(java.net.InetSocketAddress inetSocketAddr)
      Constructs a host name from an InetSocketAddress.
      HostName​(java.net.InterfaceAddress interfaceAddr)
      Constructs a host name from an InterfaceAddress.
    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      IPAddress asAddress()
      If this represents an ip address, returns that address.
      IPAddress asAddress​(IPAddress.IPVersion version)
      Deprecated.
      IPAddressString asAddressString()
      If this represents an ip address or represents any valid IPAddressString, returns the corresponding address string.
      java.net.InetAddress asInetAddress()
      Similar to toInetAddress() but does not throw, instead returns null whenever not a valid address.
      java.net.InetSocketAddress asInetSocketAddress()
      Returns the InetSocketAddress for this host.
      java.net.InetSocketAddress asInetSocketAddress​(java.util.function.Function<java.lang.String,​java.lang.Integer> serviceMapper)
      Returns the InetSocketAddress for this host.
      int compareTo​(HostName other)  
      boolean equals​(java.lang.Object o)
      Returns true if the given object is a host name and matches(HostName) this one.
      IPAddress getAddress()
      If this represents an ip address, returns that address.
      AddressStringException getAddressStringException()
      Returns the exception thrown for invalid ipv6 literal or invalid reverse DNS hosts.
      java.lang.String getHost()
      Returns the host string normalized but without port, service, prefix or mask.
      IPAddress getMask()
      If a mask was provided with this host name, this returns the resulting mask value.
      java.lang.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.
      java.lang.String[] getNormalizedLabels()
      Returns an array of normalized strings for this host name instance.
      java.lang.Integer getPort()
      If a port was supplied, returns the port, otherwise returns null
      java.lang.String getService()
      If a service name was supplied, returns the service name, otherwise returns null
      HostNameParameters getValidationOptions()
      Supplies the validation options used to validate this host name, whether the default or the one supplied with HostName(String, HostNameParameters)
      int hashCode()  
      boolean isAddress()
      Returns whether this host name is a string representing an valid specific IP address or subnet.
      boolean isAddress​(IPAddress.IPVersion version)
      Deprecated.
      boolean isAddressString()
      Returns whether this host name is a string representing an IP address or subnet.
      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).
      boolean isEmpty()
      Returns true if the address is empty (zero-length).
      boolean isLocalHost()
      Returns whether this host is "localhost"
      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()
      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).
      boolean isReverseDNS()
      Returns whether this host name is a reverse DNS string host name.
      boolean isSelf()
      Returns whether this represents a host or address representing the same host.
      boolean isUNCIPv6Literal()
      Returns whether this host name is an Uniform Naming Convention IPv6 literal host name.
      boolean isValid()
      Returns whether this represents a valid host name or address format.
      boolean matches​(HostName host)
      Returns whether the given host matches this one.
      boolean resolvesToSelf()
      Returns whether this represents, or resolves to, a host or address representing the same host.
      IPAddress toAddress()
      If this represents an IP address, returns that address.
      IPAddress[] toAllAddresses()
      Similar to toAddress(), however in the case where the host is resolved, this method returns all resolved addresses rather than the primary resolved address.
      java.net.InetAddress toInetAddress()
      Returns the InetAddress associated with this host.
      java.lang.String toNormalizedString()
      Provides a normalized string which is lowercase for host strings, and which is a normalized string for addresses.
      java.lang.String toString()
      Returns the string used to construct the object.
      void validate()
      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.
      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • 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​(java.net.InetSocketAddress inetSocketAddr)
        Constructs a host name from an InetSocketAddress.
        Parameters:
        inetSocketAddr -
      • HostName

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

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

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

        public HostName​(java.net.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​(java.lang.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​(java.lang.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 Detail

      • 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 java.net.InetAddress toInetAddress()
                                           throws HostNameException,
                                                  java.net.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
        java.net.UnknownHostException - when resolve fails
      • toNormalizedString

        public java.lang.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​(java.lang.Object o)
        Returns true if the given object is a host name and matches(HostName) this one.
        Overrides:
        equals in class java.lang.Object
      • hashCode

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

        public java.lang.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 java.lang.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 java.lang.Comparable<HostName>
      • isAddress

        @Deprecated
        public boolean isAddress​(IPAddress.IPVersion version)
        Deprecated.
      • 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 java.lang.Integer getPort()
        If a port was supplied, returns the port, otherwise returns null
        Returns:
      • getService

        public java.lang.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:
      • getNetworkPrefixLength

        public java.lang.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 java.net.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 java.net.InetSocketAddress asInetSocketAddress​(java.util.function.Function<java.lang.String,​java.lang.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 java.net.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.
      • toAllAddresses

        public IPAddress[] toAllAddresses()
                                   throws java.net.UnknownHostException,
                                          HostNameException
        Similar to toAddress(), however in the case where the host is resolved, this method returns all resolved addresses rather than the primary resolved address. In the cases where toAddress() returns null, this returns an empty array, and in the cases where this host represents an IP address, this method returns an array of length 1 with that address.
        Returns:
        Throws:
        java.net.UnknownHostException
        HostNameException
      • toAddress

        public IPAddress toAddress()
                            throws java.net.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:
        java.net.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 java.lang.String toString()
        Returns the string used to construct the object.
        Specified by:
        toString in interface HostIdentifierString
        Overrides:
        toString in class java.lang.Object