Using TransactionsEssentials with JDBC

As explained in ExternalConnectionPool 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

SimpleDataSourceBean 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 a SimpleDataSourceBean all the complexities of XA are transparenlty taken care of.

Using SimpleDataSourceBean

The SimpleDataSourceBean class is - as the name suggests - a pure simple javabean. It wraps a 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 a SimpleDataSourceBean with 5 connections in pool on an Oracle database:

SimpleDataSourceBean ds = new SimpleDataSourceBean();
ds.setUniqueResourceName("oracle");
ds.setXaDataSourceClassName("oracle.jdbc.xa.client.OracleXADataSource");
ds.setXaDataSourceProperties("user=java;password=java;URL=jdbc:oracle:thin:@localhost-xe:1521:XE");
ds.setConnectionPoolSize(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 SimpleDataSourceBean 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();