com.h3c.util.ip

## Class IpRange

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

- All Implemented Interfaces:
    Serializable, Comparable<IpRange>

      public final class IpRange
      extends CacheableDataType
      implements Comparable<IpRange>

  Represents a range of IP addresses. Instances of this class are usually created using the `valueOf(com.h3c.util.ip.Subnet)` factory method. (However, see also `Subnet.getEquivalentIpRange()`)

  A string specification is used to define the IP address range. This can be one of two forms, declaring either a range of IPv4 addresses or a range of IPv6 addresses.

  For IPv4 addresses the form is:

       {byteSpec}.{byteSpec}.{byteSpec}.{byteSpec}

  where byteSpec represents a single byte in the address, and is of the form:

       {n} | {n}-{m} | *

  where n and m are values in the range 0 to 255, m (when specified) is > n, and * stands for 0-255

  For example, the specification `"15.29.36-37.1-255"` declares that the range of IP addresses starts with `15.29.36.1` through `15.29.36.255`, then continues with `15.29.37.1` through `15.29.37.255`.

  For IPv6 addresses the form is:

       {2Bytes}:{2Bytes}:{2Bytes}:{2Bytes}:{2Bytes}:{2Bytes}:{2Bytes}:{2Bytes}

  where 2Bytes represents two bytes in the address and is of the form:

       {nnnn} | {nnnn}-{mmmm} | *

  where nnnn and mmmm are hex values in the range 0000 to FFFF, mmmm (when specified) is > nnnn, and * stands for 0000-FFFF.

  Leading zeros may be dropped, and "double-colon" shorthand notation may be used. For example, the specification `"FF:FAB::0000-0003:*"` declares that the range of IP addresses starts with

       00FF:0FAB:0000:0000:0000:0000:0000:0000

  and ends with

       00FF:0FAB:0000:0000:0000:0000:0003:FFFF

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected ByteArrayGenerator` | `bag`
    `protected static String` | `COLON_STAR`
    `protected static String` | `COMMA`
    `protected static String` | `DOT`
    `protected static BigInteger` | `MAX_INT`
    `protected static BigInteger` | `MAX_LONG`
    `protected String` | `normalizedSpec`
    `protected String` | `spec`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compareTo(IpRange o)`
    `boolean` | `contains(com.h3c.util.ip.AbstractRange<T> other)` Returns `true` if this range is a superset of the other range; false otherwise.
    `boolean` | `contains(IpAddress ipAddress)` A predicate that returns `true` if this range contains the given item; false otherwise.
    `static List<IpRange>` | `createRanges(String commaSeparatedSpecs)` Returns a list of IP ranges that embody the given range specifications.
    `boolean` | `equals(Object o)`
    `IpAddress` | `first()` Returns the first item in the range.
    `protected ByteArrayGenerator` | `getBag(String spec)` Subclasses must return a byte array generator appropriate for the given range specification.
    `Subnet` | `getEquivalentSubnet()` Returns an instance of `Subnet` equivalent to this IP address range, if appropriate; null otherwise.
    `IpAddress.Family` | `getFamily()` Returns the IP address family of this range.
    `int` | `hashCode()`
    `boolean` | `intersects(com.h3c.util.ip.AbstractRange<T> other)` Returns `true` if this range intersects the other range; false otherwise.
    `Iterator<IpAddress>` | `iterator()` Returns an iterator for the range.
    `IpAddress` | `last()` Returns the last item in the range.
    `IpAddress` | `random()` Returns a randomly generated item that falls within this range.
    `static String` | `rangeListToString(List<IpRange> ranges)` Converts a list of IP address ranges to a comma separated string representation.
    `BigInteger` | `size()` Returns the size of the range.
    `int` | `sizeAsInt()` Returns the size of the range 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 range 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 representing the internal state of this range.
    `String` | `toString()`
    `static IpRange` | `valueOf(String spec)` Returns an IP range for the given 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`

- - ### Field Detail

    - #### MAX_LONG

          protected static final BigInteger MAX_LONG

    - #### MAX_INT

          protected static final BigInteger MAX_INT

    - #### DOT

          protected static final String DOT

      See Also:
        Constant Field Values

    - #### COMMA

          protected static final String COMMA

      See Also:
        Constant Field Values

    - #### COLON_STAR

          protected static final String COLON_STAR

      See Also:
        Constant Field Values

    - #### spec

          protected final String spec

    - #### normalizedSpec

          protected final String normalizedSpec

    - #### bag

          protected final transient ByteArrayGenerator bag

  - ### Method Detail

    - #### getBag

          protected ByteArrayGenerator getBag(String spec)

      Subclasses must return a byte array generator appropriate for the given range specification.
      Parameters:
        `spec` - the range specification
      Returns:
        the byte array generator

    - #### contains

          public boolean contains(IpAddress ipAddress)

      A predicate that returns `true` if this range contains the given item; false otherwise.
      Parameters:
        `ipAddress` - the item
      Returns:
        true if this range contains the item; false otherwise

    - #### first

          public IpAddress first()

      Returns the first item in the range.
      Returns:
        the first item in the range

    - #### last

          public IpAddress last()

      Returns the last item in the range.
      Returns:
        the last item in the range

    - #### random

          public IpAddress random()

      Returns a randomly generated item that falls within this range.
      Returns:
        a random item within this range

    - #### iterator

          public Iterator<IpAddress> iterator()

      Returns an iterator for the range. The iterator will return successive items starting with the `first()` and ending with the `last()`, emitting a total count of `size()` items.
      Returns:
        an iterator for the range

    - #### compareTo

          public int compareTo(IpRange o)

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

    - #### getFamily

          public IpAddress.Family getFamily()

      Returns the IP address family of this range.
      Returns:
        the IP address family

    - #### getEquivalentSubnet

          public Subnet getEquivalentSubnet()

      Returns an instance of `Subnet` equivalent to this IP address range, if appropriate; null otherwise.

      So, what is meant by "if appropriate"? Well, if the `first` IP address in this range represents the subnet address with all zero bits in the host portion of the address, and the `last` IP address in this range represents the subnet address with all one bits in the host portion of the address, then the equivalent subnet can be computed and returned. For example:

           IpRange range = IpRange.valueOf("15.23.12-13.*");
           Subnet subnet = range.getEquivalentSubnet();

           assert(subnet.equals(Subnet.valueOf("15.23.12.0/23")));
           assert(subnet.getAddress().equals(IpAddress.valueOf("15.23.12.0");
           assert(subnet.getMask().equals(SubnetMask.valueOf("255.255.254.0");

           ---
           IpRange range = IpRange.valueOf("15.23.47.1-100");
           Subnet subnet = range.getEquivalentSubnet();

           assert(subnet == null);

      Returns:
        the subnet equivalent to this IP address range, if appropriate; null otherwise

    - #### valueOf

          public static IpRange valueOf(String spec)

      Returns an IP range for the given specification. See the class documentation for a description of the specification format.
      Parameters:
        `spec` - the IP address range specification
      Returns:
        an IP range instance that embodies the specified IP address range

    - #### createRanges

          public static List<IpRange> createRanges(String commaSeparatedSpecs)

      Returns a list of IP ranges that embody the given range specifications. The range specifications should be supplied as a comma separated list. See the class documentation for a description of the specification format.
      Parameters:
        `commaSeparatedSpecs` - the comma separated list of range specs
      Returns:
        a list of IP range instances

    - #### rangeListToString

          public static String rangeListToString(List<IpRange> ranges)

      Converts a list of IP address ranges to a comma separated string representation. This method is the inverse of `createRanges(String)`.
      Parameters:
        `ranges` - the list of ranges
      Returns:
        a comma separated list representation

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### toDebugString

          public String toDebugString()

      Returns a multi-line string representing the internal state of this range.
      Returns:
        the debug string

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### contains

          public boolean contains(com.h3c.util.ip.AbstractRange<T> other)

      Returns `true` if this range is a superset of the other range; false otherwise. Put another way, the set of all items `T_other` produced by `other.iterator()` is a subset of the set of all items `T_this` produced by `this.iterator()`.
      Parameters:
        `other` - the other range to compare with
      Returns:
        true if this range is a superset of the other range; false otherwise
      Throws:
        `IllegalArgumentException` - if other range is not the same type as this one
        `NullPointerException` - if other is null

    - #### intersects

          public boolean intersects(com.h3c.util.ip.AbstractRange<T> other)

      Returns `true` if this range intersects the other range; false otherwise. Put another way, the set of all items `T_other` produced by `other.iterator()` contains at least one item from the set of all items `T_this` produced by `this.iterator()`.
      Parameters:
        `other` - the other range to compare with
      Returns:
        true if this range intersects the other range; false otherwise
      Throws:
        `IllegalArgumentException` - if other range is not the same type as this one
        `NullPointerException` - if other is null

    - #### size

          public BigInteger size()

      Returns the size of the range. In other words, how many items are represented by the range.
      Returns:
        the size of the range
      See Also:
        `sizeAsLong()`, `sizeAsInt()`

    - #### sizeAsLong

          public long sizeAsLong()

      Returns the size of the range 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 range 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()`

Copyright © 2014. All Rights Reserved.