com.boylesoftware.cb2
Interface TransactionContext

public interface TransactionContext

Interface for transaction context implementations used by the application context to manage database transactions. Application context reads com.boylesoftware.cb2.txContext application property, which names a class that implements this interface, and uses it as transaction context with its transaction management methods.

When a new thread tries to perform a transactional database operation, the application context checks if it already has a transaction context object instance associated with it and if not, creates an instance of transaction context and binds it to the thread. Right after the new instance is created the application context calls setup on it and then other methods are called according to the protocol. The instance stays bound to the thread until the thread dies.

There are also transaction management methods in the application context that operate on transaction contexts that are not bound to any thread.

Note, that implementations should be thread-safe providing their own means of access synchronization. Multiple threads can be trying to call different methods at the same time.

CB2 has several standard transaction context implementations. See description of com.boylesoftware.cb2.txContext application property in the ApplicationContext class description.

Version:

$Id: TransactionContext.java,v 1.7 2004/04/20 16:00:58 levahim Exp $

Author:

Lev Himmelfarb

Field Summary

static java.lang.String

LOG_SUBSYS Channel name for the logger.

Method Summary

void	begin() Begin a new transaction.
boolean	commit() Commit the transaction.
java.sql.Connection	getConnection(java.lang.String dataSourceName) Get a database connection managed by this transaction context.
boolean	isActive() Tells if there is an active transaction at the moment of the call.
boolean	isRollbackOnly() Tells if the transaction is marked for rollback only.
boolean	rollback() Rollback the transaction.
void	setRollbackOnly() Marks the transaction for rollback only.
void	setup(ApplicationContext appCtx) Setup the instance before using it.
boolean	supportsUnboundTransactions() Tells if this implementation supports transaction contexts that are not bound to a thread.

Field Detail

LOG_SUBSYS

public static final java.lang.String LOG_SUBSYS

Channel name for the logger. Interface implementators should use it when logging messages.

See Also:

Constant Field Values

Method Detail

setup

public void setup(ApplicationContext appCtx)
           throws ApplicationException

Setup the instance before using it. This method is called by the application context once for every new instance.

Parameters:

appCtx - the application context.

Throws:

ApplicationException - if an error happens.

begin

public void begin()
           throws ApplicationException

Begin a new transaction.

Throws:

ApplicationException - if an error happens, if there is already an active transaction and the transaction context does not support nested transactions.

getConnection

public java.sql.Connection getConnection(java.lang.String dataSourceName)
                                  throws java.sql.SQLException

Get a database connection managed by this transaction context. This method can be called only between begin and commit or rollback method calls, that is when transaction is active.

Parameters:

dataSourceName - logical name of the datasource, from which to get the connection.

Returns:

the database connection.

Throws:

java.sql.SQLException - if the connection cannnot be retrieved due to the underlying data source error.

java.lang.IllegalStateException - if the transaction is not ative. In other words if the transaction has not been begun or is already committed or rolled back.

commit

public boolean commit()
               throws ApplicationException

Commit the transaction.

Returns:

true if there are no active transactions anymore after successful commit. Can return false if nested transactions are supported and there are still active transactions in the stack after committing the topmost one.

Throws:

ApplicationException - when the underlying subsystem error happens.

java.lang.IllegalStateException - if the transaction is not ative. In other words if the transaction has not been begun or is already committed or rolledback.

rollback

public boolean rollback()
                 throws ApplicationException

Rollback the transaction.

Returns:

true if there are no active transactions anymore after successful rollback. Can return false if nested transactions are supported and there are still active transactions in the stack after rolling back the topmost one.

Throws:

ApplicationException - when the underlying subsystem error happens.

java.lang.IllegalStateException - if the transaction is not ative. In other words if the transaction has not been begun or is already committed or rolledback.

setRollbackOnly

public void setRollbackOnly()
                     throws ApplicationException

Marks the transaction for rollback only. When the application tries to commit a transaction which is marked for rollback only, the transaction context will roll it back instead of committing. Calling this method when there are no active transactions does nothing and is perfectly valid.

Throws:

ApplicationException - when the underlying subsystem error happens.

isRollbackOnly

public boolean isRollbackOnly()
                       throws ApplicationException

Tells if the transaction is marked for rollback only.

Returns:

true if the transaction is marked for rollback only. Always returns false if there are no active transactions.

Throws:

ApplicationException - when the underlying subsystem error happens.

See Also:

setRollbackOnly()

isActive

public boolean isActive()

Tells if there is an active transaction at the moment of the call.

Returns:

true if the transaction is active.

supportsUnboundTransactions

public boolean supportsUnboundTransactions()

Tells if this implementation supports transaction contexts that are not bound to a thread.

Returns:

true if unbound transaction contexts can be created.