Peter Holditch

This month, I thought I would take a below-the-surface look at what needs to be done to achieve transactional access to the IBM MQSeries messaging product from WebLogic Server within the context of an Xa transaction managed by WebLogic's JTA subsystem. Of course, from the outset I would like to note that WebLogic Server itself boasts a very capable and reliable messaging system - which is getting more capable with every release - but it is a fact of life that MQseries for various reasons (most predating the existence of Java, never mind the JMS messaging standard) has a large installed base, so good interoperability with it is a requirement whatever your infrastructure religion.

So Tell Me the Good News
Well, Okay, I will. The first piece of good news if you are looking for programmatic integration between WebLogic Server and MQ is that there is working code to achieve just that available on BEA's dev2dev Web site at http://dev2dev.bea.com/code/codedetailcontent.jsp? productType=weblogic+server&codeType=alpha+code&filepath= components%2Fdev2dev%2Fcodelibrary%2Falphacode%2 Falphacodewlsmqseries.htm. However, there are some features of its implementation that bear closer scrutiny to get further insight into what needs to be done to interface these two environments. If you're not into intricate details, I recommend that you proceed directly to the conclusion now for an early bath - I am about to start indulging my love of the obscure...

You're still here? Good, another implementation trivia lover - I can see that we're going to get on famously. Take a deep breath; I'm sure you're going to enjoy the trip!

Enjoy the Trip!
On the face of it, part of the MQSeries product is a Java wrapper that implements the JMS programming interface and supports the XA extensions. To aid code portability, JMS provides for connection factories, queues, and topic objects to be defined prior to application runtime and stored using a JNDI provider, so using all these standards from within the WebLogic Server environment should be simplicity itself, right?

Well, almost. There are some wrinkles that come from MQSeries restrictions that derive from the implementation of MQ itself. These need to be coded around if WebLogic Server and MQ are to live together in perfect harmony. Most of the code posted on dev2dev is concerned with ironing out these wrinkles so that the two products can coexist in perfect harmony, or at least without shed loads of cacophonous discord, or as MC geek and the OLTP crew might say "so the MQ thing doesn't go in the crapper, BEA Systems have written a wrapper."

So What Is This Wrapper Up To?
Rather than a full top-down review of the whole thing, I will spend the rest of the article reviewing the purpose of a subset of it. This will hopefully provide a level of understanding both of the XA implementation of MQ, and of the WebLogic Server transaction manager.

The first part of the wrapper is a class that maps the MQ JNDI entires from an external JNDI directory into the WebLogic JNDI tree. On the way, it interposes its wrapped versions of the XQQueueConnectionFactory or XATopicConnectionFactory. The net result is that the set of connection/topic factories present in MQSeries becomes visible in the WebLogic Server environment, with a wrapper to do the rest of the integration magic.

The wrapper at the base of the remaining mystery is a wrapper for the MQSeries XA resources. As XA resources are dispensed from the MQ factories, they in turn are wrapped, and it is in this resource wrapper that the business end of things happens.

First, the constructor of the resource wrapper registers each XA resource - once per server - under a resource name that is either given or constructed from the server and domain names and the MQ resource string. The wrapper also allows the MQSeries integration to take advantage of an optimization in the WebLogic transaction manager, namely dynamic enlistment.

So, I hear you cry, what's that? The JTA specification allows only for static enlistment, which means that all resources must register their existence at startup, and from this point on the application server must assume that all resources registered with it participated in every transaction and enlist them in JTA transactions on that basis so they are sent a commit for each transaction on the off chance that they participated. With dynamic registration, resources can enlist with JTA lazily as they are invoked in a transaction - meaning that the transaction manager knows the correct set to coordinate at commit time, improving performance. The resource name associated with a resource is used by WebLogic as a branch qualifier for the transaction. It is also used in recovery so that outstanding transactions can be completed from transaction log records. This means that these resource names must be assumed to be constant across multiple server reboots to allow for transaction recovery.

Finally, an XA resource provides a method called isSameRM that allows a transaction manager to determine conclusively if two participants in a transaction are really one and the same resource. The wrapper provides its own implementation of this method with different behavior from the out-of-the-box implementation from IBM. The reasons for this are slightly obscure, but here goes... IBM's implementation of isSameRM bases the decision on the QueueManager. The wrapper is designed to base the isSameRM decision on the name associated with the XAConnectionFactory (remember the significance of the resource name in terms of the transaction branch?). This allows multiple branches to be used for a particular MQSeries QM. This is important when multiple MQ sessions are to be manipulated in a transaction. Due to the behaviors of the WL TM and the IBM JMS implementation, the direct use of multiple MQ sessions in a single transaction can result in XA errors. The IBM JMS requires that each XAResource instance, that is associated with a particular Session, be enlisted and delisted from the transaction. The WebLogic Transaction Manager implements a delayed delistment optimization, which delays calling XA.end (the XA call that performs the delistment) until absolutely necessary (transaction suspended, commit called, etc.). This optimization helps avoid multiple start/end calls when the same resource is accessed multiple times within a transaction. However, because each JMS session has a unique XAResource object, and their isSameRM methods will return true for each other, WebLogic's Transaction Manager will treat them as if they were the same. The first session accessed will receive an XA.start call.to enlist it in the current transaction. When the JMS operation returns, the optimization will delay the XA.end call to delist the resource. When an operation is invoked on the second session, XA.start will not be called because the Transaction Manager thinks that it is the same resource and it knows it has already called XA.start on it. Following that, when the JMS call is made the IBM driver will respond with a 2072 "Syncpoint not available" error because MQSeries didn't get the XA.start it was expecting - since as far as it is concerned this is a different resource - so it decides that the call is being made outside of a global transaction.

Come Up for Some Air, Here's The Really Good News
Phew, you can come up for air now.... This transaction stuff sure provides some late night entertainment. Or perhaps a cure for insomnia. It depends on your viewpoint I suppose.

The good news is that WebLogic Server versions greater than 6.1sp3 provide an out-of-the-box transactional MQ Series bridge that allows you to map WebLogic JMS queues and topics to MQ ones without writing a single line of code - just configure the source and destination queues to be bridged and away it goes. Even better news is that the next release preview bird has told me that a transparent JMS wrapper is in the works. This will allow you to configure foreign queues into the WebLogic environment where the server will transparently take care of all this wrapping.

Yet another reason why both above and below the J2EE standards surface WebLogic Server will remain ahead of the pack in terms of ease of use - bringing faster time to market to all who use it as a platform for their applications.

That's it from me for now - I'll delist until next month. Happy transacting.