WebLogics Messaging Bridge

WebLogic s Messaging Bridge

A messaging bridge provides interoperability between any two messaging systems. Messages arriving at one end of the bridge are forwarded automatically to other end, according to specified quality of service (QoS) and transaction semantics. You can set up a messaging bridge in the following scenarios:

• You can configure a bridge between two JMS servers running in your domain, or between two JMS servers running in separate domains, even on different versions of WebLogic.
• You can configure a bridge between WebLogic JMS and any other third-party JMS-compliant product say, IBM MQSeries.

Clearly, it is up to the messaging bridge to handle all the forwarding and any necessary conversions, if it is interfacing with non-JMS products.

A messaging bridge runs between two destinations: a source destination from which messages are received, and a target destination to which the messages are sent. These bridge destinations can be either topics or queues. The bridge establishes a pipe between the source and target destinations, and ensures that messages received on the source destination are forwarded to the target destination. Applications that rely on WebLogic JMS can use bridges to integrate easily with other messaging products.

A messaging bridge provides additional facilities as well. In particular, a bridge can provide a certain QoS when forwarding messages from the source to the target destination. For instance, a bridge that provides an "exactly-once" guarantee ensures that a two-phase commit is used during the forwarding mechanism. A bridge also can make several attempts to reconnect to the source or target destinations if either becomes unavailable for some reason. This ensures that bridges provide a robust integration between two messaging systems.

Later in this chapter, we shall see how to temporarily suspend all traffic running through the bridge, and adjust the size of the execute thread pool.

8.6.1 Installing a Messaging Bridge

WebLogic's messaging bridges are supplied as resource adapters. Three different bridge adapters come shipped with your WebLogic distribution, one for bridging to a JMS server running on WebLogic 5.1, and two for bridging to any JMS-compliant products. The choice depends on the kind of transaction semantics you need. Table 8-3 describes the three adapters that are supplied with WebLogic Server.

Table 8-3. JMS bridges supplied with WebLogic Server

Adapter name	JNDI name	Bridge characteristics
jms-xa-adp.rar	eis.jms.WLSConnection FactoryJNDIXA	This bridge provides transaction semantics via an XAResource. It should be used when the QoS needs to be "exactly-once."
jms-notran-adp.rar	eis.jms.WLSConnection FactoryJNDINoTX	This bridge provides no transaction semantics, and so can be used when the QoS is "at most-once" or "duplicate-okay."
jms-notran-adp51.rar	eis.jms.WLS51Connection FactoryJNDINoTX	This bridge should be used when either the source or target destination is a WebLogic Server 5.1 server.

All of these adapters can be found in the WL_HOMEserverlib directory of your WebLogic installation. If you would like to bridge to a destination on a non-JMS messaging system, you can either create your own bridge or acquire one from the vendor. These resource adapters should be installed just like any other. Refer to Chapter 7 for more information on how to deploy resource adapters. The JNDI names listed in Table 8-3 will be needed later, when we use the adapter.

All of the configuration for a messaging bridge takes place under the Services/Messaging Bridge node in the left pane of the Administration Console. Use the JMS Bridge Destinations node to configure the source and target destinations for the bridge. Use the General Bridge Destinations node if you intend to bridge to non-JMS destinations. Of course, you must create the bridge destinations first before you can create the messaging bridge itself. All of the messaging bridges can be found under the Bridges node. For now, we will look only at how to set up a bridge between WebLogic JMS and another JMS product (IBM MQSeries).

8.6.2 Configuring Bridge Destinations

To use a bridge, you will have to create a bridge destination for both the source and target destinations. Create each by selecting the JMS Bridge Destinations node and then selecting the "Configure a New JMS Bridge Destination" option. Table 8-4 lists the main configuration options that you need to set when creating a bridge.

Table 8-4. Configuration settings for a bridge destination

Setting	Description
Name	Use this attribute to specify a name for the destination. It should be unique across the domain.
Adapter JNDI Name	Use this attribute to set the JNDI name of the adapter that will be used to communicate with the destination. Refer to the adapter's documentation to find the JNDI name that should be used. Table 8-3 lists the JNDI names for the bridge adapters supplied by WebLogic.
Adapter Classpath	Use this option only if you are bridging to WebLogic Server 6.0 or earlier. If you are bridging to a third-party JMS provider, instead you must include the JMS provider's libraries in WebLogic's classpath.
Connection URL	Use this attribute to define the URL of the JNDI provider that will be used to look up the connection factory and the destination.
Initial Context Factory	Use this attribute to define the class name of the initial context factory for the destination.
Connection Factory JNDI Name	Use this attribute to hold the JNDI name of the connection factory that will be used to create connections. If the QoS is to be Exactly-once, an XAConnection Factory name must be supplied.
Destination JNDI Name	Use this attribute to determine the JNDI name of the JMS destination.
Destination Type	Use this setting to specify whether the destination is a queue or a topic.
User Name	Use this optional attribute to determine the username that enables the bridge to access the destination.
Password	Use this optional attribute to determines the password that enables the bridge to access the destination.

 

8.6.2.1 Example configuration of bridge destinations

Suppose we wish to create a bridge between IBM MQSeries and WebLogic JMS so that messages arriving on a queue on IBM MQSeries are forwarded automatically to another queue on WebLogic JMS. This means that we need to configure two bridge destinations: a source destination representing the queue on IBM MQSeries, and a target destination representing the queue on WebLogic JMS. Figure 8-5 illustrates the configuration of the destinations in our sample bridge MyBridge.

Figure 8-5. Configuring a non-XA JMS bridge between IBM MQSeries and WebLogic JMS

In this case, we're using a nontransactional bridge adapter, so the Adapter JNDI Name for both bridge destinations will be set to eis.jms.WLSConnectionFactoryJNDINoTX. You also must ensure that the required connection factories and JMS queues are set up on either JMS providers. Later in this chapter, we take a closer look at the configuration of this JMS bridge.

8.6.3 Configuring the Messaging Bridge

Now that you've set up the bridge destinations, you're ready to configure a messaging bridge and the manner in which it forwards messages from the source to the target destination. To create a bridge, click the Messaging Bridges/Bridges node in the left pane, and then select the Configure a New Messaging Bridge option. There are three sets of configuration tabs that we shall look at in turn.

8.6.3.1 General settings

Table 8-4 describes the configuration attributes that are provided in the General tab. Not surprisingly, the most important thing to do is to set the source and destination to the appropriate JMS Bridge Destinations that have been created. A bridge can provide one of three levels of QoS guarantees when forwarding messages:

Atmost-once

Each message is sent, at most, once in this mode. It is possible that some messages may not be delivered to the target destination. Use the nontransactional bridge adapter for this mode, and do not use XA-enabled connection factories.

Duplicates-only

Each message is sent at least once in this mode. All messages are delivered, though some may be delivered to the target destination more than once. Use the nontransactional bridge adapter for this mode, and do not use XA-enabled connection factories.

Exactly-once

Each message will be sent exactly once in this mode. You can use this mode only if both the source and target destinations are XA-enabled that is, both bridge destinations are configured to use XA-enabled connection factories. You must use the transactional bridge adapter for this mode, and so the Adapter JNDI name for both bridge destinations must be set to eis.jms.WLSConnectionFactoryJNDIXA. It is not recommended that you allow a QoS degradation in this mode.

Note that the Exactly-once mode requires a two-phase commit to be used by the bridge, and is hence the most expensive. If the Exactly-once guarantee is not required, use either of the other two modes for better performance.

The Asynchronous Mode Enabled flag determines whether the bridge may receive messages asynchronously. If the asynchronous mode is chosen, the messaging bridge listens for messages and forwards them as they arrive at the source destination. If the synchronous mode is chosen, the bridge will work in synchronous mode even if the source destination supports asynchronous receiving. In the synchronous mode, messages can forwarded in a batch. For an Exactly-once QoS guarantee, the synchronous mode can greatly improve the performance of the bridge. The asynchronous mode requires the bridge to start a new transaction for each message, performing the two-phase commit across both JMS servers involved in the transaction. If the synchronous mode is used, the two-phase commit will be used less often because the bridge can process multiple messages in each transaction. Thus, for a bridge with Exactly-once guarantees, it is more optimal to not set this flag. On the other hand, if the Exactly-once guarantee is not required, the bridge can forward messages more efficiently in the asynchronous modein which case, you should set the flag.

Table 8-5 explains the rest of the settings.

Table 8-5. General bridge configuration settings

Setting	Description
Name	This attribute specifies a name for the bridge.
Source Destination	This setting provides a drop-down list of all available JMS bridge destinations, and should be set to the destination that is to be the source for the bridge.
Target Destination	This setting provides a drop-down list of all available JMS bridge destinations, and should be set to the destination that is to be the target for the bridge.
Selector	This setting provides an optional message selector for the bridge. Only messages that pass the selector will be forwarded. Note that for queues, messages that do not match the selector accumulate in the queue. For topics, messages that do not match are dropped.
Quality of Service	This setting should be set to Duplicate-okay, Atmost-once, or Exactly-once, as explained earlier.
QoS Degradation Allowed	This setting indicates whether the quality of service can be downgraded if the configured QoS is not available.
Asynchronous Mode Enabled	This setting determines whether the bridge can be used in asynchronous mode.
Maximum Idle Time	If the bridge is in synchronous mode, this setting determines the maximum amount of time the bridge will block on a receive call if no transaction is involved. If the bridge is in asynchronous mode, this setting determines the maximum amount of time the bridge will remain idle before checking the health of the connection to the source destination.
Durability Enabled	This setting applies only to topics that are used as the source JMS destination. If enabled, the messaging bridge will create a durable subscription to the source destination. This means that if the bridge is down, the destination will retain messages sent to it, forwarding them to the target destination when it comes up again. If durability is not enabled, messages sent to the topic while the bridge is down will not be forwarded to the target destination. Note that if a bridge that had durability enabled is deleted, you must delete all durable subscriptions.
Started	This setting indicates the initial state of the bridge when the server is started. You also can use it during runtime to switch the bridge on or off.

 

8.6.3.2 Connection retry settings

The configuration options in the Connection Retry tab allow you to define how the bridge reconnects to a bridge destination if it fails. By doing this, you make your bridge far more robust, especially if durable sources are used, as the bridge will try and reconnect to destinations if the connections fail. There are three settings in this tab minimum, maximum, and incremental delay and all are specified in seconds. The bridge works as follows: if a connection needs to be reestablished, the bridge waits for at least "minimum delay" seconds before attempting to reconnect. Thus, if a connection is lost, or the server fails to reconnect, the minimum delay determines the delay between connection attempts. Each time a connection attempt fails, the incremental delay is added to the current delay before delaying and attempting to reconnect. The reconnect delays are increased by the specified increment, until the maximum delay is met, after which the delay is no longer increased and the bridge gives up.

8.6.3.3 Transaction settings

The configuration options in the Transactions tab tune the transaction characteristics of the bridge. If the bridge is configured to use transactions, use the Transaction Timeout setting to adjust the amount of time that the transaction manager will allow for a transaction to complete. The batch size and interval settings are used only if the bridge is operating in synchronous mode. In this case, the batch size determines the number of messages that will be batched together in a transaction. The batch interval defines the maximum time (in milliseconds) to wait before sending a batch, regardless of whether the batch size has been reached. Setting this attribute to -1 indicates that the bridge must always wait until the batch size is reached. You should experiment with both of these settings to arrive at an optimal configuration for your JMS bridge.

8.6.3.4 Example bridge configuration

Continuing with the earlier example of a bridge between MQSeries and WebLogic JMS, now that we have created two JMS bridge destinations, we need to create the messaging bridge itself. Set the source destination to IBMSource and set the target destination to WLSDest. Because we are using a nontransactional bridge, set the QoS to either Exactly-once or Duplicate-okay. Because durability is not supported for queues, deselect the Durability Enabled option. Ensure that the Started flag is selected, and hit the Apply button. Then restart the server, and you should have a fully operational bridge. Now if you send a message to the queue on the MQSeries, the bridge should forward the message to the queue at WebLogic's end automatically.

8.6.3.5 Monitoring a bridge

The state of a bridge can be determined from the Administration Console. Select the server hosting the bridge and choose the Services/Bridge tab. Clicking "Monitor all Messaging Bridge Runtimes" will show a list of messaging bridges, and their state.

8.6.3.6 Configuring the JMS thread pool

WebLogic has a default execute thread pool, as described in Chapter 15. The JMS bridge, by default, uses a separate thread pool, which is used when the bridge is operating in synchronous mode. You can change the number of threads in the pool by choosing the server hosting the bridge and then selecting the Services/Bridge tab. Next, use the Messaging Bridge Thread Pool Size attribute to adjust the size of this thread pool. Setting this to -1 will force the JMS server to use the default thread pool of the associated WebLogic instance.

Using the thread pool that is dedicated to messaging bridges avoids contention with the default execution pool. Clearly, its optimal size will depend on the characteristics of your bridge traffic and the server itself. As a rule of thumb, though, for best performance there should be at least as many threads in the pool as there are bridges that run in synchronous mode.