Sun Java System Message Queue 3.7 UR1 Developer's Guide for Java Clients

Working With Sessions

A session is a single-threaded context for producing and consuming messages. You can create multiple message producers and consumers for a single session, but you are restricted to using them serially, in a single logical thread of control.

Table 2–3 shows the methods defined in the Session interface; they are discussed in the relevant sections below.

Table 2–3 Session Methods

Name 

Description 

createProducer

Create message producer 

createConsumer

Create message consumer 

createDurableSubscriber

Create durable subscriber for topic 

unsubscribe

Delete durable subscription to topic 

createMessage

Create null message 

createTextMessage

Create text message 

createStreamMessage

Create stream message 

createMapMessage

Create map message 

createObjectMessage

Create object message 

createBytesMessage

Create bytes message 

createQueue

Create queue destination 

createTopic

Create topic destination 

createTemporaryQueue

Create temporary queue 

createTemporaryTopic

Create temporary topic 

createBrowser

Create message browser 

setMessageListener

Set distinguished message listener 

getMessageListener

Get distinguished message listener 

getAcknowledgeMode

Get session’s acknowledgment mode 

getTransacted

Is session transacted? 

commit

Commit transaction 

rollback

Roll back transaction 

recover

Recover unacknowledged messages 

close

Close session 

Every session exists within the context of a particular connection. The number of sessions you can create for a single connection is limited only by system resources. As described earlier (see Using Connections), you use the connection’s createSession method to create a session:

Session
   mySession = myConnection.createSession(false, Session.AUTO_ACKNOWLEDGE);

The first (boolean) argument specifies whether the session is transacted; see Transacted Sessions for further discussion. The second argument is an integer constant representing the session’s acknowledgment mode, as described in the next section.

Acknowledgment Modes

A session’s acknowledgment mode determines the way your application handles the exchange of acknowledgment information when receiving messages from a broker. The JMS specification defines three possible acknowledgment modes:

The standard JMS Session interface, defined in package javax.jms, defines static constants for the first three acknowledgment modes (AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, and DUPS_OK_ACKNOWLEDGE), to be used as arguments to the connection’s createSession method. The constant representing the fourth mode (NO_ACKNOWLEDGE) is defined in the extended Message Queue version of the interface, in package com.sun.messaging.jms. The session method getAcknowledgeMode returns one of these constants:

int  ackMode = mySession.getAcknowledgeMode();
switch (ackMode)
  {
    case Session.AUTO_ACKNOWLEDGE:
      /* Code here to handle auto-acknowledge mode */
      break;
    case Session.CLIENT_ACKNOWLEDGE:
      /* Code here to handle client-acknowledge mode */
      break;
    case Session.DUPS_OK_ACKNOWLEDGE:
      /* Code here to handle dups-OK-acknowledge mode */
      break;
    case com.sun.messaging.jms.Session.NO_ACKNOWLEDGE:
      /* Code here to handle no-acknowledge mode */
      break;
  }

Note –

All of the acknowledgment modes discussed above apply to message consumption. For message production, the broker’s acknowledgment behavior depends on the message’s delivery mode (persistent or nonpersistent; see Message Header). The broker acknowledges the receipt of persistent messages, but not of nonpersistent ones; this behavior is not configurable by the client.


In a transacted session (see next section), the acknowledgment mode is ignored and all acknowledgment processing is handled for you automatically by the Message Queue client runtime. In this case, the getAcknowledgeMode method returns the special constant Session.SESSION_TRANSACTED.

Transacted Sessions

Transactions allow you to group together an entire series of incoming and outgoing messages and treat them as an atomic unit. The message broker tracks the state of the transaction’s individual messages, but does not complete their delivery until you commit the transaction. In the event of failure, you can roll back the transaction, canceling all of its messages and restarting the entire series from the beginning.

Transactions always take place within the context of a single session. To use them, you must create a transacted session by passing true as the first argument to a connection’s createSession method:

Session
   mySession = myConnection.createSession(true, Session.SESSION_TRANSACTED);

The session’s getTransacted method tests whether it is a transacted session:

if ( mySession.getTransacted() )
  { /* Code here to handle transacted session */
  }
else
  { /* Code here to handle non-transacted session */
  }

A transacted session always has exactly one open transaction, encompassing all messages sent or received since the session was created or the previous transaction was completed. Committing or rolling back a transaction ends that transaction and automatically begins another.


Note –

Because the scope of a transaction is limited to a single session, it is not possible to combine the production and consumption of a message into a single end-to-end transaction. That is, the delivery of a message from a message producer to a destination on the broker cannot be placed in the same transaction with its subsequent delivery from the destination to a consumer.


When all messages in a transaction have been successfully delivered, you call the session’s commit method to commit the transaction:

mySession.commit();

All of the session’s incoming messages are acknowledged and all of its outgoing messages are sent. The transaction is then considered complete and a new one is started.

When a send or receive operation fails, an exception is thrown. While it is possible to handle the exception by simply ignoring it or by retrying the operation, it is recommended that you roll back the transaction, using the session’s rollback method:

mySession.rollback();

All of the session’s incoming messages are recovered and redelivered, and its outgoing messages are destroyed and must be re-sent.