com.h3c.of.lib.instr

## Class InstructionFactory

- java.lang.Object
- - com.h3c.of.lib.AbstractFactory
  - - com.h3c.of.lib.instr.InstructionFactory

-     public class InstructionFactory
      extends AbstractFactory

  Provides facilities for parsing, creating and encoding `Instruction` instances.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Instruction` | `createInstruction(ProtocolVersion pv, InstructionType type)` Creates a CLEAR_ACTIONS instruction.
    `static Instruction` | `createInstruction(ProtocolVersion pv, InstructionType type, ExperimenterId eid, byte[] data)` Creates an EXPERIMENTER instruction.
    `static Instruction` | `createInstruction(ProtocolVersion pv, InstructionType type, int id, byte[] data)` Creates an EXPERIMENTER instruction.
    `static Instruction` | `createInstruction(ProtocolVersion pv, InstructionType type, long metadata, long mask)` Creates a WRITE_METADATA instruction.
    `static Instruction` | `createInstruction(ProtocolVersion pv, InstructionType type, MeterId mid)` Creates a METER instruction.
    `static Instruction` | `createInstruction(ProtocolVersion pv, InstructionType type, TableId tid)` Creates a GOTO_TABLE instruction.
    `static List<Instruction>` | `createInstructionHeaders(ProtocolVersion pv, Set<InstructionType> types)` Creates instruction headers to be used in encoding a table features instructions property.
    `static InstrMutableAction` | `createMutableInstruction(ProtocolVersion pv, InstructionType type)` Creates a mutable (action-based) instruction.
    `static void` | `encodeInstrExperList(List<InstrExperimenter> instrs, OfPacketWriter pkt)` Encodes a list of experimenter instructions, writing them into the supplied buffer.
    `static void` | `encodeInstruction(Instruction ins, OfPacketWriter pkt)` Encodes an instruction, writing it into the supplied buffer.
    `static void` | `encodeInstructionList(List<Instruction> instrs, OfPacketWriter pkt)` Encodes a list of instructions, writing them into the supplied buffer.
    `static Instruction` | `parseInstruction(OfPacketReader pkt, ProtocolVersion pv)` Parses an Instruction structure from the supplied buffer.
    `static List<Instruction>` | `parseInstructionHeaders(int targetRi, OfPacketReader pkt, ProtocolVersion pv)` Parses a list of instruction header structures from the supplied buffer.
    `static List<Instruction>` | `parseInstructionList(int targetRi, OfPacketReader pkt, ProtocolVersion pv)` Parses a list of instruction structures from the supplied buffer.
    `protected String` | `tag()` Returns an identifying tag for the instruction factory.
    `static String` | `toDebugString(int indent, List<Instruction> ins)` Outputs a list of instructions in debug string format.
    `static void` | `validateInstruction(ProtocolVersion pv, Instruction ins, String msgType)` Ensures that the specified instruction 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 instruction factory.
      Specified by:
        `tag` in class `AbstractFactory`
      Returns:
        an identifying tag

    - #### parseInstructionList

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

      Parses a list of instruction 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 instructions
      Throws:
        `MessageParseException` - if unable to parse the structure

    - #### parseInstruction

          public static Instruction parseInstruction(OfPacketReader pkt,
                                     ProtocolVersion pv)
                                              throws MessageParseException

      Parses an Instruction structure from the supplied buffer. Note that this method causes the reader index of the underlying `PacketBuffer` to be advanced by the length of the structure. Also note that this method resets and uses the buffer's odometer, to verify that the total number of bytes parsed is divisible by 8.
      Parameters:
        `pkt` - the data buffer
        `pv` - the protocol version
      Returns:
        a parsed instruction structure
      Throws:
        `MessageParseException` - if unable to parse the structure

    - #### parseInstructionHeaders

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

      Parses a list of instruction header structures from the supplied buffer. This method is provided to support the parsing of an "instruction" table feature property. The list returned contains either `InstrHeader` instances or `InstrExperimenter` instances.
      Parameters:
        `targetRi` - the target reader index
        `pkt` - the data buffer
        `pv` - the protocol version
      Returns:
        a list of parsed instructions (header info only)
      Throws:
        `MessageParseException` - if unable to parse the structure
      See Also:
        `TableFeatureFactory`, `TableFeaturePropInstr`

    - #### createInstruction

          public static Instruction createInstruction(ProtocolVersion pv,
                                      InstructionType type,
                                      TableId tid)

      Creates a GOTO_TABLE instruction.
      Parameters:
        `pv` - the protocol version
        `type` - the instruction type (GOTO_TABLE)
        `tid` - the table id
      Returns:
        the instruction
      Throws:
        `VersionNotSupportedException` - if the version is not supported
        `NullPointerException` - if any required parameter is null
        `IllegalArgumentException` - if type is not GOTO_TABLE

    - #### createInstruction

          public static Instruction createInstruction(ProtocolVersion pv,
                                      InstructionType type,
                                      long metadata,
                                      long mask)

      Creates a WRITE_METADATA instruction.
      Parameters:
        `pv` - the protocol version
        `type` - the instruction type (WRITE_METADATA)
        `metadata` - the metadata
        `mask` - the metadata mask
      Returns:
        the instruction
      Throws:
        `VersionNotSupportedException` - if the version is not supported
        `NullPointerException` - if any required parameter is null
        `IllegalArgumentException` - if type is not WRITE_METADATA

    - #### createMutableInstruction

          public static InstrMutableAction createMutableInstruction(ProtocolVersion pv,
                                                    InstructionType type)

      Creates a mutable (action-based) instruction.
      Parameters:
        `pv` - the protocol version
        `type` - the instruction type (WRITE_ACTIONS, APPLY_ACTIONS)
      Returns:
        the instruction
      Throws:
        `VersionNotSupportedException` - if the version is not supported
        `NullPointerException` - if any required parameter is null
        `IllegalArgumentException` - if type is not WRITE_ACTIONS or APPLY_ACTIONS

    - #### createInstruction

          public static Instruction createInstruction(ProtocolVersion pv,
                                      InstructionType type)

      Creates a CLEAR_ACTIONS instruction.

      Note, use `createMutableInstruction(com.h3c.of.lib.ProtocolVersion, com.h3c.of.lib.instr.InstructionType)` for `WRITE_ACTIONS` or `APPLY_ACTIONS`.

      Parameters:
        `pv` - the protocol version
        `type` - the instruction type (CLEAR_ACTIONS)
      Returns:
        the instruction
      Throws:
        `VersionNotSupportedException` - if the version is not supported
        `NullPointerException` - if any required parameter is null
        `IllegalArgumentException` - if type is not CLEAR_ACTIONS

    - #### createInstruction

          public static Instruction createInstruction(ProtocolVersion pv,
                                      InstructionType type,
                                      MeterId mid)

      Creates a METER instruction.
      Parameters:
        `pv` - the protocol version
        `type` - the instruction type (METER)
        `mid` - the meter id
      Returns:
        the instruction
      Throws:
        `VersionNotSupportedException` - if the version is not supported
        `NullPointerException` - if any required parameter is null
        `IllegalArgumentException` - if type is not METER

    - #### createInstruction

          public static Instruction createInstruction(ProtocolVersion pv,
                                      InstructionType type,
                                      int id,
                                      byte[] data)

      Creates an EXPERIMENTER instruction. Note that the experimenter-defined data must be an array whose length pads the whole instruction out to a 64-bit boundary. Given the 4-byte header and the 4-byte experimenter ID, this means that the array length must be a multiple of 8.
      Parameters:
        `pv` - the protocol version
        `type` - the instruction type (EXPERIMENTER)
        `id` - the experimenter encoded ID
        `data` - experimenter-defined data
      Returns:
        the instruction
      Throws:
        `VersionNotSupportedException` - if the version is not supported
        `NullPointerException` - if any required parameter is null
        `IllegalArgumentException` - if type is not EXPERIMENTER or if data array is an unsupported length

    - #### createInstruction

          public static Instruction createInstruction(ProtocolVersion pv,
                                      InstructionType type,
                                      ExperimenterId eid,
                                      byte[] data)

      Creates an EXPERIMENTER instruction. Note that the experimenter-defined data must be an array whose length pads the whole instruction out to a 64-bit boundary. Given the 4-byte header and the 4-byte experimenter ID, this means that the array length must be a multiple of 8.
      Parameters:
        `pv` - the protocol version
        `type` - the instruction type (EXPERIMENTER)
        `eid` - the experimenter ID
        `data` - experimenter-defined data
      Returns:
        the instruction
      Throws:
        `VersionNotSupportedException` - if the version is not supported
        `NullPointerException` - if any required parameter is null
        `IllegalArgumentException` - if type is not EXPERIMENTER or if data array is an unsupported length

    - #### createInstructionHeaders

          public static List<Instruction> createInstructionHeaders(ProtocolVersion pv,
                                                   Set<InstructionType> types)

      Creates instruction headers to be used in encoding a table features instructions 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

    - #### encodeInstruction

          public static void encodeInstruction(Instruction ins,
                               OfPacketWriter pkt)

      Encodes an instruction, 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 instruction.
      Parameters:
        `ins` - the instruction
        `pkt` - the buffer into which the instruction is to be written

    - #### encodeInstructionList

          public static void encodeInstructionList(List<Instruction> instrs,
                                   OfPacketWriter pkt)

      Encodes a list of instructions, 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 instructions.
      Parameters:
        `instrs` - the list of instructions
        `pkt` - the buffer into which the instructions are to be written

    - #### encodeInstrExperList

          public static void encodeInstrExperList(List<InstrExperimenter> instrs,
                                  OfPacketWriter pkt)

      Encodes a list of experimenter instructions, 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 instructions.
      Parameters:
        `instrs` - the list of instructions
        `pkt` - the buffer into which the instructions are to be written

    - #### toDebugString

          public static String toDebugString(int indent,
                             List<Instruction> ins)

      Outputs a list of instructions in debug string format.
      Parameters:
        `indent` - the additional indent (number of spaces)
        `ins` - the list of instructions
      Returns:
        a multi-line string representation of the list of instructions

    - #### validateInstruction

          public static void validateInstruction(ProtocolVersion pv,
                                 Instruction ins,
                                 String msgType)

      Ensures that the specified instruction 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
        `ins` - the instruction to validate
        `msgType` - the message type (label)
      Throws:
        `IllegalArgumentException` - if the instruction is invalid

Copyright © 2014. All Rights Reserved.