final class InetAddresses extends Object
InetAddress instances.
Important note: Unlike InetAddress.getByName(), the
methods of this class never cause DNS services to be accessed. For
this reason, you should prefer these methods as much as possible over
their JDK equivalents whenever you are expecting to handle only
IP address string literals -- there is no blocking DNS penalty for a
malformed string.
When dealing with Inet4Address and Inet6Address
objects as byte arrays (vis. InetAddress.getAddress()) they
are 4 and 16 bytes in length, respectively, and represent the address
in network byte order.
Examples of IP addresses and their byte representations:
"127.0.0.1".
7f 00 00 01"::1".
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 012001:db8::/32),
"2001:db8::1".
20 01 0d b8 00 00 00 00 00 00 00 00 00 00 00 01"::192.168.0.1".
00 00 00 00 00 00 00 00 00 00 00 00 c0 a8 00 01"::ffff:192.168.0.1".
00 00 00 00 00 00 00 00 00 00 ff ff c0 a8 00 01A few notes about IPv6 "IPv4 mapped" addresses and their observed use in Java.
"IPv4 mapped" addresses were originally a representation of IPv4
addresses for use on an IPv6 socket that could receive both IPv4
and IPv6 connections (by disabling the IPV6_V6ONLY socket
option on an IPv6 socket). Yes, it's confusing. Nevertheless,
these "mapped" addresses were never supposed to be seen on the
wire. That assumption was dropped, some say mistakenly, in later
RFCs with the apparent aim of making IPv4-to-IPv6 transition simpler.
Technically one can create a 128bit IPv6 address with the wire
format of a "mapped" address, as shown above, and transmit it in an
IPv6 packet header. However, Java's InetAddress creation methods
appear to adhere doggedly to the original intent of the "mapped"
address: all "mapped" addresses return Inet4Address objects.
For added safety, it is common for IPv6 network operators to filter
all packets where either the source or destination address appears to
be a "compat" or "mapped" address. Filtering suggestions usually
recommend discarding any packets with source or destination addresses
in the invalid range ::/3, which includes both of these bizarre
address formats. For more information on "bogons", including lists
of IPv6 bogon space, see:
| Modifier and Type | Class and Description |
|---|---|
(package private) static class |
InetAddresses.TeredoInfo
A simple immutable data class to encapsulate the information to be found in a
Teredo address.
|
| Modifier and Type | Field and Description |
|---|---|
private static Inet4Address |
ANY4 |
private static int |
IPV4_PART_COUNT |
private static int |
IPV6_PART_COUNT |
private static Inet4Address |
LOOPBACK4 |
| Modifier | Constructor and Description |
|---|---|
private |
InetAddresses() |
| Modifier and Type | Method and Description |
|---|---|
private static InetAddress |
bytesToInetAddress(byte[] addr)
Convert a byte array into an InetAddress.
|
private static void |
compressLongestRunOfZeroes(int[] hextets)
Identify and mark the longest run of zeroes in an IPv6 address.
|
private static String |
convertDottedQuadToHex(String ipString) |
(package private) static InetAddress |
forString(String ipString)
Returns the
InetAddress having the given string representation. |
(package private) static InetAddress |
forUriString(String hostAddr)
Returns an InetAddress representing the literal IPv4 or IPv6 host
portion of a URL, encoded in the format specified by RFC 3986 section 3.2.2.
|
(package private) static InetAddress |
fromLittleEndianByteArray(byte[] addr)
Returns an address from a little-endian ordered byte array
(the opposite of what
InetAddress#getByAddress expects). |
private static Inet4Address |
getInet4Address(byte[] bytes)
Returns an
Inet4Address, given a byte array representation of the IPv4 address. |
(package private) static boolean |
hasEmbeddedIPv4ClientAddress(Inet6Address ip)
Examines the Inet6Address to determine if it is an IPv6 address of one
of the specified address types that contain an embedded IPv4 address.
|
private static String |
hextetsToIPv6String(int[] hextets)
Convert a list of hextets into a human-readable IPv6 address.
|
(package private) static InetAddress |
increment(InetAddress address)
Returns a new InetAddress that is one more than the passed in address.
|
private static byte[] |
ipStringToBytes(String ipString) |
(package private) static boolean |
is6to4Address(Inet6Address ip)
Evaluates whether the argument is a 6to4 address.
|
(package private) static boolean |
isCompatIPv4Address(Inet6Address ip)
Evaluates whether the argument is an IPv6 "compat" address.
|
(package private) static boolean |
isInetAddress(String ipString)
Returns
true if the supplied string is a valid IP string
literal, false otherwise. |
(package private) static boolean |
isIsatapAddress(Inet6Address ip)
Evaluates whether the argument is an ISATAP address.
|
(package private) static boolean |
isMappedIPv4Address(String ipString)
Evaluates whether the argument is an "IPv4 mapped" IPv6 address.
|
(package private) static boolean |
isMaximum(InetAddress address)
Returns true if the InetAddress is either 255.255.255.255 for IPv4 or
ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff for IPv6.
|
(package private) static boolean |
isTeredoAddress(Inet6Address ip)
Evaluates whether the argument is a Teredo address.
|
(package private) static boolean |
isUriInetAddress(String ipString)
Returns
true if the supplied string is a valid URI IP string
literal, false otherwise. |
private static short |
parseHextet(String ipPart) |
private static byte |
parseOctet(String ipPart) |
private static byte[] |
textToNumericFormatV4(String ipString) |
private static byte[] |
textToNumericFormatV6(String ipString) |
private static final int IPV4_PART_COUNT
private static final int IPV6_PART_COUNT
private static final Inet4Address LOOPBACK4
private static final Inet4Address ANY4
private static Inet4Address getInet4Address(byte[] bytes)
Inet4Address, given a byte array representation of the IPv4 address.bytes - byte array representing an IPv4 address (should be of length 4)Inet4Address corresponding to the supplied byte arrayIllegalArgumentException - if a valid Inet4Address can not be createdstatic InetAddress forString(String ipString)
InetAddress having the given string representation.
This deliberately avoids all nameservice lookups (e.g. no DNS).
ipString - String containing an IPv4 or IPv6 string literal, e.g.
"192.168.0.1" or "2001:db8::1"InetAddress representing the argumentIllegalArgumentException - if the argument is not a valid IP string literalstatic boolean isInetAddress(String ipString)
true if the supplied string is a valid IP string
literal, false otherwise.ipString - String to evaluated as an IP string literaltrue if the argument is a valid IP string literalprivate static byte[] ipStringToBytes(String ipString)
private static byte[] textToNumericFormatV4(String ipString)
private static byte[] textToNumericFormatV6(String ipString)
private static byte parseOctet(String ipPart)
private static short parseHextet(String ipPart)
private static InetAddress bytesToInetAddress(byte[] addr)
InetAddress#getByAddress is documented as throwing a checked
exception "if IP address if of illegal length." We replace it with
an unchecked exception, for use by callers who already know that addr
is an array of length 4 or 16.addr - the raw 4-byte or 16-byte IP address in big-endian orderprivate static void compressLongestRunOfZeroes(int[] hextets)
Only runs of two or more hextets are considered. In case of a tie, the leftmost run wins. If a qualifying run is found, its hextets are replaced by the sentinel value -1.
hextets - int[] mutable array of eight 16-bit hextetsprivate static String hextetsToIPv6String(int[] hextets)
In order for "::" compression to work, the input should contain negative sentinel values in place of the elided zeroes.
hextets - int[] array of eight 16-bit hextets, or -1sstatic InetAddress forUriString(String hostAddr)
This function is similar to InetAddresses#forString(String),
however, it requires that IPv6 addresses are surrounded by square brackets.
This function is the inverse of
InetAddresses#toUriString(java.net.InetAddress).
hostAddr - A RFC 3986 section 3.2.2 encoded IPv4 or IPv6 addresshostAddrIllegalArgumentException - if hostAddr is not a valid
IPv4 address, or IPv6 address surrounded by square bracketsstatic boolean isUriInetAddress(String ipString)
true if the supplied string is a valid URI IP string
literal, false otherwise.ipString - String to evaluated as an IP URI host string literaltrue if the argument is a valid IP URI hoststatic boolean isCompatIPv4Address(Inet6Address ip)
An "IPv4 compatible", or "compat", address is one with 96 leading
bits of zero, with the remaining 32 bits interpreted as an
IPv4 address. These are conventionally represented in string
literals as "::192.168.0.1", though "::c0a8:1" is
also considered an IPv4 compatible address (and equivalent to
"::192.168.0.1").
For more on IPv4 compatible addresses see section 2.5.5.1 of http://tools.ietf.org/html/rfc4291
NOTE: This method is different from
Inet6Address#isIPv4CompatibleAddress in that it more
correctly classifies "::" and "::1" as
proper IPv6 addresses (which they are), NOT IPv4 compatible
addresses (which they are generally NOT considered to be).
ip - Inet6Address to be examined for embedded IPv4 compatible address formattrue if the argument is a valid "compat" addressstatic boolean is6to4Address(Inet6Address ip)
6to4 addresses begin with the "2002::/16" prefix.
The next 32 bits are the IPv4 address of the host to which
IPv6-in-IPv4 tunneled packets should be routed.
For more on 6to4 addresses see section 2 of http://tools.ietf.org/html/rfc3056
ip - Inet6Address to be examined for 6to4 address formattrue if the argument is a 6to4 addressstatic boolean isTeredoAddress(Inet6Address ip)
Teredo addresses begin with the "2001::/32" prefix.
ip - Inet6Address to be examined for Teredo address formattrue if the argument is a Teredo addressstatic boolean isIsatapAddress(Inet6Address ip)
From RFC 5214: "ISATAP interface identifiers are constructed in Modified EUI-64 format [...] by concatenating the 24-bit IANA OUI (00-00-5E), the 8-bit hexadecimal value 0xFE, and a 32-bit IPv4 address in network byte order [...]"
For more on ISATAP addresses see section 6.1 of http://tools.ietf.org/html/rfc5214
ip - Inet6Address to be examined for ISATAP address formattrue if the argument is an ISATAP addressstatic boolean hasEmbeddedIPv4ClientAddress(Inet6Address ip)
NOTE: ISATAP addresses are explicitly excluded from this method due to their trivial spoofability. With other transition addresses spoofing involves (at least) infection of one's BGP routing table.
ip - Inet6Address to be examined for embedded IPv4 client addresstrue if there is an embedded IPv4 client addressstatic boolean isMappedIPv4Address(String ipString)
An "IPv4 mapped" address is anything in the range ::ffff:0:0/96 (sometimes written as ::ffff:0.0.0.0/96), with the last 32 bits interpreted as an IPv4 address.
For more on IPv4 mapped addresses see section 2.5.5.2 of http://tools.ietf.org/html/rfc4291
Note: This method takes a String argument because
InetAddress automatically collapses mapped addresses to IPv4.
(It is actually possible to avoid this using one of the obscure
Inet6Address methods, but it would be unwise to depend on such
a poorly-documented feature.)
ipString - String to be examined for embedded IPv4-mapped IPv6 address formattrue if the argument is a valid "mapped" addressstatic InetAddress fromLittleEndianByteArray(byte[] addr) throws UnknownHostException
InetAddress#getByAddress expects).
IPv4 address byte array must be 4 bytes long and IPv6 byte array must be 16 bytes long.
addr - the raw IP address in little-endian byte orderUnknownHostException - if IP address is of illegal lengthstatic InetAddress increment(InetAddress address)
address - the InetAddress to incrementIllegalArgumentException - if InetAddress is at the end of its rangestatic boolean isMaximum(InetAddress address)
address - TODOCopyright © 2014 Sven Strittmatter. All Rights Reserved.