ExtremeTransactions® # Atomikos® ExtremeTransactions® Quick Start Thank you for using ExtremeTransactions® (powered by Atomikos® TransactionsEssentials®). Below are instructions to get you started on the right foot. ## Contents What is ExtremeTransactions®? How to use ExtremeTransactions® Documentation Professional Support License Migration from a previous release New in This Release Acknowledgment ## What is ExtremeTransactions®? This product is a next-generation transaction manager for the Java™ and SOA/GRID/XTP platforms. It supports revolutionary features such as: compatible with the standard JTA API from Sun™ built-in JDBC adapters for both XA and non-XA JDBC connectors built-in JMS adapters for XA-capable JMS connectors TCC (Try-Confirm/Cancel): distributed transactions without the restrictions of XA service transactions for SOA compensating transactions full crash/restart recovery distributed recovery across service networks nested transactions RMI-IIOP transactions compatible with third-party adapters through the XA API designed for easy integration with your product ## How to use ExtremeTransactions® ExtremeTransactions® 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 our 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: ExtremeTransactions® 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 be enabled with its own, intra-VM transaction manager. Transactions can span SOAP, RMI-IIOP or JMS networks: in a network, the different intra-VM transaction managers will communicate with each other, and behave as one 'virtual' transaction manager. ### System Requirements Before using ExtremeTransactions®, you need to install the following: A Java SDK, Standard Edition version 1.5 or higher. Note that you really need the SDK, not just the runtime (or the demos won't work). 128MB of RAM. Apache Ant (only needed for the demos). ### Optimizing Performance Although ExtremeTransactions® is very fast in all situations, in general the following holds: Use the fastest disk you can find. 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 necessary (but not larger). 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, ExtremeTransactions® 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 ExtremeTransactions in J2SE To use ExtremeTransactions in your J2SE application, just do the following: Put the all jar files of the lib/ and dist/j2se folders in your classpath Create or customize your application's transactions.properties (or jta.properties) file (the configuration file for ExtremeTransactions®) 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). J2SE applications can also use non-XA transactions along the TCC paradigm (Try-Confirm/Cancel). In that case none of the above is necessary (no special JDBC/JMS connectors are required and no JTA transaction needs to be started either), but you do need to implement the compensation and confirmation logic in the application. Check out the TCC with RMI example and the ExtremeTransactionsGuide for more information. Check out the documentation for more background information. Important: although this release contains specific third-party products such as RDBMS software and JMS broker software, please note that ExtremeTransactions® 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). The demo scripts (bat files) assume that you are running everything on the SAME machine, so running the demos on multiple servers will require editing the bat files (shell scripts on UNIX). 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. #### More Information Check out the documentation for more information on how to program transactional J2SE applications, or for more information on the Java Transaction API (JTA). ### Using ExtremeTransactions® in Spring ExtremeTransactions® 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. #### Spring Examples See examples/spring for demos showing how to configure Spring-based applications to use transactions. ### Using ExtremeTransactions® in J2EE (Web) Containers To use ExtremeTransactions in your favorite J2EE (web) container, you typically need to do the following: Add the jar files from the lib and dist/j2ee/server folders to your application server's classpath. Add the jar files from the dist/j2ee/app folder to your J2EE (web) application's classpath (typically the WEB-INF/lib folder).. Add any third-party connectors for JDBC or JMS to the application server's classpath. Deploy our com.atomikos.jdbc.AtomikosDataSourceBean or com.atomikos.jdbc.nonxa.AtomikosNonXADataSourceBean on your application server. These connector classes are wrappers for your vendor-specific database drivers, and add transactional reliability for each JDBC access. Note: you can omit this step if you plan to use the TCC paradigm with compensation-based rollback (see below). To start/terminate JTA transactions in your J2EE applications, use an instance of our com.atomikos.icatch.jta.UserTransactionImp or com.atomikos.icatch.jta.J2eeTransactionManager (alternatively, an instance of these classes can be bound in the JNDI of your application server). You can omit this step if you plan to use the TCC paradigm with compensation-based rollback (see the manuals). 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. ### Web Service Transactions Atomikos supports web services transactions via its proprietary protocol (see wsdl). Web service transactions are configured via Atomikos handlers: use ExportingTransactionHandler on the client (sender) side and ImportingTransactionHandler on the server (receiving) side. (for more info, also see the ExtremeTransactionsGuide). If you configured the Atomikos native handlers with the jtaCompatible init parameter set, incoming invocations with a web service transaction context will be accessible via (and compatible with) the JTA API in the local VM. In this case, a web service transaction is 'imported' as a JTA transaction, and will control all JDBC and/or JMS accesses in the service. This implies that database locks are kept until the global web service transaction terminates. This behaviour is not appropriate nor desirable for loosely-coupled systems; in that case use the Atomikos TCC paradigm (Try-Confirm/Cancel, which is compensation-based): for TCC, an invocation will not automatically correspond to a JTA transaction in the server VM. This means that JDBC and/or JMS accesses will not lead to long XA locks. With TCC, rollback (compensation) or commit (confirmation) are to be handled at the application level. TCC ensures the consistency of full distributed transactions, but without the need for (and the drawbacks of) classical XA transactions. See the manuals for more details. #### JAX-WS Examples See examples/jaxws folder for a working demo with web services. NOTE: you need Apache Ant installed on your system before you can run these demos. The demo scripts (bat files) assume that you are running everything on the SAME machine, so running the demos on multiple servers will require editing the bat files (shell scripts on UNIX). Also, note that the demos require that your installation path is very close to the root of your hard disk, or you will get "Input line is too long" errors. #### More Information Check out the ExtremeTransactionsGuide for more information. ## Documentation ### Manuals TransactionsEssentialsGuide: Read this guide to learn about the basic JTA/XA capabilities, included from TransactionsEssentials®. AtomikosAPISpecification: Read this guide if you really want to know all the Atomikos API details. Most users will never have to read this, but if you want to use the more advanced features of ExtremeTransactions® then this guide will be interesting material. ExtremeTransactionsGuide: Read this guide to learn more on transactions for SOA and GRIDs and/or web services. ### Javadoc Click here to browse the javadoc for ExtremeTransactions®. ## Professional Support Professional support is available from Atomikos; contact sales@atomikos.com for more information. If you have any questions or feedback, you can also visit our community forums, although for guaranteed response times we highly recommend professional support. ## License Click here to read the license terms. ## Purchasing a Commercial (Redistributor) License Contact sales@atomikos.com for more information. ## Migration from a previous release Make sure to include all the (extra) jars of this release in order to make the new JDBC work. ## New in This Release Check out the release notes for a detailed overview. ## Acknowledgments This product is powered by Atomikos® TransactionsEssentials®. This product 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.