Package com.zfabrik.tx

Class TransactionUtil

java.lang.Object

com.zfabrik.tx.TransactionUtil

public class TransactionUtil
extends Object

This class provides utilities around transaction management with Z2's built-in JTA implementation for easier transaction demarcation. In particular, using get(UserTransaction, ThrowingSupplier), run(UserTransaction, Callable), or run(UserTransaction, ThrowingRunnable) it is not necessary to using complicated try-catch constructions making sure a transaction is orderly completed.

Also, these methods support nesting of invocations.

In that case, only the outer-most invocation will complete the transaction.

Leaving any invocation (nested or not) will set the current transaction to rollback only. That is also the preferred way of forcing a rollback of a transaction.

Invoking an explicit commit or rollback on the user transaction while in a call to any of the utility methods above will normally unassociate a given transaction from the thread and lead to exceptions when leaving the TransactionUtil methods. In other words: Do not use the UserTransaction other than checking on transaction status.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	TransactionUtil.TransactionUtilException	The TransactionUtilException is used to wrap system style exceptions possibly occurring when invoking transaction management methods, but normally not of interest to application, when invoking get(UserTransaction, ThrowingSupplier), run(UserTransaction, Callable), run(UserTransaction, ThrowingRunnable).

Constructor Summary

Constructors

Constructor	Description
TransactionUtil()

Method Summary

Modifier and Type	Method	Description
static <V, E extends Exception> V	get(javax.transaction.UserTransaction ut, ThrowingSupplier<V,E> supplier)	Use this method to execute work in a transaction that returns a result.
static void	mandatory(javax.transaction.UserTransaction ut)	Require an outer active transaction.
static void	never(javax.transaction.UserTransaction ut)	Do not allow an outer active transaction.
static <E extends Exception> void	run(javax.transaction.UserTransaction ut, ThrowingRunnable<E> runnable)	Use this method to execute work in a transaction that returns no result.
static <V> V	run(javax.transaction.UserTransaction ut, Callable<V> callable)	Use this method to execute work in a transaction.

Methods inherited from class java.lang.Object

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

Constructor Details

TransactionUtil

public TransactionUtil()

Method Details

never

public static void never(javax.transaction.UserTransaction ut)

Do not allow an outer active transaction.

mandatory

public static void mandatory(javax.transaction.UserTransaction ut)

Require an outer active transaction.

run

public static <V> V run(javax.transaction.UserTransaction ut,
 Callable<V> callable)
                 throws Exception

Use this method to execute work in a transaction. This is just a utility that helps implementing for example Transaction Servlet Filters that begin and end transactions at the request boundaries.

If there is an ongoing transaction already, this method will not begin a new one. Any exception caught in that case will set that new transaction to rollback.

See also ThreadUtil.confine(Callable, Class) on how to handle checked exception cases gracefully.

Parameters:

ut - the UserTransaction instance of the transaction management system in place

callable - The Callable implementation that defines the work.

Returns:

The result of the callable invocation.

Throws:

Exception

get

public static <V,
E extends Exception> V get(javax.transaction.UserTransaction ut,
 ThrowingSupplier<V,E> supplier)
                                     throws E,
TransactionUtil.TransactionUtilException

Use this method to execute work in a transaction that returns a result.

If there is an ongoing transaction already, this method will not begin a new one. Any exception caught in that case will set that new transaction to rollback.

This method relies on ThrowingSupplier to give the caller control over what exceptions may be propagated.

Any other checked exceptions that may be thrown by underlying transaction management methods, such as SystemException, NotSupportedException will be wrapped into a TransactionUtil.TransactionUtilException.

Parameters:

ut - the UserTransaction instance of the transaction management system in place

supplier - The ThrowingSupplier implementation that defines the work.

Returns:

The result of the supplier invocation.

Throws:

Exception

TransactionUtil.TransactionUtilException

run

public static <E extends Exception> void run(javax.transaction.UserTransaction ut,
 ThrowingRunnable<E> runnable)
                                      throws E,
TransactionUtil.TransactionUtilException

Use this method to execute work in a transaction that returns no result.

If there is an ongoing transaction already, this method will not begin a new one. Any exception caught in that case will set that new transaction to rollback.

This method relies on ThrowingSupplier to give the caller control over what exceptions may be propagated.

Any other checked exceptions that may be thrown by underlying transaction management methods, such as SystemException, NotSupportedException will be wrapped into a TransactionUtil.TransactionUtilException.

Parameters:

ut - the UserTransaction instance of the transaction management system in place

runnable - The ThrowingSupplier implementation that defines the work.

Throws:

Exception

TransactionUtil.TransactionUtilException