com.h3c.util.ip

## Class Subnet

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

- All Implemented Interfaces:
    Serializable, Comparable<Subnet>

      public final class Subnet
      extends CacheableDataType
      implements Comparable<Subnet>

  Represents a subnet.

  Defined by a (starting) subnet address and its associated subnet mask (for both IPv4 and IPv6).

  All constructors for this class are private. Creating instances of `Subnet` 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 is presented in an intuitive order.

  See Also:
    Serialized Form

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compareTo(Subnet o)`
    `boolean` | `contains(IpAddress ip)` Returns true if the given IP address is contained by this subnet.
    `boolean` | `contains(IpRange range)` Returns true if the given IP address range is contained by this subnet.
    `boolean` | `equals(Object o)`
    `IpAddress` | `getAddress()` Returns the subnet address.
    `IpAddress` | `getBroadcastAddress()` Returns the broadcast address for this subnet.
    `IpRange` | `getEquivalentIpRange()` Returns an IP range that represents the same set of IP addresses that belong to this subnet.
    `IpAddress.Family` | `getFamily()` Returns the IP address family of the subnet and mask.
    `SubnetMask` | `getMask()` Returns the subnet mask.
    `int` | `hashCode()`
    `String` | `toDebugString()` Returns a multi-line string representation of this instance.
    `String` | `toString()`
    `static Subnet` | `valueOf(IpAddress address, SubnetMask mask)` Returns a `Subnet` instance that encapsulates the given subnet address and subnet mask.
    `static Subnet` | `valueOf(String spec)` Returns a `Subnet` instance that encapsulates the subnet address and subnet mask expressed in the given string specification.

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

- - ### Method Detail

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### toDebugString

          public String toDebugString()

      Returns a multi-line string representation of this instance.
      Returns:
        a multi-line string representation

    - #### getAddress

          public IpAddress getAddress()

      Returns the subnet address.
      Returns:
        the subnet address

    - #### getMask

          public SubnetMask getMask()

      Returns the subnet mask.
      Returns:
        the subnet mask

    - #### getEquivalentIpRange

          public IpRange getEquivalentIpRange()

      Returns an IP range that represents the same set of IP addresses that belong to this subnet.
      Returns:
        an equivalent IP range

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### compareTo

          public int compareTo(Subnet o)

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

    - #### getFamily

          public IpAddress.Family getFamily()

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

    - #### getBroadcastAddress

          public IpAddress getBroadcastAddress()

      Returns the broadcast address for this subnet. For IPv4 this is the subnet address with the host portion set to all 1 bits. For example:

           IpAddress broadcast = Subnet.valueOf("192.168.1.0/24").getBroadcastAddress();
           assert(broadcast.equals(IpAddress.valueOf("192.168.1.255");

      TODO: need to decide how to handle IPv6 subnets
      Returns:
        the broadcast address associated with this subnet
      Throws:
        `UnsupportedOperationException` - for IPv6 instances

    - #### contains

          public boolean contains(IpAddress ip)

      Returns true if the given IP address is contained by this subnet.
      Parameters:
        `ip` - the IP address
      Returns:
        true if this subnet contains the IP address; false otherwise

    - #### contains

          public boolean contains(IpRange range)

      Returns true if the given IP address range is contained by this subnet.
      Parameters:
        `range` - the IP address range
      Returns:
        true if this subnet contains the IP address range; false otherwise
      Throws:
        `IllegalArgumentException` - if other range is not the same IP family as this one
        `NullPointerException` - if other is null

    - #### valueOf

          public static Subnet valueOf(IpAddress address,
                       SubnetMask mask)

      Returns a `Subnet` instance that encapsulates the given subnet address and subnet mask.
      Parameters:
        `address` - the subnet address
        `mask` - the subnet mask
      Returns:
        the subnet instance
      Throws:
        `NullPointerException` - if either address or mask is null
        `IllegalArgumentException` - if mask is not appropriate for the given subnet address

    - #### valueOf

          public static Subnet valueOf(String spec)

      Returns a `Subnet` instance that encapsulates the subnet address and subnet mask expressed in the given string specification. If a slash is present in the string, it is assumed that CIDR notation is being used. If no slash is present in the string, it is assumed that the address is a class-A, class-B, or class-C (IPv4) address where the subnet mask is implied.

      Classless Inter-Domain Routing (CIDR) is a way of expressing one (or many) subnets and their associated subnet mask.

      The expected form of the string is

           {subnet-address}/{n}

      where `subnet-address` is the start subnet address and `n` is the number of (leftmost) '1' bits in the mask. For example:

           192.168.12.0/23

      applies the network mask 255.255.254.0 to the 192.168 network, starting at 192.168.12.0. This notation represents the address range 192.168.12.0 - 192.168.13.255. Compared to traditional class-based networking, 192.168.12.0/23 represents an aggregation of the two Class C subnets 192.168.12.0 and 192.168.13.0 each having a subnet mask of 255.255.255.0.

      Examples of implied subnet masks:

           Subnet.valueOf("15.0.0.0")  --> address 15.0.0.0, mask 255.0.0.0
           Subnet.valueOf("180.0.0.0")  --> address 180.0.0.0, mask 255.255.0.0
           Subnet.valueOf("200.0.0.0")  --> address 200.0.0.0, mask 255.255.255.0

      Parameters:
        `spec` - the string specification
      Returns:
        the subnet instance
      Throws:
        `NullPointerException` - if the parameter is null
        `IllegalArgumentException` - if the parameter is malformed

Copyright © 2014. All Rights Reserved.