Skip navigation.
Downloads | Product Documentation | Support

Programming WebLogic JMS

# Deprecated WebLogic JMS Features

The following sections describe features that have been deprecated for this release of WebLogic Server :

- Defining Server Session Pools

# Defining Server Session Pools

Note: Session pools are now used rarely, as they are not a required part of the J2EE specification, do not support JTA user transactions, and are largely superseded by message-driven beans (MDBs), which are simpler, easier to manage, and more capable. For more information on designing MDBs, see "Designing and Developing Message-Driven Beans" in Programming WebLogic Enterprise JavaBeans.

WebLogic JMS implements an optional JMS facility for defining a server-managed pool of server sessions. This facility enables an application to process messages concurrently.

The server session pool:

- Receives messages from a destination and passes them to a server-side message listener that you provide to process messages. The message listener class provides an `onMessage()` method that processes a message.
- Processes messages in parallel by managing a pool of JMS sessions, each of which executes a single-threaded `onMessage()` method.

The following figure illustrates the server session pool facility, and the relationship between the application and the application server components.

Figure 13-1 Server Session Pool Facility

As illustrated in the figure, the application provides a single-threaded message listener. The connection consumer, implemented by JMS on the application server, performs the following tasks to process one or more messages:

1. Gets a server session from the server session pool.
2. Gets the server session's session.
3. Loads the session with one or more messages.
4. Starts the server session to consume messages.
5. Releases the server session back to pool when finished processing messages.

The following figure illustrates the steps required to prepare for concurrent message processing.

Figure 13-2 Preparing for Concurrent Message Processing

Applications can use other application server providers' session pool implementations within this flow. Server session pools can also be implemented using message-driven beans. For information on using message driven beans to implement server session pools, see "Designing Message-Driven Beans" in Programming WebLogic Enterprise JavaBeans.

If the session pool and connection consumer were defined during configuration, you can skip this section. For more information on configuring server session pools and connection consumers, see Configuring JMS System Resources in Configuring and Managing WebLogic JMS.

Currently, WebLogic JMS does not support the optional `TopicConnection.createDurableConnectionConsumer()` operation. For more information on this advanced JMS operation, refer to Sun Microsystems' JMS Specification.

## Step 1: Look Up Server Session Pool Factory in JNDI

You use a server session pool factory to create a server session pool.

WebLogic JMS defines one `ServerSessionPoolFactory` object, by default: `weblogic.jms.extensions.ServerSessionPoolFactory:<`name`>`, where <`name`> specifies the name of the JMS server to which the session pool is created.

Once it has been configured, you can look up a server session pool factory by first establishing a JNDI context (`context`) using the NamingManager.InitialContext() method. For any application other than a servlet application, you must pass an environment used to create the initial context. For more information, see the NamingManager.InitialContext() Javadoc.

Once the context is defined, to look up a server session pool factory in JNDI use the following code:

>     factory = (ServerSessionPoolFactory) context.lookup(<ssp_name>);

The `<ssp_name>` specifies a qualified or non-qualified server session pool factory name.

For more information about server session pool factories, see ServerSessionPoolFactory or the weblogic.jms.extensions.ServerSessionPoolFactory Javadoc.

## Step 2: Create a Server Session Pool Using the Server Session Pool Factory

You can create a server session pool for use by queue (PTP) or topic (Pub/Sub) connection consumers, using the `ServerSessionPoolFactory` methods described in the following sections.

For more information about server session pools, see ServerSessionPool or the javax.jms.ServerSessionPool Javadoc.

### Create a Server Session Pool for Queue Connection Consumers

The `ServerSessionPoolFactory` provides the following method for creating a server session pool for queue connection consumers:

>     public ServerSessionPool getServerSessionPool(
>      QueueConnection connection,
>      int maxSessions,
>      boolean transacted,
>      int ackMode,
>      String listenerClassName
>     ) throws JMSException

You must specify the queue connection associated with the server session pool, the maximum number of concurrent sessions that can be retrieved by the connection consumer (to be created in step 3), whether or not the sessions are transacted, the acknowledge mode (applicable for non-transacted sessions only), and the message listener class that is instantiated and used to receive and process messages concurrently.

For more information about the `ServerSessionPoolFactory` class methods, see the weblogic.jms.extensions.ServerSessionPoolFactory Javadoc. For more information about the `ConnectionConsumer` class, see the javax.jms.ConnectionConsumer Javadoc.

### Create a Server Session Pool for Topic Connection Consumers

The `ServerSessionPoolFactory` provides the following method for creating a server session pool for topic connection consumers:

>     public ServerSessionPool getServerSessionPool(
>      TopicConnection connection,
>      int maxSessions,
>      boolean transacted,
>      int ackMode,
>      String listenerClassName
>     ) throws JMSException

You must specify the topic connection associated with the server session pool, the maximum number of concurrent sessions that can be retrieved by the connection (to be created in step 3), whether or not the sessions are transacted, the acknowledge mode (applicable for non-transacted sessions only), and the message listener class that is instantiated and used to receive and process messages concurrently.

For more information about the `ServerSessionPoolFactory` class methods, see the weblogic.jms.extensions.ServerSessionPoolFactory Javadoc. For more information about the `ConnectionConsumer` class, see the javax.jms.ConnectionConsumer Javadoc.

## Step 3: Create a Connection Consumer

You can create a connection consumer for retrieving server sessions and processing messages concurrently using one of the following methods:

- Configuring the server session pool and connection consumer during the configuration, as described in Configuring JMS System Resources in Configuring and Managing WebLogic JMS
- Including in your application the Connection methods described in the following sections

For more information about the `ConnectionConsumer` class, see ConnectionConsumer or the javax.jms.ConnectionConsumer Javadoc.

### Create a Connection Consumer for Queues

The `QueueConnection` provides the following method for creating connection consumers for queues:

>     public ConnectionConsumer createConnectionConsumer(
>      Queue queue,
>      String messageSelector,
>      ServerSessionPool sessionPool,
>      int maxMessages
>     ) throws JMSException

You must specify the name of the associated queue, the message selector for filtering messages, the associated server session pool for accessing server sessions, and the maximum number of messages that can be assigned to the server session simultaneously. For information about message selectors, see Filtering Messages.

For more information about the `QueueConnection` class methods, see the javax.jms.QueueConnection Javadoc. For more information about the `ConnectionConsumer` class, see the javax.jms.ConnectionConsumer Javadoc.

### Create a Connection Consumer for Topics

The `TopicConnection` provides the following two methods for creating `ConnectionConsumers` for topics:

>     public ConnectionConsumer createConnectionConsumer(
>      Topic topic,
>      String messageSelector,
>      ServerSessionPool sessionPool,
>      int maxMessages
>     ) throws JMSException

>     public ConnectionConsumer createDurableConnectionConsumer(
>      Topic topic,
>      String messageSelector,
>      ServerSessionPool sessionPool,
>      int maxMessages
>     ) throws JMSException

For each method, you must specify the name of the associated topic, the message selector for filtering messages, the associated server session pool for accessing server sessions, and the maximum number of messages that can be assigned to the server session simultaneously. For information about message selectors, see Filtering Messages.

Each method creates a connection consumer; but, the second method also creates a durable connection consumer for use with durable subscribers. For more information about durable subscribers, see Setting Up Durable Subscriptions.

For more information about the `TopicConnection` class methods, see the javax.jms.TopicConnection Javadoc. For more information about the `ConnectionConsumer` class, see the javax.jms.ConnectionConsumer Javadoc.

## Example: Setting Up a PTP Client Server Session Pool

The following example illustrates how to set up a server session pool for a JMS client. The `startup()` method is similar to the `init()` method in the `examples.jms.queue.QueueSend` example, as described in Example: Setting Up a PTP Application. This method also sets up the server session pool.

The following illustrates the `startup()` method, with comments highlighting each setup step.

Include the following package on the import list to implement a server session pool application:

>     import weblogic.jms.extensions.ServerSessionPoolFactory

Define the session pool factory static variable required for the creation of the session pool.

>     private final static String SESSION_POOL_FACTORY=
>     	"weblogic.jms.extensions.ServerSessionPoolFactory:examplesJMSServer";

>     private QueueConnectionFactory qconFactory;
>     private QueueConnection qcon;
>     private QueueSession qsession;
>     private QueueSender qsender;
>     private Queue queue;
>     private ServerSessionPoolFactory sessionPoolFactory;
>     private ServerSessionPool sessionPool;
>     private ConnectionConsumer consumer;

Create the required JMS objects.

>     public String startup(
>      String name,
>      Hashtable args
>     ) throws Exception

>     {
>      String connectionFactory = (String)args.get("connectionFactory");
>      String queueName = (String)args.get("queue");
>      if (connectionFactory == null || queueName == null) {
>      	throw new  IllegalArgumentException("connectionFactory="+connectionFactory+
>                          ", queueName="+queueName);
>       }
>      Context ctx = new InitialContext();
>      qconFactory = (QueueConnectionFactory)
>     	ctx.lookup(connectionFactory);
>      qcon =qconFactory.createQueueConnection();
>      qsession = qcon.createQueueSession(false,
>     	Session.AUTO_ACKNOWLEDGE);
>      queue = (Queue) ctx.lookup(queueName);
>      qcon.start();

### Step 1

Look up the server session pool factory in JNDI.

>      sessionPoolFactory = (ServerSessionPoolFactory)
>      		  ctx.lookup(SESSION_POOL_FACTORY);

### Step 2

Create a server session pool using the server session pool factory, as follows:

>      sessionPool = sessionPoolFactory.getServerSessionPool(qcon, 5,
>       	false, Session.AUTO_ACKNOWLEDGE,
>       	examples.jms.startup.MsgListener);

The code defines the following:

- `qcon` as the queue connection associated with the server session pool
- `5` as the maximum number of concurrent sessions that can be retrieved by the connection consumer (to be created in step 3)
- Sessions will be non-transacted (`false`)
- `AUTO_ACKNOWLEDGE` as the acknowledge mode
- The `examples.jms.startup.MsgListener` will be used as the message listener that is instantiated and used to receive and process messages concurrently.

### Step 3

Create a connection consumer, as follows:

>      consumer = qcon.createConnectionConsumer(queue, "TRUE",
>     	sessionPool, 10);

The code defines the following:

- `queue` as the associated queue
- `TRUE` as the message selector for filtering messages
- `sessionPool` as the associated server session pool for accessing server sessions
- `10` as the maximum number of messages that can be assigned to the server session simultaneously

For more information about the JMS classes used in this example, see Understanding the JMS API or the javax.jms Javadoc.

## Example: Setting Up a Pub/Sub Client Server Session Pool

The following example illustrates how to set up a server session pool for a JMS client. The `startup()` method is similar to the `init()` method in the `examples.jms.topic.TopicSend` example, as described in Example: Setting Up a Pub/Sub Application. It also sets up the server session pool.

The following illustrates `startup()` method, with comments highlighting each setup step.

Include the following package on the import list to implement a server session pool application:

>     import weblogic.jms.extensions.ServerSessionPoolFactory

Define the session pool factory static variable required for the creation of the session pool.

>     private final static String SESSION_POOL_FACTORY=
>     	"weblogic.jms.extensions.ServerSessionPoolFactory:examplesJMSServer";

>     private TopicConnectionFactory tconFactory;
>     private TopicConnection tcon;
>     private TopicSession tsession;
>     private TopicSender tsender;
>     private Topic topic;
>     private ServerSessionPoolFactory sessionPoolFactory;
>     private ServerSessionPool sessionPool;
>     private ConnectionConsumer consumer;

Create the required JMS objects.

>     public String startup(
>      String name,
>      Hashtable args
>     ) throws Exception

>     {
>      String connectionFactory = (String)args.get("connectionFactory");
>      String topicName = (String)args.get("topic");
>      if (connectionFactory == null || topicName == null) {
>      	throw new  IllegalArgumentException("connectionFactory="+connectionFactory+
>                          ", topicName="+topicName);
>       }
>      Context ctx = new InitialContext();
>      tconFactory = (TopicConnectionFactory)
>     	ctx.lookup(connectionFactory);
>      tcon = tconFactory.createTopicConnection();
>      tsession = tcon.createTopicSession(false,
>     	Session.AUTO_ACKNOWLEDGE);
>      topic = (Topic) ctx.lookup(topicName);
>      tcon.start();

### Step 1

Look up the server session pool factory in JNDI.

>      sessionPoolFactory = (ServerSessionPoolFactory)
>      		  ctx.lookup(SESSION_POOL_FACTORY);

### Step 2

Create a server session pool using the server session pool factory, as follows:

>      sessionPool = sessionPoolFactory.getServerSessionPool(tcon, 5,
>       	false, Session.AUTO_ACKNOWLEDGE,
>       	examples.jms.startup.MsgListener);

The code defines the following:

- `tcon` as the topic connection associated with the server session pool
- `5` as the maximum number of concurrent sessions that can be retrieved by the connection consumer (to be created in step 3)
- Sessions will be non-transacted (`false`)
- `AUTO_ACKNOWLEDGE` as the acknowledge mode
- The `examples.jms.startup.MsgListener` will be used as the message listener that is instantiated and used to receive and process messages concurrently.

### Step 3

Create a connection consumer, as follows:

>      consumer = tcon.createConnectionConsumer(topic, "TRUE",
>     	sessionPool, 10);

The code defines the following:

- `topic` as the associated topic
- `TRUE` as the message selector for filtering messages
- `sessionPool` as the associated server session pool for accessing server sessions
- `10` as the maximum number of messages that can be assigned to the server session simultaneously

For more information about the JMS classes used in this example, see Understanding the JMS API or the javax.jms Javadoc.