com.h3c.of.lib.msg

## Class MessageFactory

- java.lang.Object
- - com.h3c.of.lib.AbstractFactory
  - - com.h3c.of.lib.msg.MessageFactory

-     public class MessageFactory
      extends AbstractFactory

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

- - ### 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 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 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.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 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

    - #### 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.h3c.of.lib.msg.OpenflowMessage, com.h3c.of.lib.msg.MutableMessage)` method, or implicitly through the `create(com.h3c.of.lib.ProtocolVersion, com.h3c.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.
      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.
      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

Copyright © 2014. All Rights Reserved.