As explained in Using an external connection pool with TransactionsEssentials® you cannot use a non-XA connection pool so TransactionsEssentials comes bundled with a XA-compliant JDBC connection pool.

Vendor's XADataSource

A database that supports JDBC with XA should ship with a driver that implements the javax.sql.XADataSource. Refer to the Third-Party JDBC/XA Configuration to get information on supported databases's XADataSource.

Note that unlike the non-XA JDBC Driver class, XADataSource is not meant to be directly used by an application programmer. It is supposed to be used internally by XA-compliant connection pools. In clear: you should never use XADataSource in your code.

Enlistment, delistment and recovery

AtomikosDataSourceBean takes care of resource enlistment and delistment for you. You do not have to call Transaction methods like enlistResource and delistResource. You also don't have to care about recovery as this is also handled fully transparently.

Just remember that if you use an AtomikosDataSourceBean all the complexities of XA are transparently taken care of.

Using AtomikosDataSourceBean

The AtomikosDataSourceBean class is - as the name suggests - a pure simple javabean. It wraps an XADataSource and pools connections while presenting a javax.sql.DataSource to the application programmer.

It is easy to setup by using its setter methods but can also be easily built from a Spring BeanFactory. Here is an example of code that creates an AtomikosDataSourceBean with 5 connections in pool on an Oracle database:

AtomikosDataSourceBean ds = new AtomikosDataSourceBean();
ds.setUniqueResourceName("oracle");
ds.setXaDataSourceClassName("oracle.jdbc.xa.client.OracleXADataSource");
Properties p = new Properties();
p.setProperty ( "user" , "java" );
p.setProperty ( "password" , "java" );
p.setProperty ( "URL" , "jdbc:oracle:thin:@localhost-xe:1521:XE" );
ds.setXaDataSourceProperties ( p );
ds.setPoolSize ( 5 );

You can then use it like you'd use a normal DataSource:

Connection c = ds.getConnection();

// ... make use of the connection

c.close();

XA and non-XA transactions

Connections acquired from AtomikosDataSourceBean support both XA and non-XA transactions. The only thing that differentiates them is where you use the connection in your code compared to where your UserTransaction begin and commit/rollback are:

Connection c = ds.getConnection();

// ... make use of the connection, non-XA transaction

c.close();

UserTransaction ut = ...;
ut.begin();

Connection c = ds.getConnection();

// ... make use of the connection, XA transaction

c.close();

ut.commit();