All about JMS messages

JMS providers like ActiveMQ are based on the concept of passing one-directional messages between nodes and brokers asynchronously. A thorough knowledge of the type of messages that can be sent through a JMS middleware can simplify a lot your work in mapping the communication patterns to real code.

The basic Message interface

Some object members are shared by all messages:

• header fields, used to identify univocally a message and to route it to the right brokers and consumers.
• A dynamic map of properties which can be read programmatically by JMS brokers in order to filter or to route messages.
• A body, which is differentiated in the various implementations we'll see.

Header fields

The set of getJMS*() methods on the Message interface defines the available headers.

Two of them are oriented to message identification:

• getJMSMessageID() contains a generated ID for identifying a message, unique at least for the current broker. All generated IDs start with the prefix 'ID:', but you can override it with the corresponding setter.
• getJMSCorrelationID() (and getJMSCorrelationID() as bytes) can link a message with another, usually one that has been sent previously. For example, a reply can carry the ID of the original message when put in another queue.

Two to sender and recipient identification:

• getJMSDestination() returns a Destination object (a Topic or a Queue, or their temporary version) describing where the message was directed.
• getJMSReplyTo() is a Destination object where replies should be sent; it can be null of course.
• Three tune the delivery mechanism:
• getJMSDeliveryMode() can be DeliveryMode.NON_PERSISTENT or DeliveryMode.PERSISTENT; only persistent messages guarantee delivery in case of a crash of the brokers that transport it.
• getJMSExpiration() returns a timestamp indicating the expiration time of the message; it can be 0 on a message without a defined expiration.
• getJMSPriority() returns a 0-9 integer value (higher is better) defining the priority for delivery. It is only a best-effort value.

While the remaining ones contain metadata:

• getJMSRedelivered() returns a boolean indicating if the message is being delivered again after a delivery which was not acknowledge.
• getJMSTimestamp() returns a long indicating the time of sending.
• getJMSType() defines a field for provider-specific or application-specific message types.

Of these headers, only JMSCorrelationID, JMSReplyTo and JMSType have to be set when needed. The others are generated or managed by the send() and publish() methods if not specified (there are setters available for each of these headers.)

Properties

Generic properties with a String name can be added to messages and read with getBooleanProperty(), getStringProperty() and similar methods. The corresponding setters setBooleanProperty(), setStringProperty(), ... can be used for their addition.

The reason for keeping some properties out of the content of the message (which a MapMessage can contain) is so they could be read before reaching the destination, for example in a JMS broker.

The use case for this access to message properties is routing and filtering: downstream brokers and consumers may define a filter such as "I am interested only on messages on this Topic that have property X = 'value' and Y = 'value2'".

Bodies

All the subinterfaces of javax.jms.Message defined by the API provide different types of message bodies (while actual classes are defined by the providers and are not part of the API). Actual instantiation is then handled by the Session, which implements an Abstract Factory pattern.

On the receival side, a cast is necessary for any message type (at least in the Java JMS Api), since only a generic Message is read.

BytesMessage is the most basic type: it contains a sequence of uninterpreted bytes. Hence, it can in theory contain anything, but the generation and interpretation of the content is the client's job.

BytesMessage m = session.createBytesMessage();
m.writeByte(65);
m.writeBytes(new byte[] { 66, 68, 70 });
// on receival (cast shown only here)
BytesMessage m = (BytesMessage) genericMessage;
byte[] content = new byte[4];
m.readBytes(content);

MapMessage defines a message containing an (unordered) set of key/value pairs, also called a map or dictionary or hash. However, the keys are String objects, while the values are primitives or Strings; since they are primitives, they shouldn't be null.

MapMessage = session.createMapMessage();
m.setString('key', 'value'); // or m.setObject('key', 'value') to avoid specifying a type
// on receival
m.getString('key'); // or m.getObject('key')

ObjectMessage wraps a generic Object for transmission. The Object should be Serializable.

ObjectMessage m = session.createObjectMessage();
m.setObject(new ValueObject('field1', 42));
// on receival
ValueObject vo = (ValueObject) m.getObject();

StreamMessage wraps a stream of primitive values of indefinite length.

StreamMessage m = session.createStreamMessage();
m.writeBoolean(true);
m.writeBoolean(false);
m.writeBoolean(true);
// receival
System.out.println(m.readBoolean());
System.out.println(m.readBoolean());
System.out.println(m.readBoolean()); // prints true, false, true

TextMessage wraps a String of any length.

TextMessage m = session.createTextMessage("Contents");
// or use m.setText() afterwards
// receival
String text = m.getText();

Usually all messages are in a read-only phase after receival, so only getters can be called on them.