com.h3c.util.ip

## Class MacPrefix

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

- All Implemented Interfaces:
    Serializable, Comparable<MacPrefix>

      public final class MacPrefix
      extends CacheableDataType
      implements Comparable<MacPrefix>

  Represents a MAC address prefix; that is to say, the top N bytes of the address are fixed (where N is 1 to 5) and the remaining bytes are unspecified.

  Instances of this class are created using the `valueOf(byte[])` factory methods.

  A string specification may be used to define the fixed bytes (with either colon or hyphen as the delimiter):

       {byte} [ : {byte} [ : ... ] ]    or    {byte} [ - {byte} [ - ... ] ]

  where byte represents a hex value in the range 00 to FF.

  For example, the specification `"FE:00:45"` declares a MAC prefix where the top 3 bytes are FE, 00, and 45, and the bottom three bytes may be any value.

  Another example, the specification `"FE-00-45-12-AB"` declares a MAC prefix where the top 5 bytes are FE, 00, 45, 12, and AB, and the bottom byte may be any value.

  Alternatively, a byte array may be used to specify the prefix. The byte arrays to produce the prefixes equivalent to the above examples are:

       final int B = 256; // makes it easier to read the declared byte arrays
       byte[] b1 = { 0xfe-B, 00, 0x45 };
       byte[] b2 = { 0xfe-B, 00, 0x45, 0x12, 0xab-B };

  See Also:
    Serialized Form

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compareTo(MacPrefix o)` Implements the Comparable interface, to return prefixes in natural order.
    `boolean` | `equals(Object o)`
    `int` | `hashCode()`
    `boolean` | `prefixes(MacAddress mac)` Returns true if this MAC prefix applies to the specified MAC address.
    `int` | `size()` Returns the number of bytes in this prefix.
    `String` | `toString()`
    `static MacPrefix` | `valueOf(byte[] prefixBytes)` Returns an object that represents the value of the MAC prefix defined by the specified MAC prefix bytes.
    `static MacPrefix` | `valueOf(String prefixStr)` Returns an object that represents the value of the MAC prefix 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`

- - ### Method Detail

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### compareTo

          public int compareTo(MacPrefix o)

      Implements the Comparable interface, to return prefixes in natural order.
      Specified by:
        `compareTo` in interface `Comparable<MacPrefix>`
      Parameters:
        `o` - the other MAC prefix
      Returns:
        an integer value indicating the relative ordering
      See Also:
        `Comparable.compareTo(T)`

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### size

          public int size()

      Returns the number of bytes in this prefix.
      Returns:
        the number of bytes in the prefix

    - #### prefixes

          public boolean prefixes(MacAddress mac)

      Returns true if this MAC prefix applies to the specified MAC address.
      Parameters:
        `mac` - the address to examine
      Returns:
        true if this is a prefix of the given MAC address

    - #### valueOf

          public static MacPrefix valueOf(byte[] prefixBytes)

      Returns an object that represents the value of the MAC prefix defined by the specified MAC prefix bytes. Note that the bytes are presumed to be in network byte order; that is, the highest order byte of the prefix is at index 0. The array length is expected to be 1 to 5. An exception is thrown if it is not.
      Parameters:
        `prefixBytes` - the prefix bytes
      Returns:
        a MacPrefix instance
      Throws:
        `NullPointerException` - if prefixBytes is null
        `IllegalArgumentException` - if prefixBytes is not an acceptable length

    - #### valueOf

          public static MacPrefix valueOf(String prefixStr)

      Returns an object that represents the value of the MAC prefix defined by the specified string. Both uppercase and lowercase hex digits are allowed. Acceptable input formats are:
      - "XX"
      - "XX:XX" or "XX-XX"
      - "XX:XX:XX" or "XX-XX-XX"
      - "XX:XX:XX:XX" or "XX-XX-XX-XX"
      - "XX:XX:XX:XX:XX" or "XX-XX-XX-XX-XX"
      where each "X" represents a hex digit
      Parameters:
        `prefixStr` - the string representation of the MAC prefix
      Returns:
        a MacPrefix instance
      Throws:
        `NullPointerException` - if prefixStr is null
        `IllegalArgumentException` - if prefixStr is not an acceptable format

Copyright © 2014. All Rights Reserved.