net.sourceforge.hivetranse.transaction
Class AbstractTransactionService

java.lang.Object
  net.sourceforge.hivetranse.transaction.AbstractTransactionService

All Implemented Interfaces:

TransactionService, org.apache.hivemind.Discardable, org.apache.hivemind.PoolManageable

Direct Known Subclasses:

HibernateTransactionService, JdbcTransactionService

public abstract class AbstractTransactionService
extends java.lang.Object
implements TransactionService, org.apache.hivemind.Discardable, org.apache.hivemind.PoolManageable

Base class for every actual implementation of TransactionService. This class manages the stack of transaction contexts and the notification of TransactionEventListeners.

Subclasses just have to implement two abstract methods to begin and close an actual transaction, and possibly a third method to store the changing context somewhere. For those subclasses, the notion of transaction can be any Object.

ServiceModel of subclasses must be threaded or pooled

Author:

Jean-Francois Poilpret

Nested Class Summary

protected static class	AbstractTransactionService.Context
protected static class	AbstractTransactionService.TransactionObject

Field Summary

protected AbstractTransactionService.Context	_current
protected org.apache.hivemind.util.EventListenerList	_listeners
protected org.apache.commons.logging.Log	_logger
protected Stack<AbstractTransactionService.Context>	_stack
protected boolean	_wrapRuntimeExceptions

Constructor Summary

protected

AbstractTransactionService(org.apache.commons.logging.Log logger, boolean wrapRuntimeExceptions)

Method Summary

void	activateService()
void	addTransactionEventListener(TransactionEventListener listener) Adds a new listener to the list of TransactionEventListeners notified by this TransactionService upon transaction.
void	begin(TransactionDemarcation demarcation) Marks the beginning of a new transaction demarcation scope.
protected java.lang.Object	beginTransaction()
protected void	cleanUp()
protected java.lang.Exception	cleanUp(AbstractTransactionService.Context context)
protected abstract java.lang.Object	createTransaction() Method called when creation of a new "transaction" is needed.
void	end() Marks the end of a transaction demarcation scope.
protected abstract void	endTransaction(java.lang.Object tx, boolean commit) Method called when the current "transaction" must end, either committed or rolled back.
protected void	fireAfterNewTransactionBegins()
protected void	fireAfterTransactionEnds(boolean committed)
protected void	fireBeforeNewTransactionBegins()
protected void	fireBeforeTransactionEnds(boolean committed)
java.lang.Object	getCurrentTransaction() Get the current "transaction" context for the calling thread.
void	passivateService()
void	removeTransactionEventListener(TransactionEventListener listener) Removes a listener from the list of TransactionEventListeners notified by this TransactionService upon transaction.
void	setRollbackOnly() Marks the current transaction to be rolled back when it will end.
protected void	storeTransaction()
protected void	storeTransaction(java.lang.Object tx) Method called whenever the current transaction context changes.
void	threadDidDiscardService()

Methods inherited from class java.lang.Object

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

Field Detail

_logger

protected final org.apache.commons.logging.Log _logger

_wrapRuntimeExceptions

protected final boolean _wrapRuntimeExceptions

_stack

protected final Stack<AbstractTransactionService.Context> _stack

_listeners

protected final org.apache.hivemind.util.EventListenerList _listeners

_current

protected AbstractTransactionService.Context _current

Constructor Detail

AbstractTransactionService

protected AbstractTransactionService(org.apache.commons.logging.Log logger,
                                     boolean wrapRuntimeExceptions)

Method Detail

threadDidDiscardService

public void threadDidDiscardService()

Specified by:

threadDidDiscardService in interface org.apache.hivemind.Discardable

activateService

public void activateService()

Specified by:

activateService in interface org.apache.hivemind.PoolManageable

passivateService

public void passivateService()

Specified by:

passivateService in interface org.apache.hivemind.PoolManageable

addTransactionEventListener

public void addTransactionEventListener(TransactionEventListener listener)

Description copied from interface: TransactionService

Adds a new listener to the list of TransactionEventListeners notified by this TransactionService upon transaction.

Specified by:

addTransactionEventListener in interface TransactionService

Parameters:

listener - the listener to add to the list

removeTransactionEventListener

public void removeTransactionEventListener(TransactionEventListener listener)

Description copied from interface: TransactionService

Removes a listener from the list of TransactionEventListeners notified by this TransactionService upon transaction.

Specified by:

removeTransactionEventListener in interface TransactionService

Parameters:

listener - the listener to remove from the list

getCurrentTransaction

public java.lang.Object getCurrentTransaction()

Description copied from interface: TransactionService

Get the current "transaction" context for the calling thread. The actual class of the returned object depends on every implementation.

This method is for internal use (eg, by services proxying actual connections).

Specified by:

getCurrentTransaction in interface TransactionService

Returns:

the current transaction object for the current thread, or null if there is no transaction in the current context. Note that if there is a transaction in the current context, this object cannot be null, hence the method can be used to check if there is a pending transaction for the current context.

begin

public void begin(TransactionDemarcation demarcation)
           throws TransactionException,
                  MandatoryTransactionException,
                  ForbiddenTransactionException

Description copied from interface: TransactionService

Marks the beginning of a new transaction demarcation scope. Depending on demarcation, the service may create a new transaction, throw an exception, or do nothing at all.

Specified by:

begin in interface TransactionService

Parameters:

demarcation - transaction for the new beginning scope

Throws:

MandatoryTransactionException - if there is no current transaction and demarcation == Mandatory

ForbiddenTransactionException - in a transaction currently exists and demarcation == Never

TransactionException - in case of any problem preventing the creation of a new transaction (implementation-dependent)

end

public void end()
         throws TransactionException

Description copied from interface: TransactionService

Marks the end of a transaction demarcation scope. Depending on the actual demarcation for this scope, the service may end the current transaction, throw an exception, or do nothing at all. The current transaction, if necessary, will be either committed or rolled back, depending on whether setRollbackOnly was called previously for this transaction. In addition, the method might activate a previously active transaction.

If there is no current transaction, this is not considered an error but an indication of scope-leaving, which lets the possibility of scope unfolding, in order to set the new current transaction context.

Specified by:

end in interface TransactionService

Throws:

TransactionException - in case of any problem preventing the commitment of the current transaction (implementation-dependent)

setRollbackOnly

public void setRollbackOnly()
                     throws TransactionException

Description copied from interface: TransactionService

Marks the current transaction to be rolled back when it will end. The transaction will not be rolled back at once. Once the current transaction has been marked for rollback, it is impossible to go backwards and commit it.

If there is no current transaction, calling this method is considered an error.

Specified by:

setRollbackOnly in interface TransactionService

Throws:

MandatoryTransactionException - in case there is no transaction in the current call context.

TransactionException

fireBeforeNewTransactionBegins

protected void fireBeforeNewTransactionBegins()

fireAfterNewTransactionBegins

protected void fireAfterNewTransactionBegins()

fireBeforeTransactionEnds

protected void fireBeforeTransactionEnds(boolean committed)

fireAfterTransactionEnds

protected void fireAfterTransactionEnds(boolean committed)

cleanUp

protected void cleanUp()

beginTransaction

protected java.lang.Object beginTransaction()

createTransaction

protected abstract java.lang.Object createTransaction()
                                               throws java.lang.Exception

Method called when creation of a new "transaction" is needed. It must be implemented by subclasses.

Please note that "transaction" may be anything and does not have to be just a transaction, ie it may be a JDBC Connection, a Hibernate Session...

Returns:

the new transaction created. Internal storage of this object is performed by AbstractTransactionService.

Throws:

java.lang.Exception - any exception, that will eventually be wrapped into an -unchecked- TransactionException

endTransaction

protected abstract void endTransaction(java.lang.Object tx,
                                       boolean commit)
                                throws java.lang.Exception

Method called when the current "transaction" must end, either committed or rolled back. Ending a transaction may have more meaning than just ending an actual transaction, it may as well mean closing a JDBC Connection, an Hibernate Session...

Parameters:

tx - the "transaction" object (ie, the same object returned by createTransaction)

commit - true if the transaction represented by tx must be committed, false if it must be rolled back

Throws:

java.lang.Exception - any exception, that will eventually be wrapped into an -unchecked- TransactionException

storeTransaction

protected void storeTransaction(java.lang.Object tx)

Method called whenever the current transaction context changes. Does nothing by default.

Override this method if you have specific needs when a transaction context changes occur. For instance, subclasses could store the new current transaction context into ThreadLocalStorage for use by other services.

Please carefully note that overriding this method is not equivalent to using TransactionEvents (these are triggered when a Transaction is created or ended, but they do not indicate what the next transaction context is).

Parameters:

tx - new current "transaction" object, as created by createTransaction; might be null to indicate that there is no available transaction context from now on.

storeTransaction

protected void storeTransaction()

cleanUp

protected java.lang.Exception cleanUp(AbstractTransactionService.Context context)