Sessions

JMS sessions are used for sending and receiving messages. JMS sessions that are created using connections are used for a variety of other purposes as well:

• Sessions provide an alternative method for creating destinations

• Sessions are used for creating temporary destinations

• Sessions are used as factories for creating different types of provider-optimized implementation of JMS messages

• Sessions are used for creating message producers and consumers

• Sessions can be used for receiving the messages associated with all the message consumers asynchronously

The basic methods required for JMS sessions are defined in the interface javax.jms.Session. This interface has specialized sub-interfaces used for specific purposes. Those interfaces are listed below:

• javax.jms.QueueSession

  Queue sessions are used in PTP messaging.

• javax.jms.TopicSession

  Topic sessions are used in Pub/Sub messaging.

• javax.jms.XASession

  XA sessions are sessions that support JTA (Java Transaction API).

• javax.jms.XAQueueSession

  These sessions are queue sessions that support JTA. These sessions extend the interface of XA sessions.

• javax.jms.XATopicSession

  These sessions are topic sessions that support JTA. These sessions extend the interface of XA sessions.

Creating JMS Messages

Sessions can be used for creating optimized provider implementations of JMS messages. As we have already seen the JMS specification defines interfaces for the different JMS entities like connections, sessions, messages, etc. It is the JMS providers who provide implementation classes for these interfaces. The JMS specification defines different types of message and the interface for JMS sessions defines factory methods for creating all these messages. The signatures for these methods are listed below:

Method	Description
public BytesMessage createBytesMessage () throws JMSException	Creates objects of type BytesMessage. The interface BytesMessage represents message objects holding a stream of uninterpreted bytes.
public MapMessage createMapMessage () throws JMSException	Creates objects of type MapMessage. The interface MapMessage represents message objects holding a map of key/value pairs.
public ObjectMessage createObjectMessage() throws JMSException	Creates objects of type ObjectMessage. The interface ObjectMessage represents message objects holding serialized Java objects.
public ObjectMessage createObjectMessage (Object obj) throws JMSException	Creates objects of type ObjectMessage prepopulated with the object passed to the method.
public StreamMessage createStreamMessage() throws JMSException	Creates objects of type StreamMessage. The interface StreamMessage represents message objects holding a stream of Java primitives.
public TextMessage createTextMessage() throws JMSException	Creates objects of type TextMessage. The interface TextMessage represents message objects holding plain text.
public TextMessage createTextMessage (String text) throws JMSException	Creates objects of type TextMessage prepopulated with the text passed to the method.

Destinations and Temporary Destinations

In the section on Administered objects we have seen that one way to get a reference to static destinations stored in a namespace is looking up those objects using JNDI. However, clients can also create destinations when they need to dynamically manipulate the destination identity, using provider-specific names for destinations.

Note 

It is worthwhile to note that clients using this functionality may not be portable across different JMS providers. The method used for this purpose is specific to messaging models and is defined in the session interfaces specific to messaging models.

The interfaces javax.jms.QueueSession and javax.jms.TopicSessions defines the methods for creating destinations for PTP and Pub/Sub messaging model respectively:

Method	Description
public Queue createQueue (String queueName) throws JMSException	Creates queues
public Topic-createTopic (String topicName) throws JMSException	Creates topics
public TemporaryQueue createTemporaryQueue (String queueName) throws JMSException	Creates temporary queues
public TemporaryTopic createTemporaryTopic String topicName) throws JMSException	Creates temporary topics

The first two methods don't create the destinations physically, but get a handle to the destination stored by the JMS administrator. These methods throw JMSException if the provider fails to return a handle to the specified destination.

Creating Message Processors

In JMS terminology objects used for creating messages are called message producers and objects receiving messages are called message consumers. Message producers and consumers used in the PTP messaging model are called queue senders and queue receivers and those used in the Pub/Sub model are called topic publishers and topic subscribers respectively. One of the primary purposes of JMS sessions is the creation of message consumers and producers. In the same way that a JMS connection can have multiple JMS sessions associated with it, a JMS session can have multiple consumers and producers associated with it.

The interface javax.jms.QueueSession defines factory methods for creating queue senders and queue receivers:

Method	Description
public QueueSender createSender (Queue queue) throws JMSException, InvalidDestinationException	Creates a queue sender for the specified queue that can be used by the session to send messages to this queue.
public QueueReceiver createReceiver (Queue queue) throws JMSException, InvalidDestinationException	Creates a queue receiver for the specified queue that can be used by the session to receive messages from this queue.
public QueueReceiver createReceiver (Queue queue, String selector) throws JMSException, InvalidDestinationException, InvalidSelectorException	Creates a queue receiver for the specified queue that can be used by the session to receive messages from this queue with the specified message selector.

Note 

Message selectors are used for filtering messages and are explained in detail in Appendix B.

All these methods throw JMSException if the provider fails to fulfill the request due to any internal error. In addition they throw InvalidDestinationException if the destination is not valid and InvalidSelectorException if the message selector is not valid.

The interface javax.jms.TopicSession defines factory methods for creating publishers and subscribers:

Method	Description
public TopicPublishercreatePublisher (Topic topic) throws JMSException, InvalidDestinationException	Creates a topic publisher for the specified topic that can be used by the session to send messages to this topic.
public TopicSubscribercreateSubscriber (Topic topic) throws JMSException, InvalidDestinationException	Creates a topic subscriber for the specified topic that can be used by the session to receive messages from this topic.
public TopicSubscriber createSubscriber (Topic topic, String selector, boolean noLocal) throws JMSException, InvalidDestinationException, InvalidSelectorException	Creates a topic subscriber for the specified topic. The third argument specifies whether the subscriber should receive messages published by publishers belonging to the same connection.

The interface javax.jms.TopicSession also defines methods for creating durable subscribers. JMS clients for receiving messages published even when they are inactive use durable subscribers. There are two methods defined for creating durable subscribers:

     public TopicSubscriber createDurableSubscriber (Topic topic, String name)                             throws JMSException, InvalidDestinationException     public TopicSubscriber createDurableSubscriber (Topic topic, String name,                        String selector, boolean noLocal) throws JMSException,                         InvalidDestinationException, InvalidSelectorException 

Both of these methods are similar to their non-durable counterparts apart from the fact that they provide an extra argument to specify a name to identify the subscription. JMS clients using durable subscription should use the same client identifier each time they connect to the provider. Durable subscriptions are covered in detail in Chapter 5.

Asynchronous Message Delivery

As we have already seen, messages are delivered to the message consumers associated with a session. Message consumers can receive messages either synchronously or asynchronously. Message consumers are explained in detail in later sections. A JMS session can be set to asynchronously receive the messages for all of its message consumers. This is done using the interface javax.jms.MessageListener that defines a callback method for asynchronous message delivery. The interface javax.jms.Session defines a method for registering message listeners:

     public void setMessageListener (MessageListener listener) throws JMSException 

This interface also defines an accessor method for the registered message listener:

     public MessageListener getMessageListener () throws JMSException 

javax.jms.MessageListener

This interface defines the callback method for asynchronous message delivery. JMS clients that need asynchronous message delivery should register an implementation of this interface with either the session or the message consumer:

     public void onMessage (Message msg) 

The interface javax.jms.Message is the root interface for all the JMS message interfaces. At runtime, the argument will be an implementation class of one of the specific JMS message interfaces.

Transaction Support

JMS sessions can be optionally defined as transaction bound. Transacted sessions can treat a set of messages sent and received as a single atomic unit. This means all the messages in a transaction are either processed completely or not processed at all. The factory methods defined in JMS connection interfaces take an argument to specify whether the created sessions are to be transaction bound or not.

The interface javax.jms.Session interface defines two methods for handling transactions. The first method is used for committing a transaction:

     public void commit() throws JMSException, TransactionRolledBackException,                                                         IllegalStateException 

The second method is used for rolling back a transaction:

 public void rollback() throws JMSException, IllegalStateException 

Both of these methods complete the current transaction and start a new one.

Acknowledging Messages

Message acknowledgement is automatic for transacted sessions when the transactions are committed. For non-transacted sessions there are three modes of message acknowledgement. Message acknowledgement mode is defined when the sessions are created using the factory methods provided by JMS connections.

These methods take the acknowledgement mode as one of their arguments. The different acknowledgement modes are enumerated as public static member variables in the interface javax.jms.Session.

The different message acknowledgement modes are explained below:

• _AUTO_ACKNOWLEDGE

  In this mode sessions automatically acknowledge message delivery when the message processing thread returns from the callback method of the message listener for asynchronous delivery or the receive () method of the message consumer for synchronous delivery. Asynchronous message delivery is already covered in a previous section. Synchronous message delivery is covered in the section on message consumers.

• CLIENT_ACKNOWLEDGE

  In this mode clients explicitly acknowledge messages by calling the acknowledge () method on messages.

• DUPS_OK_ACKNOWLEDGE

  In this mode, sessions lazily acknowledge messages. In this case the provider may deliver a message more than once. This mode should only be used with consumers that are tolerant of duplicate messages. The benefit of using this mode is a reduction in session overhead achieved by minimizing the work the session does to prevent duplicate messages being delivered.

An example of a session that automatically acknowledges message delivery can be seen below:

     QueueConnection qCon = qcf.createQueueConnection();     QueueSession qSes = qCon.createQueueSession(false, QueueSession.AUTO_ACKNOWLEDGE);