Tomcat 5.5 Integration with Atomikos 3.3+

It is possible to fully integrate the Atomikos transaction manager into Tomcat. Doing it this way makes the transaction manager shared across all web applications exactly like with any full-blown J2EE server.

Important note

When the Atomikos transaction manager is installed globally in Tomcat, you now must also install your JDBC driver at the same global location (ie: into the TOMCAT_HOME/common/lib folder). If you dont do that, you will get a NoClassDefFoundErrors or a ClassNotFoundException or even a ClassCastException during your web application deployment.

This is not a limitation of Atomikos nor of Tomcat but of the J2EE class loading design that both Tomcat and Atomikos must follow.

Installation

Installation is quite simple, it just involves copying some JAR files, a propery file and editing some Tomcat configuration files.

Copying Atomikos Tomcat Lifecycle library

This JAR contains a single class file that is a Tomcat lifecycle listener: it listens for Tomcat's startup and shutdown events and start or stop the transaction manager accordingly. Here is its source code:

Atomikos Lifecycle Listener.java

package com.atomikos.tomcat;

import org.apache.catalina.Lifecycle;
import org.apache.catalina.LifecycleEvent;
import org.apache.catalina.LifecycleListener;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import com.atomikos.icatch.jta.UserTransactionManager;
import com.atomikos.icatch.system.Configuration;

public class AtomikosLifecycleListener implements LifecycleListener {
   
   private static Log log = LogFactory.getLog(AtomikosLifecycleListener.class);
   
   private UserTransactionManager utm;

   public void lifecycleEvent(LifecycleEvent event) {
      if (Lifecycle.START_EVENT.equals(event.getType())) {
         if (utm == null) {
            log.info("starting Atomikos Transaction Manager " + Configuration.VERSION);
            utm = new UserTransactionManager();
         }
      }
      else if (Lifecycle.STOP_EVENT.equals(event.getType())) {
         if (utm != null) {
            log.info("shutting down Atomikos Transaction Manager");
            utm.close();
         }
      }
   }

}

Copying Atomikos Tomcat BeanFactory library

This JAR contains a single class file that is an enhanced version of Tomcat JNDI's Bean Factory. Here is its source code:

Bean Factory.java

package com.atomikos.tomcat; import java.util.Hashtable; import java.util.Enumeration; import javax.naming.Name; import javax.naming.Context; import javax.naming.NamingException; import javax.naming.Reference; import javax.naming.RefAddr; import javax.naming.spi.ObjectFactory; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import org.apache.naming.ResourceRef; import org.apache.naming.factory.Constants; import com.atomikos.beans.PropertyUtils; import com.atomikos.jdbc.AtomikosDataSourceBean; public class BeanFactory implements ObjectFactory { private final static Log log = LogFactory.getLog(BeanFactory.class); public Object getObjectInstance(Object obj, Name name, Context nameCtx, Hashtable environment) throws NamingException { if (obj instanceof ResourceRef) { try { Reference ref = (Reference) obj; String beanClassName = ref.getClassName(); Class beanClass = null; ClassLoader tcl = Thread.currentThread().getContextClassLoader(); if (tcl != null) { try { beanClass = tcl.loadClass(beanClassName); } catch(ClassNotFoundException e) { } } else { try { beanClass = Class.forName(beanClassName); } catch(ClassNotFoundException e) { e.printStackTrace(); } } if (beanClass == null) { throw new NamingException("Class not found: " + beanClassName); } if (!AtomikosDataSourceBean.class.isAssignableFrom(beanClass)) { throw new NamingException( "Class is not a AtomikosDataSourceBean: " + beanClassName); } if (log.isDebugEnabled()) log.debug("instanciating bean of class " + beanClass.getName()); AtomikosDataSourceBean bean = (AtomikosDataSourceBean) beanClass.newInstance(); int i=0; Enumeration en = ref.getAll(); while (en.hasMoreElements()) { RefAddr ra = (RefAddr) en.nextElement(); String propName = ra.getType(); if (propName.equals(Constants.FACTORY) || propName.equals("scope") || propName.equals("auth")) { continue; } String value = (String) ra.getContent(); if (log.isDebugEnabled()) log.debug("setting property '" + propName + "' to '" + value + "'"); PropertyUtils.setProperty(bean, propName, value); i++; } if (log.isDebugEnabled()) log.debug("done setting " + i + " property(ies), now initializing resource " + bean); bean.init(); return bean; } catch (Exception ex) { throw new NamingException( "error creating AtomikosDataSourceBean").initCause(ex); } } else { return null; } } } 

Copying TransactionsEssentials libraries

  • Drop the following JARs from the Atomikos distribution into the TOMCAT_HOME/common/lib folder:
    • transactions.jar
    • transactions-api.jar
    • transactions-jta.jar
    • transactions-jdbc.jar
    • atomikos-util.jar.jar
    • jta.jar

You should also copy the transactions-hibernate3.jar and/or transactions-hibernate2.jar at the same location if you're planning to use Hibernate.

Copying Atomikos configuration file

  • Drop the following properties file into the TOMCAT_HOME/common/classes folder: jta.properties

Edit server.xml

Then edit the TOMCAT_HOME/conf/server.xml file. At the beginning of the file you should see these four lines:

  <Listener className="org.apache.catalina.core.AprLifecycleListener" />
  <Listener className="org.apache.catalina.mbeans.ServerLifecycleListener" />
  <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />
  <Listener className="org.apache.catalina.storeconfig.StoreConfigLifecycleListener"/>

Right after the last one, add this fifth one:

 <Listener className="com.atomikos.tomcat.AtomikosLifecycleListener" />

Edit context.xml

Then edit the TOMCAT_HOME/conf/context.xml file. At the beginning of the file you should see this line:

 <WatchedResource>WEB-INF/web.xml</WatchedResource>

Right after it, add that one:

 <Transaction factory="com.atomikos.icatch.jta.UserTransactionFactory" />

Example application

Here is a sample application that demonstrates how you can run TransactionsEssentials in a web application after it has been globally installed.

It is a simple blueprint application that shows and updates the content of a single Derby database.

Download the sample application here: dbtest.war

To install it, simply copy the WAR file in Tomcat's webapps folder. You also need to install Derby's JDBC driver in TOMCAT_HOME/common/lib.

You can then access it via this URL: http://localhost:8080/dbtest/.

Notes

  • This demo uses an embedded Derby database. If it doesn't exist a new one is created in TOMCAT_HOME/work or else, the existing one is reused.
  • The transactions logs and debug logs are stored in TOMCAT_HOME/work.
  • You should get logs during Tomcat's startup and shutdown:
    • during startup: INFO: starting Atomikos Transaction Manager 3.3.0
    • during shutdown: INFO: shutting down Atomikos Transaction Manager
I Attachment Action Size Date Who Comment
elsejaratomikos-tomcat-beanfactory.jarmanage 2.8 K 19 May 2008 - 11:58LudovicOrban  
elsejaratomikos-tomcat-lifecycle.jarmanage 1.7 K 19 May 2008 - 11:58LudovicOrban  
elsewardbtest.warmanage 4.3 K 19 May 2008 - 12:15LudovicOrban  
elsejarderby-10.2.2.0.jarmanage 2222.7 K 19 May 2008 - 12:17LudovicOrban  
elsepropertiesjta.propertiesmanage 0.2 K 19 May 2008 - 12:12LudovicOrban  
Attach
else version 1 uploaded by LudovicOrban on 19 May 2008 - 11:58
 
else version 1 uploaded by LudovicOrban on 19 May 2008 - 11:58
 
else
dbtest.war (4.3 K)
version 1 uploaded by LudovicOrban on 19 May 2008 - 12:15
 
else
derby-10.2.2.0.jar (2222.7 K)
version 1 uploaded by LudovicOrban on 19 May 2008 - 12:17
 
else version 1 uploaded by LudovicOrban on 19 May 2008 - 12:12
 
spacer
Copyright © 2014 Atomikos BVBA. Transaction Management for Extreme Transaction Processing and SOA Environments serving ISV, Commercial, OEM and Open Source Markets
Site map RSS ATOM