On 30/10/2012 20:04, Nigel Deakin wrote:
> I have raised the following issue:
> http://java.net/jira/browse/JMS_SPEC-105
> Provide API to allow an app server or resource adapter to obtain a XAResource from a JMSContext
>
> I see this issue as a bit of tidying-up - simply extending the optional XA interfaces to provide proper support for
> JMSContext - but I think it is something that we have to do for JMS 2.0.
>
> -----------------------------------------------------------------------------------------------
>
> JMS 1.1 defined an optional API to allow an application server or resource adapter to obtain a XAResource object
> corresponding to a Session object. This is the "chapter 8" API, which defines the optional interfaces
> XAConnectionFactory, XAConnection, XASession and the method XASession#getXAResource().
>
> However there is currently no equivalent API to allow an application server or resource adapter to obtain a XAResource
> object corresponding to a JMSContext object.
>
> This means that an application server which uses the "chapter 8" API to integrate with a JMS provider (rather than using
> a resource adapter) cannot support JMSContext properly. The same applies for a generic resource adapter which uses the
> "chapter 8" API to integrate with any JMS provider.
>
> There are two alternatives:
>
> *** Option 1
>
> This option follows the same approach as the existing "chapter 8" API
>
> * Add four new new createXAContext methods to XAConnectionFactory. These are similar to the four existing createContext
> methods on ConnectionFactory except that they return a XAJMSContext rather than a JMSContext
>
> * Define a new interface XAJMSContext. This is a subtype of JMSContext with one additional method, getXAResource, which
> returns a XAResource.
>
> *** Option 2
>
> * Simply add a new method getXAResource to the JMSContext
>
> In both cases implementation of the new interfaces and methods would be optional just like the rest of the existing
> "chapter 8" API is.
>
> It is proposed that option 1 be adopted since this is consistent with the existing API, but option 2 is mentioned as a
> possible alternative.
I have now drafted the new API. As I proposed I have followed option 1. Here are the details:
XAConnectionFactory
-------------------
I have added the following new methods to allow a XAJMSContext to be created
* XAJMSContext createXAContext();
* XAJMSContext createXAContext(String userName, String password);
Note that only two methods (not four) were needed, since there is no need to support the methods which allow you to
specify sessionMode. This is consistent with the XAConnection method createXASession(), which also has no option to pass
in session mode.
XAJMSContext
------------
I have added this new interface, which extends JMSContext.
I have modelled this on XASession (which extends Session) as follows:
The following methods override methods inherited from the supertype
void commit() - always throws a TransactionInProgressRuntimeException
void rollback(); - always throws a TransactionInProgressRuntimeException
boolean getTransacted(); - always returns true
The following are new methods:
XAResource getXAResource(); - the whole point of this interface
JMSContext getContext(); - analogous to XASession.getSession()
As always, you can see the updated API docs at
http://jms-spec.java.net/2.0-SNAPSHOT/apidocs/index.html
In the spec document itself I have extended Chapter 8 to cover the new XAJMSContext interface. Again I have essentially
copied the description of XASession, but to avoid too much repetition I have refactored some generic text into a
separate section entitled "XAResource". You can read this either below or in the usual place at
http://java.net/projects/jms-spec/sources/repository/content/jms2.0/specification/word/JMS20.pdf
Note that I have not added any new text here other than for JMSContext. This is simply a rearrangement of the existing
text related to distributed transactions into a new section 8.3. I am not attempting to expand or clarify this chapter
(though I couldn't resist changing "JTS" to "JTA"). My goal here is simply extend this (optional) part of the spec to
support JMSContext.
8.3. Support for distributed transactions
Some application servers provide support for grouping resource use into a distributed transaction. To include JMS
transactions in a distributed transaction, an application server requires a Java Transaction API (JTA) capable JMS provider.
8.3.1. XAConnectionFactory
A JMS provider exposes its JTA support using a JMS XAConnectionFactory which an application server uses to create
XAConnection or JMSXAContext objects.
XAConnectionFactory provides the same authentication options as ConnectionFactory.
XAConnectionFactory objects are JMS administered objects just like ConnectionFactory objects. It is expected that
application servers will find them using JNDI.
8.3.2. XAConnection
XAConnection extends the capability of Connection by providing the ability to create XASession objects.
8.3.3. XASession
XASession provides access to what looks like a normal Session object and a javax.transaction.xa.XAResource object which
controls its transaction context.
An application server controls the transactional assignment of an XASession by obtaining its XAResource. It uses the
XAResource to assign the session to a distributed transaction; prepare and commit work on the transaction, and so on.
A client of the application server is given the XASession’s Session. Behind the scenes, the application server controls
the transaction management of the underlying XASession.
8.3.4. XAJMSContext
XAJMSContext provides access to what looks like a normal JMSContext object and a javax.transaction.xa.XAResource object
which controls its transaction context.
An application server controls the transactional assignment of an XAJMSContext by obtaining its XAResource. It uses the
XAResource to assign the session to a distributed transaction; prepare and commit work on the transaction, and so on.
A client of the application server is given the XAJMSContext’s JMSContext. Behind the scenes, the application server
controls the transaction management of the underlying XAJMSContext.
8.3.5. XAResource
The functionality of XAResource closely resembles that defined by the standard X/Open XA Resource interface.
An XAResource provides some fairly sophisticated facilities for interleaving work on multiple transactions, recovering a
list of transactions in progress, and so on. A JTA aware JMS provider must fully implement this functionality. This
could be done by using the services of a database that supports XA, or a JMS provider may choose to implement this
functionality from scratch.
It is important to note that a distributed transaction context does not flow with a message; that is, the receipt of the
message cannot be part of the same transaction that produced the message. This is the fundamental difference between
messaging and synchronized processing. Message producers and consumers use an alternative approach to reliability that
is built upon a JMS provider’s ability to supply a once-and-only-once message delivery guarantee.
To reiterate, the act of producing and/or consuming messages in a Session can be transactional. The act of producing and
consuming a specific message across different sessions cannot.
Comments and questions are welcome as always.
Nigel