com.h3c.util.ip

## Class MacAddress

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

- All Implemented Interfaces:
    Serializable, Comparable<MacAddress>

      public final class MacAddress
      extends CacheableDataType
      implements Comparable<MacAddress>

  Represents a MAC address.

  All constructors for this class are private. Creating instances of `MacAddress` is done via the static methods on the class.

  Instances of this class are immutable, making them inherently threadsafe.

  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 of addresses is presented in an intuitive order.

  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `MacAddress.Format` Designates the different MAC address string formats available.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static MacAddress` | `BROADCAST` The broadcast address, that is ff:ff:ff:ff:ff:ff.
    `static int` | `MAC_ADDR_SIZE` Number of bytes for a MAC address.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `compareTo(MacAddress o)` Implements the Comparable interface, to return addresses in natural order.
    `boolean` | `equals(Object o)`
    `String` | `getEthernetCompany()` Returns the ethernet company name that this MAC address is associated with.
    `int` | `hashCode()`
    `void` | `intoBuffer(ByteBuffer b)` Writes the bytes that represent the MAC address directly into `ByteBuffer` at the buffer's current position.
    `boolean` | `isBroadcast()` Returns true if this is the broadcast address (FF:FF:FF:FF:FF:FF).
    `boolean` | `isMulticast()` Returns true if this is a multicast address.
    `byte[]` | `toByteArray()` Returns a newly allocated byte array containing bytes that represent the MAC address.
    `String` | `toFormattedString(MacAddress.Format fmt)` Returns a string representation of this MAC address, using the specified `MacAddress.Format`.
    `String` | `toFormattedString(MacAddress.Format fmt, boolean toLowerCase)` Returns a string representation of this MAC address, using the specified `MacAddress.Format`.
    `long` | `toLong()` Returns the MAC address represented as a long.
    `String` | `toString()` Returns a string representation of this MAC address in "XX:XX:XX:XX:XX:XX" form.
    `static MacAddress` | `valueFrom(ByteBuffer buffer)` Reads 6 bytes from the specified byte buffer and creates a MAC address entity.
    `static MacAddress` | `valueOf(byte[] macBytes)` Returns an object that represents the value of the MAC address defined by the specified address bytes.
    `static MacAddress` | `valueOf(long encodedAddress)` Returns an object that represents the value of the MAC address encoded by the specified long value.
    `static MacAddress` | `valueOf(String address)` Returns an object that represents the value of the MAC address 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`

- - ### Field Detail

    - #### MAC_ADDR_SIZE

          public static final int MAC_ADDR_SIZE

      Number of bytes for a MAC address.
      See Also:
        Constant Field Values

    - #### BROADCAST

          public static final MacAddress BROADCAST

      The broadcast address, that is ff:ff:ff:ff:ff:ff.

  - ### Method Detail

    - #### getEthernetCompany

          public String getEthernetCompany()

      Returns the ethernet company name that this MAC address is associated with. This is done by looking at the top 3 bytes of the address and returning the name of the company that has been assigned that byte pattern.

      A value of "(Unknown)" will be returned if no known mapping exists.

      Returns:
        the ethernet company name

    - #### toString

          public String toString()

      Returns a string representation of this MAC address in "XX:XX:XX:XX:XX:XX" form.

      This is the same result as invoking `macAddr.toFormattedString(MacAddress.Format.MULTI_COLON)`.

      Overrides:
        `toString` in class `Object`
      Returns:
        the MAC address as a string

    - #### toFormattedString

          public String toFormattedString(MacAddress.Format fmt)

      Returns a string representation of this MAC address, using the specified `MacAddress.Format`.
      - Format.MULTI_COLON => "XX:XX:XX:XX:XX:XX"
      - Format.MULTI_DASH => "XX-XX-XX-XX-XX-XX"
      - Format.SINGLE_COLON => "XXXXXX:XXXXXX"
      - Format.SINGLE_DASH => "XXXXXX-XXXXXX"
      - Format.NO_DELIMITER => "XXXXXXXXXXXX"
      where each "X" is a hex digit
      Parameters:
        `fmt` - the format to use
      Returns:
        the formatted address

    - #### toFormattedString

          public String toFormattedString(MacAddress.Format fmt,
                                 boolean toLowerCase)

      Returns a string representation of this MAC address, using the specified `MacAddress.Format`.
      - Format.MULTI_COLON => "XX:XX:XX:XX:XX:XX"
      - Format.MULTI_DASH => "XX-XX-XX-XX-XX-XX"
      - Format.SINGLE_COLON => "XXXXXX:XXXXXX"
      - Format.SINGLE_DASH => "XXXXXX-XXXXXX"
      - Format.NO_DELIMITER => "XXXXXXXXXXXX"
      where each "X" is a hex digit
      Parameters:
        `fmt` - the format to use
        `toLowerCase` - if true, hex digits will be lowercase
      Returns:
        the formatted address

    - #### isBroadcast

          public boolean isBroadcast()

      Returns true if this is the broadcast address (FF:FF:FF:FF:FF:FF).
      Returns:
        true if this is the broadcast address

    - #### isMulticast

          public boolean isMulticast()

      Returns true if this is a multicast address. That is, if the least significant bit of the most significant byte is 1.
      Returns:
        true if this is a multicast address

    - #### toByteArray

          public byte[] toByteArray()

      Returns a newly allocated byte array containing bytes that represent the MAC address. Note that the address bytes are in network byte order; that is, the highest order byte of the address is at index 0.
      Returns:
        a byte array representing the MAC address

    - #### intoBuffer

          public void intoBuffer(ByteBuffer b)

      Writes the bytes that represent the MAC address directly into `ByteBuffer` at the buffer's current position. Note that the address bytes are in network byte order; that is, the highest order byte of the address is at index 0.
      Parameters:
        `b` - the byte buffer to write into

    - #### toLong

          public long toLong()

      Returns the MAC address represented as a long.

      This method is provided to support the encoding of MAC addresses as long values.

      Returns:
        the MAC encoded as a long

    - #### equals

          public boolean equals(Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### compareTo

          public int compareTo(MacAddress o)

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

    - #### valueOf

          public static MacAddress valueOf(byte[] macBytes)

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

    - #### valueOf

          public static MacAddress valueOf(String address)

      Returns an object that represents the value of the MAC address defined by the specified string. Both uppercase and lowercase hex digits are allowed.

      Acceptable input formats are:

      - "XX:XX:XX:XX:XX:XX"
      - "XX-XX-XX-XX-XX-XX"
      - "XXXXXX:XXXXXX"
      - "XXXXXX-XXXXXX"
      - "XXXXXXXXXXXX"
      where each "X" represents a hex digit
      Parameters:
        `address` - the string representation of the MAC address
      Returns:
        a MacAddress instance
      Throws:
        `NullPointerException` - if address is null
        `IllegalArgumentException` - if address is not an acceptable format

    - #### valueOf

          public static MacAddress valueOf(long encodedAddress)

      Returns an object that represents the value of the MAC address encoded by the specified long value.
      Parameters:
        `encodedAddress` - the encoded MAC address
      Returns:
        a MacAddress instance
      Throws:
        `IllegalArgumentException` - if the specified long is not a valid encodement

    - #### valueFrom

          public static MacAddress valueFrom(ByteBuffer buffer)

      Reads 6 bytes from the specified byte buffer and creates a MAC address entity.
      Parameters:
        `buffer` - byte buffer from which to read the bytes
      Returns:
        a MacAddress instance
      Throws:
        `BufferUnderflowException` - if the buffer does not have 6 bytes remaining

Copyright © 2014. All Rights Reserved.