Anatomy of JMS Messages

JMS unifies the content format and structure among various messaging products. It also supports messages containing Java objects. In this regard, it's similar to RMI except that the Java objects are exchanged asynchronously. JMS supports messages containing XML data as well. As shown in Figure 13.6, all JMS messages are composed of the following parts:

• Header: All message types support the same set of header fields, which contain values used to identify and route messages.

• Properties (optional): These are optional header fields added to a message. These properties can be user-defined, JMS standard, or JMS provider-specific.

• Body (optional): This indicates the type of message content used. The message body is usually called the payload.

The following sections discuss each part of the message in more detail.

Message Headers

The message headers are a predefined set of header fields used for routing by the JMS client and provider. Their names follow the pattern JMS<HEADER>. The getJMS<HEADER>() and setJMS<HEADER>() methods of the Message are used as “getter” and “setter” for the field value. Table 13.3 summarizes the header names and how they are set.

Exploring Message Properties

In addition to the header fields, these optional headers are added to the message by the application developer, the JMS provider, or JMS optional headers. They provide additional information that enhances the flexibility of the JMS API. Properties allow a client, via message selectors (see the “Message Selection” section later today), to have a JMS provider select messages on its behalf using SQL-like criteria. Property values are set prior to sending a message, and cannot be changed by the client receiving it because the client is in read-only mode.

The following sections will shed light on the different types of message properties, and how to use the message selectors to filter only the messages you want to receive.

User-Defined Properties

Application developers are free to define their message properties. User-defined properties can have any name. Properties are created as name/value pairs. The type of the property is used in the set/get method of the property. JMS provides these types to define application-specific properties: Boolean, Byte, Short, Integer, Long, Float, Double, String, and Object. Here is an example of defining the application property "password" as a String property:

TextMessage msg = (TextMessage) qSession.createTextMessage();
msg.setStringProperty("password", password);
sender.send(msg);

You can use the method clearProperties() to delete all the message's properties. The method getPropertyNames() returns an Enumeration with the names used in the message.

JMS-Defined Properties

JMS defines optional headers that start with the prefix "JMSX". They are treated similarly to the user-defined properties mentioned earlier, but are handled by the JMS provider.

JMS Provider-Specific Properties

JMS allows providers to define their own properties, and each property name must start with the prefix "JMS_<vendor_name>". This is the mechanism a JMS provider uses to make its proprietary message services available to a JMS client.

Message Selection

Message selection allows clients to set criteria for receiving specific messages. This filtering mechanism enhances performance and adds more flexibility to the applications. This is done by putting the filtering criteria (called the selector) in the message header when creating the consumer. This allows the JMS provider to handle the filtering and routing that would otherwise need to be done by the application.

The following example defines a filter to deliver only messages that belong to the enrollment of courses "CS310" and "CS320" to the registration queue "csQueue":

String filter = new String("(course = 'CS310') OR (course = 'CS320')");
QueueReceiver receiver = qSession.createReceiver(csQueue, filter);

Similarly, for a Pub/Sub model, a subscriber can use the same filter:

TopicSubscriber subscriber = tSession.createSubscriber(csTopic, filter);

Message Body

JMS defines six message types; each type depends on the body of the message. Table 13.4 lists the definition of each message type.

Many JMS providers support the XMLMessage type, which extends the TextMessage and is not supported directly by JMS. XML is a natural fit into messaging, and adds powerful semantics to message contents.

A message body can be cleared by using the method clearBody(). Clearing a message's body does not clear its properties. When a message is received, its body is read-only; any attempt to change the body results in a MessageNotWriteableException being thrown.

Each message type must be unpacked to process its body information. Table 13.5 summarizes how to unpack each message type.