Package org.sim0mq.message

Class Sim0MQMessage

java.lang.Object
org.sim0mq.message.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-2024 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:

  • Field Details

  • Constructor Details

    • 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 Details

    • 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