How to integrate JOTM

Target audience

This howto is intended to project developer who wants to integrate JOTM in their Java projects to provide JTA^TM support for distributed transactions.

It is not intended to JOTM users. For information, on how to use JOTM, you can check the installation and examples guide from the documentation page on JOTM web site.

1. JOTM definition

1.1. What JOTM is

• JOTM (Java^TM Open transaction Manager) is ... a transaction manager written in Java and released under a BSD-style Open Source license.
• It is an ObjectWeb consortium project. The goal of ObjectWeb is to develop Open Source technical components for middleware platforms.
• JOTM is a relatively small project by its line number but a very big one given the importance of transactions in a distributed systems.
• JOTM codebase has been used and tested for several years. At the beginning, JOTM was the transaction manager of JOnAS^TM, an Open Source J2EE^TM server, which has been extracted to be reused in other projects.
• JOTM is to be used by other "containers" (such as EJB^TM or Servlet^TM containers but also standalone Java application) to provide distributed transactions. It is up to those containers to correctly use JOTM with other system parts such as databases or MOM (message-oriented middlewares) to enable transactions support.

• JOTM is neither a resource manager nor an application server. It is only a transaction manager.
• JOTM does not handle JDBC^TM, JMS^TM or JCA^TM resources. The only "resources" JOTM handles are XA^TM resources (as defined by javax.transaction.xa.XAResource).
• JOTM does not automatically handle enlistment or delistment of resources . It is up to the container to do so thanks to the javax.transaction.Transaction object it can access from the javax.transaction.TransactionManager object. Some libraries doing so are included in JOTM distribution (see JDBC and JMS examples).

1.3. Relationship with Java APIs

JTA (Java Transaction API)

JOTM is an implementation of JTA.

JDBC (Java DataBase Connectivity)

JDBC provides connectivity to databases. JDBC defines XA objects (javax.sql.XADataSource and javax.sql.XAConnection which can be used to support distributed transactions across several databases. JDBC driver implementers should provide these XA objects so that JOTM can enlist JDBC resources in transactions.

JMS (Java Message Service)

JMS provides a standard API to use MOM in Java. JMS defines a set of XA objects (such as javax.jms.XAConnection or javax.jms.XASession) which can be used to support distributed transactions across several MOMs. As for JDBC, JMS providers should implements these XA objects so that JOTM can enlist JMS resources in transactions.

EJB (Enterprise JavaBeans)

JOTM can be used by EJB containers to provide both bean-managed and container-manager transaction demarcation and javax.transaction.UserTransaction object to EJB client.

Servlets

JOTM can be used by Servlet containers to provide javax.transaction.UserTransaction object to Servlets and JSP^TM (JavaServer Pages).

2. JOTM from the outside

From the outside, JOTM is a transaction manager implementing JTA interfaces (as defined in javax.transaction and javax.transaction.xa packages).

Containers starts JOTM, access JTA objects and then use them to provide distributed transactions support.

2.1. org.objectweb.transaction.jta package

JTA defines two main interfaces to interact with a transaction manager:

• javax.transaction.TransactionManager that allows an application server to manage transaction boundaries.
• javax.transaction.UserTransaction that allows an application to explicitly manage transaction boundaries.

However, JTA does not define how to get those interfaces from a transaction manager.

JOTM defines an interface ( org.objectweb.transaction.jta.TMService) which can be used to get those interfaces. It defines three methods:

• public org.objectweb.transaction.jta.TransactionManager getTransactionManager() - gets a TransactionManager object. the ObjectWeb TransactionManager interface extends the JTA one to provide support for late enlistment of resources
• public javax.transaction.UserTransaction getUserTransaction() - gets a JTA UserTransaction object
• public void stop() - stops the transaction manager

2.2. Instanciation of JOTM

JOTM defines an object, org.objectweb.jotm.Jotm, which implements org.objectweb.transaction.jta.TMService and can be used to start JOTM. In addition to the TMService methods, it has a public constructor:

• public Jotm(boolean local, boolean bound) - creates an instance of JOTM.

  the local boolean states if the transaction factory used to coordinate transactions is local to this instance or located on another instance of JOTM.
  If the transaction factory is local, the bound boolean states if it should be bound to a registry and made accessible through JNDI^TM (Java Naming and Directory Interfaces).

The rule to remember is that, in one "transaction domain", there can be one and only one JOTM with a local transaction factory. If there may be other instances, they have to be created with a remote transaction factory which has been bound by the JOTM which created it locally.

3. Integration of JOTM

To integrate JOTM in another product, some additional libraries are required.

3.1. Required libraries

JOTM requires some libraries and API (they are all in the lib/ directory of JOTM distribution:

• jotm.jar - JOTM
• jotm_jrmp_stubs.jar - JOTM stubs for RMI/JRMP
• jotm_iiop_stubs.jar - JOTM stubs for RMI/IIOP
• carol.jar - CAROL (RMI support)
• jta-spec1_0_1.jar - JTA
• jts1_0.jar - JTS^TM (Java Transaction Service)
• jonas_timer.jar - JOnAS timer
• commons-logging.jar
• log4j.jar - Log4J^TM
• commons-cli.jar - CLI^TM (Command-line interface) library (used only by standalone JOTM)

3.2. Classpath setting

You need to put in the classpath only jotm.jar and the jar files of the stubs (jotm_jrmp_stubs.jar and/or jotm_iiop_stubs.jar).
The other jar files will be loaded thanks to the class-path attribute of the manifest file of jotm.jar (the jar files still need to be in the same location than jotm.jar).

JOTM configuration files (RMI support, JNDI properties, trace configurations,...) needs to be placed in a config/ directory at the same level than the lib/ directory (the class-path attribute of JOTM jar files will look for them in ../config/ directory.

3.3. RMI registry

If you plan to bind JOTM objects such as UserTransaction or TransactionManager in JNDI by using RMI registry (rmiregistry), you'll need to start the registry with specific permissions due to use of CAROL. Such a java.policy can be found in the config/ directory of JOTM distribution.
RMI registry will also need to have both jotm.jar and jotm_jrmp_stubs.jar in its classpath.

From the lib/ directory of JOTM, you can start the RMI registry with the following commande:

rmiregistry -J-classpath -Jjotm.jar:jotm_jrmp_stubs.jar -J-Djava.security.policy=../config/java.policy

3.4. Embedded JOTM

JOTM can be embedded in a "container" (e.g. an EJB container or a Servlets one or a standalone application) and ran in the same JVM.

All you have to do is to create in the code of a container an instance of JOTM with a local transaction factory which is not bound:

    try {
       TMService jotm = new Jotm(true, false);
    } catch (NamingException e) {
      // thrown only if JOTM is started with a remote transaction
      // factory or if it has to be bound.
    }

Then you can access UserTransaction and TransactionManager objects:

    UserTransaction utx = jotm.getUserTransaction();
    TransactionManager tm = jotm.getTransactionManager();
  

It's also up to the container developper to choose if it wants to bind these objects in a registry or if they will only be used inside the same JVM. An example of such a case is the JDBC example included in the JOTM distribution where TransactionManager is only used locally whereas UserTransaction is bound to a registry.

For more information, see Jotm Javadoc.

3.5 Standalone JOTM

JOTM can be also started as a standalone application. In that case, containers can access JTA objects by looking up them in a registry.

To start JOTM as a standalone application, from a command line interface, type:

java org.objectweb.jotm.Main [args]

• -u USER_TRANSACTION_JNDI_NAME - binds a UserTransaction to the registry with the name USER_TRANSACTION_JNDI_NAME

• -m TRANSACTION_MANAGER_JNDI_NAME - binds a TransactionManager to the registry with the name TRANSACTION_MANAGER_JNDI_NAME

To have a complete list of the available arguments, type:

java org.objectweb.jotm.Main --help

Containers can then access those objects by looking up them through JNDI.

For more information, see Main Javadoc.

Contacts

If you have some trouble to integrate JOTM, any questions or if you want to contribute, do not hesitate to contact us.