com.h3c.util.ip

## Class SubnetMask

- java.lang.Object
- - com.h3c.util.cache.CacheableDataType
  - - com.h3c.util.ip.SubnetMask

- All Implemented Interfaces:
    Serializable, Comparable<SubnetMask>

      public final class SubnetMask
      extends CacheableDataType
      implements Comparable<SubnetMask>

  Represents a subnet mask (either IPv4 or IPv6).

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

  Instances of this class are immutable, making them inherently thread-safe.

  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 subnet masks is presented in an intuitive order.

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static SubnetMask` | `MASK_255_0_0_0`
    `static SubnetMask` | `MASK_255_255_0_0`
    `static SubnetMask` | `MASK_255_255_248_0`
    `static SubnetMask` | `MASK_255_255_255_0`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compareTo(SubnetMask o)`
    `boolean` | `equals(Object o)`
    `static SubnetMask` | `fromCidr(String cidr)` Returns a `SubnetMask` object that represents the value of the subnet mask implied by the given CIDR notation.
    `IpAddress.Family` | `getFamily()` Returns the IP address family of this subnet mask.
    `int` | `getOneBitCount()` Returns the number of 1 bits in the mask.
    `int` | `hashCode()`
    `IpAddress` | `hostPortion(IpAddress address)` Applies this mask (via logical AND of NOT(mask) ) to calculate and return the host portion of the specified address.
    `IpAddress` | `networkPortion(IpAddress address)` Applies this mask (via logical AND) to calculate and return the network portion of the specified address.
    `byte[]` | `toByteArray()` Returns a newly allocated byte array containing bytes that represent the subnet mask.
    `String` | `toDebugString()` Returns a string representation of this subnet mask showing the internal state.
    `IpAddress` | `toIpAddress()` Returns the IP address equivalent to this subnet mask.
    `String` | `toString()`
    `static SubnetMask` | `valueOf(byte[] maskBytes)` Returns a `SubnetMask` object that represents the subnet mask defined by the specified byte array.
    `static SubnetMask` | `valueOf(IpAddress mask)` Returns a `SubnetMask` object that represents the subnet mask with the value of the given IP address.
    `static SubnetMask` | `valueOf(String mask)` Returns a `SubnetMask` object that represents the value of the subnet mask defined by the specified string.

    - ### 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

    - #### MASK_255_0_0_0

          public static final SubnetMask MASK_255_0_0_0

    - #### MASK_255_255_0_0

          public static final SubnetMask MASK_255_255_0_0

    - #### MASK_255_255_248_0

          public static final SubnetMask MASK_255_255_248_0

    - #### MASK_255_255_255_0

          public static final SubnetMask MASK_255_255_255_0

  - ### Method Detail

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### toDebugString

          public String toDebugString()

      Returns a string representation of this subnet mask showing the internal state.
      Returns:
        a debug string representation

    - #### toByteArray

          public byte[] toByteArray()

      Returns a newly allocated byte array containing bytes that represent the subnet mask. This will be an array of length 4 for an IPv4 subnet mask, and an array of length 16 for an IPv6 subnet mask. 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 subnet mask

    - #### toIpAddress

          public IpAddress toIpAddress()

      Returns the IP address equivalent to this subnet mask.
      Returns:
        the equivalent IP address

    - #### getFamily

          public IpAddress.Family getFamily()

      Returns the IP address family of this subnet mask.
      Returns:
        the IP address family

    - #### getOneBitCount

          public int getOneBitCount()

      Returns the number of 1 bits in the mask.
      Returns:
        the number of 1 bits

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### compareTo

          public int compareTo(SubnetMask o)

      Specified by:
        `compareTo` in interface `Comparable<SubnetMask>`

    - #### networkPortion

          public IpAddress networkPortion(IpAddress address)

      Applies this mask (via logical AND) to calculate and return the network portion of the specified address. For example:

           SubnetMask.MASK_255_255_248_0
                     .networkPortion(IpAddress.valueOf("15.37.129.123"))

      will return the "IP address" `15.37.128.0`
      Parameters:
        `address` - the address to process
      Returns:
        an IP address representing the "network portion" of the given address
      Throws:
        `NullPointerException` - if address is null
        `IllegalArgumentException` - if there is a mismatch of IPv4/IPv6

    - #### hostPortion

          public IpAddress hostPortion(IpAddress address)

      Applies this mask (via logical AND of NOT(mask) ) to calculate and return the host portion of the specified address. For example:

           SubnetMask.MASK_255_255_248_0
                     .hostPortion(IpAddress.valueOf("15.37.129.123"))

      will return the "IP address" `0.0.1.123`
      Parameters:
        `address` - the address to process
      Returns:
        an IP address representing the "host portion" of the given address
      Throws:
        `NullPointerException` - if address is null
        `IllegalArgumentException` - if there is a mismatch of IPv4/IPv6

    - #### valueOf

          public static SubnetMask valueOf(IpAddress mask)

      Returns a `SubnetMask` object that represents the subnet mask with the value of the given IP address.
      Parameters:
        `mask` - the subnet mask value expressed as an IP address
      Returns:
        the subnet mask instance
      Throws:
        `NullPointerException` - if mask is null
        `IllegalArgumentException` - if mask is not a valid value for a subnet mask

    - #### valueOf

          public static SubnetMask valueOf(byte[] maskBytes)

      Returns a `SubnetMask` object that represents the subnet mask defined by the specified byte array. Note that the mask bytes are presumed to be in network byte order; that is, the highest order byte of the mask is at index 0.

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

      Parameters:
        `maskBytes` - the subnet mask bytes
      Returns:
        the subnet mask instance
      Throws:
        `NullPointerException` - if maskBytes is null
        `IllegalArgumentException` - if maskBytes do not define a valid subnet mask

    - #### valueOf

          public static SubnetMask valueOf(String mask)

      Returns a `SubnetMask` object that represents the value of the subnet mask defined by the specified string. Both uppercase and lowercase hex digits are allowed (for IPv6 masks).

      Acceptable formats are:

      - IPv4: dotted decimal format (`"n.n.n.n"`) -- where 'n' is from 0 to 255
      - 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. `"FFFF:FFFF:FFC0::"`)
      - IPv6: an address within square brackets (e.g. `"[FFFF:FFFF:FFC0::]"`)
      Parameters:
        `mask` - the string representation of the subnet mask
      Returns:
        the subnet mask instance
      Throws:
        `NullPointerException` - if mask is null
        `IllegalArgumentException` - if mask is not an acceptable format

    - #### fromCidr

          public static SubnetMask fromCidr(String cidr)

      Returns a `SubnetMask` object that represents the value of the subnet mask implied by the given CIDR notation. For example:

           SubnetMask.fromCidr("192.168.0.0/23")

      would return the subnet mask equivalent to `"255.255.254.0"`
      Parameters:
        `cidr` - the CIDR notation
      Returns:
        the appropriate subnet mask

Copyright © 2014. All Rights Reserved.