Package org.apache.activemq.artemis.utils

Class InetAddresses

  • public final class InetAddresses
extends Object
    Static utility methods pertaining to 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:

    • The IPv4 loopback address, "127.0.0.1".
      7f 00 00 01
    • The IPv6 loopback address, "::1".
      00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 01
    • From the IPv6 reserved documentation prefix (2001:db8::/32), "2001:db8::1".
      20 01 0d b8 00 00 00 00 00 00 00 00 00 00 00 01
    • An IPv6 "IPv4 compatible" (or "compat") address, "::192.168.0.1".
      00 00 00 00 00 00 00 00 00 00 00 00 c0 a8 00 01
    • An IPv6 "IPv4 mapped" address, "::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:

    • Method Detail

      • forString

        public static InetAddress forString​(String ipString)
        Returns the InetAddress having the given string representation.

        This deliberately avoids all nameservice lookups (e.g. no DNS).

        Parameters:
        ipString - String containing an IPv4 or IPv6 string literal, e.g. "192.168.0.1" or "2001:db8::1"
        Returns:
        InetAddress representing the argument
        Throws:
        IllegalArgumentException - if the argument is not a valid IP string literal

      • isInetAddress

        public static boolean isInetAddress​(String ipString)
        Returns true if the supplied string is a valid IP string literal, false otherwise.
        Parameters:
        ipString - String to evaluated as an IP string literal
        Returns:
        true if the argument is a valid IP string literal

      • toAddrString

        public static String toAddrString​(InetAddress ip)
        Returns the string representation of an 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.

        Parameters:
        ip - InetAddress to be converted to an address string
        Returns:
        String containing the text-formatted IP address
        Since:
        10.0

      • forUriString

        public 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.

        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).

        Parameters:
        hostAddr - A RFC 3986 section 3.2.2 encoded IPv4 or IPv6 address
        Returns:
        an InetAddress representing the address in hostAddr
        Throws:
        IllegalArgumentException - if hostAddr is not a valid IPv4 address, or IPv6 address surrounded by square brackets

      • isUriInetAddress

        public static boolean isUriInetAddress​(String ipString)
        Returns true if the supplied string is a valid URI IP string literal, false otherwise.
        Parameters:
        ipString - String to evaluated as an IP URI host string literal
        Returns:
        true if the argument is a valid IP URI host

      • isCompatIPv4Address

        public static boolean isCompatIPv4Address​(Inet6Address ip)
        Evaluates whether the argument is an IPv6 "compat" address.

        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).

        Parameters:
        ip - Inet6Address to be examined for embedded IPv4 compatible address format
        Returns:
        true if the argument is a valid "compat" address

      • getCompatIPv4Address

        public static Inet4Address getCompatIPv4Address​(Inet6Address ip)
        Returns the IPv4 address embedded in an IPv4 compatible address.
        Parameters:
        ip - Inet6Address to be examined for an embedded IPv4 address
        Returns:
        Inet4Address of the embedded IPv4 address
        Throws:
        IllegalArgumentException - if the argument is not a valid IPv4 compatible address