Advanced Topic: Using JMS as a Provider to Enable Cluster Support

Pub-sub server applications can run in a WebLogic Server clustered environment so as to provide scalability and server failover. However, pub-sub applications behave differently depending on the message handler (pub-sub server itself or a JMS provider) that is handling the published messages. In the default non-JMS case, the pub-sub server handles all messages and each instance of the pub-sub server on each node of the cluster is independent and isolated. This means that event messages cannot be shared between different server instances. For example, if a client subscribes to channel /chat on node A of the cluster, it cannot receive messages published to channel /chat on node B of the cluster.

If, for a given channel, you want all messages published to all nodes of a cluster to be shareable by all clients subscribed to the channel, then you must configure the channel for JMS. You do this by updating the appropriate <wlps:channel> element in the weblogic-pubsub.xml deployment descriptor of your application.

When a client publishes a message to a JMS-configured channel, the pub-sub server re-sends the message to a JMS topic. JMS message listeners running on each node of the cluster retrieve the messages from the JMS topics and then deliver them to the subscribed clients on their node.

12.6.1 Configuring JMS as a Handler

You configure the JMS as the message handler for an application in the weblogic-pubsub.xml deployment descriptor of the pub-sub server.

First, you declare the configuration of the JMS handler using the

<wlps:jms-handler-mapping> child element of the root <wlps:weblogic-pubsub>

element. This is where you specify the URL of the JMS provider, the connection factory JNDI name, and the JMS topic JNDI name. Then you configure a specific channel to be a JMS channel by adding a <wlps:jms-handler-name> child element.

The following example shows how to configure a JMS handler and channel in the weblogic-pubsub.xml deployment descriptor; only relevant information is shown in bold. See the text after the example for an explanation.

Note: It is assumed in this section that you have already configured your JMS provider and created the connection factory and topic that will be used for the pub-sub JMS channel. See Developing JMS

Applications for Oracle WebLogic Server for information about WebLogic JMS or your provider's documentation for details.

Advanced Topic: Using JMS as a Provider to Enable Cluster Support

Using the HTTP Publish-Subscribe Server 12-21

<wlps:weblogic-pubsub

xmlns:wlps="http://xmlns.oracle.com/weblogic/weblogic-pubsub">

<wlps:server-config>

...

</wlps:server-config>

<wlps:jms-handler-mapping>

<wlps:jms-handler-name>DefaultJmsHandler</wlps:jms-handler-name>

<wlps:jms-handler>

<wlps:jms-provider-url>t3://localhost:7001</wlps:jms-provider-url>

<wlps:connection-factory-jndi-name>ConnectionFactoryJNDI</wlps:connection-factory-jndi-name>

<wlps:topic-jndi-name>TopicJNDI</wlps:topic-jndi-name>

</wlps:jms-handler>

</wlps:jms-handler-mapping>

<wlps:channel>

<wlps:channel-pattern>/chat/**</wlps:channel-pattern>

<wlps:jms-handler-name>DefaultJmsHandler</wlps:jms-handler-name>

</wlps:channel>

</wlps:weblogic-pubsub>

In the preceding example:

■ The <wlps:jms-handler-mapping> element defines a JMS handler named DefaultJmsHandler. The <wlps:jms-handler> child element configures specific properties of DefaultJmsHandler that the pub-sub server uses to delegate messages to the JMS topic; in particular, the JMS provider URL that the pub-sub server uses to access the JNDI tree of the JMS provider is t3://localhost:7001, the connection factory JNDI name is ConnectionFactoryJNDI, and the JNDI name of the topic to which the messages will be delegated is TopicJNDI.

■ The <wlps:jms-handler-name> child element of <wlps:channel> specifies that the channel with pattern /chat is actually a JMS channel, with JMS configuration options specified by the DefaultJmsHandler.

If you do not define jms-provider-url in weblogic-pubsub.xml, the Pub-Sub Server uses the connection-factory-jndi-name and topic-jndi-name elements configured in weblogic-pubsub.xml to look up the reference to the connection factory and topic, as defined by the resource-ref element in web.xml and the res-ref-name element in weblogic.xml.

The following code example demonstrates:

■ defining resource-ref in web.xml (Example 12–5)

■ mapping res-ref-name to the actual JNDI name of the JMS resources in weblogic.xml (Example 12–6)

■ using the connection-factory-jndi-name and topic-jndi-name elements in weblogic-pubsub.xml to reference the connection factory and topic without specifying jms-provider-url (Example 12–7)

Example 12–5 Defining resource-ref for the connection factory and topic in web.xml

<resource-ref>

Advanced Topic: Using JMS as a Provider to Enable Cluster Support

Example 12–6 Mapping res-ref-name to the JNDI name in weblogic.xml

<resource-description>

<res-ref-name>web20/connectionFactory</res-ref-name>

<jndi-name> weblogic.web20.jms.TopicConnectionFactory</jndi-name>

</resource-description>

<resource-description>

<res-ref-name>web20/topic</res-ref-name>

<jndi-name>weblogic.web20.jms.chatTopic</jndi-name>

</resource-description>

Example 12–7 Using connection-factory-jndi-name and topic-jndi-name in weblogic-pubsub.xml

<jms-handler-mapping>

<jms-handler-name>jms-fortest</jms-handler-name>

<jms-handler>

<connection-factory-jndi-name>

web20/connectionFactory </connection-factory-jndi-name>

<topic-jndi-name>

web20/topic </topic-jndi-name>

</jms-handler>

</jms-handler-mapping>

For the full list of JMS handler-related XML elements you can include in the

weblogic-pubsub.xml deployment descriptor, see the weblogic-pubsub.xsd schema at http://xmlns.oracle.com/weblogic/weblogic-pubsub.

12.6.2 Configuring Client Session Failover

In addition to server failover, the pub-sub server also supports client session failover in clustered environments. In client failover, whenever the status of the client changes, such as when it subscribes or unsubscribes to a channel, the latest client status is stored into a replicated HTTP session. If one node of the cluster crashes, WebLogic Server attempts to recover the clients on the crashed node by moving them to other available nodes using the replicated HTTP sessions.

To configure client session failover, update the weblogic.xml deployment descriptor file of the Web application that hosts the pub-sub application by adding a

<session-descriptor> child element of the root <weblogic-web-app> element and specify that the persistent store type is replicated_if_clustered, as shown below;

only relevant sections of the file are shown in bold:

<?xml version='1.0' encoding='UTF-8'?>

<weblogic-web-app

xmlns="http://xmlns.oracle.com/weblogic/weblogic-web-app"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

...

<session-descriptor>

<persistent-store-type>replicated_if_clustered</persistent-store-type>

</session-descriptor>

</weblogic-web-app>

Advanced Topic: Persisting Messages to Physical Storage

Using the HTTP Publish-Subscribe Server 12-23