A bit of background

Atomikos has been designed in a modular way. There is a transactional kernel called 'icatch' that provides a proprietary API. On top of that, many different transactional services are built. One of them is the JTA implementation: a layer on top of icatch that implements the JTA API.

There are many other services but JTA is the only one available one in the TransactionsEssentials distribution. ExtremeTransactions also contains RMI and Web Services interfaces.

Programming JTA with Atomikos

Generally, you only need to use the JTA-related API and can ignore the proprietary icatch API.

To initialize the transaction manager, create an instance of com.atomikos.icatch.jta.UserTransactionManager then call init() on it. Do not forget to call close() during your application shutdown.

This class implements javax.transaction.TransactionManager which is all you need to control JTA transactions via the begin(), commit() and rollback() methods.

During initalization, it will read the jta.properties file at the root of the classpath. See JtaProperties to learn what can be configured.

Simple JTA example

Here is a simple example of code that initializes the transaction manager, starts a transaction, commits it then shutdown gracefully making use of the JTA API. Error handling has been omitted for clarity.

See ConfiguringJdbc and ConfiguringJms to learn more about how to configure and make use of JDBC and JMS resources.

import com.atomikos.icatch.jta.UserTransactionManager;
import com.atomikos.jdbc.SimpleDataSourceBean;

import javax.jta.TransactionManager;
import javax.sql.DataSource;

public class AtomikosExample {

  // Atomikos implementations
  private static UserTransactionManager utm;
  private static SimpleDataSourceBean sdsb;

  // Standard interfaces
  private static TransactionManager tm;
  private static DataSource ds;

  // initialize resources
  private static void init() {
    UserTransactionManager utm = new UserTransactionManager();
    utm.init();
    tm = utm;

    sdsb = ...; // omitted for clarity
    ds = sdsb;
  }

  // release resources
  private static void shutdown() {
    sdsb.close();
    utm.close();
  }

  public static void main(String[] args) {
    init();
    

    tm.begin();

    Connection c = ds.getConnection();
    // use connection to execute SQL
    c.close();

    tm.commit();


    shutdown();
  }


utm.close();
}

-- LudovicOrban - 05 Mar 2008