Creating Applications Using JMS , 4 of 9

JMS Point-to-Point Model Features

Queues

In the point-to-point model, clients exchange messages using queues - from one point to another. These queues are used by message producers and consumers to send and receive messages.

An administrator creates single-consumer queues by means of the createQueue method in AQjmsSession. A client may obtain a handle to a previously created Queue using the getQueue method on AQjmsSession.

These queues are described as Single-Consumer Queues because a message can be consumed by only a single consumer. Put another way: a message can be consumed exactly once. This raises the question: What happens when there are multiple processes or operating system threads concurrently dequeuing from the same queue? Since a locked message cannot be dequeued by a process other than the one that has created the lock, each process will dequeue the first unlocked message at the head of the queue.

Before using a queue, the queue needs to be enabled for enqueue/dequeue using start call in AQjmsDestination.

After processing, the message is removed if the retention time of the queue is 0, or is retained for a specified retention time. As long as the message is retained, it can be either

queried using SQL on the queue table view, or
dequeued using a QueueBrowser and specifying the message ID of the processed message.

Queue Sender

A client uses a QueueSender to send messages to a Queue. A QueueSender is created by passing a Queue to a session's createSender method. A client also has the option of creating a QueueSender without supplying a Queue. In that case a Queue must be specified on every send operation.

A client can specify a default delivery mode, priority and time-to-live for all messages sent by the QueueSender. Alternatively, the client can define these options on a per message basis.

Example Code

In the BooksOnline application, new orders are to be sent to the new_orders_queue. After creating a JMS connection and session, we create a sender:

public void enqueue_new_orders(QueueSession jms_session, BolOrder new_order)
{
   QueueSender   sender;
   Queue         queue;
   ObjectMessage obj_message;   

   try
   {
       /* get a handle to the new_orders queue */   
       queue = ((AQjmsSession) jms_session).getQueue("OE", "OE_neworders_que");
       sender = jms_session.createSender(queue);
       obj_message = jms_session.createObjectMessage();
       obj_message.setJMSCorrelationID("RUSH");   
       obj_message.setObject(new_order);
       sender.send(obj_message);
       jms_session.commit();   
    }
    catch (JMSException ex)
    {
      System.out.println("Exception: " + ex); 
    }
}

Queue Receiver

A client uses a QueueReceiver to receive messages from a queue. A QueueReceiver is created using the session's createQueueReceiver method. A QueueReceiver can be created with a message selector. This allows the client to restrict messages delivered to the consumer to those that match the selector.

The selector for queues containing payloads of type TextMessage, StreamMessage, BytesMessage, ObjectMessage, MapMessage can contain any expression that has a combination of one or more of the following:

JMSMessageID ='ID:23452345' to retrieve messages that have a specified message ID (all message IDs being prefixed with ID:)

JMS Message header fields or properties:

JMSPriority < 3 AND JMSCorrelationID = 'Fiction'  

JMSCorrelationID LIKE 'RE%'

User defined message properties:

color IN ('RED', BLUE', 'GREEN') AND price < 30000

For queues containing AdtMessages the selector must be a SQL expression on the message payload contents or message ID or priority or correlation ID.

Selector on message id - to retrieve messages that have a specific message ID

msgid = '23434556566767676'

Note: in this case message IDs must NOT be prefixed with 'ID:'
Selector on priority or correlation is specified as follows
```
priority < 3 AND corrid = 'Fiction'
```

Selector on message payload is specified as follows

tab.user_data.color = 'GREEN' AND tab.user_data.price < 30000

Example Scenario and Code

In the BOL application, new orders are retrieved from the new_orders_queue. These orders are then published to the OE.OE_bookedorders_topic. After creating a JMS connection and session, you create a receiver to receive messages:

  public void get_new_orders(QueueSession jms_session)
  {
   QueueReceiver   receiver;
   Queue           queue;
   ObjectMessage   obj_message;   
   BolOrder        new_order;
   BolCustomer     customer;         
   String          state;
   String          cust_name;   

   try
   {

     /* get a handle to the new_orders queue */   
     queue = ((AQjmsSession) jms_session).getQueue("OE", "OE_neworders_que");

     receiver = jms_session.createReceiver(queue);

     for(;;)
     {
       /* wait for a message to show up in the queue */
       obj_message = (ObjectMessage)receiver.receive(10);
       
       new_order = (BolOrder)obj_message.getObject();
       
       customer = new_order.getCustomer();
       state    = customer.getState();
       
       obj_message.clearBody();
       
       /* determine customer region and assign a shipping region*/
    if((state.equals("CA")) || (state.equals("TX")) ||
     (state.equals("WA")) || (state.equals("NV")))
    obj_message.setStringProperty("Region", "WESTERN");
       else
    obj_message.setStringProperty("Region", "EASTERN");
       
       cust_name = new_order.getCustomer().getName();   
       
       obj_message.setStringProperty("Customer", cust_name);
       
    if(obj_message.getJMSCorrelationID().equals("RUSH"))
    book_rush_order(obj_message);
    else
    book_new_order(obj_message);
    
       jms_session.commit();      
     } 
   }
   catch (JMSException ex)
   {
     System.out.println("Exception: " + ex);
   }
}

Queue Browser

A client uses a QueueBrowser to view messages on a queue without removing them. The browser methods return a java.util.Enumeration that is used to scan the queue's messages. The first call to nextElement gets a snapshot of the queue. A QueueBrowser may also optionally lock messages as it is scanning them. This is similar to a "SELECT ... for UPDATE" command on the message. This prevents other consumers from removing the message while they are being scanned.

A QueueBrowser can also be created with a message selector. This allows the client to restrict messages delivered to the browser to those that match the selector.

JMSMessageID ='ID:23452345' to retrieve messages that have a specified message ID (all message IDs being prefixed with ID:)

JMS Message header fields or properties:

JMSPriority < 3 AND JMSCorrelationID = 'Fiction'  

JMSCorrelationID LIKE 'RE%'

User defined message properties:

color IN ('RED', BLUE', 'GREEN') AND price < 30000

For queues containing AdtMessages the selector must be a SQL expression on the message payload contents or messageID or priority or correlationID.

Selector on message id - to retrieve messages that have a specific messageID

msgid = '23434556566767676'

Note: in this case message IDs must NOT be prefixed with 'ID:'
Selector on priority or correlation is specified as follows
```
priority < 3 AND corrid = 'Fiction'
```

Selector on message payload is specified as follows

tab.user_data.color = 'GREEN' AND tab.user_data.price < 30000

Example Scenario and Code

In the BooksOnline application, new orders are put into the new_orders_queue. A client can then browse selected messages.

public void browse_rush_orders(QueueSession jms_session)
{
   QueueBrowser    browser;
   Queue           queue;
   ObjectMessage   obj_message;   
   BolOrder        new_order;
   Enumeration     messages;
   String          customer_name;   

   try
   {
     /* get a handle to the new_orders queue */   
     queue = ((AQjmsSession) jms_session).getQueue("OE", "OE_neworders_que");
     
     /* create a Browser to look at RUSH orders in USA */
     browser = jms_session.createBrowser(queue, 
	                           "JMSCorrelationID = 'RUSH' and country = 'USA' ");
     
     for (messages = browser.getEnumeration() ; messages.hasMoreElements() ;)
     {
       obj_message = (ObjectMessage)messages.nextElement();
       
       new_order = (BolOrder)obj_message.getObject();
       
       customer_name = new_order.getCustomer().getName();
       System.out.println("Customer " +  customer_name + 
           " has placed a RUSH order");
     }
     
     browser.close(); 
   }   
   catch (Exception ex)
   {
     System.out.println("Exception " + ex);
   }
}