qflib 0.98.1

de.qfs.lib.transaction
Class Transaction

java.lang.Object
  |
  +--de.qfs.lib.transaction.Transaction

public class Transaction
extends java.lang.Object

Transaction instances allow actions to be collected and executed together by commit or to be undone together by rollback. The Transaction class also has convenience methods to create and handle Transactions, using the calling Thread as an identifier. There is no support for transaction isolation of any kind.

With the add method Commitables can be added to the Transaction, which are collected in a list. These are actions that have to be commited to really have an effect or that can be rolled back, to undo their effect. Commit and rollback always close the Transaction first, so that no further Commitables can be added to it and further calls to commit or rollback will do nothing.

When commit is called on a Transaction, all of its Commitable members are themselves commited in the order in which they were added to the Transaction. In the case of rollback each Commitable's rollback method is called in the reverse order.

During either commit or rollback, RuntimeExceptions thrown by the Commitable's methods will be logged but ignored until the whole commit or rollback is completed. Only then the first RuntimeException that occured will be rethrown.

A special case is the FatalTransactionException. It may be thrown during commit or rollback to signal that a problem has occured that makes continuation of commit or rollback useless or even impossible, e.g. a failed JDBC commit.

There are two different ways of creating and managing Transactions. One way is to simply create a Transaction through its constructor. This Transaction has to be passed as a parameter to all methods that want to use it. The more convenient way is to use the static begin method to create a Transaction and retrieve it later with instance. The current Thread of the caller of these methods identifies the Transaction to use.

It is OK to call instance from a Thread for which no Transaction has been created. In this case, a dummy Transaction will be returned, which simply commits all Commitables at the moment they are added to it. Of course, these can never be undone. This mechanism is useful for methods that don't care, whether they are part of a Transaction or not.

A Typical example might look like this:

 Transaction.begin();
 // Watch out: the following block may raise a FatalTransactionException
 try {
     Transaction.instance().add(new CommitableStateChange (object1));
     // modify object1...
     Transaction.instance().add(new CommitableNotify (object1));
     // similar for other objects...
     // call some methods that add more stuff via Transaction.instance...
     Transaction.instance().commit();
 } finally {
     // if commit has been called, rollback won't do anything
     Transaction.instance().rollback();
 }
 

Since:
0.97.0
Version:
$Revision: 1.8 $
Author:
Gregor Schmid

Constructor Summary
Transaction()
          Constructor is not hidden.
 
Method Summary
 void add(Commitable commitable)
          Add a Commitable to the Transaction's rollback list.
static Transaction begin()
          Begin a new Transaction for the current Thread.
 void close()
          Close the transaction.
 void commit()
          Close the Transaction and commit all commitables on its rollback list.
static int getMaxTransactions()
          Get the maximum number of concurrent Transactions.
static boolean insideTransaction()
          Check, whether a Transaction has been created for the current Thread.
static Transaction instance()
          Return the Transaction instance for the current Thread.
 void rollback()
          Close the Transaction and roll back all commitables on its rollback list.
static void setMaxTransactions(int _maxTransactions)
          Set the maximum number of concurrent Transactions.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Transaction

public Transaction()
Constructor is not hidden. Normally instance should be used, but Transactions may be useful in their own rights.
Method Detail

instance

public static Transaction instance()
Return the Transaction instance for the current Thread.
Returns:
The current Transaction.

begin

public static Transaction begin()
                         throws OpenTransactionException
Begin a new Transaction for the current Thread. If the maximum number of concurrent Transactions has already been reached, this call will block until a Transaction is available.
Returns:
The Transaction that is now available via instance.
Throws:
OpenTransactionException - If there is a Transaction for the current Thread that has not been commited or rolled back.

insideTransaction

public static boolean insideTransaction()
Check, whether a Transaction has been created for the current Thread.
Returns:
True, if a Transaction is in progress.

getMaxTransactions

public static final int getMaxTransactions()
Get the maximum number of concurrent Transactions.

setMaxTransactions

public static final void setMaxTransactions(int _maxTransactions)
Set the maximum number of concurrent Transactions. <= 0 means indefinite.
Parameters:
maxTransactions - The maximum to set.

add

public void add(Commitable commitable)
Add a Commitable to the Transaction's rollback list.
Parameters:
commitable - The Commitable to add.

commit

public void commit()
            throws FatalTransactionException
Close the Transaction and commit all commitables on its rollback list.

If the Transaction has already been closed, this does nothing.

Throws:
FatalTransactionException - If something fails in a way that makes completion of commit impossible.

rollback

public void rollback()
              throws FatalTransactionException
Close the Transaction and roll back all commitables on its rollback list.

If the Transaction has already been closed, this does nothing.

Throws:
FatalTransactionException - If something fails in a way that makes completion of rollback impossible.

close

public void close()
Close the transaction. Further calls to commit or rollback will be ignored. It is probably a bad idea to call this method directly instead of calling commit or rollback, but if you want to get rid of a transaction without commit or rollback, this is the way to do it.

qflib 0.98.1