inet.ipaddr

Class IPAddressString

java.lang.Object

inet.ipaddr.IPAddressString

All Implemented Interfaces:

HostIdentifierString, Serializable, Comparable<IPAddressString>

public class IPAddressString
extends Object
implements HostIdentifierString, Comparable<IPAddressString>

Parses the string representation of an IP address. Such a string can represent just a single address like 1.2.3.4 or 1:2:3:4:6:7:8, or a subnet like 1.2.0.0/16 or 1.*.1-3.1-4 or 1111:222::/64.

This supports a much wider range of address string formats than InetAddress.getByName. It 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
• the wildcard '*' can span multiple segments, so you can represent all addresses with '*', all IPv4 with '*.*', or all IPv6 with '*:*'
• 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.0.0/16, which is equivalent to 1.2.*.* (all-zero hosts are the full subnet, non-zero hosts are single addresses)
• 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 identifiers, 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
• A single value of 32 hex digits like 00aa00bb00cc00dd00ee00ff00aa00bb with or without a preceding hex delimiter 0x
• A base 85 address comprising 20 base 85 digits like 4)+k&C#VzJ4br>0wv%Yp as in rfc 1924 https://tools.ietf.org/html/rfc1924
• Binary, preceded by 0b, either with binary segments that comprise all 16 bits like ::0b0000111100001111 or a single segment address of 0b followed by 128 binary bits.

All of the above subnet variations work for IPv6, whether network prefix lengths, masks, ranges or wildcards. Similarly, all the above subnet variations 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
• 3-part IPv4: 1.2.3 (which is interpreted as 1.2.0.3 (ie the third part covers the last two)
• 2-part IPv4: 1.2 (which is interpreted as 1.0.0.2 (ie the 2nd part covers the last 3)
• 1-part IPv4: 1 (which is interpreted as 0.0.0.1 (ie the number represents all 4 segments, and can be any number of digits less than the 32 digits which would be interpreted as IPv6)
• hex or octal variants of 1, 2, and 3 part, such as 0xffffffff (which is interpreted as 255.255.255.255)

Also supported are binary segments of a 0b followed by binary digits like 0b1.0b1010.2.3, or a single segment address of 0b followed by all 32 bits.
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. The same can be said of binary segments, they can be mixed with all other formats.

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 former 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
• as noted previously, the single wildcard address "*" represents all addresses both ipv4 and ipv6, although you need to give it some help when converting to IPAddress by specifying the IP version in #getAddress(IPVersion) or #toAddress(IPVersion)
• 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)

If you have an address in which segments have been delimited with commas, such as "1,2.3.4,5.6", you can parse this with parseDelimitedSegments(String) which gives an iterator of strings. For "1,2.3.4,5.6" you will iterate through "1.3.4.6", "1.3.5.6", "2.3.4.6" and "2.3.5.6". You can count the number of elements in such an iterator with countDelimitedAddresses(String). Each string can then be used to construct an IPAddressString.

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(AddressStringException 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 a subnet in which the range of values in a segment of the subnet are not sequential, for which getAddress() throws IncompatibleAddressException 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.* with mask 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.

These exceptions do not occur with non-subnets (ie individual addresses), nor can they occur with standard CIDR prefix-based subnets.

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.

This class has a few methods with analogs in IPAddress, such as contains(IPAddressString), getSequentialRange(), prefixEquals(IPAddressString), isIPv4(), and isIPv6(). Such methods are provided to make creating the IPAddress instance unnecessary when no such IPAddress instance is needed for other reasons.

For some methods, like getSequentialRange() and getDivisionGrouping(), there might not even be an associated IPAddress due to IncompatibleAddressException. However, this is generally only the case with subnets that have non-standard and unusual formats or masks.

See Also:

Serialized Form

Core

Field Summary

Fields

Modifier and Type	Field and Description
static IPAddressStringParameters	DEFAULT_VALIDATION_OPTIONS

Fields inherited from interface inet.ipaddr.HostIdentifierString

SEGMENT_VALUE_DELIMITER

Constructor Summary

Constructors

Constructor and Description
IPAddressString(String addr) Constructs an IPAddressString instance using the given String instance.
IPAddressString(String addr, IPAddressStringParameters valOptions)

Method Summary

Modifier and Type	Method and Description
IPAddressString	adjustPrefixBySegment(boolean nextSegment) Increases or decreases prefix length to the next segment boundary of the given address version's standard segment boundaries.
IPAddressString	adjustPrefixLength(int adjustment) Increases or decreases prefix length by the given increment.
int	compareTo(IPAddressString other) All address strings are comparable.
boolean	contains(IPAddressString other) Returns whether the address subnet identified by this address string contains the address identified by the given string.
String	convertToPrefixLength() Converts this address to a prefix length
static int	countDelimitedAddresses(String str) Given a string with comma delimiters to denote segment elements, this method will count the possible combinations.
boolean	equals(Object o) Two IPAddressString objects are equal if they represent the same set of addresses.
IPAddress	getAddress() If this represents an ip address, returns that address.
IPAddress	getAddress(IPAddress.IPVersion version) Similar to toAddress(inet.ipaddr.IPAddress.IPVersion), but returns null rather than throwing an exception with the address is invalid or does not match the supplied version.
AddressStringException	getAddressStringException() Returns the parse exception thrown by validate, rather than throwing it.
IPAddressDivisionSeries	getDivisionGrouping() Returns a representation of the address string, the address string represented "as-is", converted to value ranges with bit sizes matching the original string.
IPAddress	getHostAddress() If this address string was constructed from a host address with prefix length, then this provides just the host address, rather than the address provided by getAddress() that incorporates the prefix.
IPAddress.IPVersion	getIPVersion() Returns the IP address version if isIPAddress() returns true, otherwise returns null
IPAddress	getMask() If a mask was provided with this address string, this returns the resulting mask value.
Integer	getNetworkPrefixLength() If this address is a valid address with an associated network prefix length then this returns that prefix length, otherwise returns null.
IPAddressSeqRange	getSequentialRange() Returns the range of sequential addresses from the lowest address specified in this address string to the highest.
IPAddressStringParameters	getValidationOptions()
int	hashCode()
boolean	isAllAddresses() Returns true if the string represents all IP addresses, such as the string "*" You can denote all IPv4 addresses with *.*, or all IPv6 addresses with *:*
boolean	isBase85IPv6() If this address string represents an IPv6 address, returns whether the string was base 85
boolean	isEmpty() Returns true if the address string is empty (zero-length).
boolean	isIPAddress() Returns whether the address represents a valid specific IP address or subnet, either IPv4 or IPv6, as opposed to an empty string, the address representing all addresses of all types, a prefix length, or an invalid format.
boolean	isIPv4() Returns true if the address is IPv4 (with or without a network prefix, with or without wildcard segments).
boolean	isIPv4Mapped() Returns true if the address is an IPv6 IPv4-mapped address.
boolean	isIPv6() Returns true if the address is IPv6 (with or without a network prefix, with or without wildcard segments).
boolean	isLoopback() Returns whether this string represents a loopback IP address.
boolean	isMixedIPv6() If this address string represents an IPv6 address, returns whether the lower 4 bytes were represented as IPv4
boolean	isPrefixed() Returns whether this address string has an associated prefix length.
boolean	isPrefixOnly() Returns whether this address string represents only a prefix length with no associated address value, as opposed to an empty string, an address with or without a prefix length, or an invalid format.
boolean	isSequential() Returns whether the addresses returned by this IPAddressString are sequential, meaning that if any address has a numerical value that lies in between the numerical values of two addresses represented by this IPAddressString, then that address is also represented by this IPAddressString.
boolean	isValid() Returns whether this is a valid address string format.
boolean	isZero() Returns whether this string represents an IP address whose value is zero.
static Iterator<String>	parseDelimitedSegments(String str) Given a string with comma delimiters to denote segment elements, this method will provide an iterator to iterate through the possible combinations.
boolean	prefixContains(IPAddressString other) Similar to prefixEquals(IPAddressString), but instead returns whether the prefix of this address contains the same of the given address, using the prefix length of this address.
boolean	prefixEquals(IPAddressString other) Similar to equals(Object), but instead returns whether the prefix of this address matches the same of the given address, using the prefix length of this address.
IPAddress	toAddress() Produces the IPAddress corresponding to this IPAddressString.
IPAddress	toAddress(IPAddress.IPVersion version) Produces the IPAddress of the specified address version corresponding to this IPAddressString.
IPAddressDivisionSeries	toDivisionGrouping() Returns a representation of the address string, the address string represented "as-is", converted to value ranges with bit sizes matching the original string.
IPAddress	toHostAddress() If this address string was constructed from a string comprising of a host address with prefix length or mask, then this provides just the host address, rather than the address with the prefix or mask applied that is provided by toAddress().
String	toNormalizedString() provides a normalized String representation for the host identified by this HostIdentifierString instance
IPAddressSeqRange	toSequentialRange() Returns the range of sequential addresses from the lowest address specified in this address string to the highest.
String	toString() Gives us the original string provided to the constructor.
void	validate() Validates that this string is a valid address, and if not, throws an exception with a descriptive message indicating why it is not.
void	validateIPv4() Validates that this string is a valid IPv4 address, and if not, throws an exception with a descriptive message indicating why it is not.
void	validateIPv6() Validates that this string is a valid IPv6 address, and if not, throws an exception with a descriptive message indicating why it is not.
static void	validateNetworkPrefix(IPAddress.IPVersion ipVersion, int networkPrefixLength, boolean allowPrefixesBeyondAddressSize)
static int	validateNetworkPrefixLength(IPAddress.IPVersion ipVersion, CharSequence networkPrefixLength) Validates that the string has the format "/x" for a valid prefix length x.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_VALIDATION_OPTIONS

public static final IPAddressStringParameters DEFAULT_VALIDATION_OPTIONS

Constructor Detail

IPAddressString

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

IPAddressString

public IPAddressString(String addr,
                       IPAddressStringParameters valOptions)

Parameters:

addr - the address in string format This constructor allows you to alter the default validation options.

Method Detail

getValidationOptions

public IPAddressStringParameters getValidationOptions()

isPrefixed

public boolean isPrefixed()

Returns whether this address string has an associated prefix length. If so, the prefix length is given by getNetworkPrefixLength()

Returns:

whether this address string has an associated prefix length

getNetworkPrefixLength

public Integer getNetworkPrefixLength()

If this address is a valid address with an associated network prefix length then this returns that prefix length, otherwise returns null. The prefix length may be expressed explicitly with the notation "\xx" where xx is a decimal value, or it may be expressed implicitly as a network mask such as /255.255.0.0

Returns:

the prefix length or null

getMask

public IPAddress getMask()

If a mask was provided with this address string, this returns the resulting mask value.

Returns:

isIPAddress

public boolean isIPAddress()

Returns whether the address represents a valid specific IP address or subnet, either IPv4 or IPv6, as opposed to an empty string, the address representing all addresses of all types, a prefix length, or an invalid format.

Returns:

whether the address represents a valid specific IP address.

isAllAddresses

public boolean isAllAddresses()

Returns true if the string represents all IP addresses, such as the string "*" You can denote all IPv4 addresses with *.*, or all IPv6 addresses with *:*

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 this address string represents only a prefix length with no associated address value, as opposed to an empty string, an address with or without a prefix length, or an invalid format.

Returns:

whether the address represents a valid IP address network prefix length

isEmpty

public boolean isEmpty()

Returns true if the address string 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:

isIPv4Mapped

public boolean isIPv4Mapped()

Returns true if the address is an IPv6 IPv4-mapped address.

Returns:

isMixedIPv6

public boolean isMixedIPv6()

If this address string represents an IPv6 address, returns whether the lower 4 bytes were represented as IPv4

Returns:

isBase85IPv6

public boolean isBase85IPv6()

If this address string represents an IPv6 address, returns whether the string was base 85

Returns:

getIPVersion

public IPAddress.IPVersion getIPVersion()

Returns the IP address version if isIPAddress() returns true, otherwise returns null

Returns:

the version

isLoopback

public boolean isLoopback()

Returns whether this string represents a loopback IP address.

See Also:

InetAddress.isLoopbackAddress()

isZero

public boolean isZero()

Returns whether this string represents an IP address whose value is zero.

isValid

public boolean isValid()

Returns whether this is a valid address string format. The accepted IP address formats are: an IPv4 address, an IPv6 address, a network prefix alone, the address representing all addresses of all types, or an empty string. If this method returns false, and you want more details, call validate() and examine the thrown exception.

see validate() or getAddressStringException()

Returns:

whether this is a valid address string format

getAddressStringException

public AddressStringException getAddressStringException()

Returns the parse exception thrown by validate, rather than throwing it. If there is no AddressStringException, then the string is a valid format. However, IncompatibleAddressException can be thrown if the format cannot be translated into the desired result, whether that is an address, a sequential range, or a division grouping. The translation fails only for subnets with non-standard formats or non-standard masks.

See validate() or isValid()

Returns:

the parsing exception, if there is one

validateIPv4

public void validateIPv4()
                  throws AddressStringException

Validates that this string is a valid IPv4 address, and if not, throws an exception with a descriptive message indicating why it is not.

Throws:

AddressStringException

validateIPv6

public void validateIPv6()
                  throws AddressStringException

Validates that this string is a valid IPv6 address, and if not, throws an exception with a descriptive message indicating why it is not.

Throws:

AddressStringException

validate

public void validate()
              throws AddressStringException

Validates that this string is a valid address, and if not, throws an exception with a descriptive message indicating why it is not.

Specified by:

validate in interface HostIdentifierString

Throws:

AddressStringException

validateNetworkPrefixLength

public static int validateNetworkPrefixLength(IPAddress.IPVersion ipVersion,
                                              CharSequence networkPrefixLength)
                                       throws PrefixLenException

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:

IncompatibleAddressException - if invalid with an appropriate message

PrefixLenException

validateNetworkPrefix

public static void validateNetworkPrefix(IPAddress.IPVersion ipVersion,
                                         int networkPrefixLength,
                                         boolean allowPrefixesBeyondAddressSize)
                                  throws PrefixLenException

Throws:

PrefixLenException

hashCode

public int hashCode()

Overrides:

hashCode in class Object

compareTo

public int compareTo(IPAddressString other)

All address strings are comparable. If two address strings are invalid, their strings are compared. Otherwise, address strings are compared according to which type or version of string, and then within each type or version they are compared using the comparison rules for addresses.

Specified by:

compareTo in interface Comparable<IPAddressString>

Parameters:

other -

Returns:

prefixEquals

public boolean prefixEquals(IPAddressString other)

Similar to equals(Object), but instead returns whether the prefix of this address matches the same of the given address, using the prefix length of this address.

In other words, determines if the other address is in the same prefix subnet using the prefix length of this address.

It this address has no prefix length, returns false. The other address need not have an associated prefix length for this method to return true.

If this address string or the given address string is invalid, returns false.

Parameters:

other -

Returns:

prefixContains

public boolean prefixContains(IPAddressString other)

Similar to prefixEquals(IPAddressString), but instead returns whether the prefix of this address contains the same of the given address, using the prefix length of this address.

In other words, determines if the other address is in one of the same prefix subnets using the prefix length of this address.

It this address has no prefix length, returns false. The other address need not have an associated prefix length for this method to return true.

If this address string or the given address string is invalid, returns false.

Parameters:

other -

Returns:

equals

public boolean equals(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. 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 Object

contains

public boolean contains(IPAddressString other)

Returns whether the address subnet identified by this address string contains the address identified by the given string.

If this address string or the given address string is invalid then returns false.

Parameters:

other -

Returns:

getHostAddress

public IPAddress getHostAddress()

If this address string was constructed from a host address with prefix length, then this provides just the host address, rather than the address provided by getAddress() that incorporates the prefix.

Otherwise this returns the same object as getAddress().

This method returns null for invalid formats, the equivalent method toHostAddress() throws exceptions for invalid formats.

Returns:

getAddress

public IPAddress getAddress(IPAddress.IPVersion version)

Similar to toAddress(inet.ipaddr.IPAddress.IPVersion), but returns null rather than throwing an exception with the address is invalid or does not match the supplied version.

getAddress

public IPAddress getAddress()

If this represents an ip address, returns that address. Otherwise, returns null.

This method will return null for invalid formats. Use toAddress() for an equivalent method that throws exceptions for invalid formats.

If you have a prefix address and you wish to get only the host without the prefix, use getHostAddress()

Specified by:

getAddress in interface HostIdentifierString

Returns:

the address

isSequential

public boolean isSequential()

Returns whether the addresses returned by this IPAddressString are sequential, meaning that if any address has a numerical value that lies in between the numerical values of two addresses represented by this IPAddressString, then that address is also represented by this IPAddressString. In other words, the represented range of address values is sequential.

When the IPAddressString is sequential, it can be represented exactly by the IPAddressSeqRange returned from getSequentialRange(). In some cases, no IPAddress instance can be obtained from getAddress() or toAddress(), in the cases where toAddress() throws IncompatibleAddressException, but if the IPAddressString is sequential, you can obtain a IPAddressSeqRange to represent the IPAddressString instead.

Returns:

getDivisionGrouping

public IPAddressDivisionSeries getDivisionGrouping()

Returns a representation of the address string, the address string represented "as-is", converted to value ranges with bit sizes matching the original string. The returned series has the same division count and division bit sizes as in the original string. The method does not attempt to convert to the standard segment counts or bit sizes of IPv4 or IPv6. For the IPv4 or IPv6 representation, use getAddress().

Examples of strings that do not have the standard segment counts and bit lengths include IPv6 addresses in mixed IPv6/IPv4 format, compressed IPv6 addresses, IPv6 addresses expressed as a single segment, IPv4 addresses in inet_aton form with fewer than 4 segments, and IPv4 or IPv6 addresses in which multiple segments are covered by the '*' wildcard.

The returned types is either IPAddressDivisionGrouping or IPAddressLargeDivisionGrouping in cases where one of the divisions is 64 bits or large. This does not return instances of IPAddress, for that you should call getAddress() or toAddress()

This can be useful for parsing formats that do not convert directly to a single instance of IPAddress, such as ranges of non-segmented IPv6 address values like aaaabbbbccccddddeeeeffffaaaabbb-ffffeeeeddddccccbbbbaaaabbbbaaaa, which in most cases cannot be converted to 8 ipv6 segment ranges and thus cannot be converted to a single IPAddress instance.

If the string used to construct this object is not a known format (empty string, address, range of addresses, or prefix) then null is returned.

If the string used to construct this object is a valid subnet format with a non-standard mask, and the masked result has divisions that are not sequential ranges, then null is returned.

An equivalent method that throws exceptions for invalid or incompatible formats is toDivisionGrouping()

Returns:

getSequentialRange

public IPAddressSeqRange getSequentialRange()

Returns the range of sequential addresses from the lowest address specified in this address string to the highest.

Since not all IPAddressString instances describe a sequential series of addresses, this does not necessarily match the exact set of addresses specified by the string. For example, 1-2.3.4.1-2 produces the sequential range 1.3.4.1 to 2.3.4.2 that includes the address 1.255.255.2 not specified by the string.

The sequential range matches the same set of addresses as the address string or the address when isSequential() is true. Otherwise, the range includes addresses not specified by the address string.

This method can also produce a range for a string for which no IPAddress instance can be created, those cases where isValid() returns true but toAddress() throws IncompatibleAddressException and getAddress() returns null. The range cannot be produced for the other cases where getAddress() returns null, those that are version-ambiguous and do not throw IncompatibleAddressException, such as the all address '*' or the version-ambiguous prefix length '/32'.

This is similar to toSequentialRange() except that for invalid address strings, null is returned rather than throwing an exception.

Returns:

toDivisionGrouping

public IPAddressDivisionSeries toDivisionGrouping()
                                           throws AddressStringException,
                                                  IncompatibleAddressException

Returns a representation of the address string, the address string represented "as-is", converted to value ranges with bit sizes matching the original string. The returned series has the same division count and division bit sizes as in the original string. The method does not attempt to convert to the standard segment counts or bit sizes of IPv4 or IPv6. For the IPv4 or IPv6 representation, use getAddress().

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

If the string used to construct this object is a valid subnet format with a non-standard mask, and the masked result has divisions that are not sequential ranges, then this method throws IncompatibleAddressException.

An equivalent method that does not throw exceptions for invalid or incompatible formats is getDivisionGrouping()

Examples of strings that do not have the standard segment counts and bit lengths include IPv6 addresses in mixed IPv6/IPv4 format, compressed IPv6 addresses, IPv6 addresses expressed as a single segment, IPv4 addresses in inet_aton form with fewer than 4 segments, and IPv4 or IPv6 addresses in which multiple segments are covered by the '*' wildcard.

The returned type is either IPAddressDivisionGrouping or IPAddressLargeDivisionGrouping. It is IPAddressLargeDivisionGrouping in cases where one of the divisions is 64 bits or large. This does not return instances of IPAddress, for that you should call getAddress() or toAddress()

This can be useful for parsing formats that do not convert directly to a single instance of IPAddress, such as ranges of non-segmented IPv6 address values like aaaabbbbccccddddeeeeffffaaaabbb-ffffeeeeddddccccbbbbaaaabbbbaaaa, which in most cases cannot be converted to 8 ipv6 segment ranges and thus cannot be converted to a single IPAddress instance.

Returns:

Throws:

AddressStringException

IncompatibleAddressException

toSequentialRange

public IPAddressSeqRange toSequentialRange()
                                    throws AddressStringException

Returns the range of sequential addresses from the lowest address specified in this address string to the highest.

Since not all IPAddressString instances describe a sequential series of addresses, this does not necessarily match the exact set of addresses listed by the string. For example, 1-2.3.4.1-2 produces the sequential range 1.3.4.1 to 2.3.4.2 that includes the address 1.255.255.2 not specified by the string.

The sequential range matches the same set of addresses as the address string or the address when isSequential() is true. Otherwise, the range includes addresses not specified by the address string.

This method can also produce a range for a string for which no IPAddress instance can be created. This method does not throw IncompatibleAddressException. This method does not throw for those cases where isValid() returns true but toAddress() throws IncompatibleAddressException and getAddress() returns null.

There are some cases where this method returns null. The range cannot be produced for the other cases where getAddress() returns null, those that are version-ambiguous and do not throw IncompatibleAddressException, such as the all address '*' or the version-ambiguous prefix '/32'.

Keep in mind that all single addresses, all subnets using written in the canonical address formats, and all subnets with standard network or host masks, all of these have an associated IPAddress instance.

The exceptional cases are those subnets represented in formats supported by IPAddressString that cannot be represented in the canonical formats but can be . This includes IPv6 mixed address subnets that cannot be converted to canonical IPv6 format like ::0-1.2.0-1.4, subnets with non-standard masks like 0-2.2.3.4/2.0.0.0, and subnets represented with non-canonical segments like the IPv4 subnet 1.5000-6000 or the IPv6 subnet 1234567890abcdef1234567890abcdef-1234567890abcdef1234567890abcdef.

This method is equivalent to getSequentialRange() except that for invalid address string formats, AddressStringException is thrown by this method.

Returns:

Throws:

AddressStringException

toHostAddress

public IPAddress toHostAddress()
                        throws AddressStringException,
                               IncompatibleAddressException

If this address string was constructed from a string comprising of a host address with prefix length or mask, then this provides just the host address, rather than the address with the prefix or mask applied that is provided by toAddress().

Otherwise this returns the same object as toAddress().

This method throws exceptions for invalid formats, the equivalent method getHostAddress() will simply return null in such cases.

If this instance of IPAddressString did not originate from a string, but from an IPAddress, then this will return an address that parses from a string to the same IPAddress (with prefix length added to the string if necessary to match).

This method is is intended to operate on the string that is wrapped by IPAddressString (visible from toString())

Returns:

Throws:

AddressStringException

IncompatibleAddressException

toAddress

public IPAddress toAddress(IPAddress.IPVersion version)
                    throws AddressStringException,
                           IncompatibleAddressException

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

Parameters:

version - the address version that this address should represent.

Returns:

the address or null if the parsed address version does not match

Throws:

AddressStringException

IncompatibleAddressException - 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 AddressStringException,
                           IncompatibleAddressException

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 only 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 AddressStringException.

An equivalent method that does not throw exception for invalid formats is getAddress()

If you have a prefixed address and you wish to get only the host rather than the address with the prefix, use toHostAddress()

As long as this object represents a valid address (but not necessarily a specific address), this method does not throw.

Specified by:

toAddress in interface HostIdentifierString

Throws:

AddressStringException - if the address format is invalid

IncompatibleAddressException - if a valid address string representing multiple addresses cannot be represented
This happens only for masks inconsistent with the associated address ranges, or ranges in ipv4 mixed segments that cannot be joined into ipv6 segments

adjustPrefixBySegment

public IPAddressString adjustPrefixBySegment(boolean nextSegment)

Increases or decreases prefix length to the next segment boundary of the given address version's standard segment boundaries.

This acts on address strings with an associated prefix length, whether or not there is also an associated address value, see isPrefixOnly(). If there is no associated address value then the segment boundaries are considered to be at each byte, much like IPv4.

If the address string has prefix length 0 and represents all addresses of the same version, and the prefix length is being decreased, then the address representing all addresses of any version is returned.

Follows the same rules as adjustPrefixLength(int) when there is an associated address value:
When prefix length is increased, the bits moved within the prefix become zero. When a prefix length is decreased, the bits moved outside the prefix become zero. Also see IPAddress.adjustPrefixBySegment(boolean)

Parameters:

nextSegment - whether to move prefix to previous or following segment boundary

Returns:

adjustPrefixLength

public IPAddressString adjustPrefixLength(int adjustment)

Increases or decreases prefix length by the given increment.

This acts on address strings with an associated prefix length, whether or not there is also an associated address value.

If the address string has prefix length 0 and represents all addresses of the same version, and the prefix length is being decreased, then the address representing all addresses of any version is returned.

When there is an associated address value and the prefix length is increased, the bits moved within the prefix become zero, and if prefix length is extended beyond the segment series boundary, it is removed. When there is an associated address value and the prefix length is decreased, the bits moved outside the prefix become zero. Also see IPAddress.adjustPrefixLength(int)

Parameters:

adjustment -

Returns:

countDelimitedAddresses

public static int countDelimitedAddresses(String str)

Given a string with comma delimiters to denote segment elements, this method will count the possible combinations.

For example, given "1,2.3.4,5.6" this method will return 4 for the possible combinations: "1.3.4.6", "1.3.5.6", "2.3.4.6" and "2.3.5.6"

Parameters:

str -

Returns:

parseDelimitedSegments

public static Iterator<String> parseDelimitedSegments(String str)

Given a string with comma delimiters to denote segment elements, this method will provide an iterator to iterate through the possible combinations.

For example, given "1,2.3.4,5.6" this will iterate through "1.3.4.6", "1.3.5.6", "2.3.4.6" and "2.3.5.6"

Another example: "1-2,3.4.5.6" will iterate through "1-2.4.5.6" and "1-3.4.5.6".

This method will not validate strings. Each string produced can be validated using an instance of IPAddressString.

Parameters:

str -

Returns:

convertToPrefixLength

public String convertToPrefixLength()
                             throws AddressStringException

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:

AddressStringException - if the address is invalid

toNormalizedString

public String toNormalizedString()

Description copied from interface: HostIdentifierString

provides a normalized String representation for the host identified by this HostIdentifierString instance

Specified by:

toNormalizedString in interface HostIdentifierString

Returns:

the normalized string

toString

public String toString()

Gives us the original string provided to the constructor. For variations on this string, call getAddress()/toAddress() and then use string methods on the address object.

Specified by:

toString in interface HostIdentifierString

Overrides:

toString in class Object