How to integrate JOTM

Target audience

This howto is intended for project developers who want to integrate JOTM in their Java projects to provide JTATM support for distributed transactions.

It is not intended for JOTM users. For information, on how to use JOTM, please refer to the installation and examples guides from the documentation page on JOTM web site.

1. JOTM definition

1.1. What JOTM is

1.2. What JOTM is not

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 JSPTM (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 start 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:

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:

2.2. Instanciation of JOTM

JOTM defines an object, org.objectweb.jotm.Jotm, implementing org.objectweb.transaction.jta.TMService and can be used to start JOTM. In addition to the TMService methods, there is a public constructor:

The rule to remember is, in one "transaction domain", there is one and only one JOTM with a local transaction factory. If there are other instances, they are created with a remote transaction factory and are bound by the JOTM creating them locally.

3. Integration of JOTM

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

3.1. Required libraries

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

3.2. Classpath setting

The classpath requires jotm.jar and the jar files of the stubs (jotm_jrmp_stubs.jar and/or jotm_iiop_stubs.jar) only.
Other jar files are loaded due to the class-path attribute of the jotm.jar manifest file. (The jar files are required to be in the same directory as jotm.jar).

JOTM configuration files (RMI support, JNDI properties, trace configurations,...) need to reside in the conf/ directory at the same level as the lib/ directory (the class-path attribute of JOTM jar files looks for them in ../conf/ directory.

3.3. RMI registry

If you plan to bind JOTM objects such as UserTransaction or TransactionManager in JNDI using RMI registry (rmiregistry), you'll need to start the registry with specific permissions required by CAROL. The java.policy is found in the conf/ directory of the JOTM distribution.
RMI registry needs both jotm.jar and jotm_jrmp_stubs.jar in its classpath.

From the lib/ directory of JOTM, start the RMI registry with the following command: (NOTE! UNIX uses a ':' separator. For Windows, use ';')

rmiregistry -J-classpath -Jjotm.jar:jotm_jrmp_stubs.jar:commons-cli-1.0.jar:connector-1_5.jar:howl-0.1.8.jar -J-Djava.security.policy=../conf/java.policy

3.4. Embedded JOTM

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

All you have to do is to create in the container code, a JOTM instance 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 developer to choose to bind these objects in a registry or if they will only be used inside the same JVM. A case example is the JDBC example included in the JOTM distribution where TransactionManager is used locally whereas UserTransaction is bound to a registry.

For more information, see Jotm Javadoc.

3.5 Standalone JOTM

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

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

java org.objectweb.jotm.Main [args]
with [args] being:

To have a complete list of 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 trouble integrating JOTM, questions, or if you want to contribute, do not hesitate to contact us.