com.h3c.of.lib

## Class OfpCodeBasedCodec<E extends OfpCodeBasedEnum>

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

- Type Parameters:
    `E` - type of code-based enumeration

      public class OfpCodeBasedCodec<E extends OfpCodeBasedEnum>
      extends AbstractBitCodec<E>

  Provides an implementation of an integer based bitmap to enum-set coder/decoder (codec) which can handle differences across OpenFlow versions. This implementation is capable of handling a bit mask containing 32 bits.

  The type parameter <E> is an enumeration class that implements the set of code values, derived from `OfpCodeBasedEnum`. The code values for the constants described by the enumeration class must be greater than or equal to 0 and not exceed 31 for this codec to function correctly.

  The code associated with the enumeration constant is used to indicate the corresponding position in the encoded bitmap for that constant. A value of 1 in the bitmap in the position determined by the constant code indicates that the flag is present.

  For example, an enumeration constant has code value of 2. To determine if this constant is set in the bit map, a value of 1 is shifted left twice (1 << 2). If the bitmap has a 1 in this position, then the flag is present.

  Suppose you a have set of codes encoded as bits in a field; in OpenFlow version 1.0:

  - FOO = `0` (treated as 1 << 0)
  - GOO = `1` (treated as 1 << 1)
  - ZOO = `2` (treated as 1 << 2)
  where version 1.1 added another code:
  - BAR = `4` (treated as 1 << 4)
  and in version 1.3 removed GOO and added BAZ, BOP and BAM:
  - BAZ = `5` (treated as 1 << 5)
  - BOP = `6` (treated as 1 << 6)
  - BAM = `7` (treated as 1 << 7)
  Then the set of valid bit positions for the different versions of the protocol should be encoded in bit masks like this:

           private static final int[] MASKS = {
               0x07,    // 1.0  (0000 0111)
               0x17,    // 1.1  (0001 0111)
               0x17,    // 1.2  (0001 0111)
               0xf5,    // 1.3  (1111 0101)
           };

  The code-based enumeration class should be written something like this:

       public enum FooBar implements OfpCodeEnum {}
           FOO(0),
           GOO(1),
           ZOO(2),
           BAR(4),
           BAZ(5),
           BOP(6),
           BAM(7),
           ;

           private int code;

           FooBar(int code) {
               this.code = code;
           }

           private static final int[] MASKS = {
               0x07,    // 1.0
               0x17,    // 1.1
               0x17,    // 1.2
               0xf5,    // 1.3
           }

           @Override
           public int getCode(ProtocolVersion pv) {
               return code;
           }

           // secret decoder ring
           private static final OfpCodeBasedCodec<FooBar> CODEC =
               new OfpCodeBasedCodec<FooBar>(MASKS, values);

           // (javadocs go here)
           public static Set<FooBar> decodeFlags(int bitmap, ProtocolVersion pv) {
               return CODEC.decode(bitmap, pv);
           }

           // (javadocs go here)
           public static int encodeFlags(Set<FooBar> flags, ProtocolVersion pv) {
               return CODEC.encode(flags, pv);
           }

- - ### Field Summary

    - ### Fields inherited from class com.h3c.of.lib.AbstractBitCodec

      `flagSet, masks, NA_CODE`

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected 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.
    `protected String` | `formatValue(int value)` Returns the appropriate formatting of the value for an exception message.
    `protected 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 int` | `getValue(E flag, ProtocolVersion pv)` Returns the value (bit, or code) from the given flag, for the given version.

    - ### Methods inherited from class com.h3c.of.lib.AbstractBitCodec

      `decode, disposeStorage, encode, initStorage`

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

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

- - ### Constructor Detail

    - #### OfpCodeBasedCodec

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

      Constructs the codec, which squirrels away the bit masks and flag set for use during the `AbstractBitCodec.encode(java.util.Set<E>, com.h3c.of.lib.ProtocolVersion)` and `AbstractBitCodec.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

    - #### getValue

          protected int getValue(E flag,
                     ProtocolVersion pv)

      Description copied from class: `AbstractBitCodec`
      Returns the value (bit, or code) from the given flag, for the given version.
      Specified by:
        `getValue` in class `AbstractBitCodec<E extends OfpCodeBasedEnum>`
      Parameters:
        `flag` - the flag
        `pv` - the protocol version
      Returns:
        the bit value, or code value

    - #### cannotBeMapped

          protected boolean cannotBeMapped(int value)

      Description copied from class: `AbstractBitCodec`
      This test should return true if the given value (code, or bit) cannot be mapped into the bitmap; false if it is okay.
      Specified by:
        `cannotBeMapped` in class `AbstractBitCodec<E extends OfpCodeBasedEnum>`
      Parameters:
        `value` - the value to test
      Returns:
        true if unmappable; false otherwise

    - #### formatValue

          protected String formatValue(int value)

      Description copied from class: `AbstractBitCodec`
      Returns the appropriate formatting of the value for an exception message.
      Specified by:
        `formatValue` in class `AbstractBitCodec<E extends OfpCodeBasedEnum>`
      Parameters:
        `value` - the value
      Returns:
        the formatted value

    - #### getBitToMap

          protected int getBitToMap(E flag,
                        ProtocolVersion pv)

      Description copied from class: `AbstractBitCodec`
      Given a flag and a protocol version, this method should return the appropriate bit in the map that represents this flag.
      Specified by:
        `getBitToMap` in class `AbstractBitCodec<E extends OfpCodeBasedEnum>`
      Parameters:
        `flag` - the flag
        `pv` - the protocol version
      Returns:
        the corresponding bit

Copyright © 2014. All Rights Reserved.