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.

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.