JBoss.orgCommunity Documentation

Chapter 2. Quick Start to JTA

2.1. Introduction
2.2. Package layout
2.3. Setting properties
2.3.1. Specifying the object store location
2.4. Demarcating Transactions
2.4.1. UserTransaction
2.4.2. TransactionManager
2.4.3. The Transaction interface
2.5. Local vs Distributed JTA implementations
2.6. JDBC and Transactions
2.7. Configurable options

2.1. Introduction

This chapter will briefly cover the key features required to construct a JTA application. It is assumed that the reader is familiar with the concepts of the JTA.

2.2. Package layout

The key Java packages (and corresponding jar files) for writing basic JTA applications are:

All of these packages appear in the lib directory of the JBossTS installation, and should be added to the programmer’s CLASSPATH.

In order to fully utilize all of the facilities available within JBossTS, it will be necessary to add some additional jar files to your classpath. See bin/setup-env.sh or bin\setup-env.bat for details.

2.3. Setting properties

has also been designed to be configurable at runtime through the use of various property attributes. These attributes can be provided at runtime on command line or specified through a properties file.

requires an object store in order to persistently record the outcomes of transactions in the event of failures. In order to specify the location of the object store it is necessary to specify the location when the application is executed; for example:

<!-- <br/> --><span class="java_plain">java&nbsp;</span><!-- <br/> --><span class="java_type">DObjectStoreEnvironmentBean</span><!-- <br/> --><span class="java_separator">.</span><!-- <br/> --><span class="java_plain">objectStoreDir</span><!-- <br/> --><span class="java_operator">=/</span><!-- <br/> --><span class="java_plain">var</span><!-- <br/> --><span class="java_operator">/</span><!-- <br/> --><span class="java_plain">tmp</span><!-- <br/> --><span class="java_operator">/</span><!-- <br/> --><span class="java_type">ObjectStore</span><!-- <br/> --><span class="java_plain">&nbsp;myprogram</span>

The default location is a directory under the current execution directory.

By default, all object states will be stored within the defaultStore subdirectory of the object store root, e.g., /usr/local/Arjuna/TransactionService/ObjectStore/defaultStore. However, this subdirectory can be changed by setting the ObjectStoreEnvironmentBean.localOSRoot property variable accordingly.

2.4. Demarcating Transactions

The Java Transaction API consists of three elements: a high-level application transaction demarcation interface, a high-level transaction manager interface intended for application server, and a standard Java mapping of the X/Open XA protocol intended for transactional resource manager. All of the JTA classes and interfaces occur within the javax.transaction package, and the corresponding implementations within the com.arjuna.ats.jta package.

The UserTransaction interface provides applications with the ability to control transaction boundaries.

In , UserTransaction can be obtained from the static com.arjuna.ats.jta.UserTransaction.userTransaction() method. When obtained the UserTransaction object can be used to control transactions

Example 2.1. User Transaction Example

 //get UserTransaction 

UserTransaction utx = com.arjuna.ats.jta.UserTransaction.userTransaction();

// start transaction work..

utx.begin();


// perform transactional work


utx.commit(); 

The TransactionManager interface allows the application server to control transaction boundaries on behalf of the application being managed.

In , transaction manager implementations can be obtained from the static com.arjuna.ats.jta.TransactionManager.transactionManager() method

The Transaction interface allows operations to be performed on the transaction associated with the target object. Every top-level transaction is associated with one Transaction object when the transaction is created. The Transaction object can be used to:

A Transaction object can be obtained using the TransactionManager by invoking the method getTransaction() method.

<!-- <br/> --><span class="java_type">Transaction</span><!-- <br/> --><span class="java_plain">&nbsp;txObj&nbsp;</span><!-- <br/> --><span class="java_operator">=</span><!-- <br/> --><span class="java_plain">&nbsp;</span><!-- <br/> --><span class="java_type">TransactionManager</span><!-- <br/> --><span class="java_separator">.</span><!-- <br/> --><span class="java_plain">getTransaction</span><!-- <br/> --><span class="java_separator">();</span>

2.5. Local vs Distributed JTA implementations

In order to ensure interoperability between JTA applications, it is recommended to rely on the JTS/OTS specification to ensure transaction propagation among transaction managers.

In order to select the local JTA implementation it is necessary to perform the following steps:

In order to select the distributed JTA implementation it is necessary to perform the following steps:

2.6. JDBC and Transactions

ArjunaJTS supports the construction of both local and distributed transactional applications which access databases using the JDBC APIs. JDBC supports two-phase commit of transactions, and is similar to the XA X/Open standard. The JDBC support is found in the com.arjuna.ats.jdbc package.

The ArjunaJTS approach to incorporating JDBC connections within transactions is to provide transactional JDBC drivers through which all interactions occur. These drivers intercept all invocations and ensure that they are registered with, and driven by, appropriate transactions. (There is a single type of transactional driver through which any JDBC driver can be driven. This driver is com.arjuna.ats.jdbc.TransactionalDriver, which implements the java.sql.Driver interface.)

Once the connection has been established (for example, using the java.sql.DriverManager.getConnection method), all operations on the connection will be monitored by . Once created, the driver and any connection can be used in the same way as any other JDBC driver or connection.

connections can be used within multiple different transactions simultaneously, i.e., different threads, with different notions of the current transaction, may use the same JDBC connection. does connection pooling for each transaction within the JDBC connection. So, although multiple threads may use the same instance of the JDBC connection, internally this may be using a different connection instance per transaction. With the exception of close, all operations performed on the connection at the application level will only be performed on this transaction-specific connection.

will automatically register the JDBC driver connection with the transaction via an appropriate resource. When the transaction terminates, this resource will be responsible for either committing or rolling back any changes made to the underlying database via appropriate calls on the JDBC driver.

2.7. Configurable options

The following table shows some of the configuration features, with default values shown in italics. For more detailed information, the relevant section numbers are provided. You should look at the various Programmers Guides for more options.

Note

You need to prefix certain properties in this table with the string com.arjuna.ats.internal.jta.transaction. The prefix has been removed for formatting reasons, and has been replaced by ...

Configuration NamePossible Values

com.arjuna.ats.jta.supportSubtransactions

YES NO

com.arjuna.ats.jta.jtaTMImplementation

...arjunacore.TransactionManagerImple

...jts.TransactionManagerImple

com.arjuna.ats.jta.jtaUTImplementation

...arjunacore.UserTransactionImple

...jts.UserTransactionImple

com.arjuna.ats.jta.xaBackoffPeriod

Time in seconds.

com.arjuna.ats.jdbc.isolationLevel

Any supported JDBC isolation level.