- All Implemented Interfaces:
HostIdentifierString
,Serializable
,Comparable<HostName>
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:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final HostNameParameters
static final char
static final char
static final char
static final char
Fields inherited from interface inet.ipaddr.HostIdentifierString
SEGMENT_VALUE_DELIMITER
-
Constructor Summary
ConstructorsConstructorDescriptionConstructs a host name from an IP address.Constructs a host name from an IP address and a port.Constructs a host name instance from the given string.HostName
(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
(InetAddress inetAddr) Constructs a host name from an IP address.HostName
(InetAddress inetAddr, IPAddressStringParameters addressOptions) Constructs a host name from an IP address, allowing control over conversion to an IPAddress instance.HostName
(InetAddress inetAddr, Integer prefixLength) Constructs a host name from an address with prefix length, which can be null.HostName
(InetSocketAddress inetSocketAddr) Constructs a host name from an InetSocketAddress.HostName
(InterfaceAddress interfaceAddr) Constructs a host name from an InterfaceAddress. -
Method Summary
Modifier and TypeMethodDescriptionIf this represents an ip address, returns that address.asAddress
(IPAddress.IPVersion version) If this represents an ip address, returns that address.If this represents an ip address or represents any valid IPAddressString, returns the corresponding address string.Similar totoInetAddress()
but does not throw, instead returns null whenever not a valid address.Returns the InetSocketAddress for this host.asInetSocketAddress
(Function<String, Integer> serviceMapper) Returns the InetSocketAddress for this host.int
boolean
Returns true if the given object is a host name andmatches(HostName)
this one.If this represents an ip address, returns that address.Returns the exception thrown for invalid ipv6 literal or invalid reverse DNS hosts.getHost()
Returns the host string normalized but without port, service, prefix or mask.getMask()
If a mask was provided with this host name, this returns the resulting mask value.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.String[]
Returns an array of normalized strings for this host name instance.getPort()
If a port was supplied, returns the port, otherwise returns nullIf a service name was supplied, returns the service name, otherwise returns nullSupplies the validation options used to validate this host name, whether the default or the one supplied withHostName(String, HostNameParameters)
int
hashCode()
boolean
Returns whether this host name is a string representing an valid specific IP address or subnet.boolean
isAddress
(IPAddress.IPVersion version) boolean
Returns whether this host name is a string representing an IP address or subnet.boolean
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
Returns whether this host is "localhost"boolean
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
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
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
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
Returns whether the given host matches this one.boolean
Returns whether this represents, or resolves to, a host or address representing the same host.If this represents an ip address, returns that address.Returns the InetAddress associated with this host.Provides a normalized string which is lowercase for host strings, and which is a normalized string for addresses.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 Details
-
LABEL_SEPARATOR
public static final char LABEL_SEPARATOR- See Also:
-
IPV6_START_BRACKET
public static final char IPV6_START_BRACKET- See Also:
-
IPV6_END_BRACKET
public static final char IPV6_END_BRACKET- See Also:
-
PORT_SEPARATOR
public static final char PORT_SEPARATOR- See Also:
-
DEFAULT_VALIDATION_OPTIONS
-
-
Constructor Details
-
HostName
Constructs a host name from an IP address.- Parameters:
addr
-
-
HostName
Constructs a host name from an IP address and a port.- Parameters:
addr
-
-
HostName
Constructs a host name from an InetSocketAddress.- Parameters:
inetSocketAddr
-
-
HostName
Constructs a host name from an address with prefix length, which can be null.- Parameters:
inetAddr
-
-
HostName
Constructs a host name from an InterfaceAddress.- Parameters:
interfaceAddr
-
-
HostName
Constructs a host name from an IP address.- Parameters:
inetAddr
-
-
HostName
Constructs a host name from an IP address, allowing control over conversion to an IPAddress instance.- Parameters:
inetAddr
-
-
HostName
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
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 Details
-
getValidationOptions
Supplies the validation options used to validate this host name, whether the default or the one supplied withHostName(String, HostNameParameters)
- Returns:
-
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.- 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
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 failsUnknownHostException
- when resolve fails
-
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
Returns true if the given object is a host name andmatches(HostName)
this one. -
hashCode
public int hashCode() -
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
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
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
- Specified by:
compareTo
in interfaceComparable<HostName>
-
isAddress
-
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
If a port was supplied, returns the port, otherwise returns null- Returns:
-
getService
If a service name was supplied, returns the service name, otherwise returns null- Returns:
-
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
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
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
If this represents an ip address, returns that address. Otherwise, returns null. CalltoAddress()
orgetAddress()
to get the resolved address.- Returns:
-
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
If a mask was provided with this host name, this returns the resulting mask value.- Returns:
-
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
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
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
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:
UnknownHostException
HostNameException
-
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
Returns the string used to construct the object.- Specified by:
toString
in interfaceHostIdentifierString
- Overrides:
toString
in classObject
- Returns:
-