How to integrate JOTM

Target audience

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

It is not intended to JOTM users. For information, on how to use JOTM, you can chek the installation and examples guide 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 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:

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

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:

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]
with some [args] being:

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.