Ultra Messaging JMS Guide

2.1. The JMS Specification

The Oracle JMS Specification 1.0.2b provides requirements and guidelines for developing JMS-based Java messaging applications. The specification provides for two models: Publish/Subscribe, and Point-To-Point. Both models are supported by Ultra Messaging JMS.

Ultra Messaging JMS also supports Oracle JMS Specification 1.1, which unifies the class hierarchies of the Point-To-Point and Pub/Sub domains, but is fully backward compatible.

2.2. Publish/Subscribe Model

With the JMS publish/subscribe model, a JMS user (or client) publishes messages to a topic. Other clients then subscribe to the topic and are thus able to receive the published messages. The JMS model supports the concept of topic being an unadministered object (defined simply by its name), which directly correlates to the Ultra Messaging model. You can configure Ultra Messaging JMS to use either the streaming or persistence features.

2.3. Point-To-Point Model

The Point-To-Point model differs from the Publish/Subscribe model mainly in that it employs a message queue and that the sending and receiving clients are aware of each other. Receiving clients extract messages from the queue and notifies it that the messages have been consumed. The queue retains messages until they are consumed or time out. Ultra Messaging JMS employs UM's queue provided by UMQ.

2.4. JMS Messages

The JMS message generally consists of a header and body (data payload). You can set a JMS body type programatically and optionally identify the body type in a header field. JMS Messages can be of the types shown below. (Numeric values are used in the UM message property LBMMessageType.)

• TextMessage (0)

• BytesMessage (1)

• MapMessage (2)

• Message (3) (this message type has no body)

• ObjectMessage (4)

• StreamMessage (5)

2.5. JMS Implementation

The Ultra Messaging JMS API serves as a wrapper, allowing JMS clients access to UM functionality. This section describes in more detail the relationship between the Ultra Messaging JMS and UM layers.

2.6. Ultra Messaging JMS Programming Architecture

The general JMS programming model is shown in the following figure. Life Cycle of an Ultra Messaging JMS Application offers details for developing producer and consumer applications.

2.7. Quality of Service

Ultra Messaging JMS uses UMP and UMQ to provide the desired QoS based on the type of destination configured in JMSConfig.xml.

MessageProducer

• Persistent - The send method, if using a Destination configured as a UMP-type destination, blocks until the producer receives a Stability Acknowledgement.

• Non-Persistent - The send method does not block if using a Destination configured as a UMS or UMQ type.

MessageConsumer

• Consumer - Only receives messages while the application is active.

• Durable Consumer - Receives all messages for the topic if the MessageConsumer was created with a UMP type destination, including messages sent while the durable consumer application was not running.

2.8. Interoperability

In general, it is possible for JMS producers to send messages to UM receivers, or UM sources to send to JMS consumers. This is typically successful with default settings and message body types of TextMessage or BytesMessage. Such interoperability scenarios are also possible with non-default JMS or UM settings if you carefully select and test compatible configurations.

A JMS application can communicate with a UM application on a limited basis, with the proper attention paid to mapping with JMS headers and message properties. A UM application can receive and process the data of a JMS message the same way as when it receives standard UM messages.

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

2.9. Unsupported JMS Specifications

The Ultra Messaging JMS does not currently support the following JMS specifications.

• Message prioritization

• JMS Application Server Facilities

• synchronous message consumption/delivery (partial support; see Point-To-Point Model)

• recover() method (for session recovery)

• pull model for delivering messages from a queue to a receiver

• provider-supplied property naming requirement

• TopicSubscriber NoLocal attribute

• JMSMessageID passed over the wire from sender to receiver

3.1. Producer Application

Producer applications take the following actions.

1. Look-up ConnectionFactory. The Ultra Messaging JMS implementation supports JNDI lookup of a ConnectionFactory.

2. Create a physical connection. The ConnectionFactory creates the Connection.

3. Create logical session(s) of a Connection. Sessions are light-weight connections that can multiplex over a single physical Connection. Sessions provide the following.

   1. Concurrent use of the physical Connection across multiple threads (one session per thread) and thus are resource efficient.

   2. Delineation of work between multiple producers.

   3. A factory of producers.

4. Create a Destination. You can create the destination programmatically or via JNDI lookup. The destination consists of a Topic or Queue name.

5. Create a producer of a session and provide the destination.

6. Create Messages. For each Message, set the business data and set the associated routing properties.

7. Send Messages to the Destination address using the producer.

8. Close Objects by destroying the Message, Destination(s), producer, session(s), and Connection.

The following simple JMS producer example application demonstrates how to program the above actions.

// Obtain a ConnectionFactory via lookup or direct instantiation
ConnectionFactory factory = (ConnectionFactory)jndiContext.lookup("uJMSConnectionFactory");
 
// Create a connection - assuming no username/password required for UM
Connection connection = factory.createConnection();

// Create a session
Session session = connection.createSession(false, javax.jms.Session.AUTO_ACKNOWLEDGE);

// Create a topic destination
Destination destination = session.createTopic("TOPIC.1");

// Create a producer
MessageProducer msgProducer = session.createProducer(null);

// create a bytes message
BytesMessage msg = session.createBytesMessage();

byte[] buffer = {1,2,3,4,5};

msg.writeBytes(buffer);

// Publish the message
msgProducer.send(destination, msg);

// close the connection
connection.close();
           

3.2. Consumer Application

Consumer applications normally take the following actions.

1. Look up ConnectionFactory. The Ultra Messaging JMS implementation supports JNDI lookup of a ConnectionFactory.

2. Create a physical connection. The ConnectionFactory creates the Connection.

3. Create logical session(s) of a Connection. Sessions are light-weight connections that can multiplex over a single physical Connection. Sessions provide the following.

   1. Concurrent use of the physical Connection across multiple threads (one session per thread) and thus are resource efficient

   2. Delineation of work between multiple consumers.

   3. A factory of consumers.

4. Create a Destination. You can create the destination, which consists of a Topic/Queue name, programmatically or via JNDI/UMM lookup. The UMM repository contains a Wildcard designation for a Destination.

5. Create a consumer of a session, providing the Destination created. If the messages are read asynchronously, register the listener call-back function and exception with the consumer.

6. Read Messages from the Destination Address. For each destination address (absolute or wildcard), the read could be synchronous, the consumer could register a listener call-back function to asynchronously receive messages, or the consumer could also register a listener call-back exception function to asynchronously receive exceptions, business or technical.

7. Process messages to access data and properties.

8. Close Objects by destroying Message; Destination(s), consumer, session(s), Connection.

The following simple JMS consumer example application demonstrates how to program the above actions.

// Obtain a ConnectionFactory via lookup or direct instantiation
 ConnectionFactory factory = (ConnectionFactory)jndiContext.lookup("uJMSConnectionFactory");

// Create a connection - assuming no username/password required for UM
Connection connection = factory.createConnection();

// Create a session
Session session = connection.createSession(false, javax.jms.Session.AUTO_ACKNOWLEDGE);

// Create a topic destination
Destination destination = session.createTopic("TOPIC.1");

// create the consumer 
MessageConsumer msgConsumer = session.createConsumer(destination);

// start the connection 
connection.start();

// read messages 
while(true)
{
    // receive the message 
        msg = msgConsumer.receive();
    if (msg == null)
        break;
}

// close the connection 
connection.close();
           

4.1. Look Up Administered Objects Using JNDI

The code below shows the typical steps to create an initial context and look up a ConnectionFactory and a Destination using JNDI. The JNDI repository used depends on the values used for providerContextFactory and providerUrl and would typically need to specify a userName and password.

// Import of Sun's JMS interface
import javax.jms.*;

// Imports for JNDI
import javax.naming.*;
import javax.naming.directory.*;

// Create the Context
InitialContext jndiContext = new InitialContext();
// Lookup the objects
ConnectionFactory cf = (ConnectionFactory)jndiContext.lookup("uJMSConnectionFactory");
Destination d = (Destination)jndiContext.lookup("TOPIC1");
           

5.1. jndi.properties

The /jmsclient/bin/jndi.properties governs from where your JMS applications receive their configuration data. Regardless of which of the three configuration methods you decide to use, you must edit or ensure that this file matches the selected method. The jndi.properties, in its default form, appears below. Note that the file specifies the third configuration method (JMSConfig XML file).

## Use the LBM XML based context factory
#java.naming.factory.initial = com.latencybusters.jms.LBMXmlContextFactory
## where the xml config file is one of
#java.naming.provider.url = classpath:umjms.xml
#java.naming.provider.url = file:C:/umjms.xml
#java.naming.provider.url = file:/home/user1/umjms.xml
 
## Use the UMM based context factory
#java.naming.factory.initial = com.latencybusters.jms.UMMContextFactory
## where the ummd is running at the following url
#java.naming.provider.url = localhost:15701
#java.naming.security.principal = JMSUser
#java.naming.security.credentials = JMSUser
 
## Use Sun's RefFSContextFactory (with .bindings file)
java.naming.factory.initial = com.sun.jndi.fscontext.RefFSContextFactory
## where the .bindings file is
java.naming.provider.url = file:.
   

The next three sections describe how to edit the appropriate sections of this file.

5.2. Configuring Ultra Messaging JMS with a UM XML File

You can create an XML configuration file using an XML editor or by using the UMM GUI. See Using the UMM GUI for details. With this method, the UMM Daemon doesn't have to be running when your Ultra Messaging JMS applications start.

To use this configuration method, edit the jndi.properties file as follows:

1. Make sure that all lines in the second and third section are commented out.

2. Un-comment the line, java.naming.factory.initial = com.latencybusters.jms.LBMXmlContextFactory

3. Un-comment one of the java.naming.provider.url lines and supply the path and filename of your XML configuration file. See also Configuring Ultra Messaging JMS with Ultra Messaging Manager.

4. Save the jndi.properties file.

The UM XML configuration file has the following high-level structure.

<?xml version="1.0" encoding="UTF-8"?>
<um-configuration version="1.0">
 
<applications>
 <application name="uJMS">
 
  <contexts>
    <context name="uJMSConnectionFactory" template="">
      <sources/>
      <receivers/>
      <wildcard-receivers/>
      <options type="context"> 
    </context>
    <context name="uJMSConnectionFactory-UMS">
      <sources/>
       <receivers/>
       <wildcard-receivers/>
    </context>
    <context name="uJMSConnectionFactory-UMP">
      <sources/>
      <receivers/>
      <wildcard-receivers/>
    </context>
    <context name="uJMSConnectionFactory-UMQ">
      <sources/>
      <receivers/>
      <wildcard-receivers/>
    </context>
  </contexts>
 
  <event-queues>
    <event-queue/>
  </event-queues>
 
  <application-data>
    <ConnectionFactory name="uJMSConnectionFactory">
      <options type="ConnectionFactory">
      </options>
    </ConnectionFactory>
    <Destination name="TempQueue">
      <options type="Destination">
      </options>
    </Destination>
  </application-data>
 
 </application>
</applications>
</um-configuration>
   

Essentially, the structure has two parts. The first part contains the contexts that allow you to specify traditional UM configuration option values. The second part, <application-data>, allows you to specify JMS options to factories and destinations. The following details some of the major sections of the above high-level structure.

• <context name="uJMSConnectionFactory" template=""> - Accepts general UM configuration option values for the contexts, sources, and receivers used by your applications.

• <context name="uJMSConnectionFactory-UMS"> - Accepts option values specific to any Streaming activities of your applications.

• <context name="uJMSConnectionFactory-UMP"> - Accepts option values specific to Persistent activities, such as store configuration options.

• <context name="uJMSConnectionFactory-UMQ"> - Accepts option values specific to Queueing activities, such as queue configuration options.

• <ConnectionFactory name="uJMSConnectionFactory"> - Accepts JMS Factory option values such as default_message_type or default_topic_type.

• <Destination name="TempQueue"> - Accepts JMS destination option values such as type or dest_type .

To see a more complete XML file, see /jmsclient/config/umjms.xml. Unlike the high-level structure above, this file contains relevant option values. You can also review the same information in the UMM GUI. The XML file you create must adhere to the high-level structure presented above.

5.3. Configuring Ultra Messaging JMS with Ultra Messaging Manager

You can use the UMM GUI to create configurations for your JMS applications. With this method, the UMM Daemon must be running to provide server configuration and license information to your JMS applications when they start. To use this method, edit the jndi.properties file as follows:

1. Make sure that all lines in the first and third section are commented out.

2. Un-comment the line, java.naming.factory.initial = com.latencybusters.jms.UMMContextFactory

3. Un-comment java.naming.provider.url and substitute an IP address and port number for localhost:15701 to specify where the UMM Daemon runs. You can add a comma-separated list of daemons.

4. Save the jndi.properties file.

5.4. Configuring Ultra Messaging JMS with a JMSConfig XML File

With this method, you use the /jmsclient/bin/config.bat or /jmsclient/bin/config.sh script to create a .bindings file from your config.xml. To use this method, edit the jndi.properties file as follows:

1. Make sure that all lines in the first and second section are commented out.

2. Un-comment the line, java.naming.factory.initial = com.sun.jndi.fscontext.RefFSContextFactory

3. Un-comment java.naming.provider.url = file:..

4. Save the jndi.properties file.

The JMSConfig.xml file allows you to assign UM configuration values to the Ultra Messaging JMS ConnectionFactory and specify message topics as destinations. You can create a JMSConfig format XML configuration file using an XML editor or text editor. See /jmsclient/config/config.xml for an example of a JMSConfig file. This is the configuration file for the UM JMS examples described in Ultra Messaging JMS Quick Start.

The configuration file has the following high-level structure.

<JMSConfig>
    <ConnectionFactories>
        <ConnectionFactory>
            <FactoryAttributes>
                <Attribute/>
            </FactoryAttributes>
            <ContextAttributes>
                <Attribute "UM configuration options, scope=context" />
            </ContextAttributes>
            <SourcetAttributes>
                <Attribute "UM configuration options, scope=source" />
            </SourcetAttributes>
            <ReceiverAttributes>
                <Attribute "UM configuration options, scope=receiver" />
            </ReceiverAttributes>
            <WildcardRceiverAttributes>
                <Attribute "UM configuration options, scope=wildcard-receiver" />
            </WildcardReceiverAttributes>
        </ConnectionFactory>
    </ConnectionFactories>
    <Destinations>
        <Destination>
            <DestinationAttributes>
                <Attribute/>
            </DestinationAttributes>
            <ReceiverAttributes>
                <Attribute/>
            </RecieverAttributes>
        </Destination>
    </Destinations>
</JMSConfig>
       

This section discusses the following topics.

• ConnectionFactory Attributes

• Destination Attributes

<ConnectionFactories>
    <ConnectionFactory>
        <FactoryAttributes>
            <Attribute name="CLIENT_ID" value="UME1"/>
            <Attribute name="DEBUG" value="false"/> 
            <Attribute name="DEFAULT_TOPIC_TYPE" value="UME"/>
            <Attribute name="DEFAULT_TEMP_TOPIC_TYPE" value="LBM"/>
            <Attribute name="USE_APP_HEADER" value="true"/>
            <Attribute name="DEFAULT_MESSAGE_TYPE" value="TextMessage"/>
        </FactoryAttributes>
    </ConnectionFactory>
</ConnectionFactories>
       

<ContextAttributes>
    <Attribute name="operational_mode" value="sequential"/>
    <Attribute name="resolver_multicast_ttl" value="16"/>
    <Attribute name="resolver_multicast_address" value="225.72.39.173"/>
    <Attribute name="mim_address" value="225.72.39.174"/>
    <Attribute name="transport_lbtrm_multicast_address_low" value="225.73.39.200"/>
    <Attribute name="transport_lbtrm_multicast_address_high" value="225.73.39.210"/>
    <Attribute name="request_tcp_port_low" value="16000"/>
    <Attribute name="request_tcp_port_high" value="16010"/>
    <Attribute name="transport_lbtrm_source_port_low" value="15000"/>
    <Attribute name="transport_lbtrm_source_port_high" value="15500"/>
    <Attribute name="transport_tcp_maximum_ports" value="20"/>
    <Attribute name="transport_tcp_port_low" value="16500"/>
    <Attribute name="transport_tcp_port_high" value="16600"/>
    <Attribute name="resolver_unicast_port_high" value="45000"/>
    <Attribute name="transport_lbtrm_data_rate_limit" value="500000000"/>
    <Attribute name="transport_lbtrm_retransmit_rate_limit" value="1000000"/>
    <Attribute name="transport_lbtrm_receiver_socket_buffer" value="8000000"/>
    <Attribute name="request_tcp_reuseaddr" value="1"/>
</ContextAttributes>
               

<SourceAttributes>
    <Attribute name="transport" value="lbtrm"/>
    <Attribute name="late_join" value="1"/>
    <Attribute name="ume_store_name" value="JMSStore1"/>
    <Attribute name="ume_store_name" value="JMSStore2"/>
    <Attribute name="ume_store_name" value="JMSStore3"/>
    <Attribute name="ume_store_behavior" value="qc"/>
    <Attribute name="ume_proxy_source" value="1"/>
    <Attribute name="umq_queue_name" value="JMSQueue"/>
    <Attribute name="implicit_batching_minimum_length" value="1"/>
</SourceAttributes>
               

<ReceiverAttributes>
    <Attribute name="umq_receiver_type_id" value="100"/>
</ReceiverAttributes>
               

<Destination name="ReplyTopic" type="Topic">
    <DestinationAttributes>
            <Attribute name="REGID" value="4400"/>
        <Attribute name="WILDCARD" value="false"/>
        <Attribute name="TYPE" value="LBM"/>
    </DestinationAttributes>
</Destination>
                   

7.1. Publish/Subscribe

In the publish/subscribe scenario, you can have many consumers subscribed to the same topic, but use message selectors to filter out selected consumers, and hence, selected receiving clients and applications. In this scenario, each consumer decides whether or not to discard the message.

For example, to create a topic subscriber with a message selector for consuming messages with one property greater than 5 and another property equal to 3:

// Create a selector to receive only messages with MyProp1 greater than 5 and MyProp2 equal to 3.
String selector = "MyProp1 > 5 AND MyProp2 = 3";

// Create a topic subscriber using the selector.
TopicSubscriber topicSubscriber = topicSession.createSubscriber(queue, selector);
   

7.2. Point-To-Point

In the point-to-point scenario, you can employ message selectors at the queue to determine which of multiple consumers to send messages to. To ensure once-and-only-once delivery, the queue typically ensures that only the consumer assigned per message selector consumes a given message.

For example, to create a queue receiver with a message selector for consuming messages with one property greater than 5 and another property equal to 3:

// Create a selector to receive only text messages with MyProp greater than 5.
String selector = "MyProp1 > 5 AND MyProp2 = 3";

// Create a queue receiver using the selector.
QueueReceiver queueReceiver = queueSession.createReceiver(queue, selector);
   

If a consumer is not available for a particular filtered message, the queue skips and retains this message, and then continues processing subsequent messages.

When you configure a queuing application to use application sets, the message selectors can target individual consumers in an application set. Application sets essentially split consumers into logical queues so that the desired once-and-only-once message delivery behavior applies to all consumers inside them. A consumer in one application set can receive the same message as a consumer in another. Message selectors in different application sets let the queue assign messages to selected consumers within the same application set.

7.3. Native Applications

You can use message selectors at the native provider level (i.e., UM sources or receivers written in C, Java, or .NET). Message selectors can work in the native application scenarios listed below.

JMS Producer to UM Receiver - Set option message_selector to the desired message selector string when creating the consumer. This string must follow SQL92 syntax as described in the JMS Specification, for example "MyProp1 = 6 AND MyProp2 < 7". See also Ultra Messaging JMS Options.

UM Source to JMS Consumer - Set message properties so that the name matches that used by the JMS consumer's message selector.

UM Source to UM Receiver - You can use the message selector feature outside of the JMS environment by setting message properties at the UM source, and the message_selector option at the UM receiver.

8.1. UMP Session IDs

A UMP Session ID allows stores to identify an application's sources and receivers by automatically assigning them registration IDs. With session IDs, you do not need to directly assign registration IDs. You assign a UMP session ID by first setting option use_ump_session_ids to True, then assigning the session ID with the setClientID() method, or by setting the client_id option. Note that with this option enabled, UM ignores attempts to maintain registration IDs directly.

When using this option, we recommend that you call the setClientID() function after creating a Connection rather than setting the client_id option, to ensure that each created connection has a unique client identifier .

For more information about UMP registration IDs and session IDs, see Registration Identifiers, and more specifically, Managing RegIDs with Session IDs.

8.2. UMQ Session IDs

You can use UMQ Session IDs to manage context registration IDs and receiver assignment IDs. For expanded information on UMQ Session IDs, see Queue Session IDs.

In configurations where a queue must always send messages, in order, to a specific assigned receiver, use UMQ Session IDs, as described in the next paragraphs. This ensures that if a receiver fails, the queue retains messages for that receiver until it recovers.

To configure this scenario, perform the following steps:

1. Set option message-reassignment-timeout (see Options for a Topic's ume-attributes Element) for the queue to a value of 0.

2. Set option umq_session_id to a unique value. Do not replicate this value elsewhere, even for sending applications.

9.1. Request Sample Application

// Obtain a ConnectionFactory via lookup or direct instantiation
ConnectionFactory factory = (ConnectionFactory)jndiContext.lookup("uJMSConnectionFactory");


// Create a connection - assuming no username/password required for UM
Connection connection = factory.createConnection();

// Create a Session
Session session = connection.createSession(false,
                              javax.jms.Session.AUTO_ACKNOWLEDGE);
// Create request and reply destinations
Destination requestTopic = lookupDestination(requestTopicName);
Destination replyTopic = lookupDestination(replyTopicName);
        
MessageProducer requestProducer = session.createProducer(requestTopic);
MessageConsumer replyConsumer = session.createConsumer(replyTopic);

TextMessage requestMessage = session.createTextMessage();
requestMessage.setText("Hello world.");
requestMessage.setJMSReplyTo(replyTopic);
requestProducer.send(requestMessage);

// start the connection 
connection.start();

// Wait for the reply
Message replyMessage = replyConsumer.receive();

// Could check correlationID, not really necessary with sync request reply
if (replyMessage.getJMSCorrelationID() != requestMessage.getJMSMessageID())
{
    System.err.println("Unexpected reply message"+ e.getMessage());
}
           

9.2. Reply Sample Application

// Obtain a ConnectionFactory via lookup or direct instantiation
ConnectionFactory factory = (ConnectionFactory)jndiContext.lookup("uJMSConnectionFactory");


// Create a connection - assuming no username/password required for UM
Connection connection = factory.createConnection();

// Create a Session
Session session = connection.createSession(false,
                              javax.jms.Session.AUTO_ACKNOWLEDGE);
// Create request destination
Destination requestTopic = lookupDestination(requestTopicName);

// Create consumer on request topic     
MessageConsumer requestConsumer = session.createConsumer(requestTopic);

// Create a producer, don't know reply destination at this point.
MessageProducer replyProducer = session.createProducer(null);


// set the message listener callback
msgConsumer.setMessageListener(this);

// start the connection 
connection.start();


// The message listener callback
public void onMessage(Message message)
{
    try
    {
        TextMessage requestMessage = (TextMessage) message;
        String contents = requestMessage.getText();

        // get the reply to destination
        Destination replyDestination = requestMessage.getJMSReplyTo();

        TextMessage replyMessage = session.createTextMessage();
        replyMessage.setText(contents);
        
        replyMessage.setJMSCorrelationID(requestMessage.getJMSMessageID());
        replyProducer.send(replyDestination, replyMessage);
    }
    catch(Exception e)
    {
            System.err.println("Exception occurred: "+ e.getMessage());
                System.exit(-1);
        }
}