com.h3c.of.lib

## Class AbstractBitCodec<E extends OfpEnum>

- java.lang.Object
- - com.h3c.of.lib.AbstractBitCodec<E>

- Type Parameters:
    `E` - type of enumeration
  Direct Known Subclasses:
    OfpBitmapCodec, OfpCodeBasedCodec

      public abstract class AbstractBitCodec<E extends OfpEnum>
      extends Object

  Provides a common base for the two bitmap codec classes.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected E[]` | `flagSet` The union of all flags that can be bitmapped, across all versions.
    `protected int[]` | `masks` Bit masks indicating valid bit placements for each protocol version.
    `protected static int` | `NA_CODE` The value used to indicate that a flag is not applicable (for a given protocol version.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractBitCodec(int[] masks, E[] flagSet)` Constructs the codec, which squirrels away the bit masks and flag set for use during the `encode(java.util.Set<E>, com.h3c.of.lib.ProtocolVersion)` and `decode(int, com.h3c.of.lib.ProtocolVersion)` methods.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract boolean` | `cannotBeMapped(int value)` This test should return true if the given value (code, or bit) cannot be mapped into the bitmap; false if it is okay.
    `Set<E>` | `decode(int bitmap, ProtocolVersion pv)` Decodes the given int value into a set of flags from the enumeration class associated with this codec instance.
    `protected void` | `disposeStorage()` Gives subclasses an opportunity to prepare temporary storage for garbage collection.
    `int` | `encode(Set<E> flags, ProtocolVersion pv)` Encodes the given set of flags into a bitmap represented by an integer value.
    `protected abstract String` | `formatValue(int value)` Returns the appropriate formatting of the value for an exception message.
    `protected abstract int` | `getBitToMap(E flag, ProtocolVersion pv)` Given a flag and a protocol version, this method should return the appropriate bit in the map that represents this flag.
    `protected abstract int` | `getValue(E flag, ProtocolVersion pv)` Returns the value (bit, or code) from the given flag, for the given version.
    `protected void` | `initStorage()` Gives subclasses an opportunity to initialize temporary storage before validation of the flag set.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### NA_CODE

          protected static final int NA_CODE

      The value used to indicate that a flag is not applicable (for a given protocol version.
      See Also:
        Constant Field Values

    - #### masks

          protected final int[] masks

      Bit masks indicating valid bit placements for each protocol version.

    - #### flagSet

          protected final E extends OfpEnum[] flagSet

      The union of all flags that can be bitmapped, across all versions.

  - ### Constructor Detail

    - #### AbstractBitCodec

          public AbstractBitCodec(int[] masks,
                          E[] flagSet)

      Constructs the codec, which squirrels away the bit masks and flag set for use during the `encode(java.util.Set<E>, com.h3c.of.lib.ProtocolVersion)` and `decode(int, com.h3c.of.lib.ProtocolVersion)` methods. Note that, most of the time, the flag set should be `EnumClass.values()`.
      Parameters:
        `masks` - the "valid bit position" masks; one for each protocol version
        `flagSet` - the set of flags to iterate over during decode
      Throws:
        `NullPointerException` - if either parameter is null
        `IllegalArgumentException` - if masks does not include a mask for every protocol version or flagSet is not valid for this codec

  - ### Method Detail

    - #### initStorage

          protected void initStorage()

      Gives subclasses an opportunity to initialize temporary storage before validation of the flag set. This default implementation does nothing.

    - #### disposeStorage

          protected void disposeStorage()

      Gives subclasses an opportunity to prepare temporary storage for garbage collection. This default implmentation does nothing.

    - #### getValue

          protected abstract int getValue(E flag,
                     ProtocolVersion pv)

      Returns the value (bit, or code) from the given flag, for the given version.
      Parameters:
        `flag` - the flag
        `pv` - the protocol version
      Returns:
        the bit value, or code value

    - #### cannotBeMapped

          protected abstract boolean cannotBeMapped(int value)

      This test should return true if the given value (code, or bit) cannot be mapped into the bitmap; false if it is okay.
      Parameters:
        `value` - the value to test
      Returns:
        true if unmappable; false otherwise

    - #### formatValue

          protected abstract String formatValue(int value)

      Returns the appropriate formatting of the value for an exception message.
      Parameters:
        `value` - the value
      Returns:
        the formatted value

    - #### decode

          public Set<E> decode(int bitmap,
                      ProtocolVersion pv)

      Decodes the given int value into a set of flags from the enumeration class associated with this codec instance. If the message library has been configured for `strict parsing`, an exception will be thrown if a 1-bit is discovered in an invalid position. If non-strict parsing is in effect, such invalid bits will be ignored silently.
      Parameters:
        `bitmap` - the encoded bitmap
        `pv` - the protocol version
      Returns:
        a set of flags corresponding to set bit positions in the bitmap
      Throws:
        `NullPointerException` - if pv is null
        `VersionMismatchException` - if a bit position is not supported in the given version, and strict parsing is enabled

    - #### getBitToMap

          protected abstract int getBitToMap(E flag,
                        ProtocolVersion pv)

      Given a flag and a protocol version, this method should return the appropriate bit in the map that represents this flag.
      Parameters:
        `flag` - the flag
        `pv` - the protocol version
      Returns:
        the corresponding bit

    - #### encode

          public int encode(Set<E> flags,
                   ProtocolVersion pv)

      Encodes the given set of flags into a bitmap represented by an integer value. The `flags` parameter may be empty or null, in which case a bitmap of 0 (zero) is returned.
      Parameters:
        `flags` - the set of flags to be encoded
        `pv` - the protocol version
      Returns:
        a bitmap corresponding to the given set of flags
      Throws:
        `NullPointerException` - if protocol version is null
        `VersionMismatchException` - if a flag is present that is not supported in the given protocol version
        `IllegalArgumentException` - if a flag is present that cannot be mapped into the bitmap

Copyright © 2014. All Rights Reserved.