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.

It's embedded

Atomikos is an embedded transaction manager, This means there is no separate transaction manager service to start, it just runs inside your application's JVM.

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 JTA Properties 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 Using TransactionsEssentials with JDBC and Using TransactionsEssentials with JMS 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.AtomikosDataSourceBean;

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

public class AtomikosExample {

  // Atomikos implementations
  private static UserTransactionManager utm;
  private static AtomikosDataSourceBean adsb;

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

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

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

  // release resources
  private static void shutdown() {
    adsb.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();
  }

}