com.h3c.util.ip

Class IpAddress

java.lang.Object

com.h3c.util.cache.CacheableDataType

com.h3c.util.ip.IpAddress

All Implemented Interfaces:

Serializable, Comparable<IpAddress>

public final class IpAddress
extends CacheableDataType
implements Comparable<IpAddress>

Represents an IP address (either IPv4 or IPv6).

Useful predicates allow the consumer to test for properties of the represented IP address; for example, isLoopback().

All constructors for this class are private. Creating instances of IpAddress is done via the static methods on the class.

Instances of this class are immutable, making them inherently threadsafe.

This class overrides equals(java.lang.Object) and hashCode() so that instances play nicely with the Collection classes.

This class implements the Comparable interface to ensure that a sorted list of addresses is presented in an intuitive order.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	IpAddress.AddressClass Specifies the IP address class.
static class	IpAddress.Family Specifies the IP address families.

Field Summary

Fields

Modifier and Type	Field and Description
static IpAddress	BROADCAST_IPv4 The (limited) broadcast address (IPv4), that is "255.255.255.255".
static String	DELIMITER_V4 The field delimiter in IPv4 addresses (i.e. a dot).
static String	DELIMITER_V6 The field delimiter in IPv6 addresses (i.e. a colon).
static int	IP_V4_ADDR_SIZE Number of bytes for IPv4 address.
static int	IP_V6_ADDR_SIZE Number of bytes for IPv6 address.
static IpAddress	LOOPBACK_IPv4 The loopback address (IPv4), that is 127.0.0.1
static IpAddress	LOOPBACK_IPv6 The loopback address (IPv6), that is "::1".
static IpAddress	UNDETERMINED_IPv4 The undetermined address (IPv4), that is "0.0.0.0".
static IpAddress	UNDETERMINED_IPv6 The undetermined address (IPv6), that is "::".

Method Summary

Methods

Modifier and Type	Method and Description
int	compareTo(IpAddress o) Implements the Comparable interface, to return addresses in natural order.
boolean	equals(Object o)
IpAddress.AddressClass	getAddressClass() Returns the address class.
IpAddress.Family	getFamily() Returns the family this address belongs to.
String	getMulticastName() Returns a friendly name for this IP address, if it is a multicast address, and if the name exists.
int	hashCode()
void	intoBuffer(ByteBuffer b) Writes the bytes that represent the IP address directly into ByteBuffer at the buffer's current position.
boolean	isBroadcast() Returns true if the address represented is a "broadcast" address.
boolean	isLinkLocal() Returns true if this address is a "link local" address.
boolean	isLoopback() Returns true if the address represented is a "loopback" address.
boolean	isMulticast() Returns true if the address represented is a "multicast" address.
boolean	isReserved() Returns true if the address is "reserved".
boolean	isUndetermined() Returns true if the address represented is the "undetermined" address.
byte[]	toByteArray() Returns a newly allocated byte array containing bytes that represent the IP address.
String	toFullString() If IPv6, returns the address with all fields zero-filled.
InetAddress	toInetAddress() Returns an InetAddress instance equivalent to this IP address.
long	toLong()
String	toShortString() If IPv6, returns the shortened form of this address.
String	toString()
String	toStringWithPort(int portNumber) Returns this IP address as a string that includes the specified port number.
static IpAddress	valueFrom(ByteBuffer buffer, boolean v6) Reads bytes from the specified byte buffer and creates an IP address entity.
static IpAddress	valueOf(byte[] addrBytes) Returns an IpAddress object that represents the value of the IP address defined by the specified address bytes.
static IpAddress	valueOf(InetAddress ia) Returns an IpAddress object that represents the value of the IP address defined by the specified InetAddress instance.
static IpAddress	valueOf(String address) Returns an IpAddress object that represents the value of the IP address defined by the specified string.
static int	valueOfPort(String address) Returns the value of the port number from an address string (if one is present).

Methods inherited from class com.h3c.util.cache.CacheableDataType

getRefQ, keyFromBytes

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

IP_V4_ADDR_SIZE

public static final int IP_V4_ADDR_SIZE

Number of bytes for IPv4 address.

See Also:

Constant Field Values

IP_V6_ADDR_SIZE

public static final int IP_V6_ADDR_SIZE

Number of bytes for IPv6 address.

See Also:

Constant Field Values

DELIMITER_V4

public static final String DELIMITER_V4

The field delimiter in IPv4 addresses (i.e. a dot).

See Also:

Constant Field Values

DELIMITER_V6

public static final String DELIMITER_V6

The field delimiter in IPv6 addresses (i.e. a colon).

See Also:

Constant Field Values

LOOPBACK_IPv4

public static final IpAddress LOOPBACK_IPv4

The loopback address (IPv4), that is 127.0.0.1

LOOPBACK_IPv6

public static final IpAddress LOOPBACK_IPv6

The loopback address (IPv6), that is "::1".

UNDETERMINED_IPv4

public static final IpAddress UNDETERMINED_IPv4

The undetermined address (IPv4), that is "0.0.0.0".

UNDETERMINED_IPv6

public static final IpAddress UNDETERMINED_IPv6

The undetermined address (IPv6), that is "::".

BROADCAST_IPv4

public static final IpAddress BROADCAST_IPv4

The (limited) broadcast address (IPv4), that is "255.255.255.255". (To other hosts on the LAN.)

Method Detail

toString

public String toString()

Overrides:

toString in class Object

toShortString

public String toShortString()

If IPv6, returns the shortened form of this address. If IPv4, returns the same as toString().

Returns:

the shortened form

toFullString

public String toFullString()

If IPv6, returns the address with all fields zero-filled. If IPv4, returns the same as toString().

Returns:

the fully written string

toStringWithPort

public String toStringWithPort(int portNumber)

Returns this IP address as a string that includes the specified port number. In the case of an IPv6 address, square brackets are included.

Examples:

• "15.43.37.2:8080"
• "[FEDC:0:1:0:0:0:AB:23]:8080"

Parameters:

portNumber - the port number to append

Returns:

the ip address and port number

Throws:

IllegalArgumentException - if portNumber is < 0 or > 65535

toByteArray

public byte[] toByteArray()

Returns a newly allocated byte array containing bytes that represent the IP address. This will be an array of length 4 for an IPv4 address, or an array of length 16 for an IPv6 address. Note that the address bytes are in network byte order; that is, the highest order byte of the address is at index 0.

Returns:

a byte array representing the IP address

intoBuffer

public void intoBuffer(ByteBuffer b)

Writes the bytes that represent the IP address directly into ByteBuffer at the buffer's current position. This will be an array of length 4 for an IPv4 address, or an array of length 16 for an IPv6 address. Note that the address bytes are in network byte order; that is, the highest order byte of the address is at index 0.

Parameters:

b - the byte buffer to write into

toInetAddress

public InetAddress toInetAddress()

Returns an InetAddress instance equivalent to this IP address. This method doesn't block, i.e. no reverse name service lookup is performed.

Returns:

the InetAddress for this IpAddress instance

See Also:

InetAddress.getByAddress(java.lang.String, byte[])

getFamily

public IpAddress.Family getFamily()

Returns the family this address belongs to.

Returns:

IPv4 or IPv6

getAddressClass

public IpAddress.AddressClass getAddressClass()

Returns the address class.

Returns:

the address class

getMulticastName

public String getMulticastName()

Returns a friendly name for this IP address, if it is a multicast address, and if the name exists. If this is not a multicast address, null is returned.

A value of "(Unknown)" will be returned if no known mapping exists.

Returns:

the multicast address friendly name; or null if this is not a multicast address

isMulticast

public boolean isMulticast()

Returns true if the address represented is a "multicast" address. 224.0.0.0 - 239.255.255.255 for IPv4 (Address class D).

TODO - include logic for IPv6

Returns:

true if this is a multicast address

isBroadcast

public boolean isBroadcast()

Returns true if the address represented is a "broadcast" address. 255.255.255.255 for IPv4.

TODO - include logic for IPv6

Returns:

true if this is a broadcast address

isReserved

public boolean isReserved()

Returns true if the address is "reserved". 0.0.0.0 - 0.255.255.255 for IPv4.

TODO - include logic for IPv6

Returns:

true if this is a reserved address

isLoopback

public boolean isLoopback()

Returns true if the address represented is a "loopback" address. (127.0.0.0 - 127.255.255.255 for IPv4; ::1 for IPv6).

Returns:

true if this is the loopback address for the appropriate family

isUndetermined

public boolean isUndetermined()

Returns true if the address represented is the "undetermined" address. (0.0.0.0 for IPv4; :: for IPv6 ).

Returns:

true if this is the undetermined address for the appropriate family

isLinkLocal

public boolean isLinkLocal()

Returns true if this address is a "link local" address. (169.254.*.* for IPv4; fe80::*:*:*:* for IPv6 ).

Returns:

true if this is a link local address

compareTo

public int compareTo(IpAddress o)

Implements the Comparable interface, to return addresses in natural order. If an IPv6 address is compared with an IPv4 address, the former will always come after the latter if any of its top 3/4 bits are non-zero.

Specified by:

compareTo in interface Comparable<IpAddress>

Parameters:

o - the other IP address

Returns:

an integer value indicating the relative ordering

See Also:

Comparable.compareTo(T)

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

valueOf

public static IpAddress valueOf(byte[] addrBytes)

Returns an IpAddress object that represents the value of the IP address defined by the specified address bytes. Note that the address bytes are presumed to be in network byte order; that is, the highest order byte of the address is at index 0.

If the bytes array is of length 4, it is interpreted as an IPv4 address. If the bytes array is of length 16, it is interpreted as an IPv6 address. Other array lengths will throw an exception.

Parameters:

addrBytes - the address bytes

Returns:

an IpAddress instance

Throws:

NullPointerException - if addressBytes is null

IllegalArgumentException - if addrBytes is an unsupported length

valueOf

public static IpAddress valueOf(String address)

Returns an IpAddress object that represents the value of the IP address defined by the specified string. Both uppercase and lowercase hex digits are allowed (for IPv6 addresses).

Acceptable formats are:

• IPv4: dotted decimal format ("n.n.n.n") -- where 'n' is from 0 to 255
• IPv4: dotted decimal format with port number suffix ("n.n.n.n:p") -- where 'n' is from 0 to 255, and 'p' is from 0 to 65535
• IPv6: eight groups of hexadecimal digits, separated by colon ("x:x:x:x:x:x:x:x") -- where 'x' is from 0000 to FFFF. Leading zeros may be dropped.
• IPv6: shortened form, i.e. a single run of zeros may be replaced with double colons (e.g. "FF:BAD::3")
• IPv6: an address within square brackets (e.g. "[2001:db8::1428:57ab]")
• IPv6: an address within square brackets with port number suffix (e.g. "[2001:db8::1428:57ab]:443")

Note that if a port number suffix is included:

• the port number is dropped
• even though the port number is dropped, an exception will be thrown if the port number is < 0 or > 65535

Parameters:

address - the string representation of the IP address

Returns:

an IpAddress instance

Throws:

NullPointerException - if address is null

IllegalArgumentException - if address is not an acceptable format

valueOf

public static IpAddress valueOf(InetAddress ia)

Returns an IpAddress object that represents the value of the IP address defined by the specified InetAddress instance.

Parameters:

ia - the InetAddress

Returns:

an IpAddress instance representing the same address

Throws:

NullPointerException - if the parameter is null

valueFrom

public static IpAddress valueFrom(ByteBuffer buffer,
                  boolean v6)

Reads bytes from the specified byte buffer and creates an IP address entity. If v6 is true 16 bytes will be read; otherwise 4 bytes will be read.

Parameters:

buffer - byte buffer to get bytes from

v6 - true if reading IPv6 address; if false IPv4 will be read

Returns:

an IpAddress instance

Throws:

BufferUnderflowException - the buffer does not have sufficient bytes remaining

valueOfPort

public static int valueOfPort(String address)

Returns the value of the port number from an address string (if one is present).

Some examples:

• "127.0.0.1:8080" will return 8080
• "127.0.0.1" will return -1 (no port number)
• "[2001:db8::1428:57ab]:443" will return 443
• "[2001:db8::1428:57ab]" will return -1 (no port number)

Parameters:

address - the address string

Returns:

the port number

Throws:

NullPointerException - if address string is null

IllegalArgumentException - if the string is badly formatted or the port number is < 0 or > 65535

toLong

public long toLong()