|
|
| |
Using the WebLogic Messaging Bridge
The following sections explain how to configure and manage a WebLogic Messaging Bridge:
What Is a Messaging Bridge?
The WebLogic Messaging Bridge allows you to configure a forwarding mechanism between any two messaging products—thereby, providing interoperability between separate implementations of WebLogic JMS or between WebLogic JMS and another messaging product. You can use the WebLogic Messaging Bridge to integrate your messaging applications between:
A messaging bridge consists of two destinations that are being bridged: a source destination from which messages are received, and a target destination to which messages are forwarded. For WebLogic JMS and third-party JMS products, a messaging bridge communicates with source and target destinations using the resource adapters provided with WebLogic Server. For non-JMS messaging products, a custom adapter must be obtained from a third-party OEM vendor or by contacting BEA Professional Services in order to access non-JMS source or target destinations.
Source and target bridge destinations can be either queues or topics. For example, messages that are sent to a source topic or queue are automatically forwarded by the messaging bridge to a designated target topic or queue. You can also specify a quality of service (QOS), as well as message filters, transaction semantics, and connection retry policies.
Once a messaging bridge is configured, it is easily managed from the Administration Console, including temporarily suspending bridge traffic whenever necessary, tuning the execute thread pool size to suit your application, and monitoring the status of all your configured bridges.
Messaging Bridge Configuration Tasks
Before you can deploy a messaging bridge, you need to configure its required components:
About the Bridge's Resource Adapters
A messaging bridge uses resource adapters to communicate with the configured source and target JMS destinations. You need to associate both the source and target JMS destinations with a supported adapter in order for the bridge to communicate with them. The JNDI name for the adapter is configured as part of the adapter's deployment descriptor.
Note: Although WebLogic JMS includes a provisional "General Bridge Destination" framework for accessing non-JMS messaging products, WebLogic Server does not provide supported adapters for such products. Therefore, you must obtain a custom adapter from a third-party OEM vendor and consult their documentation for configuration instructions. You could also contact BEA Professional Services more information about obtaining a custom non-JMS adapter.
The supported adapters are located in the WL_HOME\lib
directory and are described in the following table.
Adapter |
JNDI Name |
Description |
---|---|---|
|
|
Provides transaction semantics via
Note: Before deploying this adapter, refer to the Using the Messaging Bridge to Interoperate with Different WebLogic Server Versions and Domains for specific transactional configuration requirements and guidelines. |
|
|
Provides no transaction semantics. Used when the required QOS is Atmost-once or Duplicate-okay. If the requested QOS is Atmost-once, the adapter uses the Note: For more information about the acknowledge modes used in non-transacted sessions, see "WebLogic JMS Fundamentals" in Programming WebLogic JMS. |
|
|
Provides interoperability when either the source or target destination is WebLogic Server 5.1. This adapter provides no transaction semantics; therefore, it only supports a QOS of Atmost-once or Duplicate-okay. If the requested QOS is Atmost-once, the adapter uses the |
You will specify the appropriate adapter by its JNDI name when you configure each source and target bridge destination on the Administration Console.
Deploying the Bridge's Resource Adapters
Before you configure the messaging bridge components, deploy the appropriate resource adapters in the WebLogic Server domain that is hosting the messaging bridge, using either of the following methods:
RAR
adapter file, as defined in Messaging Bridge Adapters and JNDI Names.
\applications
directory of the administration server, they will be automatically deployed if the server is already running. Otherwise, they will be deployed the next time you start WebLogic Server. The auto deployment method is used only in a single-server development environment for testing an application, and is not recommended for use in production mode.
Note: When configuring a messaging bridge to interoperate between WebLogic Server release 6.1 and release 5.1, then the release 5.1 resource adapter (jms-notran-adp51.rar
) and the non-transaction adapter (jms-notran-adp.rar
) must be deployed on the 6.1 domain running the messaging bridge.
For step-by-step instructions on deployment tasks using the Administration Console, or for more information on using the auto-deployment feature, see Deploying Applications.
Configuring the Source and Target Bridge Destinations
A messaging bridge connects two actual destinations that are mapped to bridge destinations: a source destination from which messages are received, and a target destination to which messages are sent. Depending on the messaging products that need to be bridged, there are two types of bridge destinations:
JMSBridgeDestination
instance for each actual source and target JMS destination being mapped to a messaging bridge.
BridgeDestination
instance for each actual source and target destination being mapped to a messaging bridge.
Before starting the procedure in this section, refer to the Using the Messaging Bridge to Interoperate with Different WebLogic Server Versions and Domains for specific configuration requirements and guidelines.
Configuring JMS Bridge Destinations
A JMSBridgeDestination
instance defines a unique name for the actual JMS queue or topic destination within a WebLogic domain, the name of the resource adapter used to communicate with the specified destination, property information to pass to the adapter (Connection URL, Connection Factory JNDI Name, etc.), and, optionally, a user name and password.
You need to configure a JMSBridgeDestination
instance for each actual source and target JMS destination to be mapped to a messaging bridge. Therefore, when you finish defining attributes for a source JMS bridge destination, repeat these steps to configure a target JMS bridge destination, or vice versa. You will designate the source and target JMS Bridge Destinations in Configuring a Messaging Bridge Instance.
To configure a JMS bridge destination, follow these steps.
The following table describes the attributes you set on the Configuration tab.
Attribute |
Description |
---|---|
Name |
A JMS bridge destination name for the actual JMS destination being mapped to the bridge. This name must be unique across a WebLogic domain. For example, if you are bridging between WebLogic Server releases 6.1 and 7.0, for the source destination you could change the default bridge destination name to "61to70SourceDestination". Then, when you create the corresponding target destination, you could name it as "61to70TargetDestination". Once the bridge destinations are configured, these names are listed as options in the Source Destination and Target Destination attributes on the Bridges Æ General tab. |
Adapter JNDI Name |
The JNDI name of the resource adapter used to communicate with the bridge destinations. For more information on which adapter name to enter, see Messaging Bridge Adapters and JNDI Names. |
Adapter Classpath |
When connecting to a destination that is running on WebLogic Server 6.0 or earlier, the bridge destination must supply a When connecting to a third-party JMS provider, the bridge destination must supply the provider's |
Connection URL |
The URL of the JNDI provider used to look up the connection factory and destination. |
Initial Context Factory |
The factory used to get the JNDI context. |
Connection Factory |
The JMS connection factory used to create a connection for the actual JMS destination being mapped to the JMS bridge destination. Note: In order to use the Exactly-once QOS, the connection factory has to be a XAConnection Factory. For more information about connection factory and QOS requirements, see Messaging Bridge Attributes on the General Tab. |
Destination JNDI Name |
The JNDI name of the actual JMS destination being mapped to the JMS bridge destination. |
Destination Type |
Select either a Queue or Topic destination type. |
User Name and |
The user name and password that the messaging bridge will give to the bridge adapter. Note: All operations done to the specified destination are done using that user name and password. Therefore, the User Name/Password for the source and target destinations must have permission to access the underlying JMS destinations in order for the messaging bridge to work. |
Configuring General Bridge Destinations
A general BridgeDestination
instance defines a unique name for the actual queue or topic destination within the domain, the name of the resource adapter used to communicate with the specified destination, a list of properties to pass to the adapter, and, optionally, a user name and password.
Note: Although WebLogic JMS includes a provisional "General Bridge Destination" framework for accessing non-JMS messaging products, WebLogic Server does not provide supported adapters for such products. Therefore, you must obtain a custom adapter from a third-party OEM vendor and consult their documentation for configuration instructions. You could also contact BEA Professional Services more information about obtaining a custom non-JMS adapter.
You need to configure a BridgeDestination
instance for each actual source and target destination to be mapped to a messaging bridge. Therefore, when you finish defining attributes for a source general bridge destination, repeat these steps to configure a target general bridge destination, or vice versa. You will designate the source and target general Bridge Destinations in Configuring a Messaging Bridge Instance.
To configure a general bridge destination, follow these steps:
The following table describes the attributes you set on the Configuration tab.
Configuring a Messaging Bridge Instance
A messaging bridge instance communicates with the configured source and target bridge destinations. For each mapping of a source bridge destination to a target bridge destination, whether it is another WebLogic JMS implementation, a third-party JMS provider, or another non-JMS messaging product, you must configure a MessagingBridge
instance via the Administration Console. Each MessagingBridge
instance defines the source and target destination for the mapping, a message filtering selector, a QOS, transaction semantics, and various reconnection parameters.
Before starting the procedure in this section, refer to the Using the Messaging Bridge to Interoperate with Different WebLogic Server Versions and Domains or Bridging to a Third-Party Messaging Provider for specific configuration requirements and guidelines.
To configure a messaging bridge, follow these steps:
The following table describes the attributes you set on the General tab.
Attribute |
Description |
---|---|
Name |
Enter a name for the messaging bridge that is unique across a WebLogic domain. |
Source Destination |
Select the source destination from which messages are received by the messaging bridge. For example, for a JMS messaging bridge, you should select the "JMS Source Bridge Destination" name that you created on the JMS Bridge Destination |
Target Destination |
Select the target destination to which messages are sent from the messaging bridge. For example, for a JMS messaging bridge, you should select the "JMS Target Bridge Destination" name that you created on the JMS Bridge Destination |
Selector |
Allows you to filter the messages that are sent across the messaging bridge. Only messages that match the selection criteria are sent across the messaging bridge. For queues, messages that do not match the selection criteria are left behind and accumulate in the queue. For topics, messages that do not match the connection criteria are dropped. For more information on using selectors to filter messages, see "Developing a WebLogic JMS Application" in Programming WebLogic JMS. |
Quality Of Service (QOS) |
Select a QOS guarantee for forwarding a message across a messaging bridge. The valid qualities of service are: Exactly-once—Each message will be sent exactly once. This is the highest quality of service. In order to use this QOS:
Atmost-once—Each message is sent at most one time. Some messages may not be delivered to the target destination. Duplicate-okay—Each message is sent at least one time. Duplicate messages can be delivered to the target destination. |
QOS Degradation Allowed |
When selected, the messaging bridge automatically degrades the requested QOS when the configured one is not available. If this occurs, a message is delivered to the WebLogic startup window (or log file). If this option is not selected (false), and the messaging bridge cannot satisfy the requested QOS, it will result in an error and the messaging bridge will not start. |
Maximum Idle Time |
For bridges running in asynchronous mode, this is the maximum amount of time, in seconds, the messaging bridge sits idle before checking the health of its connections. For bridges running in synchronous mode, this dictates the amount of time the messaging bridge can block on a receive call if no transaction is involved. |
Asynchronous Mode Enabled |
Defines whether a messaging bridge works in asynchronous mode. Messaging bridges that work in asynchronous mode (true) are driven by the source destination. The messaging bridge listens for messages and forwards them as they arrive. When the value is false, the bridge works in synchronous mode even if the source supports asynchronous receiving. Note: For a messaging bridge with a QOS of Exactly-once to work in asynchronous mode, the source destination has to support the |
Durability Enabled |
This attribute is used only for JMS topics or for destinations with similar characteristics as a JMS topic. By enabling durability, a messaging bridge creates a durable subscription for the source destination. This allows the source JMS implementation to save messages that are sent to it when the bridge is not running. The bridge will then forward these messages to the target destination once it is restarted. If this attribute is not selected, messages that are sent to the source JMS topic while the bridge is down cannot be forwarded to the target destination. Note: If the messaging bridge is running on WebLogic Server 6.1, it cannot support durable subscribers when the source destination is a JMS topic running on WebLogic Server 7.0. This issue has been resolved for messaging bridges running on WebLogic Server 7.0. Note: If a bridge must be taken permanently offline, you must delete any durable subscriptions that use the bridge. For information on deleting durable subscribers, see "Deleting Durable Subscriptions" in Programming WebLogic JMS. |
Started |
Indicates the initial state of the messaging bridge when it is configured and whenever the server is restarted. You can also use this field to dynamically start and stop the messaging bridge. To stop the bridge, clear the check box. Conversely, reselect the check box to restart the bridge. Note: Unless there is a configuration issue that prevents the messaging bridge from starting, this field indicates the expected run-time state of the messaging bridge. For information on monitoring all the configured messaging bridges in your domain, see Monitoring Messaging Bridges. |
The source and target destinations for a messaging bridge will not always be available. As such, the messaging bridge must be able to reconnect to the destination at some periodic interval. These attributes govern the time between reconnection attempts.
Using the Messaging Bridge to Interoperate with Different WebLogic Server Versions and Domains
The following interoperability guidelines apply when using the messaging bridge to access JMS destinations in different releases of WebLogic Server and in other WebLogic Server domains.
Note: When the messaging bridge is used to communicate between two domains running different releases of Weblogic Server, a best-practice recommendation is for the messaging bridge to be configured to run on the domain using the latest release of Weblogic Server.
Naming Guidelines for WebLogic Servers and Domains
Unique naming rules apply to all WebLogic Server deployments if more than one domain is involved. Therefore, make sure that:
Enabling Security Interoperability for WebLogic Domains
Follow these security guidelines when a release 6.1 domain is interoperating with another release 7.0 or later domain:
Note: For more information about release 6.1 domain interoperability security, see "Using Compatibility Security" in Managing WebLogic Security. For more information about WebLogic Server 7.0 domain interoperability security, see "Enabling Trust Between WebLogic Domains" in Managing WebLogic Security.
Using the Messaging Bridge To Access Destinations In a Release 6.1 or Later Domain
Use these guidelines when configuring a messaging bridge on a release 6.1 domain to provide "Exactly-once" transactional message communication between two release 6.1 or later domains.
Note: The Exactly-once quality of service for transactions is only supported for implementations of WebLogic Server 6.1 or later.
jms-xa-adp.rar
, on the 6.1 bridge domain, as described in Deploying the Bridge's Resource Adapters.
eis.jms.WLSConnectionFactoryJNDIXA
.
Using the Messaging Bridging To Access Destinations In a Release 6.0 Domain
When configuring a messaging bridge involves interoperability between WebLogic Server 6.1 and a release 6.0 domain, you must configure the following settings on the release 6.1 domain that the bridge is running on:
Note: The Exactly-once QOS for transactions is not supported for WebLogic Server 6.0. For more information on the bridge QOS options, see Messaging Bridge Attributes on the General Tab.
jms-notran-adp.rar
on the 6.1 bridge domain, as described in Deploying the Bridge's Resource Adapters.
In the Adapter JNDI Name field:
eis.jms.WLSConnectionFactoryJNDINoTX
.
In the Adapter Classpath field:
For example, if you have WebLogic Server 6.0 GA installed in a directory named WL60_HOME
, then set the Adapter Classpath as follows for the 6.0 JMS bridge destination:
WL60_HOME
\lib\weblogic60.jar
Using the Messaging Bridging To Access Destinations In a Release 5.1 Domain
When configuring a messaging bridge involves interoperability between WebLogic Server 6.1 and release 5.1, you must configure the following settings on the release 6.1 domain that the messaging bridge is running on:
Note: The Exactly-once QOS for transactions is not supported for WebLogic Server 5.1. For more information on the bridge QOS options, see Messaging Bridge Attributes on the General Tab.
jms51-interop.jar
file in the WL_HOME
\lib
directory must be in the CLASSPATH
of the WebLogic Server 6.1 implementation.
jms-notran-adp51.rar
) and the non-transaction adapter (jms-notran-adp.rar
) must be deployed on the 6.1 bridge domain, as described in Deploying the Bridge's Resource Adapters.
In the Adapter JNDI Name field:
eis.jms.WLSConnectionFactoryJNDINoTX
.
eis.jms.WLS51ConnectionFactoryJNDINoTX
.
In the Adapter Classpath field:
jms51-interop.jar
file for the 6.1 release.
For example, if you have WebLogic Server 5.1 GA installed in a directory named WL51_HOME
and your WebLogic Server 6.1 release is installed in WL81_HOME
, then set the Adapter Classpath as follows for the 5.1 destination:
WL51_HOME
\classes;
WL51_HOME
\lib\
weblogicaux.jar
;
WL61_HOME
\server\lib\jms51-interop.jar
Note: If your implementation is using a 5.1 Service Pack, the corresponding sp.jar
files must also be added to the Adapter Classpath field.
Bridging to a Third-Party Messaging Provider
When configuring a messaging bridge involves interoperability with a third-party messaging provider, you must configure the following:
CLASSPATH
in the WebLogic Server CLASSPATH
.
PATH
of any native code required by the provider's client-side libraries in the WebLogic Server system PATH
. (This variable may vary depending on your operating system.)
JMSBridgeDestination
instance for the third-party messaging product being bridged, provide vendor-specific information in the following attributes:
For more information on configuring the remaining attributes for a JMS Bridge Destination, see Configuring JMS Bridge Destinations.
Note: The messaging bridge cannot provide the "Exactly-once" quality of service when the source and target bridge destinations are located on the same resource manager (that is, when the bridge is forwarding a global transaction that is using the XA resource of the resource manager). For example, when using MQ Series, it is not possible to use the same Queue Manager for the source and target bridge destinations.
Managing a Messaging Bridge
Once a messaging bridge is up and running, it can managed from the Administration Console.
Stopping and Restarting a Messaging Bridge
To temporarily suspend and restart an active messaging bridge:
Monitoring Messaging Bridges
You can monitor the status of all the messaging bridges in your domain from the Administration Console:
Configuring the Execute Thread Pool Size
You can configure the default execute thread pool size for your messaging bridges from the Administration Console. For example, you may want to increase the default size to reduce competition from the WebLogic Server default thread pool. Entering a value of -1 disables this thread pool and forces a messaging bridge to use the WebLogic Server default thread pool.
For more information about tuning execute threads, see "Tuning WebLogic Server Applications" in the Performance and Tuning Guide.
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|