Messages

A message is composed of three parts: a header, properties, and a body. You must understand this structure in order to compose a message properly and to configure certain messaging behaviors.

Message Header

A header is required of every JMS message. The header contains ten predefined fields, which are listed and described in Table 2–3.

Table 2–3 JMS-Defined Message Header

Header Field	Description	Set By
JMSDestination	Specifies the name of the destination to which the message is sent.	JMS provider
JMSDeliveryMode	Specifies whether the message is persistent.	Client, per producer or per individual message produced.
JMSExpiration	Specifies the time when the message will expire.	Client, per producer or per individual message produced..
JMSPriority	Specifies the priority of the message within a 0 (low) to 9 (high) range.	Client, per producer or per individual message produced.
JMSMessageID	Specifies a unique ID for the message within the context of a JMS provider installation.	JMS provider
JMSRedelivered	Specifies whether the message has already been delivered but not acknowledged.	JMS provider
JMSTimestamp	Specifies the time when the JMS provider received the message.	JMS provider
JMSCorrelationID	A value that allows a client to define a correspondence between two messages.	Client, if needed
JMSReplyTo	Specifies a destination where the consumer should send a reply.	Client, if needed
JMSType	A value that can be evaluated by a message selector.	Client, if needed

As you can see from reading through this table, message header fields serve a variety of purposes: identifying a message, configuring the routing of messages, providing information about message handling, and so on.

One of the most important fields, JMSDeliveryMode, determines the reliability of message delivery. This field indicates whether a message is persistent.

• Persistent messages. are guaranteed to be delivered and successfully consumed exactly once. Persistent messages are not lost if the message service fails.

• Non-persistent messages are guaranteed to be delivered at most once. Non-persistent messages can be lost if the message service fails.

Some message header fields are set by the JMS provider (the Message Queue broker and/or client runtime) and others are set by the client. Message producers may need to configure header values to obtain certain messaging behaviors; message consumers may need to read header values in order to understand how the message was routed and what further processing it might need.

Three of the header fields (JMSDeliveryMode, JMSExpiration, and JMSPriority) can be set at two different levels:

• For all messages produced by a specific message producer.

• For each message when it is produced.

If these fields are set at more than one level, values set when producing a message override those set for the message’s producer.

Names of constant used for message header fields vary with the language implementation. See Sun GlassFish Message Queue 4.4 Developer’s Guide for Java Clients or Sun GlassFish Message Queue 4.4 Developer’s Guide for C Clients for more information.

Message Properties

A message can also include optional header fields, called properties, specified as property name and property value pairs. Properties allow clients and providers to extend the message header and can contain any information that the client or the JMS provider finds useful to identify and process a message. Message properties allow a consuming client to ask that only those messages be delivered which fit a given criteria. For instance, a consuming client might indicate an interest for payroll messages concerning part-time employees located in New Jersey. The JMS provider will not deliver messages that do not meet the specified criteria.

The JMS specification defines nine standard properties. Some of these are set by the client and some by the JMS provider. Their names begin with the reserved characters “JMSX.” The client or the JMS provider can use these properties to determine who sent a message, the identity of the application sending a message, the state of the message, how often and when it was delivered, tansaction identification, and so forth. These properties are useful to the JMS provider in routing messages and in providing diagnostic information.

Message Queue defines a number of additional message properties. These properties are used to identify compressed messages and how messages should be handled if they cannot be delivered. For more information see Managing Message Size in Sun GlassFish Message Queue 4.4 Developer’s Guide for Java Clients.

Message Body

The message body contains the data that clients want to exchange.

The JMS message body type determines what the body may contain and how it should be processed by the consumer, as specified in Table 2–4. The Session object includes a create method for each type of message body.

Table 2–4 Message Body Types

Message Body Type	Description
StreamMessage	A message whose body contains a stream of Java primitive values. It is filled and read sequentially.
MapMessage	A message whose body contains a set of name-value pairs. The order of entries is not defined.
TextMessage	A message whose body contains a Java string, for example an XML message.
ObjectMessage	A message whose body contains a serialized Java object.
BytesMessage	A message whose body contains a stream of uninterpreted bytes.
Message	A message that contains a header and properties but no body.

Java clients can set a property to have the client runtime compress the body of a message being produced. The Message Queue runtime on the consumer side decompresses the message before delivering it.