com.h3c.of.lib

## Class OfpBitmapCodec<E extends OfpBitmapEnum>

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

- Type Parameters:
    `E` - type of the bitmap enumeration

      public class OfpBitmapCodec<E extends OfpBitmapEnum>
      extends AbstractBitCodec<E>

  Provides a default implementation of a 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 the enumeration class that implements the set of bit values.

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

  - FOO = `0x1`
  - GOO = `0x2`
  - ZOO = `0x4`
  where version 1.1 added another bit value:
  - BAR = `0x8`
  and version 1.3 removed GOO, but added BAZ:
  - BAZ = `0x10`
  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
               0x0f,   // 1.1
               0x0f,   // 1.2 (no change from 1.1)
               0x1d,   // 1.3
          };

  The enumeration class representing the field, should be written something like this:

       public enum FooBar implements OfpBitmapEnum {
           FOO(0x1),
           GOO(0x2),
           ZOO(0x4),
           BAR(0x8),
           BAZ(0x10),
           ;

           private int bit;

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

           private static final int[] MASKS = {
               0x07,   // 1.0
               0x0f,   // 1.1
               0x0f,   // 1.2 (no change from 1.1)
               0x1d,   // 1.3
           }

           @Override
           public int getBit(ProtocolVersion pv) {
               return bit;
           }

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

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

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

  A couple of things to note:
  - In the simple example above, the bit values for each constant remain the same across all versions, so the `pv` parameter is not used in the `getBit()` implementation. Sometimes, however, the bit value changes for the same flag; for example `PortFeature.COPPER` is encoded as `0x80` in version 1.0, and as `0x800` in versions 1.1, 1.2 and 1.3.
  - Most of the time, the flags to iterate across during decoding are precisely all the defined constants (i.e. the result of `values()`). But in a few cases, bits have been grouped together to represent mutually exclusive values; these bit positions should not be iterated over by the decoder, but handled separately. See `PortState` for an example of this.

- - ### Field Summary

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

      `flagSet, masks, NA_CODE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `OfpBitmapCodec(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

    - #### OfpBitmapCodec

          public OfpBitmapCodec(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

  - ### 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 OfpBitmapEnum>`
      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 OfpBitmapEnum>`
      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 OfpBitmapEnum>`
      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 OfpBitmapEnum>`
      Parameters:
        `flag` - the flag
        `pv` - the protocol version
      Returns:
        the corresponding bit

Copyright © 2014. All Rights Reserved.