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

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:

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

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:

The following figure illustrates the steps required to prepare 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:

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:

Step 3

Create a connection consumer, as follows:

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

The code defines the following:

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:

Step 3

Create a connection consumer, as follows:

 consumer = tcon.createConnectionConsumer(topic, “TRUE”,
	sessionPool, 10);

The code defines the following:

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