A Deprecated WebLogic JMS Features

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

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 "Message-Driven EJBs" in Programming WebLogic Enterprise JavaBeans for Oracle WebLogic Server.

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 A-1 Server Session Pool Facility

Description of Figure A-1 follows
Description of "Figure A-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 A-2 Preparing for Concurrent Message Processing

Description of Figure A-2 follows
Description of "Figure A-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 "Message-Driven EJBs" in Programming WebLogic Enterprise JavaBeans for Oracle WebLogic Server.

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 Basic JMS System Resources" in Configuring and Managing JMS for Oracle WebLogic Server.

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, described at http://www.javasoft.com/products/jms/docs.html.

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, at http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/InitialContext.html#InitialContext(). 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, at http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/InitialContext.html#InitialContext().

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, at http://java.sun.com/javaee/5/docs/api/javax/jms/ServerSessionPool.html.

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, described at http://java.sun.com/javaee/5/docs/api/javax/jms/ConnectionConsumer.html.

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, described at http://java.sun.com/javaee/5/docs/api/javax/jms/ConnectionConsumer.html.

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 Basic JMS System Resources" in Configuring and Managing JMS for Oracle WebLogic Server.

  • 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, described at http://java.sun.com/javaee/5/docs/api/javax/jms/ConnectionConsumer.html.

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, at http://java.sun.com/javaee/5/docs/api/javax/jms/QueueConnection.html. For more information about the ConnectionConsumer class, see the javax.jms.ConnectionConsumer Javadoc, at http://java.sun.com/javaee/5/docs/api/javax/jms/ConnectionConsumer.html.

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, at http://java.sun.com/javaee/5/docs/api/javax/jms/TopicConnection.html. For more information about the ConnectionConsumer class, see the javax.jms.ConnectionConsumer Javadoc, at http://java.sun.com/javaee/5/docs/api/javax/jms/ConnectionConsumer.html.

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:

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:

The code defines the following:

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

  • 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 at http://www.java.sun.com/products/jms/docs.html.

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 described at http://www.java.sun.com/products/jms/docs.html.