External JMS Providers

Sometimes, you may need to use another messaging system to be able to access a legacy application. Many of the legacy messaging systems in use today are starting to provide JMS APIs that make this job easier. The J2EE 1.3 specification does not really define exactly how J2EE applications deployed using one vendor s application server should be able to integrate with JMS providers from another vendor. For example, the EJB 2.0 specification does not define how the MDBs should support interaction with a foreign JMS provider. Fortunately, WebLogic Server provides seamless integration with foreign JMS providers.

In general, there are two strategies for integrating your J2EE applications deployed in WebLogic Server with external JMS providers: direct and indirect integration. These external JMS providers might be another vendor s JMS product or just another WebLogic Server instance that hosts the JMS destinations. With direct integration, the application interacts directly with the external JMS destinations from the application code or the MDB s deployment descriptors. This method has the advantage of being the most efficient but exposes the J2EE application to the availability of the external provider.

Indirect integration uses a store-and-forward model where the application produces messages to and/or consumes messages from local JMS destinations. A message bridge is responsible for moving messages between the local and external destinations. Because all availability and reconnection issues are handled by the bridge, the application itself never has to worry about the external JMS provider.

In this section, we will start by looking briefly at the capabilities of the WebLogic JMS Messaging Bridge. We follow that with a discussion of MDB support for foreign JMS providers. Next, we discuss the new foreign JMS provider support. We end this section with a brief discussion of the trade-offs of the different approaches.

Understanding the Messaging Bridge

WebLogic Server provides a built-in message bridge that you can configure using the WebLogic Console to move messages between any two JMS destinations. The WebLogic Server Messaging Bridge provides several qualities of service (QoS) that control the message delivery: Exactly-once , Atmost-once , and Duplicates-okay . Exactly-once delivery means just that; the message will be delivered from the sending destination to the receiving destination using XA transactions so that the receiver gets exactly one copy of each message. Atmost-once delivery uses a best-effort delivery mode to make sure that the receiving destination receives only a single copy of the message or does not receive it at all. With the Duplicates-okay delivery mode, the bridge acknowledges receiving the message from the source destination only after writing it to the target destination. Because this is done outside the scope of a transaction, failures after writing the message to the target and before acknowledging the source can result in duplicate messages being delivered but should never result in a message being lost. This type of delivery is better known as at-least-once delivery.

The bridge uses J2EE CA adapters to connect to the different messaging systems, though the adapters it can use are currently limited to the following built-in set of adapters:

jms-xa-adp.rar.     The bridge uses this adapter to communicate with any XA-compliant JMS provider to provide Exactly-once delivery.

jms-notran-adp.rar.     The bridge uses this adapter to communicate with any JMS provider to provide either Atmost-once or Duplicates-okay delivery.

jms-notran-adp51.rar.     This adapter provides interoperability with WebLogic Server 5.1 s JMS implementation. As the name suggests, it does not support transactional delivery so it supports only the Atmost-once and Duplicates-okay delivery modes.

You must create an instance of the bridge for each source and target destination pair and deploy it to a WebLogic Server instance. Before you can do this, you need first to deploy the appropriate adapters that the bridge will need, based on the messaging systems and QoS being used. The WebLogic Server Messaging Bridge provides many different configuration options that we will not spend time on here. For a complete discussion of the bridge, please refer to the WebLogic Server documentation at http://edocs.bea.com/wls/docs81/ConsoleHelp/messaging_bridge.html .

Best Practice  

Use the WebLogic Server Messaging Bridge to store and forward messages between different JMS providers.

Using Message-Driven Beans

MDBs use JNDI to retrieve connection factories and destinations. You can use MDBs in WebLogic Server to work with any JMS provider that supports and implements the JMS and JNDI specifications. When configuring an MDB to use a remote JMS provider, you must provide the JNDI information needed to look up the remote connection factory and destination using the weblogic-ejb-jar.xml deployment descriptor. This information includes the values of the JNDI Context.INITIAL_CONTEXT_FACTORY and Context.PROVIDER_URL parameters that WebLogic should use to create the InitialContext , as well as the JNDI names of the connection factory and destination.

WebLogic Server also supports using container-managed transactions with foreign JMS providers to provide transactional delivery of messages to the MDBs. Make sure that the connection factory the MDB deployment descriptors references is an instance of javax.jms.XAConnectionFactory so that WebLogic Server will fully support the transactional settings of the MDB and provide for transaction coordination between the external provider and any other resources your business logic might involve in the transaction.

Mapping External JMS Objects to WebLogic JNDI

WebLogic Server 8.1 introduces the ability to create a sort of symbolic link between a JMS connection factory and destination in an external JNDI provider and a binding in your local WebLogic Server s JNDI tree. This makes it easier for your applications, or the Messaging Bridge configuration, to abstract itself away from the external JNDI provider s configuration details. To use this facility, you start by using the WebLogic Console to create a Foreign JMS Server entry for each of your external JMS providers. This entry contains the information about how to connect to the external JMS provider s JNDI provider. Once the Foreign JMS Server entry exists, you can configure any number of links between external connection factories and destinations for that server and local JNDI bindings. For more information about using this feature, see http://edocs.bea.com/wls/docs81/ConsoleHelp/jms_config.html .

Though this new feature allows you to map foreign JMS provider s JNDI objects in the local WebLogic Server s JNDI tree easily, it does come with a price. To avoid the synchronization problems associated with caching remote objects locally, WebLogic Server automatically does a remote JNDI lookup every time your application looks up these local bindings. This approach is highly desirable because some JMS providers connection factory and destination objects are invalid once the JMS provider is restarted. This also means that a JNDI lookup of one of these objects is not any cheaper than looking it up directly from the remote location.

Best Practice  

Use the new Foreign JMS Server capabilities to isolate the rest of your application configuration away from the external JMS provider s configuration by making the objects visible from the local JNDI tree.

Choosing an Integration Strategy

When your application is consuming messages from an external JMS provider, consider using the direct integration approach with MDBs rather than the indirect bridging approach. MDBs deployed in WebLogic Server can support the same qualities of service supported by the bridge. MDBs support exactly-once delivery through the use of XA transactions. By using either AUTO_ACKNOWLEDGE or DUPS_OK_ACKNOWLEDGE modes, you can get at-least-once delivery. The trade-offs between the two acknowledgment modes are really about reducing the chances for duplicate messages versus improving performance. By using the WebLogic JMS-specific modes of NO_ACKNOWLEDGE or MULTICAST_NO_ACKNOWLEDGE , you can achieve at-most-once delivery of your messages. MDBs also support automatic reconnection to the external provider should the connection fail, such as when the external JMS provider is restarted. You can tune the polling interval with which the MDBs will try to reconnect by using the jms-polling-interval-seconds element in the weblogic-ejb-jar.xml deployment descriptor. The default value is to try to reconnect once every 10 seconds.

WebLogic Server provides a configurable mechanism to pause MDB message consumption after some number of consecutive errors when using transactions with foreign JMS providers that do not implement the weblogic.jms.extensions.MDBTransaction interface. By default, WebLogic Server MDBs will pause their message processing for 5 seconds when the MDB deployment encounters 10 consecutive errors. An error is defined by either the MDB calling setRollbackOnly() or throwing a RuntimeException , such as EJBException , from the onMessage() method. You can tune the number of consecutive errors and sleep time by setting the following Java system properties at the server startup:

weblogic.ejb20.MaxMDBErrors.     This property controls the number of consecutive errors before processing of a message-driven bean will pause. Each message-driven bean deployment has an independent counter, which is reset every time a message is successfully processed .

weblogic.ejb20.MDBErrorSleepTime.     This property specifies the number of seconds a message-driven bean s processing will pause after encountering weblogic.ejb20.MaxMDBErrors consecutive errors.

This feature could be very useful in solving the more general problem of how to suspend message processing when the system is temporarily unable to process messages, such as when the back-end database is down. We hope that future versions of WebLogic Server will use this or some similar mechanism to help you address the more general problem. We would also expect to see this feature promoted into the WebLogic Console and made configurable per destination or MDB rather than at the entire server level.

To debug connection problems with message-driven beans using an external provider, try setting the weblogic.ejb.jms.connect.verbose and weblogic.ejb.jms.connect.debug Java system properties to true on the server command line (in older version, these properties were named weblogic.ejb20.jms.connect.verbose and weblogic.ejb20.jms.connect.debug) . As with all of these undocumented properties, these properties are subject to change without notice.

For applications that are sending messages to a foreign provider, using the messaging bridge is typically a better option unless the application is waiting on a response to be able to continue processing. For example, a Web application that is using request/reply style messaging to an external back-end system in order to be able to send a Web page back to the client s browser would not be a good candidate for the messaging bridge. Of course, we could argue that this isn t the best design, as we did earlier in the chapter, but we hope that the example gets our point across. Using the bridge allows the application to complete requests by writing the message to a local JMS queue. This means that the application will continue to function properly even when the remote system is down. The bridge handles all of the reconnect logic to deal with the external JMS provider being unavailable for a period of time.