Copyright © TIBCO Software Inc. All Rights Reserved

> JMS Message Structure
> JMS messages have a standard structure. This structure includes the following sections:

> • | Header (required)

> • | Properties (optional)

> • | Body (optional)

> JMS Message Header Fields
> The header contains ten predefined fields that contain values used to route and deliver messages. Table 4 describes the message header fields.

> Table 4 JMS Message Headers
> Header Field | Set by | Comments
> JMSDestination | send or publish method | Destination to which message is sent
> JMSDeliveryMode | send or publish method | Persistent or non-persistent message. The default is persistent. EMS extends the delivery mode to include a RELIABLE_DELIVERY mode, as described in RELIABLE_DELIVERY on page 25.
> JMSExpiration | send or publish method | Length of time that message will live before expiration. If set to 0, message does not expire. The time-to-live is specified in milliseconds. If the server expiration property is set for a destination, it will override the JMSExpiration value set by the message producer. In EMS version 4.4 and later, clients automatically synchronize their clocks with the server when a connection is created. However, for long-lasting connections, Network Time Protocol (NTP) is the most reliable method for ensuring continuing synchronization between server and client. Additionally, if your EMS server or client application are based on a version of EMS prior to 4.4, you must ensure that clocks are synchronized among all the host computers that send and receive messages, if your client application uses non-zero values for message expiration. Synchronize clocks to a tolerance that is a very small fraction of the smallest message expiration time.
> JMSPriority | send or publish method | Uses a numerical ranking, between 0 and 9, to define message priority as normal or expedited. Larger numbers represent higher priority. See Message Priority for more information.
> JMSMessageID | send or publish method | Value uniquely identifies each message sent by a provider.
> JMSTimestamp | send or publish method | Timestamp of time when message was handed off to a provider to be sent. Message may actually be sent later than this timestamp.
> JMSCorrelationID | message client | This ID can be used to link messages, such as linking a response message to a request message. Entering a value in this field is optional. The JMS Correlation ID has a recommended maximum of 4 KB. Higher values may result in the message being rejected.
> JMSReplyTo | message client | A destination to which a message reply should be sent. Entering a value for this field is optional.
> JMSType | message client | message type identifier
> JMSRedelivered | JMS provider | If this field is set, it is possible that the message was delivered to the client earlier, but not acknowledged at that time.

> EMS Message Properties
> In the properties area, applications, vendors, and administrators on JMS systems can add optional properties. The properties area is optional, and can be left empty. The JMS specification describes the JMS message properties. This section describes the message properties that are specific to EMS.
> TIBCO-specific property names begin with JMS_TIBCO. Client programs may use the TIBCO-specific properties to access EMS features, but not for communicating application-specific information among client programs.
> The EMS properties are summarized in Table 5 and described in more detail in subsequent sections in this chapter.

> Table 5 Summary of message properties
> Property | Description | More Info
> JMS_TIBCO_CM_PUBLISHER | Correspondent name of an RVCM sender for messages imported from TIBCO Rendezvous. | 394
> JMS_TIBCO_CM_SEQUENCE | Sequence number of an RVCM message imported from TIBCO Rendezvous. | 394
> JMS_TIBCO_COMPRESS | Allows messages to be compressed for more efficient storage. | 37
> JMS_TIBCO_DISABLE_SENDER | Specifies that the user name of the message sender should not be included in the message, if possible. | 21
> JMS_TIBCO_IMPORTED | Set by the server when the message has been imported from Rendezvous or SmartSockets. | 394 414
> JMS_TIBCO_MSG_EXT | Extends the functionality of the MapMessage and StreamMessage body types to include submessages or arrays. | 16 394 414
> JMS_TIBCO_MSG_TRACE | Specifies the message should be traced from producer to consumer. | 428
> JMS_TIBCO_PRESERVE_UNDELIVERED | Specifies the message is to be placed on the undelivered message queue if the message must be removed. | 20
> JMS_TIBCO_SENDER | Contains the user name of the message sender. | 21
> JMS_TIBCO_SS_SENDER | When the EMS server imports a message from TIBCO SmartSockets, it sets this property to the SmartSockets sender header field (in SmartSockets syntax). | 414

> Undelivered Message Queue
> If a message expires or has exceeded the value specified by the maxRedelivery property on a queue, the server checks the message’s JMS_TIBCO_PRESERVE_UNDELIVERED property. If JMS_TIBCO_PRESERVE_UNDELIVERED is set to true, the server moves the message to the undelivered message queue, $sys.undelivered. This undelivered message queue is a system queue that is always present and cannot be deleted. If JMS_TIBCO_PRESERVE_UNDELIVERED is set to false, the message will be deleted by the server.
> To make use of the undelivered message queue, the application that sends or publishes the message must set the boolean JMS_TIBCO_PRESERVE_UNDELIVERED property to true before sending or publishing the message.
> You can only set the undelivered property on individual messages, there is no way to set the undelivered message queue as an option at the per-topic or per-queue level.
> You should create a queue receiver to receive and handle messages as they arrive on the undelivered message queue. If you wish to remove messages from the undelivered message queue without receiving them, you can purge the $sys.undelivered queue with the administration tool, using the purge queue command described under Command Listing. You can also remove messages using the administrative API included with TIBCO Enterprise Message Service.
> Note that $sys.undelivered ignores the global destination property setting. Messages in the undelivered message queue are not routed to other servers.
> Including the Message Sender
> Within a message, EMS can supply the user name given by the message producer when a connection is created. The sender_name and sender_name_enforced server properties on the destination determine whether the message producer’s user name is included in the sent message.
> When a user name is included in a message, a message consumer can retrieve that user name by getting the string message property named JMS_TIBCO_SENDER.
> When the sender_name property is enabled and the sender_name_enforced property is not enabled on a destination, message producers can specify that the user name is to be left out of the message. Message producers can specify the JMS_TIBCO_DISABLE_SENDER boolean property for a particular message, and the message producer’s user name will not be included in the message. However, if the sender_name_enforced property is enabled, the JMS_TIBCO_DISABLE_SENDER property is ignored and the user name is always included in the message.
> JMS Message Bodies
> A JMS message has one of several types of message bodies, or no message body at all.
> The types of messages are described in Table 6.

> Table 6 JMS Message Types
> Message Type | Contents of Message Body
> Message | This message type has no body. This is useful for simple event notification.
> TextMessage | A java.lang.String.
> MapMessage | A set of name/value pairs. The names are java.lang.String objects, and the values are Java primitive value types or their wrappers. The entries can be accessed sequentially by enumeration or directly by name. The order of entries is undefined. When EMS is exchanging messages with Rendezvous or ActiveEnterprise, you can generate a series of nested MapMessages, as described in EMS Extensions to JMS Messages.
> BytesMessage | A stream of uninterrupted bytes. The bytes are not typed; that is, they are not assigned to a primitive data type.
> StreamMessage | A stream of primitive values in the Java programming language. Each set of values belongs to a primitive data type, and must be read sequentially. When EMS is exchanging messages with Rendezvous or ActiveEnterprise, you can generate a series of nested StreamMessages, as described in EMS Extensions to JMS Messages.
> ObjectMessage | A serializable object constructed in the Java programming language.

> Maximum Message Size
> EMS supports messages up to a maximum size of 512MB. However, we recommend that application programs use smaller messages, since messages approaching this maximum size will strain the performance limits of most current hardware and operating system platforms.

Copyright © TIBCO Software Inc. All Rights Reserved