com.h3c.of.lib.instr

## Class ActionFactory

- java.lang.Object
- - com.h3c.of.lib.AbstractFactory
  - - com.h3c.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.

- - ### 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, VId vid)` 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.h3c.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,
                                    VId vid)

      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)
        `vid` - 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 or the value 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

Copyright © 2014. All Rights Reserved.