Atomikos TransactionsEssentials Quick Start

Contents

• What is Atomikos TransactionsEssentials?
• How to use Atomikos TransactionsEssentials
• Documentation
• License
• Rebuilding TransactionsEssentials
• Migration from a previous release
• New in This Release
• Developers
• Acknowledgment

What is Atomikos TransactionsEssentials?

• full crash/restart recovery
• compatible with the standard JTA API from Sun™
• nested transactions
• built-in JDBC adapters for both XA and non-XA JDBC connectors
• built-in JMS adapter for XA-capable JMS queue connectors
• built-in JMS adapter for XA-capable JMS topic connectors (sponsored by Webtide)
• compatible with third-party adapters through the XA API
• designed for easy integration with your product
• integration with Hibernate

How to use Atomikos TransactionsEssentials

IMPORTANT: Atomikos TransactionsEssentials is a very fast, embedded transaction manager. This means that you don't have to start a separate transaction manager process (don't look for any bin folder). Instead, your application (server) will have its own, intra-VM transaction manager.

System Requirements

Optimizing Performance

• More RAM means higher throughput (number of transactions per second). Ideally, you should start the Java virtual machine with as much initial heap size as possible.
• Make the connection pools as large as possible.
• Close connections as soon as you no longer need them. Don't cache connections in your application: let the internal connection pools do that for you. This will result in much more efficient connection reuse (and overall memory utilization).
• Don't let active transactions hang around: terminate a transaction in all cases, especially after exceptions. This will minimize database lock times, and also the number of active transactions.

It is worth noting that in all our stress tests, Atomikos TransactionsEssentials had a higher throughput than the J2EE webserver could process requests. These measurements include the logging overhead of transaction states. Also, the performance we measured with both XA and non-XA transactions were the same in all our measurements.

Using Atomikos Transactions Essentials in J2SE

To use Atomikos TransactionsEssentials in your J2SE application, just do the following:

1. Put the jar files of the dist/ and lib/ folders in your classpath
2. Create or customize your application's transactions.properties (or jta.properties) file (configuration of the transaction manager) and put it in your classpath. A sample file is included in the installation folder; properties in comments (#) are the defaults. Uncomment a line and change the value to customize.
3. In your application, create an instance of com.atomikos.icatch.jta.UserTransactionImp or com.atomikos.icatch.jta.UserTransactionManager (use the default no-argument constructors).
4. For JDBC, use an instance of our com.atomikos.jdbc.AtomikosDataSourceBean or, for non-XA drivers, use com.atomikos.jdbc.nonxa.AtomikosNonXADataSourceBean
5. For JMS, use an instance of our com.atomikos.jms.AtomikosConnectionFactoryBean, com.atomikos.jms.extra.AbstractJmsSenderTemplate (for sending), com.atomikos.jms.extra.MessageDrivenContainer (for receiving).
6. Please check the full product for complete user guides and more docs.

JBossMQ note: if you plan to include JBossMQ in your transactions then you must copy the transactions-jta.jar of Atomikos into the JBoss application server classpath. Otherwise, two-phase commit to JBossMQ will fail.

J2SE Examples

Recompiling the samples (optional) is best done by first installating Ant, then opening a command (shell) window in the examples/jse folder and typing 'ant'.

Linux/Unix/Mac OSX Note: On these systems, you have to enable the scripts for execution, by typing 'chmod u+x *.sh' in the terminal window. Otherwise, the examples may not run.

Solving Problems: Occasionally, some of the demos may not start-up any more (despite working fine initially). This is usually due to orphaned processes (such as the JMS broker in the background). Killing any pending processes will solve the problem. Alternatively, restart of your computer will also help.

Using Atomikos TransactionsEssentials in Spring

Atomikos TransactionsEssentials can easily be used in combination with Spring, allowing you to program enterprise-class J2EE applications without the need for EJB or even an EJB container. In addition, our extra JMS message-driven functionality provides a powerful addition to Spring's built-in feature set.

See examples/spring for demos showing how to configure Spring-based applications to use Atomikos TransactionsEssentials.

Hibernate 2.x Integration

You can use Atomikos TransactionsEssentials with Hibernate 2.x by setting the Hibernate TransactionManagerLookup property called hibernate.transaction.manager_lookup_class to com.atomikos.icatch.jta.hibernate.TransactionManagerLookup, and the Hibernate property called hibernate.transaction.factory_class to value net.sf.hibernate.transaction.JTATransactionFactory. See the Hibernate docs for more details on the meaning of this.

Hibernate 3.x Integration

You can use Atomikos TransactionsEssentials with Hibernate 3.x by setting the Hibernate TransactionManagerLookup property called hibernate.transaction.manager_lookup_class to com.atomikos.icatch.jta.hibernate3.TransactionManagerLookup, and the Hibernate property called hibernate.transaction.factory_class to value org.hibernate.transaction.JTATransactionFactory. See the Hibernate docs for more details on the meaning of this.

Using TransactionsEssentials in J2EE (Web) Containers

The easiest way to use TransactionsEssentials in your J2EE application environment is by using Spring as the pico-container. See the Spring section for more details.

Documentation

Wiki

Manuals

Javadoc

License

Rebuilding TransactionsEssentials

1. Install Apache Ant if you don't have it already.
2. Open a command (shell) window and navigate into the installation folder of TransactionsEssentials.
3. Type 'ant' and the system will rebuild itself. NOTE: JDK 1.5 is required to build (but the resulting jars and classes can be used in higher Java versions as well)!
4. Type 'ant -projecthelp' in the command shell to see what other Ant build options there are.

Migration from a previous release

J2SE Installations

1. For JMS, make sure to use version 1.1 of the jms.jar (included in this release).
2. Remove (delete) the old log file. Make sure there are no pending transaction first!
3. Change the initialization property names (they are now fully qualified with com.atomikos.icatch prefixes).
4. The following new initialization properties have been added. You can check the included jta.properties file for the defaults. These defaults may not be appropriate for your case, so we encourage you to override them with the correct values for your application.
   • com.atomikos.icatch.automatic_resource_registration: true by default, this setting allows easy enlist of XAResource instances (without extra setup). However, if you are explicitly enlisting TransactionalResource instances then we recommend that you set this value to false.
   • com.atomikos.icatch.service: this new property determines what implementation of our JTA transaction service you will be using. Set the value to com.atomikos.icatch.standalone.UserTransactionServiceFactory (for the intra-VM JTA) or to com.atomikos.icatch.trmi.UserTransactionServiceFactory (for the RMI transaction service).
   • com.atomikos.icatch.enable_logging: true by default, this setting allows you to switch off the logging of the transaction manager. Doing so is only safe if you have at most one database to connect to.
   • com.atomikos.icatch.console_log_level: this property allows you to select different modes (WARN, INFO or DEBUG) for the output file.
5. Optionally change the initialization procedure and the JDBC setup to the newer and simpler design.
6. Review the new features list (see below) for any changes related to deprecated code.

New in This Release

Developers

Acknowledgments