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

Copyright © 2014. All Rights Reserved.