# Atomikos TransactionsEssentials Quick Start Thank you for using Atomikos TransactionsEssentials; below are instructions to get you started on the right foot... If you have any questions or feedback, please visit our support web page. Contact sales@atomikos.com for commercial support agreements. ## 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? Atomikos TransactionsEssentials is a premium and open sourced class transaction manager for the Java™ platform. The following are some of the features included in this open source release: 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 Atomikos TransactionsEssentials is a library set that adds transactional robustness to your Java applications (both J2SE and J2EE are supported). This means that in order to use this product, you have to add a number of JAR files (included in the dist and lib folders of this installation) to your application or application server. 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 We recommend using at least a Java 1.5 platform (or higher), and a minimum of 128MB of RAM. ### Optimizing Performance Although this software is very fast in all situations, in general the following holds: 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. Also see the documentation for more information on the details of each of these points. 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: Put the jar files of the dist/ and lib/ folders in your classpath 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. In your application, create an instance of com.atomikos.icatch.jta.UserTransactionImp or com.atomikos.icatch.jta.UserTransactionManager (use the default no-argument constructors). For JDBC, use an instance of our com.atomikos.jdbc.AtomikosDataSourceBean or, for non-XA drivers, use com.atomikos.jdbc.nonxa.AtomikosNonXADataSourceBean 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). Please check the full product for complete user guides and more docs. Important: although this release contains specific third-party products such as RDBMS software and JMS broker software, please note that Atomikos TransactionsEssentials is BY NO MEANS restricted to these particular products only. Most (if not all) other RDMBS or JMS products are equally compatible. In addition, some included products have been selected mostly for their ease of use for the demos, rather than for their enterprise-readiness. 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 The folder examples/jse contains various example programs with source code included. To run the examples programs, execute the run scripts (the example programs only have text output, no graphical output). 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 Make sure to check our wiki for up-to-date information and many examples! ### Manuals Please check the commercial product for complete user guides and more docs. ### Javadoc Click here to browse the javadoc for Atomikos TransactionsEssentials. ## License Click here to read the license terms. Contact sales@atomikos.com for commercial support agreements or other licensing possibilities. ## Rebuilding TransactionsEssentials This edition includes the source code in the sources folder of your installation. To rebuild the product (i.e., all the jar files in the dist folder) do the following: Install Apache Ant if you don't have it already. Open a command (shell) window and navigate into the installation folder of TransactionsEssentials. 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)! Type 'ant -projecthelp' in the command shell to see what other Ant build options there are. Note that the test suite for TransactionsEssentials is licensed separately; contact sales@atomikos.com for more details. ## Migration from a previous release ### J2SE Installations If you are migrating from a previous release, then please make sure to do the following: For JMS, make sure to use version 1.1 of the jms.jar (included in this release). Remove (delete) the old log file. Make sure there are no pending transaction first! Change the initialization property names (they are now fully qualified with com.atomikos.icatch prefixes). 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. Optionally change the initialization procedure and the JDBC setup to the newer and simpler design. Review the new features list (see below) for any changes related to deprecated code. ## New in This Release Check out the release notes for a detailed overview. ## Developers See the team page on our wiki... ## Acknowledgments Besides many contributions from the community, this product also includes software developed by the Apache Software Foundation: http://www.apache.org/, to which the following license conditions apply: http://www.apache.org/licenses/LICENSE-2.0.html.