Show TOC

Background documentationUsing Local Transactions Locate this document in the navigation structure

 

You can use local transactions in your application if it is a relatively simple one, and you are certain that you do not need to use distributed transaction.

When deciding if you want to use local transaction, keep in mind the following considerations:

  • Local transactions cannot be used with a connection that supports XAResources — that is, any connection obtained from a XA connection factory.

  • If there is an active JTA transaction in the executing thread, you cannot run a local transaction in the same thread.

    Recommendation Recommendation

    Avoid using local transactions in your Java EE applications. Using JTA transactions instead makes your application compliant with the Java EE standards, and enables the use of distributed transactions and XAResources as well.

    End of the recommendation.

Features

Local Transaction Interfaces

According to the technology that you use to connect to the persistence layer, you may use the following interfaces for demarcating local transactions:

  • java.sql.Connection (Java Database Connectivity (JDBC))

    When using JDBC, you start a local transaction by setting the autocommit flag of the connection to false (connection.setAutoCommit(false)). The transaction is completed by an invocation of connection.commit() or connection.rollback(). The use of the autocommit flag is explained in more detail in the following section.

  • javax.resource.cci.LocalTransaction (Java Connector Architecture (JCA))

    When using a connection provided by a resource adapter that is compliant with the JCA and supports local transaction, you can demarcate local transactions using the LocalTransaction interface.

    The mechanism is different from the JDBC one. With the connector architecture, you must first call the getLocalTransaction() method of the javax.resource.cci.Connection instance. If the adapter supports the javax.resource.cci.LocalTransaction interface, the method returns a LocalTransaction instance, on which you can call begin() to start the transaction, and finally commit() or rollback() to end it.

  • javax.jdo.Transaction (Java Data Objects (JDO))

    If you work with JDO, you must use the PersistenceManager to obtain a transaction instance. You do this by calling PersistenceManager.currentTransaction(). Then you can start the local transaction by a transaction.begin() call. The transaction ends when you call transaction.commit() or transaction.rollback().

The Autocommit Flag

The autocommit flag is related to the concept of the JDBC local transactions. For a java.sql.Connection, the autocommit flag defines if the SQL statements are executed through the connection separately (if the value of the flag is true) or if they are grouped into a single transaction (if the value is false).

The value of the autocommit flag is set by an invocation of the connection.setAutoCommit() method with a parameter true or false.

You can set the autocommit flag for connections obtained from DataSources with LocalTransaction support. These are the DataSources obtained from a JDBC 1.x-compliant driver.

Outside a JTA transaction, a connection is created with the autocommit flag set to true. When the DataSource.getConnection() method is invoked within the scope of a global transaction, the autocommit flag of the connection is false if the connection is a transactional resource. However, if the DataSource has been declared nontransactional in the deployment descriptor of the component that uses it, the value of the autocommit flag remains true even within the transaction. The flag remains unchanged until the transaction completes. In the case of a nontransactional connection, the transaction does not determine the value of the flag.

More information: Connection Handling in JTA and Local Transactions

An invocation of setAutocommit(false) outside the scope of a JTA transaction or when the connection is nontransactional starts a local transaction. If the autocommit flag has already been set to false, this invocation is equal to an empty call. An invocation of the commit() or rollback() methods respectively commits or rolls back the changes done after the previous commit(), rollback() or setAutocommit(true) call.

An invocation of setAutocommit(true) commits the transaction and sets the autocommit flag to true. If the flag has been previously set to true, this is equal to an empty call.

If you call the setAutocommit() method during a JTA transaction with parameter either true or false, you get an SQLException.