com.hp.of.lib

Class AbstractBitCodec<E extends OfpEnum>

java.lang.Object

com.hp.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.

Author:

Simon Hunt

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.hp.of.lib.ProtocolVersion) and decode(int, com.hp.of.lib.ProtocolVersion) methods.

Method Summary

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.hp.of.lib.ProtocolVersion) and decode(int, com.hp.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