How to use Atomikos as the transaction manager in jetty6

These instructions are for Atomikos 3.3 onwards, and have been verified against Atomikos 3.4.2. If you are using an older version, see #Configuration for older versions for additional instructions (for Atomikos versions 2.10, 3.0.1).

Step 1: Copy the Atomikos jars

Copy the following jars from your Atomikos installation to the jetty6 lib directory:

  • transactions-essentials-all.jar
  • jta.jar

Step 2: Configure Atomikos as the transaction manager

Copy the following into your jetty config file:

<New id="tx" class="org.mortbay.jetty.plus.naming.Transaction">
 <Arg>
   <New class="com.atomikos.icatch.jta.UserTransactionImp"/>
 </Arg>
</New>

Step 3: Configure DataSources that are transaction aware

The easiest way to do this is to use the DataSources that ship with Atomikos. Atomikos provides two different flavours of DataSource. One is for use with database datasources that are XADataSource compliant (ie they fully participate in two phase commits), and another which allows non-XA aware datasources to nevertheless work with the transaction manager (however some XA features such as pending transaction recovery will not be available).

Here's an example of using Atomikos with a DataSource that implements javax.sql.XADataSource:

  <New id="mydatasource" class="org.mortbay.jetty.plus.naming.Resource">
    <Arg><Ref id='wac'/></Arg>
    <Arg>jdbc/mydatasource</Arg>
    <Arg>
      <New class="com.atomikos.jdbc.AtomikosDataSourceBean">
        <Set name="xaDataSourceClassName">org.apache.derby.jdbc.EmbeddedXADataSource</Set>
        <Set name="xaProperties">
          <New class="java.util.Properties">
            <Call name="setProperty"><Arg>databaseName</Arg><Arg>testdb</Arg></Call>
            <Call name="setProperty"><Arg>createDatabase</Arg><Arg>true</Arg></Call>
          </New>
        </Set>
        <Set name="UniqueResourceName">mydatasource</Set>
      </New>
    </Arg>
  </New>

The com.atomikos.jdbc.AtomikosDataSourceBean implements javax.sql.DataSource and interacts with the javax.sql.XADataSource provided in this instance by Derby.

If your database vendor does not provide an XADataSource, you can use Atomikos's com.atomikos.jdbc.nonxa.NonXADataSourceBean to allow your database connections to be controlled by the transaction manager:

<New id="example-nonxads" class="org.mortbay.jetty.plus.naming.Resource">
      <Arg>jdbc/exampleNonXADS</Arg>
      <Arg>
       <New class="com.atomikos.jdbc.nonxa.NonXADataSourceBean">
         <Set name="Url">jdbc:derby:example;create=true</Set>
         <Set name="driverClassName">org.apache.derby.jdbc.EmbeddedDriver</Set>
       </New>
      </Arg>
</New>

Again, we've used Derby as an example, but as the NonXADataSourceBean uses only the class name and url of a java.sql.Driver, you can use it with any database providing a JDBC driver.

There is more documentation available from the Atomikos site on using their DataSources.

Configuration for older versions

The sample configurations in this section have been verified against Atomikos 2.10 and 3.0.1, and are provided for legacy purposes. Updated code and more detailed explanations of each section are available above.

Step 1: Copy the Atomikos jars

Copy the following jars from your Atomikos installation to the jetty6 lib directory:

  • transactions_2_10.jar
  • jta.jar
  • licenseJTA.jar
  • transactions.jar
  • jta.jar
  • transactions-jta.jar
  • transactions-api.jar
  • atomikos-utils.jar

Step 2: Copy and install the Atomikos console webapp

Skip this step for Atomikos 3.0.1 and higher

Copy the following webapp to a jetty6 deployment directory, for example webapps-plus:

If you are using the etc/jetty-plus.xml configuration file and you are deploying from webapps-plus you won't need to configure the webapp for jetty6, as the etc/jetty-plus.xml file automatically deploys everything in webapps-plus. If you are doing something different, you can use the following xml snippet to configure the Atomikos console webapp for jetty6:

<New id="atomikos"  class="org.mortbay.jetty.webapp.WebAppContext">
  <Set name="contextPath">/atomikos</Set>
  <Set name="war">MY/DEPLOY/DIRECTORY/atomikos</Set>
  <Set name="ConfigurationClasses"><Ref id="plusConfig"/></Set>
</New>

Don't forget to substitute MY/DEPLOY/DIRECTORY with the location of your deploy directory.

Step 3: Configure Atomikos as the transaction manager

Copy the following into your jetty config file:

<New id="tx" class="org.mortbay.jetty.plus.naming.Transaction">
 <Arg>
   <New class="com.atomikos.icatch.jta.J2eeUserTransaction"/>
 </Arg>
</New>
<New id="tx" class="org.mortbay.jetty.plus.naming.Transaction">
 <Arg>
   <New class="com.atomikos.icatch.jta.UserTransactionImp"/>
 </Arg>
</New>

Step 4: Configure DataSources that are transaction aware

Here's an example of using Atomikos with a DataSource that implements javax.sql.XADataSource:

<New id="mydatasource" class="org.mortbay.jetty.plus.naming.Resource">
  <Arg>jdbc/mydatasource</Arg>
  <Arg>
    <New class="com.atomikos.jdbc.SimpleDataSourceBean">
      <Set name="xaDataSourceClassName">org.apache.derby.jdbc.EmbeddedXADataSource</Set>
      <Set name="xaDataSourceProperties">databaseName=testdb;createDatabase=create</Set>
      <Set name="UniqueResourceName">mydatasource</Set>
    </New>
  </Arg>
</New>

Note that com.atomikos.jdbc.SimpleDataSourceBean has been deprecated in favor of com.atomikos.jdbc.AtomikosDataSourceBean since 3.3.x. com.atomikos.jdbc.SimpleDataSourceBean takes a semi-colon delimited string of attribute pairs, while com.atomikos.jdbc.AtomikosDataSourceBean accepts java.util.Properties.

If your database vendor does not provide an XADataSource, you can use Atomikos's com.atomikos.jdbc.nonxa.NonXADataSourceBean to allow your database connections to be controlled by the transaction manager. For an example of this, see "Configure DataSources that are transaction aware" for recent versions of Atomikos