org.mbs.services.transaction
Interface Transaction

All Superinterfaces:

TransactionContext

public interface Transaction
extends TransactionContext

A Transaction object can be obtained from the TransactionManager with the createTransaction() method. The returned transaction is open and associated with the current thread. (getCurrentTransaction() will return it). However, the object's methods may be called in other threads as well. The transaction object is created by client code. When the client code calls other subsystems, the subsystems can join the transaction. joining the transaction means they can affect the outcome of the transaction. Once the client is finished, it should call commit if all the changes were successful, or call roll-back if there were problems. The commit will persist the changes while roll-back will undo all the changes since the beginning of the transaction. A transaction will pass through a well defined set of states.

Author:

Valentin Valchev

Field Summary

Fields inherited from interface org.mbs.services.transaction.TransactionContext

STATUS_ACTIVE, STATUS_COMMITTED, STATUS_COMMITTING, STATUS_MARKED_ROLLBACK, STATUS_NO_TRANSACTION, STATUS_PREPARED, STATUS_PREPARING, STATUS_ROLLEDBACK, STATUS_ROLLING_BACK, STATUS_UNKNOWN

Method Summary

void	commit() Complete the transaction associated with the current thread.
void	rollback() Roll back the transaction associated with the current thread.
void	setTransactionTimeout(int seconds) Modify the timeout value that is associated with transactions started by subsequent invocations of the begin method.

Methods inherited from interface org.mbs.services.transaction.TransactionContext

associateThread, disassociateThread, getPid, getStatus, join, resetTimeout, setRollbackOnly, waitThreadsToFinish

Method Detail

commit

void commit()
            throws TransactionException

Complete the transaction associated with the current thread. If the status is TransactionContext.STATUS_MARKED_ROLLBACK, this transaction must be rolled back. If the status is anything else but TransactionContext.STATUS_ACTIVE, an IllegalStateException is thrown. The status is set to TransactionContext.STATUS_PREPARING Call all participating Resource Managers with the prepare method in no particular order. The transaction manager may use multiple threads to call the different resource managers. If any of them throw an exception, perform a roll-back and return false. In that case, the remaining prepare methods should not be called. The status is set to TransactionContext.STATUS_PREPARED The status is set to TransactionContext.STATUS_COMMITTING Call all participating Resource Managers with the commit method. If a resource manager fails the commit (exception, timeout), continue with the remaining resource managers and log the offending resource managers. The status is set to TransactionContext.STATUS_COMMITTED if all commits are successful. Before returning, the transaction will release all the locks held by this transaction.

Throws:

java.lang.SecurityException - Thrown to indicate that the thread is not allowed to commit the transaction.

TransactionException - if the transaction was rolled back, instead of committed

rollback

void rollback()

Roll back the transaction associated with the current thread. The status is set to TransactionContext.STATUS_ROLLING_BACK Call the TransactionResource.rollback(TransactionContext) method on all participating resource managers. Exceptions should be logged but may not block calling the other resource managers. The status is set to TransactionContext.STATUS_ROLLEDBACK

Throws:

java.lang.SecurityException - Thrown to indicate that the thread is not allowed to commit the transaction.

setTransactionTimeout

void setTransactionTimeout(int seconds)

Modify the timeout value that is associated with transactions started by subsequent invocations of the begin method. If an application has not called this method, the transaction service uses some default value for the transaction timeout.

Parameters:

seconds - - The value of the timeout in seconds. If the value is zero, the transaction service restores the default value.

Throws:

java.lang.IllegalArgumentException - if the seconds parameter has negative value