com.hp.of.lib.instr

Class ActionFactory

java.lang.Object

com.hp.of.lib.AbstractFactory

com.hp.of.lib.instr.ActionFactory

public class ActionFactory
extends AbstractFactory

Provides facilities for parsing, creating and encoding Action instances.

Used by the InstructionFactory in its loftier goal of creating action-list-based instructions.

Author:

Simon Hunt

Method Summary

Methods

Modifier and Type	Method and Description
static Action	createAction(ProtocolVersion pv, ActionType type) Creates an action (header only, no payload), using the specified protocol version.
static Action	createAction(ProtocolVersion pv, ActionType type, BigPortNumber port) Creates an OUTPUT action.
static Action	createAction(ProtocolVersion pv, ActionType type, BigPortNumber port, int maxLen) Creates an OUTPUT action.
static Action	createAction(ProtocolVersion pv, ActionType type, EthernetType ethType) Creates an EthernetType-based action.
static Action	createAction(ProtocolVersion pv, ActionType type, ExperimenterId eid, byte[] data) Creates an EXPERIMENTER action.
static Action	createAction(ProtocolVersion pv, ActionType type, GroupId id) Creates a GROUP action.
static Action	createAction(ProtocolVersion pv, ActionType type, int ttl) Creates a TTL-based action.
static Action	createAction(ProtocolVersion pv, ActionType type, int id, byte[] data) Creates an EXPERIMENTER action.
static Action	createAction(ProtocolVersion pv, ActionType type, MFieldBasic mf) Creates a SET_FIELD action.
static Action	createAction(ProtocolVersion pv, ActionType type, QueueId id) Creates a SET_QUEUE action for version 1.1 onwards.
static Action	createAction(ProtocolVersion pv, ActionType type, QueueId id, BigPortNumber port) Creates a SET_QUEUE action (used to be named ENQUEUE) for version 1.0.
static List<Action>	createActionHeaders(ProtocolVersion pv, Set<ActionType> types) Creates action headers to be used in encoding a table features actions property.
static Action	createActionSetField(ProtocolVersion pv, OxmBasicFieldType ft, EthernetType ethType) Creates a set-field action for an ETH_TYPE match field, using the given protocol version.
static Action	createActionSetField(ProtocolVersion pv, OxmBasicFieldType ft, ICMPv4Type icmpv4Type) Creates a set-field action for an ICMPv4 Type match field, using the given protocol version.
static Action	createActionSetField(ProtocolVersion pv, OxmBasicFieldType ft, ICMPv6Type icmpv6Type) Creates a set-field action for an ICMPv6 Type match field, using the given protocol version.
static Action	createActionSetField(ProtocolVersion pv, OxmBasicFieldType ft, int value) Creates a set-field action for an int-payload-based match field, using the given protocol version.
static Action	createActionSetField(ProtocolVersion pv, OxmBasicFieldType ft, IpAddress ip) Creates a set-field action for an ip-address-based match field, using the given protocol version.
static Action	createActionSetField(ProtocolVersion pv, OxmBasicFieldType ft, IpProtocol ipp) Creates a set-field action for an IP Protocol match field, using the given protocol version.
static Action	createActionSetField(ProtocolVersion pv, OxmBasicFieldType ft, long value) Creates a set-field action for a long-payload-based match field, using the given protocol version.
static Action	createActionSetField(ProtocolVersion pv, OxmBasicFieldType ft, MacAddress mac) Creates a set-field action for a mac-address-based match field, using the given protocol version.
static Action	createActionSetField(ProtocolVersion pv, OxmBasicFieldType ft, Map<IPv6ExtHdr,Boolean> flags) Creates a set-field action for an IPv6 Extension Header match field, using the given protocol version.
static Action	createActionSetField(ProtocolVersion pv, OxmBasicFieldType ft, PortNumber port) Creates a set-field action for a port-number-based match field, using the given protocol version.
static Action	createActionSetField(ProtocolVersion pv, OxmBasicFieldType ft, VlanId vlanId) Creates a set-field action for a VLAN_VID, using the given protocol version.
static void	encodeAction(Action act, OfPacketWriter pkt) Encodes an action, writing it into the supplied buffer.
static void	encodeActionExperList(List<ActExperimenter> acts, OfPacketWriter pkt) Encodes a list of experimenter actions, writing them into the supplied buffer.
static void	encodeActionList(List<Action> acts, OfPacketWriter pkt) Encodes a list of actions, writing them into the supplied buffer.
static Action	parseAction(OfPacketReader pkt, ProtocolVersion pv) Parses a single action from the supplied buffer.
static List<Action>	parseActionHeaders(int targetRi, OfPacketReader pkt, ProtocolVersion pv) Parses a list of action header structures from the supplied buffer.
static List<Action>	parseActionList(int targetRi, OfPacketReader pkt, ProtocolVersion pv) Parses a list of action structures from the supplied buffer.
protected String	tag() Returns an identifying tag for the action factory.
static String	toDebugString(int indent, List<Action> acts) Outputs a list of actions in debug string format.
static void	validateAction(ProtocolVersion pv, Action act, String msgType) Ensures that the specified action is appropriate to add to a message of the specified version.

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 action factory.

Specified by:

tag in class AbstractFactory

Returns:

an identifying tag

parseAction

public static Action parseAction(OfPacketReader pkt,
                 ProtocolVersion pv)
                          throws MessageParseException

Parses a single action from the supplied buffer. Note that this method causes the reader index of the underlying PacketBuffer to be advanced by the length of the action.

Parameters:

pkt - the data buffer

pv - the protocol version

Returns:

a parsed action

Throws:

MessageParseException - if unable to parse the action

parseActionList

public static List<Action> parseActionList(int targetRi,
                           OfPacketReader pkt,
                           ProtocolVersion pv)
                                    throws MessageParseException

Parses a list of action structures from the supplied buffer. The caller must calculate and specify the target reader index of the buffer that marks the end of the list, so we know when to stop.

Note that this method causes the reader index of the underlying PacketBuffer to be advanced by the length of the list, which should leave the reader index at targetRi.

Parameters:

targetRi - the target reader index

pkt - the data buffer

pv - the protocol version

Returns:

a list of parsed actions

Throws:

MessageParseException - if unable to parse the structure

parseActionHeaders

public static List<Action> parseActionHeaders(int targetRi,
                              OfPacketReader pkt,
                              ProtocolVersion pv)
                                       throws MessageParseException

Parses a list of action header structures from the supplied buffer. This method is provided to support the parsing of an "action" table feature property. The list returned contains either ActHeader instances or ActExperimenter instances.

Parameters:

targetRi - the target reader index

pkt - the data buffer

pv - the protocol version

Returns:

a list of parsed actions (header info only)

Throws:

MessageParseException - if there is an issue parsing the structure

See Also:

TableFeatureFactory, TableFeaturePropAction

createAction

public static Action createAction(ProtocolVersion pv,
                  ActionType type)

Creates an action (header only, no payload), using the specified protocol version.

Parameters:

pv - the protocol version

type - the type of action

Returns:

the action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if type is inappropriate

createAction

public static Action createAction(ProtocolVersion pv,
                  ActionType type,
                  MFieldBasic mf)

Creates a SET_FIELD action.

The supplied match field should be a basic match field with its type identifying the field to set, and its value denoting the value to set. There must be no mask included.

Additional note: The match of the flow entry must contain the OXM prerequisite corresponding to the field to be set, otherwise an error will be generated.

The type of the set-field action can be any valid OXM header type. Set-field actions for types IN_PORT, IN_PHY_PORT, and METADATA are not supported, because those are not header fields.

The set-field actions overwrite the header field specified by the OXM type, and perform the necessary CRC recalculation based on the header field. The OXM fields refer to the outermost-possible occurrence in the header, unless the field type explicitly specifies otherwise, and therefore in general the set-field actions apply to the outermost-possible header (e.g. a "Set VLAN ID" set-field action always sets the ID of the outermost VLAN tag).

Parameters:

pv - the protocol version

type - the action type (SET_FIELD)

mf - the match field

Returns:

the action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if type is not SET_FIELD, or if mf is inappropriate

See Also:

FieldFactory

createAction

public static Action createAction(ProtocolVersion pv,
                  ActionType type,
                  BigPortNumber port,
                  int maxLen)

Creates an OUTPUT action.

When port is Port.CONTROLLER (i.e. the action is to output the packet to the controller), maxLen indicates the maximum number of bytes of the frame (from 0 to CONTROLLER_MAX) to send to the controller:

• 0 : no bytes should be sent
• 1 .. ActOutput.CONTROLLER_MAX : at most, send this number of bytes
• ActOutput.CONTROLLER_NO_BUFFER : the complete packet is to be sent

When port is not Port.CONTROLLER, the maxLen value should be ignored (since the only reasonable action is to send all the bytes of the packet), but this method will allow a value of either 0 or ActOutput.CONTROLLER_NO_BUFFER to be set.

The degenerate form of this method invokes this method with maxLen equal to 0.

Note that in 1.0, port numbers are u16.

Parameters:

pv - the protocol version

type - the action type (OUTPUT)

port - output port

maxLen - max length to send to the controller

Returns:

the action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if type is not OUTPUT, or if maxLen is out of bounds, or if the port number is invalid

createAction

public static Action createAction(ProtocolVersion pv,
                  ActionType type,
                  BigPortNumber port)

Creates an OUTPUT action.

If the required output port is Port.CONTROLLER, use createAction(ProtocolVersion, ActionType, BigPortNumber, int) instead.

Parameters:

pv - the protocol version

type - the action type (OUTPUT)

port - output port

Returns:

the action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if type is not OUTPUT, or if port is CONTROLLER

createAction

public static Action createAction(ProtocolVersion pv,
                  ActionType type,
                  GroupId id)

Creates a GROUP action.

Parameters:

pv - the protocol version

type - the action type (GROUP)

id - the group id

Returns:

the action

Throws:

VersionNotSupportedException - if the version is not supported

VersionMismatchException - if the version is < 1.1

NullPointerException - if any required parameter is null

IllegalArgumentException - if type is not GROUP

createAction

public static Action createAction(ProtocolVersion pv,
                  ActionType type,
                  QueueId id)

Creates a SET_QUEUE action for version 1.1 onwards.

Parameters:

pv - the protocol version

type - the action type (SET_QUEUE)

id - the queue id

Returns:

the action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if type is not SET_QUEUE

createAction

public static Action createAction(ProtocolVersion pv,
                  ActionType type,
                  QueueId id,
                  BigPortNumber port)

Creates a SET_QUEUE action (used to be named ENQUEUE) for version 1.0.

The specified port is the port to which the queue belongs. It should refer to a valid physical port; that is less than MAX (defined as 0xff00 in 1.0) or equal to Port.IN_PORT.

Note that in 1.0, port numbers are u16.

Parameters:

pv - the protocol version

type - the action type (SET_QUEUE)

id - the queue id

port - the port to which the queue belongs

Returns:

the action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if type is not SET_QUEUE, or if the port number is invalid

createAction

public static Action createAction(ProtocolVersion pv,
                  ActionType type,
                  int ttl)

Creates a TTL-based action.

Parameters:

pv - the protocol version

type - the action type (SET_MPLS_TTL or SET_NW_TTL)

ttl - the TTL value (u8)

Returns:

the action

Throws:

VersionNotSupportedException - if the version is not supported

VersionMismatchException - if the version is < 1.1

NullPointerException - if any required parameter is null

IllegalArgumentException - if type is inappropriate or ttl is out of bounds

createAction

public static Action createAction(ProtocolVersion pv,
                  ActionType type,
                  EthernetType ethType)

Creates an EthernetType-based action. This corresponds to the PUSH_VLAN, PUSH_MPLS, PUSH_PBB, and POP_MPLS actions. Note that the acceptable values for EthernetType are:

• PUSH_VLAN can be VLAN(0x8100) or PRV_BRDG(0x88a8)
• PUSH_MPLS can be MPLS_U(0x8847) or MPLS_M(0x8848)
• PUSH_PBB can be PBB(0x88e7)

Parameters:

pv - the protocol version

type - the action type

ethType - the EthernetType of the tag to be pushed/popped

Returns:

the action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if the ethernet type is not appropriate

createAction

public static Action createAction(ProtocolVersion pv,
                  ActionType type,
                  int id,
                  byte[] data)

Creates an EXPERIMENTER action. Note that the experimenter-defined data must be an array whose length pads the whole action out to a 64-bit boundary. Given the 4-byte header and 4-byte experimenter id, this means that the array must be exactly 0, 8, 16, 24, ... bytes in length; that is, n*8 bytes, where n is 0, 1, 2, 3, ...

Parameters:

pv - the protocol version

type - the action type (EXPERIMENTER)

id - the experimenter encoded ID

data - experimenter-defined data

Returns:

the action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if data is of an unsupported length

createAction

public static Action createAction(ProtocolVersion pv,
                  ActionType type,
                  ExperimenterId eid,
                  byte[] data)

Creates an EXPERIMENTER action. Note that the experimenter-defined data must be an array whose length pads the whole action out to a 64-bit boundary. Given the 4-byte header and 4-byte experimenter ID, this means that the array length must be a multiple of 8.

Parameters:

pv - the protocol version

type - the action type (EXPERIMENTER)

eid - the experimenter ID

data - experimenter-defined data

Returns:

the action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if data is of an unsupported length

createActionSetField

public static Action createActionSetField(ProtocolVersion pv,
                          OxmBasicFieldType ft,
                          MacAddress mac)

Creates a set-field action for a mac-address-based match field, using the given protocol version.

Parameters:

pv - the protocol version

ft - the field type

mac - the MAC address

Returns:

the set-field action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if field type is not appropriate

createActionSetField

public static Action createActionSetField(ProtocolVersion pv,
                          OxmBasicFieldType ft,
                          IpAddress ip)

Creates a set-field action for an ip-address-based match field, using the given protocol version.

Parameters:

pv - the protocol version

ft - the field type

ip - the IP address

Returns:

the set-field action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if field type is not appropriate or IP address family is not appropriate

createActionSetField

public static Action createActionSetField(ProtocolVersion pv,
                          OxmBasicFieldType ft,
                          PortNumber port)

Creates a set-field action for a port-number-based match field, using the given protocol version.

Parameters:

pv - the protocol version

ft - the field type

port - the port number

Returns:

the set-field action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if field type is not appropriate

createActionSetField

public static Action createActionSetField(ProtocolVersion pv,
                          OxmBasicFieldType ft,
                          ICMPv4Type icmpv4Type)

Creates a set-field action for an ICMPv4 Type match field, using the given protocol version.

Parameters:

pv - the protocol version

ft - the field type (ICMPV4_TYPE)

icmpv4Type - the ICMPv4 Type

Returns:

the set-field action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if field type is not appropriate

createActionSetField

public static Action createActionSetField(ProtocolVersion pv,
                          OxmBasicFieldType ft,
                          ICMPv6Type icmpv6Type)

Creates a set-field action for an ICMPv6 Type match field, using the given protocol version.

Parameters:

pv - the protocol version

ft - the field type (ICMPV6_TYPE)

icmpv6Type - the ICMPv6 Type

Returns:

the set-field action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if field type is not appropriate

createActionSetField

public static Action createActionSetField(ProtocolVersion pv,
                          OxmBasicFieldType ft,
                          int value)

Creates a set-field action for an int-payload-based match field, using the given protocol version.

Parameters:

pv - the protocol version

ft - the field type

value - the value

Returns:

the set-field action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if field type is not appropriate or the value is not appropriate

createActionSetField

public static Action createActionSetField(ProtocolVersion pv,
                          OxmBasicFieldType ft,
                          EthernetType ethType)

Creates a set-field action for an ETH_TYPE match field, using the given protocol version.

Parameters:

pv - the protocol version

ft - the field type

ethType - the Ethernet Type

Returns:

the set-field action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if field type is not appropriate

createActionSetField

public static Action createActionSetField(ProtocolVersion pv,
                          OxmBasicFieldType ft,
                          VlanId vlanId)

Creates a set-field action for a VLAN_VID, using the given protocol version.

Parameters:

pv - the protocol version

ft - the field type (VLAN_VID)

vlanId - the VLAN vid to match

Returns:

the set-field action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if field type is not appropriate

createActionSetField

public static Action createActionSetField(ProtocolVersion pv,
                          OxmBasicFieldType ft,
                          IpProtocol ipp)

Creates a set-field action for an IP Protocol match field, using the given protocol version.

Parameters:

pv - the protocol version

ft - the field type (IP_PROTO)

ipp - the IP protocol

Returns:

the set-field action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if field type is not appropriate

createActionSetField

public static Action createActionSetField(ProtocolVersion pv,
                          OxmBasicFieldType ft,
                          long value)

Creates a set-field action for a long-payload-based match field, using the given protocol version.

Parameters:

pv - the protocol version

ft - the field type

value - the value

Returns:

the set-field action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if field type is not appropriate or the value is not appropriate

createActionSetField

public static Action createActionSetField(ProtocolVersion pv,
                          OxmBasicFieldType ft,
                          Map<IPv6ExtHdr,Boolean> flags)

Creates a set-field action for an IPv6 Extension Header match field, using the given protocol version.

Parameters:

pv - the protocol version

ft - the field type (IPV6_EXTHDR)

flags - the IPv6 Extension Header flags

Returns:

the set-field action

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

IllegalArgumentException - if field type is not appropriate

createActionHeaders

public static List<Action> createActionHeaders(ProtocolVersion pv,
                               Set<ActionType> types)

Creates action headers to be used in encoding a table features actions property.

Parameters:

pv - the protocol version

types - the types of headers to create

Returns:

the list of headers

Throws:

VersionNotSupportedException - if the version is not supported

NullPointerException - if any required parameter is null

encodeAction

public static void encodeAction(Action act,
                OfPacketWriter pkt)

Encodes an action, writing it into the supplied buffer. Note that this method causes the writer index of the underlying PacketBuffer to be advanced by the length of the action.

Parameters:

act - the action

pkt - the buffer into which the action is to be written

encodeActionList

public static void encodeActionList(List<Action> acts,
                    OfPacketWriter pkt)

Encodes a list of actions, writing them into the supplied buffer. Note that this method causes the writer index of the underlying PacketBuffer to be advanced by the length of the written actions.

Parameters:

acts - the list of actions

pkt - the buffer into which the actions are to be written

encodeActionExperList

public static void encodeActionExperList(List<ActExperimenter> acts,
                         OfPacketWriter pkt)

Encodes a list of experimenter actions, writing them into the supplied buffer. Note that this method causes the writer index of the underlying PacketBuffer to be advanced by the length of the written actions.

Parameters:

acts - the list of actions

pkt - the buffer into which the actions are to be written

toDebugString

public static String toDebugString(int indent,
                   List<Action> acts)

Outputs a list of actions in debug string format.

Parameters:

indent - the additional indent (number of spaces)

acts - the list of actions

Returns:

a multi-line string representation of the list of actions

validateAction

public static void validateAction(ProtocolVersion pv,
                  Action act,
                  String msgType)

Ensures that the specified action is appropriate to add to a message of the specified version. If all is well, silently returns. If not, throws an exception.

Parameters:

pv - the protocol version

act - the action to validate

msgType - the message type (label)

Throws:

IllegalArgumentException - if the action is invalid