2. Ultra Messaging JMS Overview

2.4.1. Message Components

When a JMS message passes through UM layers, its message properties are preserved as UM message properties. Also, header fields are translated into additional message properties.

A JMS message header consists of the following fields. In the UM layers, their information becomes UM message properties. Note that there is not always a one-to-one correlation between UM message properties and JMS properties/header fields.

• JMSDestination

• JMSDeliveryMode

• JMSMessageID

• JMSTimestamp

• JMSCorrelationID

• JMSReplyTo

• JMSRedelivered

• JMSType

• JMSExpiration

• JMSPriority

2.4.2. Message Properties

Message properties are defined by unique names and can be assigned values. UM supports all JMS message properties, which come in three categories.

JMS defined properties - The JMS Specification defines these properties (with prefix "JMSX") and reserves the use of their names.

Provider-specific properties - These are properties defined and reserved for UM, and include:

• LBMMessageType (JMS message body types)

• JMSTopicType (string, UMS/UMP/UMQ)

• JMSReplyToName (string, topic name)

• JMSReplyToWildcard (boolean)

• JMSReplyToType (string, UMS/UMP/UMQ)

User properties - These are properties that you defined for your applications. A typical use for these is as Message Selectors.

2.5.1. JMS Architecture

The following diagram shows how Ultra Messaging JMS relates to the UM core middleware. When creating connections and sessions, you typically use JNDI (Java Naming and Directory Interface) to look up administered objects in Ultra Messaging Manager (UMM).

The store (UMP) can be used with Publish/Subscribe applications, and the UMQ queue is needed for use with Point-To-Point applications.

2.5.2. JMS-To-UM Object Mapping

From the JMS API layer to the Java API layer, there is a functional mapping of objects, as shown in the following diagram.

ConnectionFactory - One of the two objects that are administered (the other being Destination). A client uses the ConnectionFactory to create a connection with a provider.

Connection - A connection to the provider can be either a queue connection or a topic connection, and creates session objects.

Session - The session is the factory for producing producers and consumers. The ConnectionFactory, Connection, and Session combine to functionally map to a UM context, though you can reuse a context for multiple ConnectionFactories/connections.

Producer - The producer maps directly to a UM source.

Consumer - The consumer maps directly to a UM receiver. The JMS concept of a durable consumer and persistent delivery employ UMP receivers and UMP persistent stores.

Destination - A client uses a destination to specify the target of messages it produces and/or the source of messages it consumes.

Message - The JMS and UM message are variations on each other, with the primary difference being that JMS message header fields are message properties in the UM message.

2.8.1. Native Source

For a UM application sending to a JMS application, we recommend you send message data in byte or text format to avoid the risk of unrecognized data formatting. At the JMS application, set the DEFAULT_MESSAGE_TYPE attribute in FactoryAttributes to match this format. If you need to use more than one message type, at the UM source use the LBMMessageType property to manage this on a per-message basis.

2.8.2. Native Receiver

Native receiver applications can receive messages from a JMS producer. These messages contain all JMS message properties and JMS header information within their own UM message properties objects.

2.8.3. Request/Reply Example

The JMS Request/Reply feature employs the JMSReplyTo and JMSCorrelationID header fields to ensure that the correct receiver/consumer receives a reply and knows which request it pertains to. Consider the Request/Reply case where a native application issues a request to a JMS client (see the figure below).

In this scenario, the UM application sends a request that the JMS client receives, and the JMS application responds by sending a reply. The following sequence of events provides more detail about this scenario. Note that code excerpts are from a C-sharp UM application and a Java JMS application, and example classes may not be part of any UM API.

1. The UM application creates a source, which sends a message on topic AAA. The application has set several message properties to identify the topic type, message type, who to reply to, and a unique message identifier.

                   LBMSourceSendExInfo exinfo = new LBMSourceSendExInfo();
   
                   /* We want JMS to reply via the JMSReplyTo */
                   LBMMessageProperties props = new LBMMessageProperties();
                   props.set("JMSReplyToName", replyTopicString);
                   props.set("JMSReplyToWildcard", false);
                   props.set("JMSReplyToType", "LBM");
                   props.set("JMSTopicType", "topic");
                   props.set("LBMMessageType", 0); // Indicates to JMS that the message payload will be a text message
                   exinfo.setMessageProperties(props);
                   exinfo.setFlags(LBM.SRC_SEND_EX_FLAG_PROPERTIES);
   
                   /* Added sequence number info flag to print out the expected JMSCorrelationID */
                   exinfo.setFlags(exinfo.flags() | LBM.SRC_SEND_EX_FLAG_SEQUENCE_NUMBER_INFO | LBM.SRC_SEND_EX_FLAG_UMQ_MESSAGE_ID_INFO);
   
                   src.send(message, msglen, block ? 0 : LBM.SRC_NONBLOCK, exinfo);
              
   

2. The UM application also creates a receiver for the anticipated reply.

           private static string replyTopicString = "REPLY_" + Guid.NewGuid().ToString();
              
   

   The key here is that the source sends replyTopicString as a message property to provide a "return address". The application then creates a receiver that listens on this topic for the reply.

               SampleJMSRequestReceiver rcv = new SampleJMSRequestReceiver(verbose);
               LBMReceiverAttributes rattr = new LBMReceiverAttributes();
               LBMTopic replyTopic = ctx.lookupTopic(replyTopicString, rattr);
               
               LBMReceiver lbmrcv = new LBMReceiver(ctx, replyTopic, rcv.onReceive, null);
              
   

3. The network passes the message to the JMS application, which converts message properties to JMS header field values and JMS properties, and confirms message type.

4. The JMS application has a consumer that is listening on AAA. It receives the message.

5. Using the JMS header fields, the JMS application's producer sends its reply message to the receiver, getting its reply destination extracted from the JMSReplyTo field. The native application's UM receiver already listening on this topic then receives the reply.

       public void onMessage(Message message) {
           try {
               TextMessage requestMessage = (TextMessage) message;
               String contents = requestMessage.getText();
               System.out.println("Got Message: " + contents);
               // get the reply to destination
               Destination replyDestination = requestMessage.getJMSReplyTo();
               
               TextMessage replyMessage = session.createTextMessage();
               contents = "Re:" + contents;
               replyMessage.setText(contents);
   
               replyMessage.setJMSCorrelationID(requestMessage.getJMSMessageID());
               System.out.println("Sending reply of: " + contents);
               
               replyProducer.send(replyDestination, replyMessage);
           } catch (Exception e) {
               System.err.println("Exception occurred: " + e.getMessage());
               System.exit(-1);
           }
       }
              
   

6. The network again passes the reply message to the UM application, which converts JMS header field values and JMS properties to UM message properties usable by the receiver. The UM application uses the JMSCorrelationID to match the reply to its original request.

This example conveniently illustrates both native source and native receiver scenarios. Note that the key to successful interoperation is the correct exchange of information between UM message properties and JMS headers/properties.

2.8.4. Native Application Notes

When a native source or receiver accesses message property JMSDeliveryMode, the property must be an integer type, with a value of 1 (NON_PERSISTENT) or 2 (PERSISTENT). For example (in C language):

int delivery_mode = 1;
lbm_msg_properties_set(properties, "JMSDeliveryMode", &delivery_mode, LBM_MSG_PROPERTY_INT,
sizeof(int));
       

2.8.5. Compatibility With Other UM Features

Please note that while most UM features are compatible with Ultra Messaging JMS, some are not. Following is a table of features and their compatibilities with Ultra Messaging JMS.