com.h3c.util.ip

## Class MacRange

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

- All Implemented Interfaces:
    Serializable, Comparable<MacRange>

      public final class MacRange
      extends CacheableDataType
      implements Comparable<MacRange>

  Represents a range of MAC addresses. Instances of this class are created using the `valueOf(java.lang.String)` factory method.

  A string specification is used to define the MAC address range, using the form:

       {byteSpec}:{byteSpec}:{byteSpec}:{byteSpec}:{byteSpec}:{byteSpec}

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

       {nn} | {nn}-{mm} | *

  where nn and mm are hex values in the range 00 to FF, mm (when specified) is > nn, and * stands for 00-FF.

  For example, the specification `"FE:00:45:01:00-03:*"` declares that the range of MAC addresses starts with `FE:00:45:01:00:00` and ends with `FE:00:45:01:03:FF`.

  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(MacRange 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(MacAddress macAddress)` A predicate that returns `true` if this range contains the given item; false otherwise.
    `static List<MacRange>` | `createRanges(String commaSeparatedSpecs)` Returns a list of MAC ranges that embody the given range specifications.
    `boolean` | `equals(Object o)`
    `MacAddress` | `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.
    `int` | `hashCode()`
    `boolean` | `intersects(com.h3c.util.ip.AbstractRange<T> other)` Returns `true` if this range intersects the other range; false otherwise.
    `Iterator<MacAddress>` | `iterator()` Returns an iterator for the range.
    `MacAddress` | `last()` Returns the last item in the range.
    `MacAddress` | `random()` Returns a randomly generated item that falls within this range.
    `static String` | `rangeListToString(List<MacRange> ranges)` Converts a list of MAC 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 MacRange` | `valueOf(MacPrefix prefix)` Returns a MAC range for the given prefix.
    `static MacRange` | `valueOf(String spec)` Returns a MAC 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(MacAddress macAddress)

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

    - #### first

          public MacAddress first()

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

    - #### last

          public MacAddress last()

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

    - #### random

          public MacAddress random()

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

    - #### iterator

          public Iterator<MacAddress> 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(MacRange o)

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

    - #### valueOf

          public static MacRange valueOf(String spec)

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

    - #### valueOf

          public static MacRange valueOf(MacPrefix prefix)

      Returns a MAC range for the given prefix. The implicit lower bytes will be defined as '*'. For example,

               MacPrefix p = MacPrefix.valueOf("11:22:33:44");
               MacRange r = MacRange.valueOf(p);    // 11:22:33:44:*:*
               MacAddress low = MacRange.first();   // 11:22:33:44:00:00
               MacAddress high = MacRange.last();   // 11:22:33:44:FF:FF

      Parameters:
        `prefix` - the MAC prefix
      Returns:
        the equivalent MAC range

    - #### createRanges

          public static List<MacRange> createRanges(String commaSeparatedSpecs)

      Returns a list of MAC 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 MAC range instances

    - #### rangeListToString

          public static String rangeListToString(List<MacRange> ranges)

      Converts a list of MAC 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.