TransXTrail - The simplest transaction controller API for Java

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):

commons-beanutils.jar
commons-collections-3.0.jar
commons-dbcp-1.1.jar
commons-digester.jar
commons-logging.jar
commons-pool-1.1.jar

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:

<test>

<url>jdbc:oracle:thin:@127.0.0.1:1522:testdb</url>

<username>sysadm</username>

<password>sysadm</password>

<driver-class-name>oracle.jdbc.driver.OracleDriver</driver-class-name>

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

</datasource>

</test>

Important considerations:

The tag element that surrounds the data source tag (<test>) doesn’t matter. It could be anything. This means that you can either create a separate XML file to configure your data sources or you can add a data source section at you existing XML file. It doesn’t matter where it is located. Only what’s beneath the data source tag matters. You can also create several data source tags, but you can’t repeat the name property, it must be unique.
The validation query must be provided and must be a query string that retrieves minimal data from the database (it also must be compatible with the database you’re using – the query string in the example would not work in a MS SQL Server for example). The presence of this parameter is very important. If this parameter is missing transactions could fail (I’ll improve a check procedure for this parameter in later versions). It’s very important that the validation query actually retrieve some data. So you should not use something like ‘select * from test’ because test might be empty. Instead use something like ‘select sysdate from dual’ (the validation queries I usually use: [Oracle] = ’select sysdate from dual’ / [MSSQL] = ‘select @@VERSION’ / [MySQL] = ‘select sysdate()’).

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 {

Domain.configDataSources("datasources.xml");

Domain.getInstance().beginTransaction();

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

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

Connectionconn1 = null;

Connectionconn2 = null;

try {

conn1= dataSource1.getConnection();

conn2= dataSource2.getConnection();

//Use the connection

conn1.close();

conn2.close();

Domain.getInstance().commit();

} catch (Exception e) {

Domain.getInstance().rollback();

}

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.