3 Designing a Messaging Bridge

When to use a Messaging Bridge

The following sections provide information on when to use a messaging bridge:

• Store and Forward Messaging

• Replicating a Topic

When to Avoid using a Messaging Bridge

The following sections provide information on when to avoid using messaging bridge:

• Receiving messages from a remote destination—Use a message driven EJB or implement a client consumer directly.

• Sending messages to a local destination—Send directly to the local destination.

• Environment with low tolerance for message latency. Messaging Bridges increase latency and may lower throughput. Messaging bridges increase latency for messages as they introduce an extra destination in the message path and may lower throughput because they forward messages using a single thread.

• Forward messages between WebLogic 9.0 and higher domains—Use WebLogic Store-and-Forward.

Table 3-1 summarizes information on when to use WebLogic Messaging Bridge or other forwarding technologies:

Selecting a Quality-of-Service (QOS) Level

The WebLogic Messaging Bridge supports three different QOS levels:

• Exactly-once—The highest QOS guarantees that a message is sent to the remote endpoint once and only once. With Exactly-once, messages survive server crashes and network down time, while guaranteeing one occurrence of each message at the endpoint.

• At-least-once—Guarantees that a message is sent to the remote endpoint, but with the possibility of duplicates. With At-least-once, multiple copies of a message may appear on the remote endpoint because of network failures or server crashes that occur when the message is in transit.

• At-most-once—The lowest QOS guarantees that each message is sent to the remote endpoint only once, if at all. It does not guarantee that a message is sent to the endpoint. With At-most-once, messages may get lost because of network failures or server crashes. No duplicate messages reach the endpoint.

In some instances, the target destination may not be able to provide the quality of service configured for the bridge. In these cases, configure the bridge instance to allow the quality of service to be degraded by setting the QOSDegradationAllowed flag. See "Create messaging bridge instances" in Oracle WebLogic Server Administration Console Help.

Messaging Persistence

Store-and-forward messaging enables a local JMS client to produce messages to a local destination and have those messages automatically forwarded to a remote destination when it is available. The bridge forwards these messages to the target destination when it is restarted. A messaging bridge stores and forwards messages to a target destination under the following conditions:

• The source destination is a queue.

• The source destination is a topic and the "Durability Enabled" attribute is set. This creates a durable subscription. For more information configuring durable topic subscribers, see "Setting Up Durable Subscriptions" in Programming JMS for Oracle WebLogic Server.

Message Ordering

If an application message is in a transaction, saving the message in the persistent store must be part of the user transaction to preserve exactly-once semantics. In particular, the message is removed from the persistent store as part of the transaction rollback if the application decides to rollback the transaction. However, forwarding is not part of the application transaction. The sending agent does not forward a transactional message until the transaction commits. Within a transaction, message ordering is preserved based on when the messages are sent.

To ensure message ordering, configure a message unit-of-order. See "Using Message Unit-of-Order" in Programming JMS for Oracle WebLogic Server.

Setting the Number of Connection Factories

Consider modifying the capacity of the connection factory associated with each resource adaptor by adjusting the initial-capacity and max-capacity attributes the weblogic-ra.xml descriptor file. In general, the value of the max-capacity attribute should be at least two times the number of bridge instances. For example, if your environment has up to ten message bridge instances targeted, a max-capacity attribute setting of 20 in the default configuration is adequate. But if you increase the number of bridge instances to 15, increase the max-capacity attribute to 30.

Use the following steps to modify the weblogic-ra.xml descriptor file:

1. Using the editor of your choice, update the attribute with the desired value. See Example 3-1.

2. Deploy the updated adapter.

3. Stop and restart any bridge instance that requires the new values.

<weblogic-connection-factory-dd>

     <connection-factory-name>WLSJMSConnectionFactoryLocal</connection-factory-name>
     <jndi-name>eis/jms/WLSConnectionFactoryJNDILocal</jndi-name>
          <pool-params>
               <initial-capacity>0</initial-capacity>
               <max-capacity>20</max-capacity>
          </pool-params>

</weblogic-connection-factory-dd>

Preserving Message Properties

Set PreserveMsgProperty to preserve message properties in a message header when a message is forwarded by a bridge instance. In previous releases, message properties are inherited from the Default Delivery Mode attribute on the connection factory used when a message is forwarded to its target destination. If the Default Delivery Mode is persistent, a non-persistent message is forwarded as a persistent message resulting in a significant performance loss.

When PreserveMsgProperty is enabled, an incoming non-persistent message is forwarded by the bridge to the target destination as a non-persistent message and an incoming persistent message is forwarded to the target destination as a persistent message. See "Configure messaging bridge instances" in Oracle WebLogic Server Administration Console Help.

The behavior of a messaging bridge instance is determined according to the following guidelines:

• The PreserveMsgProperty is not enabled. This setting provides the same forwarding behavior as previous releases.

• The default value of PreserveMsgProperty when configuring a messaging bridge instance is not enabled.

• The PreserveMsgProperty is enabled. Message properties are preserved as described in Table 3-2:

Using the JMSXUserID Property with a Messaging Bridge

The messaging bridge does not disclose a message's JMSXUserID across messaging bridge boundaries. A JMSXUserID is a system generated property that identifies the user sending the message, see the JMS Specification, published by Sun Microsystems, Inc., at http://java.sun.com/products/jms/docs.html.

Using Distributed Destinations as Source and Target Destinations

A messaging bridge can send to and receive from "distributed destinations". Oracle recommends the following configurations:

• If the source is a distributed destination, the bridge is pinned to one of the members when it connects to the destination. It stays connected to that member until an event occurs that breaks the connection. On reconnection, the bridge uses the next available member. Once a bridge is connected, it does not receive messages from other members of the distributed destination. It is a best practice to configure one bridge for each member of a distributed destination using the member's JNDI Name.

• If the target is a distributed destination, the best practice is to send to the distributed destination using the distributed destination's JNDI Name and disable server affinity. This allows the distributed destination to load balance incoming messages. See "Load Balancing for JMS" in Using Clusters for Oracle WebLogic Server.

Tuning a WebLogic Messaging Bridge

The main objective when tuning a messaging bridge is to improve overall messaging performance. Raw speed, though important, is only one of several performance-related factors. Other performance factors include reliability, scalability, manageability, monitoring, user transactions, message-driven bean support, and integration with an application server. See "Tuning WebLogic Message Bridge" in Performance and Tuning for Oracle WebLogic Server.