inet.ipaddr

Class IPAddressString

  • java.lang.Object
    • inet.ipaddr.IPAddressString
  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<IPAddressString>

    public class IPAddressString
extends java.lang.Object
implements java.lang.Comparable<IPAddressString>, java.io.Serializable
    Parses the string representation of an IP address. Such a string can represent just a single address or a subnet like 1.2.0.0/16 or 1.*.1-3.1-4.

    This supports a much wider range of address string formats than InetAddress.getByName, supports subnet formats, provides specific error messages, and allows more specific configuration.

    You can control all of the supported formats using IPAddressStringParameters.Builder to build a parameters instance of IPAddressStringParameters. When not using the constructor that takes a IPAddressStringParameters, a default instance of IPAddressStringParameters is used that is generally permissive.

    Supported formats

    Both IPv4 and IPv6 are supported.

    Subnets are supported:

    • wildcards '*' and ranges '-' (for example 1.*.2-3.4), useful for working with subnets
    • SQL wildcards '%" and "_", although '%' is considered an SQL wildcard only when it is not considered an IPv6 zone indicator
    • CIDR network prefix length addresses, like 1.2.3.4/16, which is equivalent to 1.2.*.*
    • address/mask pairs, in which the mask is applied to the address, like 1.2.3.4/255.255.0.0, which is also equivalent to 1.2.*.*

    You can combine these variations, such as 1.*.2-3.4/255.255.255.0

    IPv6 is fully supported:

    • IPv6 addresses like ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
    • IPv6 zones or scope ids, like ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff%zone
    • IPv6 mixed addresses are supported, which are addresses for which the last two IPv6 segments are represented as IPv4, like ffff:ffff:ffff:ffff:ffff:ffff:255.255.255.255
    • IPv6 compressed addresses like ::1

    All of the above subnet variations also work for IPv6, whether network prefixes, masks, ranges or wildcards. Similarly, all the the above subnet variations also work for any supported IPv4 format, such as the standard dotted-decimal IPv4 format as well as the inet_aton formats listed below.

    This class support all address formats of the C routine inet_pton and the Java method java.net.InetAddress.getByName. This class supports all IPv4 address formats of the C routine inet_aton as follows:

    • IPv4 hex: 0x1.0x2.0x3.0x4 (0x prefix)
    • IPv4 octal: 01.02.03.0234. Note this clashes with the same address interpreted as dotted decimal
    • IPv4 3 part: 1.2.3 (which is interpreted as 1.2.0.3 (ie the third part covers the last two)
    • IPv4 2 part: 1.2 (which is interpreted as 1.0.0.2 (ie the 2nd part covers the last 3)
    • IPv4 1 part: 1 (which is interpreted as 0.0.0.1 (ie the number represents all 4 segments)

    inet_aton (and this class) allows mixing octal, hex and decimal (e.g. 0xa.11.013.11 which is equivalent to 11.11.11.11). String variations using prefixes, masks, ranges, and wildcards also work for inet_aton style.

    Note that there is ambiguity when supporting both inet_aton octal and dotted-decimal leading zeros, like 010.010.010.010 which can be interpreted as octal or decimal, thus it can be either 8.8.8.8 or 10.10.10.10, with the default behaviour using the latter interpretation

    This behaviour can be controlled by IPAddressStringParameters.Builder.getIPv4AddressParametersBuilder() and IPv4AddressStringParameters.Builder.allowLeadingZeros(boolean)

    Some additional formats:

    • null or empty strings are interpreted as the loopback, in the same way as InetAddress.getByName interprets null or empty strings
    • the single wildcard address "*" which represents all addresses both ipv4 and ipv6
    • specifying CIDR prefix lengths with no corresponding addresses are interpreted as the corresponding network mask. For instance, /64 is interpreted as the 64 bit network mask (ie 64 ones followed by 64 zeros)

    Not supported:
    IPv6 dotted decimal: 1.2.3.4.1.2.3.4.1.2.3.4.1.2.3.4
    IPv6 base 85: RFC 1924

    Usage

    Once you have constructed an IPAddressString object, you can convert it to an IPAddress object with various methods. It is as simple as:
    
 IPAddress address = new IPAddressString("1.2.3.4").getAddress();

    If your application takes user input IP addresses, you can validate with: 

    
 try {
  IPAddress address = new IPAddressString("1.2.3.4").toAddress();
 } catch(IPAddressStringException e) {
        //e.getMessage() provides description of validation failure
 }
    Most address strings can be converted to an IPAddress object using getAddress() or toAddress(). In most cases the IP version is determined by the string itself.

    There are a few exceptions, cases in which the version is unknown or ambiguous, for which getAddress() returns null:

    • strings which do not represent valid addresses (eg "bla")
    • ambiguous address strings (eg "/32" is a prefix that could be IPv4 or IPv6). For such strings you can provide the IPv4/IPv6 version to #getAddress(IPVersion) to get an address.
    • the "all" address "*" which represents all IPv4 and IPv6 addresses. For this string you can provide the IPv4/IPv6 version to #getAddress(IPVersion) to get an address representing either all IPv4 or all IPv6 addresses.
    • empty string "" is interpreted as the default loopback address. You can provide the ipv4/ipv6 version to#getAddress(IPVersion)to get the loopback version of your choice.

    The other exception is subnets in which the range of values in a segment of the subnet are not sequential, for which getAddress() throws IPAddressTypeException because there is no single IPAddress value, there would be many. An IPAddress instance requires that all segments can be represented as a range of values. There are only two unusual circumstances when this can occur:

    • using masks on subnets specified with wildcard or range characters causing non-sequential segments such as the final IPv4 segment of 0.0.0.*\/0.0.0.128, this example translating to the two addresses 0.0.0.0 and 0.0.0.128, so the last IPv4 segment cannot be represented as a sequential range of values.
    • using wildcards or range characters in the IPv4 section of an IPv6 mixed address causing non-sequential segments such as the last IPv6 segment of ::ffff:0.0.*.0, this example translating to the addresses ::ffff:0:100, ::ffff:0:200, , ::ffff:0:300, ..., so the last IPv6 segment cannot be represented as a sequential range of values.

    This class is thread-safe. In fact, IPAddressString objects are immutable. An IPAddressString object represents a single IP address representation that cannot be changed after construction. Some of the derived state is created upon demand and cached, such as the derived IPAddress instances.

    See Also:
    Serialized Form
    Core

    • Constructor Detail

      • IPAddressString

        public IPAddressString(java.lang.String addr)
        Constructs an IPAddressString instance using the given String instance.
        Parameters:
        addr - the address in string format, either IPv4 like a.b.c.d or IPv6 like a:b:c:d:e:f:g:h or a:b:c:d:e:f:h.i.j.k or a::b or some other valid IPv4 or IPv6 form. IPv6 addresses are allowed to terminate with a scope id which starts with a % symbol. Both types of addresses can terminate with a network prefix value like a.b.c.d/24 or ::/24 Optionally, you can specify just a network prefix value like /24, which represents the associated masks 255.255.255.0/24 or ffff:ff00::/24.

        Both IPv4 and IPv6 addresses can terminate with a mask instead of a prefix length, like a.b.c.d/255.0.0.0 or ::/ffff:: If a terminating mask is equivalent to a network prefix, then it will be the same as specifying the prefix, so a.b.c.d/16 is the same as a.b.c.d/255.255.0.0 If a terminating mask is not equivalent to a network prefix, then the mask will simply be applied to the address to produce a single address.

        You can also alter the addresses to include ranges using the wildcards * and -, such as 1.*.1-2.3, although this behaviour is not allowed by default, you must provide your own IPAddressStringParameters for this, or you can use DEFAULT_WILDCARD_OPTIONS or DEFAULT_WILDCARD_AND_RANGE_OPTIONS as the validation options supplied to the constructor.

      • IPAddressString

        public IPAddressString(java.lang.String addr,
                       IPAddressStringParameters valOptions)
        Parameters:
        addr - the address in string format This constructor allows you to alter the default validation options. For example, you can alter the validation options to allow ranges using the wildcards * and -, such as 1.*.1-2.3. Wildcards are not allowed in trailing masks.

    • Method Detail

      • isPrefixed

        public boolean isPrefixed()
        Returns:
        whether this address represents a network prefix or the set of all addresses with the same network prefix

      • getNetworkPrefixLength

        public java.lang.Integer getNetworkPrefixLength()
        Returns:
        if this address is a valid address with a network prefix then this returns that prefix, otherwise returns null

      • isValid

        public boolean isValid()
        Returns:
        whether the address represents one of the accepted IP address types, which are: an IPv4 address, an IPv6 address, a network prefix, the address representing all addresses of all types, or an empty string. If it does not, and you want more details, call validate() and examine the thrown exception.

      • isIPAddress

        public boolean isIPAddress()
        Returns:
        whether the address represents a valid specific IP address, as opposed to an empty string, the address representing all addresses of all types, a prefix length, or an invalid format.

      • isAllAddresses

        public boolean isAllAddresses()
        Returns:
        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).

      • isPrefixOnly

        public boolean isPrefixOnly()
        Returns:
        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).

      • isEmpty

        public boolean isEmpty()
        Returns true if the address is empty (zero-length).
        Returns:

      • isIPv4

        public boolean isIPv4()
        Returns true if the address is IPv4 (with or without a network prefix, with or without wildcard segments).
        Returns:

      • isIPv6

        public boolean isIPv6()
        Returns true if the address is IPv6 (with or without a network prefix, with or without wildcard segments).
        Returns:

      • isMixedIPv6

        public boolean isMixedIPv6()

      • isLoopback

        public boolean isLoopback()
        See Also:
        InetAddress.isLoopbackAddress()

      • isZero

        public boolean isZero()

      • validateIPv4

        public void validateIPv4()
                  throws IPAddressStringException
        Validates this string is a valid IPv4 address, and if not, throws an exception with a descriptive message indicating why it is not.
        Throws:
        IPAddressStringException

      • validateIPv6

        public void validateIPv6()
                  throws IPAddressStringException
        Validates this string is a valid IPv6 address, and if not, throws an exception with a descriptive message indicating why it is not.
        Throws:
        IPAddressStringException

      • validateNetworkPrefixLength

        public static int validateNetworkPrefixLength(IPAddress.IPVersion ipVersion,
                                              java.lang.CharSequence networkPrefixLength)
                                       throws IPAddressTypeException
        Validates that the string has the format "/x" for a valid prefix length x.
        Parameters:
        ipVersion - IPv4, IPv6, or null if you do not know in which case it will be assumed that it can be either
        networkPrefixLength - the network prefix length integer as a string, eg "24"
        Returns:
        the network prefix length
        Throws:
        IPAddressTypeException - if invalid with an appropriate message

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • equals

        public boolean equals(java.lang.Object o)
        Two IPAddressString objects are equal if they represent the same set of addresses. Whether one or the other has an associated network prefix length is not considered. Also, an IPAddressString and IPAddress are considered equal if they represent the same set of addresses. If an IPAddressString is invalid, it is equal to another address only if the other address was constructed from the same string.
        Overrides:
        equals in class java.lang.Object

      • toAddress

        public IPAddress toAddress(IPAddress.IPVersion version)
                    throws IPAddressStringException,
                           IPAddressTypeException
        Produces the IPAddress of the specified address version corresponding to this IPAddressString.

        In most cases the string indicates the address version and calling toAddress() is sufficient, with a few exceptions.

        When this object represents only a network prefix length, specifying the address version allows the conversion to take place to the associated mask for that prefix length.

        When this object represents all addresses, specifying the address version allows the conversion to take place to the associated representation of all IPv4 or all IPv6 addresses.

        When this object represents the empty string and that string is interpreted as a loopback, then it returns the corresponding loopback address. If empty strings are not interpreted as loopback, null is returned.

        When this object represents an ipv4 or ipv6 address, it returns that address if and only if that address matches the provided version.

        If the string used to construct this object is an invalid format, or a format that does not match the provided version, then this method throws IPAddressException.

        Parameters:
        version - the address version that this address should represent.
        Returns:
        Throws:
        IPAddressStringException
        IPAddressTypeException - address in proper format cannot be converted to an address: for masks inconsistent with associated address range, or ipv4 mixed segments that cannot be joined into ipv6 segments

      • toAddress

        public IPAddress toAddress()
                    throws IPAddressStringException,
                           IPAddressTypeException
        Produces the IPAddress corresponding to this IPAddressString. If this object does not represent a specific IPAddress or a ranged IPAddress, null is returned, which may be the case if this object represents a network prefix or if it represents the empty address string. If the string used to construct this object is not a known format (empty string, address, range of addresses, or prefix) then this method throws IPAddressException. As long as this object represents a valid address (but not necessarily a specific address), this method does not throw.
        Throws:
        IPAddressStringException - if the address format is invalid
        IPAddressTypeException - address in proper format cannot be converted to an address: for masks inconsistent with associated address range, or ipv4 mixed segments that cannot be joined into ipv6 segments

      • toSupernet

        public IPAddressString toSupernet(java.lang.Integer prefixLengthDecrement)
        Return an address for the network encompassing this address. The bits indicate the number of additional network bits in the network address in comparison to this address.
        Parameters:
        prefixLengthDecrement - the number to reduce the network bits in order to create a larger network. If null, then this method has the same behaviour as toSupernet()
        Returns:
        the encompassing network

      • toSupernet

        public IPAddressString toSupernet()
        Return an address for the network encompassing this address, with the network portion of the returned address extending to the furthest segment boundary located entirely within but not matching the network portion of this address. If the network portion has no bits then ALL_ADDRESSES is returned. If this object is equal to ALL_ADDRESSES then null is returned.
        Returns:
        the encompassing network

      • convertToPrefixLength

        public java.lang.String convertToPrefixLength()
                                       throws IPAddressStringException
        Converts this address to a prefix length
        Returns:
        the prefix of the indicated IP type represented by this address or null if this address is valid but cannot be represented by a network prefix length
        Throws:
        IPAddressStringException - if the address is invalid

      • toNormalizedString

        public java.lang.String toNormalizedString()
        provides a unique normalized String representation for the host identified by this HostIdentifierString instance
        Returns:
        the normalized string

      • toString

        public java.lang.String toString()
        Gives us the original string provided to the constructor. For variations, call getAddress()/toAddress() and then use string methods on the address object.
        Overrides:
        toString in class java.lang.Object
Skip navigation links