com.h3c.util.ip

## Class PartialSubnet

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

- All Implemented Interfaces:
    Serializable, Comparable<PartialSubnet>

      public final class PartialSubnet
      extends CacheableDataType
      implements Comparable<PartialSubnet>

  Represents a `Subnet` that has one or more `IpRange`s associated with it that narrow the scope of the subnet (hence "partial").

  It follows that all IP addresses represented within the range(s) must fall within the given subnet, and that if more than one range is specified they do not overlap.

  All constructors for this class are private. Creating instances of `PartialSubnet` 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(PartialSubnet o)`
    `boolean` | `contains(IpAddress ip)` Returns true if this partial subnet contains the given IP address; false otherwise.
    `boolean` | `contains(IpRange range)` Returns true if this partial subnet contains the given IP address range; false otherwise.
    `boolean` | `equals(Object o)`
    `IpRange` | `getRange()` Returns the first IP range.
    `List<IpRange>` | `getRanges()` Returns a copy of the list of IP ranges.
    `Subnet` | `getSubnet()` Returns the subnet.
    `int` | `hashCode()`
    `Iterator<IpAddress>` | `iterator()` Returns an IP address iterator that iterates across the IP addresses defined in the range(s) associated with this partial subnet.
    `BigInteger` | `size()` Returns the size of the partial subnet.
    `int` | `sizeAsInt()` Returns the size of the partial subnet as an integer value, unless the value would be greater than `Integer.MAX_VALUE`, in which case this method returns -1.
    `long` | `sizeAsLong()` Returns the size of the partial subnet as a long value, unless the value would be greater than `Long.MAX_VALUE`, in which case this method returns -1L.
    `String` | `toDebugString()` Returns a multi-line string representation of this instance.
    `String` | `toString()`
    `static PartialSubnet` | `valueOf(String spec)` Returns a `PartialSubnet` instance that encapsulates the subnet and any specified IP address range(s) expressed by the given string specification.
    `static PartialSubnet` | `valueOf(Subnet subnet)` Returns a `PartialSubnet` instance that encapsulates the given subnet, with an implied IP address range that spans the complete subnet.
    `static PartialSubnet` | `valueOf(Subnet subnet, IpRange range)` Returns a `PartialSubnet` instance that encapsulates the given subnet, and IP address range.
    `static PartialSubnet` | `valueOf(Subnet subnet, List<IpRange> ranges)` Returns a `PartialSubnet` instance that encapsulates the given subnet, and IP address ranges.

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

    - #### getSubnet

          public Subnet getSubnet()

      Returns the subnet.
      Returns:
        the subnet

    - #### getRange

          public IpRange getRange()

      Returns the first IP range. Equivalent to:

           .getRanges().get(0);

      Returns:
        the first IP range

    - #### getRanges

          public List<IpRange> getRanges()

      Returns a copy of the list of IP ranges.
      Returns:
        a copy of the list of IP ranges

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### compareTo

          public int compareTo(PartialSubnet o)

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

    - #### contains

          public boolean contains(IpAddress ip)

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

    - #### contains

          public boolean contains(IpRange range)

      Returns true if this partial subnet contains the given IP address range; false otherwise.
      Parameters:
        `range` - the IP address range
      Returns:
        true if this partial subnet contains the IP address range; false otherwise.

    - #### size

          public BigInteger size()

      Returns the size of the partial subnet. In other words, how many IP addresses are represented by the defined range(s).
      Returns:
        the size of the partial subnet (number of IP addresses)
      See Also:
        `sizeAsLong()`, `sizeAsInt()`

    - #### sizeAsLong

          public long sizeAsLong()

      Returns the size of the partial subnet as a long value, unless the value would be greater than `Long.MAX_VALUE`, in which case this method returns -1L.
      Returns:
        the size of the range if it does not overflow a long; -1L otherwise
      See Also:
        `size()`

    - #### sizeAsInt

          public int sizeAsInt()

      Returns the size of the partial subnet as an integer value, unless the value would be greater than `Integer.MAX_VALUE`, in which case this method returns -1.
      Returns:
        the size of the range if it does not overflow an int; -1 otherwise
      See Also:
        `size()`

    - #### iterator

          public Iterator<IpAddress> iterator()

      Returns an IP address iterator that iterates across the IP addresses defined in the range(s) associated with this partial subnet.
      Returns:
        an IP address iterator

    - #### valueOf

          public static PartialSubnet valueOf(Subnet subnet)

      Returns a `PartialSubnet` instance that encapsulates the given subnet, with an implied IP address range that spans the complete subnet. This is equivalent to calling:

           PartialSubnet.valueOf(subnet, (IpRange)null);

      Parameters:
        `subnet` - the subnet
      Returns:
        the partial subnet instance
      Throws:
        `NullPointerException` - if subnet is null

    - #### valueOf

          public static PartialSubnet valueOf(Subnet subnet,
                              IpRange range)

      Returns a `PartialSubnet` instance that encapsulates the given subnet, and IP address range. Note that the IP range (if specified) must fall completely within the IP addresses specified by the subnet. If `null` is specified as the range, this is taken as shorthand for specifying a range that completely matches the entire subnet.
      Parameters:
        `subnet` - the subnet
        `range` - the IP range (or null for entire subnet)
      Returns:
        the partial subnet instance
      Throws:
        `NullPointerException` - if subnet is null
        `IllegalArgumentException` - if range is not appropriate for the given subnet

    - #### valueOf

          public static PartialSubnet valueOf(Subnet subnet,
                              List<IpRange> ranges)

      Returns a `PartialSubnet` instance that encapsulates the given subnet, and IP address ranges. Note that the IP ranges (if specified) must fall completely within the IP addresses specified by the subnet, and must not overlap. If `null` or an empty list is supplied as the list of ranges, this is taken as shorthand for specifying a single range that completely matches the entire subnet.
      Parameters:
        `subnet` - the subnet
        `ranges` - the list of ranges (or null/empty for entire subnet)
      Returns:
        the partial subnet instance
      Throws:
        `NullPointerException` - if subnet is null
        `IllegalArgumentException` - if the ranges are not appropriate for the given subnet

    - #### valueOf

          public static PartialSubnet valueOf(String spec)

      Returns a `PartialSubnet` instance that encapsulates the subnet and any specified IP address range(s) expressed by the given string specification. Note that the IP range(s) (if specified) must fall completely within the IP addresses specified by the subnet, and if more than one range is declared, they must not overlap.

      The expected form of the specification string is:

           {subnet}[,{ip-range}[,{ip-range}[,...]]]

      where `subnet` is the form accepted by `Subnet.valueOf(String)`, and `ip-range` is the form accepted by `IpRange.valueOf(String)`. For example:

           192.168.12.0/24,192.168.12.11-17

      defines a partial subnet that restricts the given subnet (`192.168.12.0` through `192.168.12.255` with subnet mask `255.255.255.0`) to the IP addresses `192.168.12.11` through `192.168.12.17`.

      Another example:

           192.168.12.0/23

      defines a partial subnet that is equivalent to the subnet (`192.168.12.0` through `192.168.13.255` with subnet mask `255.255.254.0`) with all IP addresses included. The implied range is `192.168.12-13.*`.

      Some more examples:

           10.11.12.0/24,10.11.12.0-127,10.11.12.200-205
           15.37.24.0/21,15.37.24.*,15.37.25.1-100,15.37.25.121-123

      Note that there can be no white-space in the string.
      Parameters:
        `spec` - the string specification
      Returns:
        the partial subnet instance
      Throws:
        `NullPointerException` - if spec is null
        `IllegalArgumentException` - if the parameter is malformed

Copyright © 2014. All Rights Reserved.