public 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 01
2001: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 01
A 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 | Method and Description |
---|---|
static InetAddress |
forString(String ipString)
Returns the
InetAddress having the given string representation. |
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.
|
static Inet4Address |
getCompatIPv4Address(Inet6Address ip)
Returns the IPv4 address embedded in an IPv4 compatible address.
|
static boolean |
isCompatIPv4Address(Inet6Address ip)
Evaluates whether the argument is an IPv6 "compat" address.
|
static boolean |
isInetAddress(String ipString)
Returns
true if the supplied string is a valid IP string
literal, false otherwise. |
static boolean |
isUriInetAddress(String ipString)
Returns
true if the supplied string is a valid URI IP string
literal, false otherwise. |
static String |
toAddrString(InetAddress ip)
Returns the string representation of an
InetAddress . |
static String |
toUriString(InetAddress ip)
Returns the string representation of an
InetAddress suitable
for inclusion in a URI. |
public static 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 literalpublic static 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 literalpublic static String toAddrString(InetAddress ip)
InetAddress
.
For IPv4 addresses, this is identical to
InetAddress.getHostAddress()
, but for IPv6 addresses, the output
follows RFC 5952
section 4. The main difference is that this method uses "::" for zero
compression, while Java's version uses the uncompressed form.
This method uses hexadecimal for all IPv6 addresses, including IPv4-mapped IPv6 addresses such as "::c000:201". The output does not include a Scope ID.
ip
- InetAddress
to be converted to an address stringString
containing the text-formatted IP addresspublic static String toUriString(InetAddress ip)
InetAddress
suitable
for inclusion in a URI.
For IPv4 addresses, this is identical to
InetAddress.getHostAddress()
, but for IPv6 addresses it
compresses zeroes and surrounds the text with square brackets; for example
"[2001:db8::1]"
.
Per section 3.2.2 of
http://tools.ietf.org/html/rfc3986,
a URI containing an IPv6 string literal is of the form
"http://[2001:db8::1]:8888/index.html"
.
Use of either toAddrString(java.net.InetAddress)
,
InetAddress.getHostAddress()
, or this method is recommended over
InetAddress.toString()
when an IP address string literal is
desired. This is because InetAddress.toString()
prints the
hostname and the IP address string joined by a "/".
ip
- InetAddress
to be converted to URI string literalString
containing URI-safe string literalpublic static InetAddress forUriString(String hostAddr)
This function is similar to forString(String)
,
however, it requires that IPv6 addresses are surrounded by square brackets.
This function is the inverse of
toUriString(java.net.InetAddress)
.
hostAddr
- A RFC 3986 section 3.2.2 encoded IPv4 or IPv6 addresshostAddr
IllegalArgumentException
- if hostAddr
is not a valid
IPv4 address, or IPv6 address surrounded by square bracketspublic static 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 hostpublic static 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" addresspublic static Inet4Address getCompatIPv4Address(Inet6Address ip)
ip
- Inet6Address
to be examined for an embedded IPv4 addressInet4Address
of the embedded IPv4 addressIllegalArgumentException
- if the argument is not a valid IPv4 compatible addressCopyright © 2019 JBoss by Red Hat. All rights reserved.