This chapter describes how to configure and use Server Session Pools, a deprecated JMS facility for defining a server-managed pool of server sessions. This facility enables an application to process messages concurrently a deprecated release of WebLogic Server.
Note:
Session pools are now used rarely, as they are not a required part of the Java EE 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 Developing Enterprise JavaBeans, Version 2.1, 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.
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:
Gets a server session from the server session pool.
Gets the server session's session.
Loads the session with one or more messages.
Starts the server session to consume messages.
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
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 Developing Enterprise JavaBeans, Version 2.1, 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 Administering JMS Resources 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 the JMS Specification, described at http://www.oracle.com/technetwork/java/jms/index.html
.
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://docs.oracle.com/javase/6/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://docs.oracle.com/javase/6/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.
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://docs.oracle.com/javaee/7/api/javax/jms/ServerSessionPool.html
.
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://docs.oracle.com/javaee/7/api/javax/jms/ConnectionConsumer.html
.
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://docs.oracle.com/javaee/7/api/javax/jms/ConnectionConsumer.html
.
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 Administering JMS Resources 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://docs.oracle.com/javaee/7/api/javax/jms/ConnectionConsumer.html
.
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://docs.oracle.com/javaee/7/api/javax/jms/QueueConnection.html
. For more information about the ConnectionConsumer
class, see the javax.jms.ConnectionConsumer
Javadoc, at http://docs.oracle.com/javaee/7/api/javax/jms/ConnectionConsumer.html
.
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://docs.oracle.com/javaee/7/api/javax/jms/TopicConnection.html
. For more information about the ConnectionConsumer
class, see the javax.jms.ConnectionConsumer
Javadoc, at http://docs.oracle.com/javaee/7/api/javax/jms/ConnectionConsumer.html
.
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 Point-To-Point JMS Application Using Classic API. 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();
Look up the server session pool factory in JNDI.
sessionPoolFactory = (ServerSessionPoolFactory) ctx.lookup(SESSION_POOL_FACTORY);
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.
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.oracle.com/technetwork/java/jms/index.html
.
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 Publish-Subscribe JMS Application Using Classic API. 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();
Look up the server session pool factory in JNDI.
sessionPoolFactory = (ServerSessionPoolFactory) ctx.lookup(SESSION_POOL_FACTORY);
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.
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.oracle.com/technetwork/java/jms/index.html
.