TransXTrail HOW-TO:


TransXTrail is a very simple transaction API for Java developers. This HOW-TO will explain how to create a new application and how to write some code that uses TransXTrail features.


1 – Create a new application and include the following libraries in your classpath (all libraries can be found at Jakarta Project’s web site):


2 – Include the latest version of transxtrail.jar in your project’s classpath.


3 – Create a new XML file to configure your datasources and include it in your project structure. The XML configuration file must look like this:




  <datasource name="test">





    <validation-query>select sysdate from dual</validation-query>





Important considerations:


Now you’re ready to create some distributed transactions. How exciting is that?


Let’s take a look at some Java code:


1. public void testTransXTrail() throws Exception {

2.     Domain.configDataSources("datasources.xml");

3.     Domain.getInstance().beginTransaction();

4.     DataSourcedataSource = Domain.getInstance().getDataSource("test");

5.     Connectionconn = null;

6.     try {

7.            conn = dataSource.getConnection();

8.            //Use the connection

9.            conn.close();

10.           Domain.getInstance().commit();

11.    } catch (Exception e) {

12.           Domain.getInstance().rollback();

13.    }

14. }


This is not the best try-catch structure, but that is not the point about this example anyway.


The explanation:


Line 1: Configure all data sources specified in the XML into the Domain object. The domain object is used as a Singleton, meaning that it has only one instance per Virtual Machine. The path for the XML file must be a valid path (absolute or relative).


Line 2: Create a new transaction where operations will be made and will be committed or rolled back as the user requests. There’s a very important issue here: each thread can have only ONE transaction opened. Only one!!!! If you’re developing a multi-threaded system, each thread will have its own transaction. The TransXTrail system will take care of everything for you. If you try to open two transactions in the same thread, an exception will be thrown. Why only one? Why can’t I open two transactions in the same thread? Well, the answer is very simple: Why do you want to do such a stupid thing? If you think you must open two transactions in the same thread at the same time, try to look at your design model and find another solution.


Line 3: Get a reference to the data source object. The key object used to find a data source is the name you specified in the XML configuration file. How to use a datasource is up to you. Look at the java.sql.DataSource documentation.


Line 7: Create a connection based on all parameters specified in the XML configuration file.


Line 8: Selects, inserts, updates, stored procedures, anything.


Line 9: Close the connection.


Line 10: If no exception was thrown then you can safely commit.


Line 12: Otherwise, roll back all previous actions.


That’s it. You’re dealing with a full transaction system with very little effort. Now, here’s the fun part. You can do whatever you want in multiple databases. Should be something like this:


public void testTransXTrail2() throws Exception {



       DataSourcedataSource1 = Domain.getInstance().getDataSource("test1");

       DataSourcedataSource2 = Domain.getInstance().getDataSource("test2");

       Connectionconn1 = null;

       Connectionconn2 = null;

       try {

              conn1= dataSource1.getConnection();

              conn2= dataSource2.getConnection();

              //Use the connection




       } catch (Exception e) {





Please take a look into my class model. I like it a lot, especially for being so simple.

If you have something to contribute with, go to SourceForge’s home page. It’ll be my pleasure.


You can contact me through the Source Forge project page.



SourceForge Logo