org.genericdao

Class Transaction

java.lang.Object

org.genericdao.Transaction

public class Transaction
extends Object

This class is used to begin and end transactions. Transactions are associated with threads. When Transaction.begin() is called a new transaction is started for the current thread. To successfully complete a transaction and save its work, call Transaction.commit(). To undo a transaction's work call Transaction.rollback().

All DAO methods that perform their work on behalf of a transaction should throw RollbackException if there is a problem performing the work. By convention, the current thread's transaction is rolled back before (or in the process of) throwing RollbackException. The reason for rolling back the transaction is described in the message. Should the transaction have been rolled back due to some underlying exception, RollbackException will be thrown as a chained exception with the underlying exception as its cause.

Because transactions can hold locks in the underlying database, it is recommended that user interactions not occur during a transaction. For similar reasons, a method that begins a transaction should ensure that all avenues of departure from the method either commit or roll back the transaction This is typically handled using :

     try {
         Transaction.begin();
         // Application logic, including CRUD calls
         Transaction.commit();
     } catch (...) {
         ...
     } finally {
         if (Transaction.isActive()) Transaction.rollback();
     }
 

Transactions cannot be nested. In other words, calling Transaction.begin() when a transaction is already active in a thread will throw RollbackException.

To write a method that starts a new transaction, unless one is already active, use recursion:

 public void exampleSpecialDAOMethod(B bean) throws RollbackException {
     if (!Transaction.isActive()) {
         try {
             Transaction.begin();
             exampleSpecialDAOMethod(bean);
             Transaction.commit();
             return;
         } finally {
             if (Transaction.isActive())
                 Transaction.rollback();
         }
     }
 
     // Application logic, including CRUD calls
 }
 

Method Summary

Modifier and Type	Method and Description
static void	begin() Begins a new transaction for this thread.
static void	commit() Commits the work performed by this thread's currently running transaction.
static boolean	isActive() Tests whether a transaction is currently running for this thread.
static void	rollback() Causes the work performed by the current thread's currently running transaction to be undone.
static void	setDebugOutput(OutputStream out) Sets an OutputStream to which debugging output will be printed for the current transaction.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

begin

public static void begin()
                  throws RollbackException

Begins a new transaction for this thread.

Throws:

RollbackException - if there is some reason the transaction could not be started. One reason is if you are already in a transaction.

commit

public static void commit()
                   throws RollbackException

Commits the work performed by this thread's currently running transaction.

Throws:

RollbackException - if there is some reason the transaction could not be committed.

isActive

public static boolean isActive()

Tests whether a transaction is currently running for this thread.

Returns:

true if this thread is in a transaction.

rollback

public static void rollback()

Causes the work performed by the current thread's currently running transaction to be undone.

Throws:

AssertionError - if not in a transaction.

setDebugOutput

public static void setDebugOutput(OutputStream out)

Sets an OutputStream to which debugging output will be printed for the current transaction. This method must be call when in a transaction (i.e., after Transaction.begin()). These messages are usually the SQL generated by the GenericDAO. By default, printing of debugging messages is inherited from the connection pool involved in the transaction. To override that default on a particular transaction, use this call (or setDebugWriter). This method is a convenience method which just calls setDebugWriter. It is provided to make it easy to direct debugging messages to System.out.

Parameters:

out - an OutputStream to which debugging messages will be printed or null to turn off printing of debug messages.