JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle GlassFish Server Message Queue 4.5 Developer's Guide for Java Clients
search filter icon
search icon

Document Information


1.  Overview

2.  Using the Java API

Messaging Domains

Working With Connections

Obtaining a Connection Factory

Looking Up a Connection Factory With JNDI

Overriding Configuration Settings

Instantiating a Connection Factory

Using Connections

Creating Secure Connctions (SSL)

Working With Destinations

Looking Up a Destination With JNDI

To Look Up a Destination With JNDI

Instantiating a Destination

Temporary Destinations

Working With Sessions

Acknowledgment Modes

Transacted Sessions

Working With Messages

Message Structure

Message Header

Message Properties

Message Body

Composing Messages

Composing Text Messages

Composing Stream Messages

Composing Map Messages

Composing Object Messages

Composing Bytes Messages

Sending Messages

Receiving Messages

Creating Message Consumers

Message Selectors

Durable Subscribers

Receiving Messages Synchronously

Receiving Messages Asynchronously

Acknowledging Messages

Browsing Messages

Closing a Consumer

Processing Messages

Retrieving Message Header Fields

Retrieving Message Properties

Processing the Message Body

Processing Text Messages

Processing Stream Messages

Processing Map Messages

Processing Object Messages

Processing Bytes Messages

3.  Message Queue Clients: Design and Features

4.  Using the Metrics Monitoring API

5.  Working with SOAP Messages

6.  Embedding a Message Queue Broker in a Java Client

A.  Warning Messages and Client Error Codes


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

Create message producer
Create message consumer
Create durable subscriber for topic
Delete durable subscription to topic
Create null message
Create text message
Create stream message
Create map message
Create object message
Create bytes message
Create queue destination
Create topic destination
Create temporary queue
Create temporary topic
Create message browser
Set distinguished message listener
Get distinguished message listener
Get session’s acknowledgment mode
Is session transacted?
Commit transaction
Roll back transaction
Recover unacknowledged messages
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:

   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 */
    case Session.CLIENT_ACKNOWLEDGE:
      /* Code here to handle client-acknowledge mode */
    case Session.DUPS_OK_ACKNOWLEDGE:
      /* Code here to handle dups-OK-acknowledge mode */
    case com.sun.messaging.jms.Session.NO_ACKNOWLEDGE:
      /* Code here to handle no-acknowledge mode */

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:

   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 */
  { /* 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:


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:


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