Class Sim0MQMessage

  • All Implemented Interfaces:
    Serializable
    Direct Known Subclasses:
    FM1StartFederateMessage, FM2SimRunControlMessage, FM3SetParameterMessage, FM4SimStartMessage, FM5RequestStatus, FM6RequestStatisticsMessage, FM7SimResetMessage, FM8KillFederateMessage, FM9KillAllMessage, FS1RequestStatusMessage, FS2FederateStartedMessage, FS3KillModelMessage, FS4FederateKilledMessage, FS5FederatesKilledMessage, HB1HeartbeatMessage, MC3StatisticsMessage, MC4StatisticsErrorMessage, Sim0MQReply

    public class Sim0MQMessage
    extends Object
    implements Serializable
    Sim0MQMessage contains the abstract body of the message with the first fields of every Sim0MQ message. The message structure of a typical typed Sim0MQ simulation message looks as follows:
    • Frame 0. Magic number = |9|0|0|0|5|S|I|M|#|#| where ## stands for the version number, e.g., 02.
    • Frame 1. Endianness. A boolean that is True for Big-Endian encoding and false for Little-Endian encosing of the message.
    • Frame 2. Federation id. Federation ids can be provided in different types. Examples are a 64-bit long, or a String with a UUID number, a String with meaningful identification, or a short or an int with a simulation run number. In order to check whether the right information has been received, the id can be translated to a String and compared with an internal string representation of the required simulation run id. Typically we use a String to provide maximum freedom. In that case, the run id can be coded as UTF-8 or UTF-16.
    • Frame 3. Sender id. Sender ids can be provided in different types. Examples are a 64-bit long, or a String with a UUID number, a String with meaningful identification, or a short or an int with a sender id number. The sender id can be used to send back a message to the sender at some later time. Typically we use a String to provide maximum freedom. In that case, the sender id can be coded as UTF-8 or UTF-16.
    • Frame 4. Receiver id. Receiver ids can be provided in different types. Examples are a 64-bit long, or a String with a UUID number, a String with meaningful identification, or a short or an int with a receiver id number. The receiver id can be used to check whether the message is meant for us, or should be discarded (or an error can be sent if we receive a message not meant for us). Typically we use a String to provide maximum freedom. In that case, the receiver id can be coded as UTF-8 or UTF-16.
    • Frame 5. Message type id. Message type ids can be defined per type of simulation, and can be provided in different types. Examples are a String with a meaningful identification, or a short or an int with a message type number. For interoperability between different types of simulation, a String id with dot-notation (e.g., DSOL.1 for a simulator start message from DSOL or OTS.14 for a statistics message from OpenTrafficSim) would be preferred. In that case, the message type id can be coded as UTF-8 or UTF-16.
    • Frame 6. Unique message number. The unique message number can have any type, but is typically sent as a long (64 bits), and is meant to confirm with a callback that the message has been received correctly. The number is unique for the sender, so not globally within the federation.
    • Frame 7. Number of fields. The number of fields in the payload is indicated to be able to check the payload and to avoid reading past the end. The number of fields can be encoded using byte, short, int, or long. A 16-bit positive short (including zero) is the standard encoding.
    • Frame 8-n. Payload, where each field has a 1-byte prefix denoting the type of field.

    Copyright (c) 2016-2020 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
    BSD-style license. See Sim0MQ License.

    initial version Mar 3, 2017
    Author:
    Alexander Verbraeck
    See Also:
    Serialized Form
    • Constructor Detail

      • Sim0MQMessage

        public Sim0MQMessage​(boolean bigEndian,
                             Object federationId,
                             Object senderId,
                             Object receiverId,
                             Object messageTypeId,
                             Object messageId,
                             Object[] payload)
                      throws Sim0MQException,
                             NullPointerException
        Encode the object array into a message.
        Parameters:
        bigEndian - boolean; Indicates whether this message using little endian or big endian encoding. Big endian is encoded as true, and little endian as false.
        federationId - the federation id can be coded using different types. Examples are two 64-bit longs indicating a UUID, or a String with a UUID number, a String with meaningful identification, or a short or an int with a simulation run number.
        senderId - The sender id can be used to send back a message to the sender at some later time.
        receiverId - The receiver id can be used to check whether the message is meant for us, or should be discarded (or an error can be sent if we receive a message not meant for us).
        messageTypeId - Message type ids can be defined per type of simulation, and can be provided in different types. Examples are a String with a meaningful identification, or a short or an int with a message type number.
        messageId - The unique message number is meant to confirm with a callback that the message has been received correctly. The number is unique for the sender, so not globally within the federation.
        payload - Object[]; Payload as an Object array
        Throws:
        Sim0MQException - on unknown data type
        NullPointerException - when one of the parameters is null
      • Sim0MQMessage

        public Sim0MQMessage​(Object[] objectArray,
                             int expectedNumberOfPayloadFields,
                             Object expectedMessageTypeId)
                      throws Sim0MQException,
                             NullPointerException
        Encode the object array into a message.
        0 = magic number, equal to the String "SIM##" where ## stands for the version number of the protocol.
        1 = endianness, boolean indicating the endianness for the message. True is Big Endian, false is Little Endian.
        2 = federation id, could be String, int, Object, ...
        3 = sender id, could be String, int, Object, ...
        4 = receiver id, could be String, int, Object, ...
        5 = message type id, could be String, int, Object, ...
        6 = message id, could be long, Object, String, ....
        7 = number of fields that follow, as a Number (byte, short, int, long).
        8-n = payload, where the number of fields was defined by message[7].
        Parameters:
        objectArray - Object[]; Full message object array
        expectedNumberOfPayloadFields - int; the expected number of fields in the message (field 8 and further)
        expectedMessageTypeId - the expected message type id
        Throws:
        Sim0MQException - on unknown data type
        NullPointerException - when one of the parameters is null
    • Method Detail

      • getMagicNumber

        public final Object getMagicNumber()
        Returns:
        Magic number = |9|0|0|0|5|S|I|M|#|#| where ## stands for the version number, e.g., 01. Internally, the magic number is always coded as a UTF-8 String, so it always starts with a byte equal to 9.
      • isBigEndian

        public final boolean isBigEndian()
        Returns:
        bigEndian
      • getFederationId

        public final Object getFederationId()
        Returns:
        federationId
      • getSenderId

        public final Object getSenderId()
        Returns:
        senderId
      • getReceiverId

        public final Object getReceiverId()
        Returns:
        receiverId
      • getMessageTypeId

        public final Object getMessageTypeId()
        Returns:
        messageTypeId
      • getMessageId

        public final Object getMessageId()
        Returns:
        messageId
      • createObjectArray

        public final Object[] createObjectArray()
        Create a Sim0MQ object array of the fields.
        Returns:
        Object[] a Sim0MQ object array of the fields
      • createByteArray

        public final byte[] createByteArray()
                                     throws Sim0MQException,
                                            SerializationException
        Create a byte array of the fields.
        Returns:
        byte[] a Sim0MQ byte array of the content
        Throws:
        Sim0MQException - on unknown data type as part of the content
        SerializationException - when the byte array cannot be created, e.g. because the number of bytes does not match
      • getNumberOfPayloadFields

        public final short getNumberOfPayloadFields()
        Get the number of payload fields in the message.
        Returns:
        short; the number of payload fields in the message.
      • check

        public static void check​(Object[] fields,
                                 int expectedPayloadFields,
                                 String expectedMessageType,
                                 Object intendedReceiverId)
                          throws Sim0MQException
        Check the consistency of a message from an Object[] that was received.
        Parameters:
        fields - Object[]; the fields in the message
        expectedPayloadFields - the expected number of payload fields
        expectedMessageType - the expected message type
        intendedReceiverId - id of the intended receiver
        Throws:
        Sim0MQException - when errors in the message have been detected
      • encodeUTF8

        public static byte[] encodeUTF8​(boolean bigEndian,
                                        Object federationId,
                                        Object senderId,
                                        Object receiverId,
                                        Object messageTypeId,
                                        Object messageId,
                                        Object... content)
                                 throws Sim0MQException,
                                        SerializationException
        Encode the object array into a message. Use UTF8 to code Strings.
        Parameters:
        bigEndian - boolean; Indicates whether this message using little endian or big endian encoding. Big endian is encoded as true, and little endian as false.
        federationId - the federation id can be coded using different types. Examples are two 64-bit longs indicating a UUID, or a String with a UUID number, a String with meaningful identification, or a short or an int with a simulation run number.
        senderId - The sender id can be used to send back a message to the sender at some later time.
        receiverId - The receiver id can be used to check whether the message is meant for us, or should be discarded (or an error can be sent if we receive a message not meant for us).
        messageTypeId - Message type ids can be defined per type of simulation, and can be provided in different types. Examples are a String with a meaningful identification, or a short or an int with a message type number.
        messageId - The unique message number is meant to confirm with a callback that the message has been received correctly. The number is unique for the sender, so not globally within the federation.
        content - the objects to encode
        Returns:
        the zeroMQ message to send as a byte array
        Throws:
        Sim0MQException - on unknown data type
        SerializationException - on serialization problem
      • encodeUTF16

        public static byte[] encodeUTF16​(boolean bigEndian,
                                         Object federationId,
                                         Object senderId,
                                         Object receiverId,
                                         Object messageTypeId,
                                         Object messageId,
                                         Object... content)
                                  throws Sim0MQException,
                                         SerializationException
        Encode the object array into a message. Use UTF16 to code Strings.
        Parameters:
        bigEndian - boolean; Indicates whether this message using little endian or big endian encoding. Big endian is encoded as true, and little endian as false.
        federationId - the federation id can be coded using different types. Examples are two 64-bit longs indicating a UUID, or a String with a UUID number, a String with meaningful identification, or a short or an int with a simulation run number.
        senderId - The sender id can be used to send back a message to the sender at some later time.
        receiverId - The receiver id can be used to check whether the message is meant for us, or should be discarded (or an error can be sent if we receive a message not meant for us).
        messageTypeId - Message type ids can be defined per type of simulation, and can be provided in different types. Examples are a String with a meaningful identification, or a short or an int with a message type number.
        messageId - The unique message number is meant to confirm with a callback that the message has been received correctly. The number is unique for the sender, so not globally within the federation.
        content - the objects to encode
        Returns:
        the zeroMQ message to send as a byte array
        Throws:
        Sim0MQException - on unknown data type
        SerializationException - on serialization problem
      • encodeReplyUTF8

        public static byte[] encodeReplyUTF8​(String identity,
                                             boolean bigEndian,
                                             Object federationId,
                                             Object senderId,
                                             Object receiverId,
                                             Object messageTypeId,
                                             Object messageId,
                                             Object... content)
                                      throws Sim0MQException,
                                             SerializationException
        Encode the object array into a reply message. Use UTF8 to code Strings.
        Parameters:
        identity - the identity of the federate to which this is the reply
        bigEndian - boolean; Indicates whether this message using little endian or big endian encoding. Big endian is encoded as true, and little endian as false.
        federationId - the federation id can be coded using different types. Examples are two 64-bit longs indicating a UUID, or a String with a UUID number, a String with meaningful identification, or a short or an int with a simulation run number.
        senderId - The sender id can be used to send back a message to the sender at some later time.
        receiverId - The receiver id can be used to check whether the message is meant for us, or should be discarded (or an error can be sent if we receive a message not meant for us).
        messageTypeId - Message type ids can be defined per type of simulation, and can be provided in different types. Examples are a String with a meaningful identification, or a short or an int with a message type number.
        messageId - The unique message number is meant to confirm with a callback that the message has been received correctly. The number is unique for the sender, so not globally within the federation.
        content - the objects to encode
        Returns:
        the zeroMQ message to send as a byte array
        Throws:
        Sim0MQException - on unknown data type
        SerializationException - on serialization problem
      • encodeReplyUTF16

        public static byte[] encodeReplyUTF16​(String identity,
                                              boolean bigEndian,
                                              Object federationId,
                                              Object senderId,
                                              Object receiverId,
                                              Object messageTypeId,
                                              Object messageId,
                                              Object... content)
                                       throws Sim0MQException,
                                              SerializationException
        Encode the object array into a reply message. Use UTF16 to code Strings.
        Parameters:
        identity - the identity of the federate to which this is the reply
        bigEndian - boolean; Indicates whether this message using little endian or big endian encoding. Big endian is encoded as true, and little endian as false.
        federationId - the federation id can be coded using different types. Examples are two 64-bit longs indicating a UUID, or a String with a UUID number, a String with meaningful identification, or a short or an int with a simulation run number.
        senderId - The sender id can be used to send back a message to the sender at some later time.
        receiverId - The receiver id can be used to check whether the message is meant for us, or should be discarded (or an error can be sent if we receive a message not meant for us).
        messageTypeId - Message type ids can be defined per type of simulation, and can be provided in different types. Examples are a String with a meaningful identification, or a short or an int with a message type number.
        messageId - The unique message number is meant to confirm with a callback that the message has been received correctly. The number is unique for the sender, so not globally within the federation.
        content - the objects to encode
        Returns:
        the zeroMQ message to send as a byte array
        Throws:
        Sim0MQException - on unknown data type
        SerializationException - on serialization problem
      • decode

        public static Sim0MQMessage decode​(byte[] bytes)
                                    throws Sim0MQException,
                                           SerializationException
        Decode the message into an object array. Note that the message fields are coded as follows:
        0 = magic number, equal to the String "SIM##" where ## stands for the version number of the protocol.
        1 = endianness, boolean indicating the endianness for the message. True is Big Endian, false is Little Endian.
        2 = federation id, could be String, int, Object, ...
        3 = sender id, could be String, int, Object, ...
        4 = receiver id, could be String, int, Object, ...
        5 = message type id, could be String, int, Object, ...
        6 = message id, could be long, Object, String, ....
        7 = number of fields that follow, as a Number (byte, short, int, long).
        8-n = payload, where the number of fields was defined by message[7].
        Parameters:
        bytes - the ZeroMQ byte array to decode
        Returns:
        Sim0MQMessage; a newly created Sim0MQMessage based on the decoded bytes
        Throws:
        Sim0MQException - on unknown data type
        SerializationException - when deserialization fails
      • decodeToArray

        public static Object[] decodeToArray​(byte[] bytes)
                                      throws Sim0MQException,
                                             SerializationException
        Decode the message into an object array. Note that the message fields are coded as follows:
        0 = magic number, equal to the String "SIM##" where ## stands for the version number of the protocol.
        1 = endianness, boolean indicatingthe enfianness for the message. True is Big Endian, false is Little Endian.
        2 = simulation run id, could be String, int, Object, ...
        3 = sender id, could be String, int, Object, ...
        4 = receiver id, could be String, int, Object, ...
        5 = message type id, could be String, int, Object, ...
        6 = message id, as a long.
        7 = number of fields that follow.
        8-n = payload, where the number of fields was defined by message[6].
        Parameters:
        bytes - the ZeroMQ byte array to decode
        Returns:
        an array of objects of the right type
        Throws:
        Sim0MQException - on unknown data type
        SerializationException - when deserialization fails
      • print

        public static String print​(Object[] message)
        Return a printable version of the message, e.g. for debugging purposes.
        Parameters:
        message - the message to parse
        Returns:
        a string representation of the message
      • listPayload

        public static String listPayload​(Object[] message)
        Return a printable line with the payload of the message, e.g. for debugging purposes.
        Parameters:
        message - the message to parse
        Returns:
        a string representation of the message