XA Transaction Integration
If an application server is to provide XA transactions alongside a third-party JMS, it must be able to:

• Create and manage JMS connections and sessions
• Create and manage XAConnections and XASessions
• Enlist the XAResource.

When the WLSAdapter creates an XASession, it also creates a single XAResource object inside a JVM (singleton), which is presented to the WLS transaction manager for each XA transaction. The real XAResources, provided within the JMS transaction manager, are created by WLSAdapter and registered with the singleton, which in turn delegates all WLS transaction manager calls to the appropriate SonicMQ XAResource. The adapter manages all SonicMQ XA branches internally. In MDBs, the WLSAdapter automatically enlists the XAResource on each transaction, while session beans explicitly enlist XAResources via the WLS TxHelper, javax.transaction.Transaction txn = weblogic.transaction.TxHelper.getTransaction(), and a direct call to the enlist method txn.enlistResource(myXAResource).

The result is equivalent to the JMS adapter providing a small transaction manager to participate as a single resource for the WLS transaction manager. And, since an XA resource can now be obtained for the WLS transaction manager, issues 1 and 2 are resolved.

The WLSAdapter addresses issue 3 by implementing the BEA proprietary interface, MDBTransaction, in its session object and uses the associateTransaction() method to trigger automatic enlistment from MDB transactions. Because the method is now implemented in the adapter XA session object, the WLS exceptions are no longer thrown.

Finally, the WLSAdapter addresses issue 4 by managing XA transaction branches so they remain completely serialized. It does this by catching SonicMQ exceptions whenever WLS allows a transaction branch overlap, and holding the overlapping branch until the previous one has completed. Only then does it permit the next transaction branch to be started. Exceptions are masked, branch overlap is avoided, and XA transactions conform to the JTA Specification.

With the WLSAdapter for SonicMQ, all four of the WLS XA-compliance issues are resolved, providing a fully JTA-compliant Global Transaction solution within an enterprise-class JMS.

Other Integration Challenges
Runtime and Development-Time Considerations
The introduction of an adapter presents an opportunity to incorporate various value-added features that enhance the robustness of an enterprise solution. Key considerations include automating runtime reconnection around failed brokers or links and providing facilities for testing application-level exception handling (particularly connection- and transaction-level recovery logic).

Automatic Client Reconnect
Reconnection and failover capabilities are important to any large-scale distributed application. Both WebLogic and SonicMQ provide clustering and reconnection capabilities. Figure 1 represents a typical WebLogic clustering configuration with two servers in a cluster.

Topic A and Topic B can be accessed from any WLS in the cluster. However, the topics must be created in advance, and topic information is tied locally to a particular server.

In the event Instance A goes down, traffic will be routed to the remaining server in the cluster. However, Topic A will no longer be accessible.

Figure 2 shows a WebLogic cluster and a SonicMQ cluster working together to leverage the reconnect capabilities of WLSAdapter.

In this example, if either of the WLS instances fails, all topics will still be available through SonicMQ. In addition, if either of the SonicMQ brokers goes down, they'll automatically fail over to the backup server or servers, and topic information won't be lost. When WLSAdapter is used in a SonicMQ cluster, topics can be dynamically created and information is shared across the JMS cluster.

To accomplish a reconnect in the first example (which doesn't use WLSAdapter), a producer or a synchronous consumer in an EJB would have to trap the exception inside the application logic when the broker goes down and explicitly reconnect and reconstitute all the connection and session objects.

WLS does recreate a reconnection within an MDB; however, the listener isn't recreated and the messages can be lost. The solution provided by WLSAdapter:

Since the connection failure and the reconnect are completely transparent to the user and business logic, the developer is freed from writing code to manage reconnect scenarios.

Failure Insertion Points
WLSAdapter can insert failure points for debugging and analysis. The advantages geared to development time address one of the most daunting aspects of integration testing - introducing controlled but realistic failures to test exception-handling pathways. WLSAdapter provides two types of failure injection: connection drop failure points and method failures.

Connection-Drop Failure
A connection-drop failure pauses the application in a specified method. This way, an external action can be taken by the developer to have an effect at a specific point in the execution of the application.

For example, to test application behavior when a broker goes down or a connection fails, randomly pulling cables or "killing" a broker won't provide a reliably reproducible test case. However, using the SonicMQ WLSAdapter, you can isolate the failure occurrences by forcing a connection-drop failure to occur during the execution of a particular method, for example the onMessage() method of an MDB. When the method is called, the application will be paused by the adapter. At that point you can force a broker to disconnect and simulate the problem. After releasing the failure point, execution of the application resumes to reveal how the exception logic copes with the situation.

Method Failure
A method failure is similar in design, but it simply forces a particular exception to be thrown from a specific method rather than requiring developer intervention (such as killing a broker or pulling a cable). When a method failure point is set, the application will pause when it reaches the method specified. There the option is offered to have that method raise an exception, or continue normally.

There are 10 methods in which you can set a connection-drop or method failure. Five of them are for JMS methods, and five are specifically for XA transactions. An application simply needs to implement the method in question for the WLSAdapter to execute it and inject a failure point; thus, no temporary test logic needs to be embedded within the application code. Table 1 lists the JMS and XA methods where failure insertion may occur.

Using failure point insertion in WebLogic is as simple as including the WLSAdapter package in the classpath of the WebLogic domain startup and adding the appropriate flags to the application server start-up:

-DSonicsw.WLSAdapter.Test.DoFail=true
-DSonicsw.WLSAdapter.Test.FailType=%1
-DSonicsw.WLSAdapter.Test.FailPoint=%2

The parameter %1 would be either "ConnectionDrop" or "MethodFailure", and %2 would represent one of the methods listed in Table 1.

Enterprise-Class Design Patterns
Value-added features can be included with adapter packages in templates that implement advanced transactional design patterns. Often enterprise-level EJB scenarios employing JMS require several beans to interact transactionally. These complex scenarios necessitate clever construction for robustness and some form of session pooling for scalability.

For example, a common circumstance might be to have an MDB acting as a consumer to a Pub/Sub topic listening for RFPs. When an RFP message arrives, it might process the document into a local database via an entity bean, and then a session bean to produce a proposal for transmission over a point-to-point queue back to the proposal requestor. In a high throughput environment, the outbound queue transmission might pool session beans to improve scalability. In this complex arrangement, the MDB, entity bean, and session beans must all become part of a single transaction, where two of the beans are interacting with the JMS transaction manager.

The WLSAdapter uniquely answers questions surrounding these enterprise-grade problems. It does so by including prebuilt code templates that implement design patterns suitable for supporting multibean interactions. Solutions are illustrated for consumers and producers, along with a robust, yet lightweight, pooling mechanism for stateless session beans.

Looking Ahead
There are five primary transactional-JMS design patterns included in the Sonic WLSAdapter (illustrated in Figure 3). These include:

• Message-Driven Bean
• Message-Driven Bean Router
• Message-Producing Bean
• Message-Consuming Bean
• Message-Consuming Bean Router

• Message-driven bean (with a queue listener)
• Message-driven bean (with a topic listener and reconnect)
• Message-consumer bean
• Message-producing bean (with cross-JMS domain XA and reconnect)