com.hp.of.lib.msg

Class MessageFactory

java.lang.Object

com.hp.of.lib.AbstractFactory

com.hp.of.lib.msg.MessageFactory

public class MessageFactory
extends AbstractFactory

Provides facilities for parsing, creating, copying and encoding OpenFlow messages.

Author:

Simon Hunt, Radhika Hegde

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	MessageFactory.TestReset Denotes things that can be reset, during unit tests.

Method Summary

Methods

Modifier and Type	Method and Description
static void	assignXid(MutableMessage msg) Assigns the next available transaction ID to the specified message.
static void	checkVersionSupported(ProtocolVersion pv) Throws an exception if the specified version is not supported by this OpenFlow message library.
static OpenflowMessage	copy(OpenflowMessage msg) Creates an immutable (deep) copy of the specified OpenFlow message.
static void	copyXid(OpenflowMessage src, MutableMessage dst) Copies the transaction ID from given source message to the specified destination message.
static MutableMessage	create(Message msg, MessageType type) Creates a mutable OpenFlow message of the specified type, with protocol version and transaction ID matching those of the given message.
static MutableMessage	create(Message msg, MessageType type, Enum<?> subtype) Creates a mutable OpenFlow message of the specified type and subtype, with protocol version and transaction ID matching those of the given message.
static MutableMessage	create(ProtocolVersion pv, MessageType type) Creates a mutable OpenFlow message of the specified type, with the specified protocol version, assigning it the next available transaction ID.
static MutableMessage	create(ProtocolVersion pv, MessageType type, Enum<?> subtype) Creates a mutable OpenFlow message of the specified type and subtype, with the specified protocol version, assigning it the next available transaction ID.
static OfmMutablePacketOut	createPacketOutFromPacketIn(OfmPacketIn pi) Creates a mutable packet-out message pre-populated with salient data from the given packet-in message.
static byte[]	encodeMessage(OpenflowMessage msg) Encodes the specified OpenFlow message, returning the result in a newly allocated byte array.
static void	encodeMessage(OpenflowMessage msg, ByteBuffer buffer) Encodes the specified OpenFlow message into the supplied byte buffer.
static OpenflowMessage	exactCopy(OpenflowMessage msg) Creates an immutable (deep) copy of the specified OpenFlow message.
static MutableMessage	exactMutableCopy(OpenflowMessage msg) Creates a mutable (deep) copy of the specified OpenFlow message.
static UnitTestSupport	getTestSupport() Returns a unit test support instance, to allow priviledged operations to be performed by test code.
static boolean	isStrictMessageParsing() Returns true if strict message parsing is in effect.
static boolean	isVersionSupported(ProtocolVersion pv) Returns true if the specified version is supported by this OpenFlow message library.
static MutableMessage	mutableCopy(OpenflowMessage msg) Creates a mutable (deep) copy of the specified OpenFlow message.
static OpenflowMessage	parseMessage(ByteBuffer buffer) Parses a single OpenFlow message from the supplied byte buffer consuming the bytes in the process.
static OpenflowMessage	parseMessage(OfPacketReader pkt) Parses the supplied packet reader as a single OpenFlow message.
static OpenflowMessage	parseMessage(OfPacketReader pkt, OpenflowMessage msg) Parses the supplied packet reader as a single OpenFlow message, but patches in the XID of the specified message.
static OfmFlowMod	patchFlowModPriority(OfmFlowMod flowMod, int newPriority) Patches the specified flow mod message with a new priority.
static void	setStrictMessageParsing(boolean strict) Sets message parsing to be either strict or non-strict.
static Set<ProtocolVersion>	supportedVersions() Returns the set of OpenFlow protocol versions that this library supports.
protected String	tag() Returns an identifying tag for the message factory.

Methods inherited from class com.hp.of.lib.AbstractFactory

mpe, mpe, mpe, mpe

Methods inherited from class java.lang.Object

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

Method Detail

tag

protected String tag()

Returns an identifying tag for the message factory.

Specified by:

tag in class AbstractFactory

Returns:

an identifying tag

supportedVersions

public static Set<ProtocolVersion> supportedVersions()

Returns the set of OpenFlow protocol versions that this library supports.

Returns:

the set of supported versions

checkVersionSupported

public static void checkVersionSupported(ProtocolVersion pv)

Throws an exception if the specified version is not supported by this OpenFlow message library.

Parameters:

pv - the protocol version to check

Throws:

VersionNotSupportedException - if the version is not supported

isVersionSupported

public static boolean isVersionSupported(ProtocolVersion pv)

Returns true if the specified version is supported by this OpenFlow message library.

Parameters:

pv - the protocol version to check

Returns:

true if supported; false otherwise

setStrictMessageParsing

public static void setStrictMessageParsing(boolean strict)

Sets message parsing to be either strict or non-strict.

In strict mode, the message parser will expect all non-spec-defined bits in bitmaps, and reserved fields, to be zero; if a 1-bit is found, an exception will be thrown.

In non-strict mode, the message parser will zero-out all non-spec-defined bits in bitmaps, and reserved fields, before parsing.

Parameters:

strict - true, for strict message parsing; false for non-strict

isStrictMessageParsing

public static boolean isStrictMessageParsing()

Returns true if strict message parsing is in effect.

Returns:

true if configured for strict message parsing

See Also:

setStrictMessageParsing(boolean)

parseMessage

public static OpenflowMessage parseMessage(ByteBuffer buffer)
                                    throws MessageParseException

Parses a single OpenFlow message from the supplied byte buffer consuming the bytes in the process.

Parameters:

buffer - byte buffer containing the message encoding

Returns:

an OpenFlow message

Throws:

NullPointerException - if buffer is null

MessageParseException - if a message cannot be parsed from the reader contents

parseMessage

public static OpenflowMessage parseMessage(OfPacketReader pkt)
                                    throws MessageParseException

Parses the supplied packet reader as a single OpenFlow message.

Parameters:

pkt - the packet reader

Returns:

an OpenFlow message

Throws:

NullPointerException - if pkt is null

MessageParseException - if a message cannot be parsed from the reader contents

parseMessage

public static OpenflowMessage parseMessage(OfPacketReader pkt,
                           OpenflowMessage msg)
                                    throws MessageParseException

Parses the supplied packet reader as a single OpenFlow message, but patches in the XID of the specified message. This method is provided to allow unit tests to read in "canned" message replies, but to patch the XID to match that of the supplied message, assumed to be the "request" to which we are generating the "reply".

Parameters:

pkt - the packet reader

msg - the (request) message from which to take the XID

Returns:

an OpenFlow message

Throws:

NullPointerException - if either parameter is null

MessageParseException - if a message cannot be parsed from the reader contents

create

public static MutableMessage create(ProtocolVersion pv,
                    MessageType type,
                    Enum<?> subtype)

Creates a mutable OpenFlow message of the specified type and subtype, with the specified protocol version, assigning it the next available transaction ID. Note that if the subtype is not appropriate for the given type, an exception will be thrown.

Parameters:

pv - the protocol version to set

type - the required message type

subtype - the required message subtype

Returns:

a mutable instance of the required message type

Throws:

NullPointerException - if any parameter is null

VersionNotSupportedException - if the required message cannot be created for the given version

create

public static MutableMessage create(ProtocolVersion pv,
                    MessageType type)

Creates a mutable OpenFlow message of the specified type, with the specified protocol version, assigning it the next available transaction ID.

Parameters:

pv - the protocol version to set

type - the required message type

Returns:

a mutable instance of the required message type

Throws:

NullPointerException - if either parameter is null

VersionNotSupportedException - if the required message cannot be created for the given version

create

public static MutableMessage create(Message msg,
                    MessageType type)

Creates a mutable OpenFlow message of the specified type, with protocol version and transaction ID matching those of the given message. This form is useful when formulating a response to a given OpenFlow message.

Parameters:

msg - the message from which to copy the protocol version and transaction id

type - the required message type

Returns:

a mutable instance of the required message type

Throws:

NullPointerException - if either parameter is null

VersionNotSupportedException - if the required message cannot be created for the given version

create

public static MutableMessage create(Message msg,
                    MessageType type,
                    Enum<?> subtype)

Creates a mutable OpenFlow message of the specified type and subtype, with protocol version and transaction ID matching those of the given message. This form is useful when formulating a response to a given OpenFlow message. Note that if the subtype is not appropriate for the given type, an exception will be thrown.

Parameters:

msg - the message from which to copy the protocol version and transaction id

type - the required message type

subtype - the required message subtype

Returns:

a mutable instance of the required message type

Throws:

NullPointerException - if either parameter is null

VersionNotSupportedException - if the required message cannot be created for the given version

createPacketOutFromPacketIn

public static OfmMutablePacketOut createPacketOutFromPacketIn(OfmPacketIn pi)

Creates a mutable packet-out message pre-populated with salient data from the given packet-in message.

Parameters:

pi - the source packet-in

Returns:

a mutable packet-out instance

Throws:

IllegalArgumentException - if the packet-in is mutable

patchFlowModPriority

public static OfmFlowMod patchFlowModPriority(OfmFlowMod flowMod,
                              int newPriority)

Patches the specified flow mod message with a new priority.

Parameters:

flowMod - flow mod message to be patched

newPriority - new priority to assign to the flow mod

Returns:

patched flow mod

assignXid

public static void assignXid(MutableMessage msg)

Assigns the next available transaction ID to the specified message. Note that transaction ID assignment is only available through this method, the copyXid(com.hp.of.lib.msg.OpenflowMessage, com.hp.of.lib.msg.MutableMessage) method, or implicitly through the create(com.hp.of.lib.ProtocolVersion, com.hp.of.lib.msg.MessageType, java.lang.Enum<?>) methods (which call this method).

Parameters:

msg - the mutable message to which the next transaction ID is to be assigned

Throws:

NullPointerException - if msg is null

InvalidMutableException - if the message is not writable

copyXid

public static void copyXid(OpenflowMessage src,
           MutableMessage dst)

Copies the transaction ID from given source message to the specified destination message.

Parameters:

src - the message whose XID should be copied

dst - the (mutable) message into which the XID should be copied

Throws:

NullPointerException - if either parameter is null

InvalidMutableException - if dst is not writable

copy

public static OpenflowMessage copy(OpenflowMessage msg)

Creates an immutable (deep) copy of the specified OpenFlow message. (Note that a new transaction ID will be assigned to the copy).

Parameters:

msg - the message to copy

Returns:

an immutable copy

exactCopy

public static OpenflowMessage exactCopy(OpenflowMessage msg)

Creates an immutable (deep) copy of the specified OpenFlow message. (Note that the transaction ID of the original message is retained in the copy).

Parameters:

msg - the message to copy

Returns:

an immutable copy

mutableCopy

public static MutableMessage mutableCopy(OpenflowMessage msg)

Creates a mutable (deep) copy of the specified OpenFlow message. (Note that a new transaction ID will be assigned to the copy).

Parameters:

msg - the message to copy

Returns:

a mutable copy

exactMutableCopy

public static MutableMessage exactMutableCopy(OpenflowMessage msg)

Creates a mutable (deep) copy of the specified OpenFlow message. (Note that the transaction ID of the original message is retained in the copy).

Parameters:

msg - the message to copy

Returns:

a mutable copy

encodeMessage

public static void encodeMessage(OpenflowMessage msg,
                 ByteBuffer buffer)
                          throws IncompleteMessageException,
                                 IncompleteStructureException

Encodes the specified OpenFlow message into the supplied byte buffer.

Parameters:

msg - the message to encode

buffer - byte buffer to receive message bytes

Throws:

IllegalArgumentException - if the message is mutable

IncompleteMessageException - if the message was insufficiently initialized

IncompleteStructureException - if any internal structure was insufficiently initialized

encodeMessage

public static byte[] encodeMessage(OpenflowMessage msg)
                            throws IncompleteMessageException,
                                   IncompleteStructureException

Encodes the specified OpenFlow message, returning the result in a newly allocated byte array.

Parameters:

msg - the message to encode

Returns:

the encoded message as a byte array

Throws:

IllegalArgumentException - if the message is mutable

IncompleteMessageException - if the message was insufficiently initialized

IncompleteStructureException - if any internal structure was insufficiently initialized

getTestSupport

public static UnitTestSupport getTestSupport()

Returns a unit test support instance, to allow priviledged operations to be performed by test code.

Returns:

the test support instance