- java.lang.Object
-
- inet.ipaddr.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 byIPAddressString
. 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
-
-
Field Summary
Fields Modifier and Type Field Description static HostNameParameters
DEFAULT_VALIDATION_OPTIONS
static char
IPV6_END_BRACKET
static char
IPV6_START_BRACKET
static char
LABEL_SEPARATOR
static char
PORT_SEPARATOR
-
Fields inherited from interface inet.ipaddr.HostIdentifierString
SEGMENT_VALUE_DELIMITER
-
-
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 toHostName(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 Modifier and Type Method Description IPAddress
asAddress()
If this represents an ip address, returns that address.IPAddress
asAddress(IPAddress.IPVersion version)
If this represents an ip address, returns that address.IPAddressString
asAddressString()
If this represents an ip address or represents any valid IPAddressString, returns the corresponding address string.java.net.InetAddress
asInetAddress()
Similar totoInetAddress()
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 andmatches(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 nulljava.lang.String
getService()
If a service name was supplied, returns the service name, otherwise returns nullHostNameParameters
getValidationOptions()
Supplies the validation options used to validate this host name, whether the default or the one supplied withHostName(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)
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 seeisSelf()
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.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.
-
-
-
Field Detail
-
LABEL_SEPARATOR
public static final char LABEL_SEPARATOR
- See Also:
- Constant Field Values
-
IPV6_START_BRACKET
public static final char IPV6_START_BRACKET
- See Also:
- Constant Field Values
-
IPV6_END_BRACKET
public static final char IPV6_END_BRACKET
- See Also:
- Constant Field Values
-
PORT_SEPARATOR
public static final char PORT_SEPARATOR
- See Also:
- Constant Field Values
-
DEFAULT_VALIDATION_OPTIONS
public static final HostNameParameters DEFAULT_VALIDATION_OPTIONS
-
-
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. AnyIPAddressString
format is supported.- Parameters:
host
-
-
HostName
public HostName(java.lang.String host, HostNameParameters options)
Similar toHostName(String)
, but allows you to control which elements are allowed and which are not, using the given options. The default options used byHostName(String)
are permissive.- Parameters:
host
-options
-
-
-
Method Detail
-
getValidationOptions
public HostNameParameters getValidationOptions()
Supplies the validation options used to validate this host name, whether the default or the one supplied withHostName(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 interfaceHostIdentifierString
- 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 seeisLocalHost()
andisLoopback()
- 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 seeisSelf()
-
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 failsjava.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 interfaceHostIdentifierString
- Returns:
-
equals
public boolean equals(java.lang.Object o)
Returns true if the given object is a host name andmatches(HostName)
this one.- Overrides:
equals
in classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.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 astoNormalizedString()
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 interfacejava.lang.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 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. CalltoAddress()
orgetAddress()
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. CalltoAddress()
orgetAddress()
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. CalltoAddress()
orgetAddress()
to get the resolved address.- 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 totoInetAddress()
but does not throw, instead returns null whenever not a valid address. This method does not resolve hosts. For that, calltoAddress()
and thenIPAddress.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.
-
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 methodgetAddress()
will simply return null rather than throw those exceptions. If you wish to get the represented address and avoid DNS resolution, useasAddress()
orasAddressString()
- Specified by:
toAddress
in interfaceHostIdentifierString
- 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, useasAddress()
orasAddressString()
- Specified by:
getAddress
in interfaceHostIdentifierString
- Returns:
-
toString
public java.lang.String toString()
Returns the string used to construct the object.- Specified by:
toString
in interfaceHostIdentifierString
- Overrides:
toString
in classjava.lang.Object
-
-