Additions to the transaction SPI

[mmusgrov]

I would like to introduce a small set of classes into our SPI to facilitate embedded usage and open it up to the community for discussion.

The requirement is coming from a request from the ceylon community to integrate transactions into their SDK so my initial focus is on satisfying that requirement only. The broader discussion of cleaning up our SPI is still ongoing. But first a caveat, the SPI needs to support JDBC DataSources: in the medium term we will be using JCA but for now there are still issues to resolve around embedded IJ on ceylon so my SPI changes rely on the transactional driver which ultimately we would prefer not to support. That said the interface is phrased in terms of javax.sql.DataSource so I would hope for minor changes only when we eventually switch to JCA but to protect ourselves I have annotated it with @Deprecated.

There is transaction service factory for obtaining a transaction service (there can be only one with the current narayana implementation) and a DataSource manager factory for obtaining a DataSource Manager.

The interface to obtain a transaction service accepts a parameter to configure the environment that the transaction service will run it.

The transaction service is for starting a transaction (returning javax.transaction.Transaction for controlling its' subsequent life cycle);

The DataSource Manager instance returned by the DataSource manager factory contains a pair of methods:

• one to register a resource (transactional driver relies on JNDI);
• the other to obtain a DataSource (that has been previously registered).

Apart from a couple of Exception classes that's it.

You can take a look at the proposed interface via my private git branch

The unit tests should give you a clear idea of how to use the SPI.

And there is also an example of how to use it from ceylon

Message was edited by: Michael Musgrove Updated to incorporate changes requested by Tom

[tomjenkinson]

Please can you introduce what your plans/options are for DataSource Manager longer term?

[tomjenkinson]

Also, I noticed some commented out builder stuff, personally I like the android SDK manner of builders: http://developer.android.com/reference/android/app/Notification.Builder.html

[mmusgrov]

That is more or less what I have except that the build method in ConfigurationHolder is package private. I don't want to make it public because the build method actually applies the config settings to the TM environment - in this incarnation of the SPI I want to ensure config props have to be set before the TM is instantiated. Otherwise the client could end up setting properties which will never take effect (since most of our props have no effect once the TM is running).

[marklittle]

Rather than me trawling through git could you call out here what changes you're suggesting and why? Thanks.

[mmusgrov]

The changes are in the last two commits on the branch but the link I provided in the article is all new code (and is the part of the SPI that's used by ceylon) so it should be easier to start there. The link for the compare view for the two commits is https://github.com/mmusgrov/narayana/compare/JBTM-1699-spi?expand=1

The changes are to facilitate the ceylon work. I need a simple interface to call from ceylon to start transactions and to obtain (XA) DataSources (under the control of TransactionalDriver). I also want to constrain which options are configurable from ceylon to minimise potential support cases. So, I provide a transaction service interface with a method to start a transaction, a DataSource manager with a method to bind a resource into JNDI and a method to obtain a bound datasource. I updated the article to include hyperlinks to these classes:

"There is transaction service factory for obtaining a transaction service (there can be only one with the current narayana implementation) and a DataSource manager factory for obtaining a DataSource Manager.

The interface to obtain a transaction service accepts a parameter to configure the environment that the transaction service will run it."

[mmusgrov]

Please can you introduce what your plans/options are for DataSource Manager longer term?

We will be using embedded IJ. With IJ the user "deploys a datasource" by passing it the definition in an xml file (and I think there is a programmatic equivalent) which then gets bound into JNDI. So the plans will most likely be to just offer an interface for deploying the datasource definition and (maybe) a wrapper around the call to lookup a datasource in JNDI..

[marklittle]

Have you taken a look at what the TorqueBox team did when integrating transactions and databases there and exposing interfaces to their users?

[mmusgrov]

Have you taken a look at what the TorqueBox team did when integrating transactions and databases there and exposing interfaces to their users?

No I hadn't but I have now

It is interesting but I'm not sure whether I can reuse any of there approaches. They get a handle on the TM from the app server currently running in the VM and do not have any explicit control over its instantiation or over the environment the TM runs in.

They also explicitly register XA resources with the transaction. In ceylon I am integrating with a pre existing module for doing local JDBC SQL operations so I need to integrate at the JCA/TransactionalDriver level of abstraction.

[marklittle]

How much of this needs to go into the existing SPI or could be done as an extension? My biggest concern about making changes to the "core" SPI is if these changes then need to be further changed for these edge cases and what knock-on effect that might have on the majority of users (WildFly based or not) who probably don't really care about them. How about defining an extension SPI that is available separately? And no, I haven't gone through the whole git repo - I saw xml and stopped ;-)

[mmusgrov]

The compare view includes all the maven fluff, that's why I omitted it from the article - the link I gave goes straight to the meat.

We need to revamp the existing SPI (jbosstm/jboss-transaction-spi · GitHub) since it exposes internal arjuna APIs (and contains a lot of classes that as far as tatletale is concerned are never used). The revamp will include migration and rationalization of the existing sources into the narayana code base. Having the SPI under a new package and location will also mean that we don't accidentally break any other users out there we don't know about (the old SPI will still be there just no longer developed). I have run my plans by the WFLY team and they are OK with the proposed migration.

We haven't done that migration yet but I need something for ceylon now so this current proposal is a new SPI and no existing users will be affected.

[marklittle]

Do you believe these changes are generally applicable though? I'm concerned about adding extensions to "the core" that are not needed by the majority of users.

[mmusgrov]

OK so how about the following proposal:

• I will try do as much of the ceylon work using jboss-transaction-spi where possible
• the jboss-transaction-spi does not expose any configuration so if ceylon users need to configure anything they will need to use our existing XML property file mechanism
• there is no easy interface to TransactionalDriver for using XA datasources so I will expose this using an "extension SPI". But can you explain what you mean by an extension SPI?

[mmusgrov]

Are you also questioning the need to clean up the existing jboss-transaction-spi. There is already a  discussion for that requirement.

[marklittle]

No I'm not questioning the need to do a tidy up. I'm questioning the need to introduce anything that may be useful only for a small set of use cases, particularly when those use cases may not be concrete yet. That's why I try to differentiate between what I call "core" SPI (those things we know we need for everything) and "extensions".