EclipseLink 2.2.0, build 'v20110202-r8913' API Reference

org.eclipse.persistence.transaction
Class AbstractTransactionController

java.lang.Object
  extended by org.eclipse.persistence.transaction.AbstractTransactionController
All Implemented Interfaces:
ExternalTransactionController
Direct Known Subclasses:
JTATransactionController

public abstract class AbstractTransactionController
extends java.lang.Object
implements ExternalTransactionController

Purpose: Abstract implementation of an ExternalTransactionController.

Description: This class implements the ExternalTransactionController interface. Concrete implementations of this class are responsible for performing the coordination with the external transaction manager through whatever means available to that manager. Different transaction services may do this in slightly different ways, but most common ones (JTA and JTS/OTS) will use a synchronization interface.

See Also:
AbstractSynchronizationListener, ExternalTransactionController

Field Summary
protected  java.lang.ThreadLocal activeUnitOfWorkThreadLocal
          PERF: Cache the active uow in a thread local.
protected  java.util.Map<java.lang.Object,AbstractSynchronizationListener> currentlyProcessedListeners
          Non-null only in case sequencing callbacks are used: numSessionsRequiringSequencingCallback > 0
protected  SynchronizationListenerFactory listenerFactory
          Generates listener instances for synchronization
protected  int numSessionsRequiringSequencingCallback
          more - the session is a session broker with several members requiring sequencing callbacks.
protected  java.util.Map<java.lang.Object,AbstractSynchronizationListener> sequencingListeners
          Non-null only in case sequencing callbacks are used: numSessionsRequiringSequencingCallback > 0
protected  org.eclipse.persistence.internal.sessions.AbstractSession session
          The session this controller is responsible for controlling
protected  java.util.Map unitsOfWork
          Table of external transaction object keys and unit of work values
 
Constructor Summary
AbstractTransactionController()
          INTERNAL: Return a new controller.
 
Method Summary
 void addUnitOfWork(java.lang.Object transactionKey, org.eclipse.persistence.internal.sessions.UnitOfWorkImpl activeUnitOfWork)
          INTERNAL: Add a UnitOfWork object to the Hashtable keyed on the external transaction object.
protected abstract  void beginTransaction_impl()
          INTERNAL: Begin an external transaction.
 void beginTransaction(org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Begin an external transaction.
 void bindToCurrentTransaction(org.eclipse.persistence.internal.sessions.UnitOfWorkImpl unitOfWork, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Associate the given unit of work and EclipseLink session with the active external transaction.
protected abstract  boolean canBeginTransaction_impl(java.lang.Object status)
          INTERNAL: Return true if the status indicates that a transaction can be started.
protected abstract  boolean canCommitTransaction_impl(java.lang.Object status)
          INTERNAL: Return true if the status indicates that a transaction can be committed.
protected abstract  boolean canIssueSQLToDatabase_impl(java.lang.Object status)
          INTERNAL: Return true if the status indicates that the SQL should be issued to the db.
protected abstract  boolean canMergeUnitOfWork_impl(java.lang.Object status)
          INTERNAL: Return true if the status indicates that the unit of work should be merged into the shared cache.
protected abstract  boolean canRollbackTransaction_impl(java.lang.Object status)
          INTERNAL: Return true if the status indicates that a transaction can be rolled back.
 void clearSequencingListeners()
          INTERNAL: Clears sequencing listeners.
protected abstract  void commitTransaction_impl()
          INTERNAL: Commit the external transaction.
 void commitTransaction(org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Commit the external transaction.
 org.eclipse.persistence.internal.sequencing.SequencingCallback getActiveSequencingCallback(DatabaseSession dbSession, org.eclipse.persistence.internal.sequencing.SequencingCallbackFactory sequencingCallbackFactory)
          INTERNAL: Returns sequencingCallback for the current active external transaction.
 org.eclipse.persistence.internal.sessions.UnitOfWorkImpl getActiveUnitOfWork()
          INTERNAL: Return the active unit of work for the current external transaction.
 SynchronizationListenerFactory getListenerFactory()
          INTERNAL: Get the factory used to generate synchronization listeners.
 org.eclipse.persistence.internal.sessions.AbstractSession getSession()
          INTERNAL: Return the manager's session.
protected abstract  java.lang.Object getTransaction_impl()
          INTERNAL: Return the active external transaction for the calling thread, or null if none is currently active for this thread.
 java.lang.Object getTransaction()
          INTERNAL: Return the active external transaction object, or null if none is active.
protected abstract  java.lang.Object getTransactionKey_impl(java.lang.Object transaction)
          INTERNAL: Return a key for the specified external transaction object.
 java.lang.Object getTransactionKey(java.lang.Object transaction)
          INTERNAL: Return a key for the specified external transaction object.
protected abstract  java.lang.Object getTransactionStatus_impl()
          INTERNAL: Return the transaction status.
 java.lang.Object getTransactionStatus()
          INTERNAL: Return the transaction status.
 java.util.Map getUnitsOfWork()
          INTERNAL: Return the hashtable keyed on the external transaction objects with values that are the associated units of work.
 boolean hasActiveUnitOfWork()
          INTERNAL: Return true if there is a unit of work associated with the active external transaction.
 void initializeSequencingListeners()
          INTERNAL: Initializes sequencing listeners.
abstract  boolean isRolledBack_impl(java.lang.Object status)
          INTERNAL: Return true if the transaction is in the rolled back state.
 boolean isSequencingCallbackRequired()
          INTERNAL: Indicates whether sequencing callback may be required.
 java.lang.Object jndiLookup(java.lang.String jndiName)
          PUBLIC: Look up a given name in JNDI.
 void logTxStateTrace(org.eclipse.persistence.internal.sessions.AbstractSession session, java.lang.String msgInd, java.lang.Object status)
           
 void logTxTrace(org.eclipse.persistence.internal.sessions.AbstractSession session, java.lang.String msgInd, java.lang.Object[] args)
           
 org.eclipse.persistence.internal.sessions.UnitOfWorkImpl lookupActiveUnitOfWork()
          INTERNAL: Return the unit of work associated with the active external transaction.
 org.eclipse.persistence.internal.sessions.UnitOfWorkImpl lookupActiveUnitOfWork(java.lang.Object transaction)
          INTERNAL: Return the unit of work associated with the active external transaction.
protected abstract  void markTransactionForRollback_impl()
          INTERNAL: Mark the external transaction for rollback.
 void markTransactionForRollback()
          INTERNAL: Mark the external transaction for rollback.
 boolean noTransactionOrRolledBackOrCommited()
          INTERNAL: Used the EJB 3.0 to determine if a transaction is in a state where an EntityManager can be closed
 int numSessionsRequiringSequencingCallback()
          INTERNAL: Indicates how many sessions require sequencing callbacks.
protected abstract  void registerSynchronization_impl(AbstractSynchronizationListener listener, java.lang.Object txn)
          INTERNAL: Register the specified synchronization listener with the given active transaction.
 void registerSynchronizationListener(org.eclipse.persistence.internal.sessions.UnitOfWorkImpl uow, org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Associate the given unit of work and EclipseLink session with the current external transaction.
 void removeSequencingListener(java.lang.Object transactionKey)
          INTERNAL: Clears sequencingCallbacks.
 void removeUnitOfWork(java.lang.Object transactionKey)
          INTERNAL: Remove the unit of work associated with the transaction passed in.
protected abstract  void rollbackTransaction_impl()
          INTERNAL: Roll back the external transaction.
 void rollbackTransaction(org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Roll back the external transaction.
 void setListenerFactory(SynchronizationListenerFactory factory)
          INTERNAL: Set the factory used to generate synchronization listeners.
 void setSession(org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Set the manager's session.
protected  void setUnitsOfWork(java.util.Map unitsOfWork)
          INTERNAL: Set the table of transactions to units of work.
protected abstract  java.lang.String statusToString_impl(java.lang.Object status)
          INTERNAL: Convert the status to a string for tracing.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

unitsOfWork

protected java.util.Map unitsOfWork
Table of external transaction object keys and unit of work values


session

protected org.eclipse.persistence.internal.sessions.AbstractSession session
The session this controller is responsible for controlling


listenerFactory

protected SynchronizationListenerFactory listenerFactory
Generates listener instances for synchronization


activeUnitOfWorkThreadLocal

protected java.lang.ThreadLocal activeUnitOfWorkThreadLocal
PERF: Cache the active uow in a thread local.


sequencingListeners

protected java.util.Map<java.lang.Object,AbstractSynchronizationListener> sequencingListeners
Non-null only in case sequencing callbacks are used: numSessionsRequiringSequencingCallback > 0


currentlyProcessedListeners

protected java.util.Map<java.lang.Object,AbstractSynchronizationListener> currentlyProcessedListeners
Non-null only in case sequencing callbacks are used: numSessionsRequiringSequencingCallback > 0


numSessionsRequiringSequencingCallback

protected int numSessionsRequiringSequencingCallback
more - the session is a session broker with several members requiring sequencing callbacks.

Constructor Detail

AbstractTransactionController

public AbstractTransactionController()
INTERNAL: Return a new controller.

Method Detail

bindToCurrentTransaction

public void bindToCurrentTransaction(org.eclipse.persistence.internal.sessions.UnitOfWorkImpl unitOfWork,
                                     org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Associate the given unit of work and EclipseLink session with the active external transaction. This may be done by whatever means supported by the transaction manager (i.e. through a synchronization protocol).

Parameters:
unitOfWork - The unit of work that is to be bound to the active transaction
session - The session ancestor of the unit of work

beginTransaction

public void beginTransaction(org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Begin an external transaction.

Specified by:
beginTransaction in interface ExternalTransactionController
Parameters:
session - The session for which the transaction is being begun.

commitTransaction

public void commitTransaction(org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Commit the external transaction.

Specified by:
commitTransaction in interface ExternalTransactionController
Parameters:
session - The session for which the transaction is being committed.

rollbackTransaction

public void rollbackTransaction(org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Roll back the external transaction.

Specified by:
rollbackTransaction in interface ExternalTransactionController
Parameters:
session - The session for which the transaction is being rolled back.

markTransactionForRollback

public void markTransactionForRollback()
INTERNAL: Mark the external transaction for rollback.

Specified by:
markTransactionForRollback in interface ExternalTransactionController

getTransaction

public java.lang.Object getTransaction()
INTERNAL: Return the active external transaction object, or null if none is active. This may be in whatever form the transaction system uses.


getTransactionKey

public java.lang.Object getTransactionKey(java.lang.Object transaction)
INTERNAL: Return a key for the specified external transaction object. The key is just something that can be inserted into a hashtable (must support hashCode() and equals() methods).


getTransactionStatus

public java.lang.Object getTransactionStatus()
INTERNAL: Return the transaction status. This may be any type of status or value, depending upon the transaction system.


noTransactionOrRolledBackOrCommited

public boolean noTransactionOrRolledBackOrCommited()
INTERNAL: Used the EJB 3.0 to determine if a transaction is in a state where an EntityManager can be closed


isRolledBack_impl

public abstract boolean isRolledBack_impl(java.lang.Object status)
INTERNAL: Return true if the transaction is in the rolled back state.


hasActiveUnitOfWork

public boolean hasActiveUnitOfWork()
INTERNAL: Return true if there is a unit of work associated with the active external transaction. Return false if no transaction is current, or if no uow has been associated with the active transaction yet.


getActiveUnitOfWork

public org.eclipse.persistence.internal.sessions.UnitOfWorkImpl getActiveUnitOfWork()
INTERNAL: Return the active unit of work for the current external transaction. If no transaction is active then return null. If a transaction is active but no unit of work has been bound to it then create and return one.

Specified by:
getActiveUnitOfWork in interface ExternalTransactionController

lookupActiveUnitOfWork

public org.eclipse.persistence.internal.sessions.UnitOfWorkImpl lookupActiveUnitOfWork()
INTERNAL: Return the unit of work associated with the active external transaction. Return null if no transaction is active, or if no uow has been associated with the active transaction yet.


lookupActiveUnitOfWork

public org.eclipse.persistence.internal.sessions.UnitOfWorkImpl lookupActiveUnitOfWork(java.lang.Object transaction)
INTERNAL: Return the unit of work associated with the active external transaction. Return null if no transaction is active, or if no uow has been associated with the active transaction yet.


addUnitOfWork

public void addUnitOfWork(java.lang.Object transactionKey,
                          org.eclipse.persistence.internal.sessions.UnitOfWorkImpl activeUnitOfWork)
INTERNAL: Add a UnitOfWork object to the Hashtable keyed on the external transaction object.


removeUnitOfWork

public void removeUnitOfWork(java.lang.Object transactionKey)
INTERNAL: Remove the unit of work associated with the transaction passed in.


getSession

public org.eclipse.persistence.internal.sessions.AbstractSession getSession()
INTERNAL: Return the manager's session.

Specified by:
getSession in interface ExternalTransactionController

setSession

public void setSession(org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Set the manager's session.

Specified by:
setSession in interface ExternalTransactionController

getUnitsOfWork

public java.util.Map getUnitsOfWork()
INTERNAL: Return the hashtable keyed on the external transaction objects with values that are the associated units of work.


setUnitsOfWork

protected void setUnitsOfWork(java.util.Map unitsOfWork)
INTERNAL: Set the table of transactions to units of work.


getListenerFactory

public SynchronizationListenerFactory getListenerFactory()
INTERNAL: Get the factory used to generate synchronization listeners.


setListenerFactory

public void setListenerFactory(SynchronizationListenerFactory factory)
INTERNAL: Set the factory used to generate synchronization listeners. This should be set if a listener other than the default one is being used.


registerSynchronizationListener

public void registerSynchronizationListener(org.eclipse.persistence.internal.sessions.UnitOfWorkImpl uow,
                                            org.eclipse.persistence.internal.sessions.AbstractSession session)
                                     throws DatabaseException
INTERNAL: Associate the given unit of work and EclipseLink session with the current external transaction. This method is offered only for backwards compatibility.

Specified by:
registerSynchronizationListener in interface ExternalTransactionController
Throws:
DatabaseException

jndiLookup

public java.lang.Object jndiLookup(java.lang.String jndiName)
PUBLIC: Look up a given name in JNDI. This can be used by a subclass or even an application to look up transaction artifacts that are required for the implementation.

The lookup assumes that it is taking place on the server side, and that the InitialContext can be used without requiring any special properties.

Parameters:
jndiName - The name to look up
Returns:
The object bound in JNDI to the specified name
Throws:
TransactionException - Thrown in case of lookup failure

initializeSequencingListeners

public void initializeSequencingListeners()
INTERNAL: Initializes sequencing listeners. Always clears sequencing listeners first. There are two methods calling this method: 1. setSession method - this could lead to initialization of sequencing listeners only if sequencing already connected (that would happen if setSession is called after session.login, which is normally not the case). 2. in the very end of connecting sequencing, after it's determined whether sequencing callbacks (and therefore listeners) will be required.

Specified by:
initializeSequencingListeners in interface ExternalTransactionController

getActiveSequencingCallback

public org.eclipse.persistence.internal.sequencing.SequencingCallback getActiveSequencingCallback(DatabaseSession dbSession,
                                                                                                  org.eclipse.persistence.internal.sequencing.SequencingCallbackFactory sequencingCallbackFactory)
INTERNAL: Returns sequencingCallback for the current active external transaction. DatabaseSession is passed for the sake of SessionBroker case. This method requires active external transaction.

Specified by:
getActiveSequencingCallback in interface ExternalTransactionController

clearSequencingListeners

public void clearSequencingListeners()
INTERNAL: Clears sequencing listeners. Called by initializeSequencingListeners and by sequencing on disconnect.

Specified by:
clearSequencingListeners in interface ExternalTransactionController

isSequencingCallbackRequired

public boolean isSequencingCallbackRequired()
INTERNAL: Indicates whether sequencing callback may be required.


numSessionsRequiringSequencingCallback

public int numSessionsRequiringSequencingCallback()
INTERNAL: Indicates how many sessions require sequencing callbacks.


removeSequencingListener

public void removeSequencingListener(java.lang.Object transactionKey)
INTERNAL: Clears sequencingCallbacks. Called by initializeSequencingCallbacks and by sequencing on disconnect.


logTxTrace

public void logTxTrace(org.eclipse.persistence.internal.sessions.AbstractSession session,
                       java.lang.String msgInd,
                       java.lang.Object[] args)

logTxStateTrace

public void logTxStateTrace(org.eclipse.persistence.internal.sessions.AbstractSession session,
                            java.lang.String msgInd,
                            java.lang.Object status)

registerSynchronization_impl

protected abstract void registerSynchronization_impl(AbstractSynchronizationListener listener,
                                                     java.lang.Object txn)
                                              throws java.lang.Exception
INTERNAL: Register the specified synchronization listener with the given active transaction.

Parameters:
listener - The synchronization listener created for this transaction
txn - The active transaction for which notification is being requested
Throws:
java.lang.Exception

getTransaction_impl

protected abstract java.lang.Object getTransaction_impl()
                                                 throws java.lang.Exception
INTERNAL: Return the active external transaction for the calling thread, or null if none is currently active for this thread.

Returns:
The active transaction object, or null if no transaction is active
Throws:
java.lang.Exception

getTransactionKey_impl

protected abstract java.lang.Object getTransactionKey_impl(java.lang.Object transaction)
                                                    throws java.lang.Exception
INTERNAL: Return a key for the specified external transaction object. The key is just something that can be inserted into a hashtable (must support hashCode() and equals() methods).

Parameters:
transaction - The transaction to which the returned key applies (may be null)
Returns:
A key for the passed in transaction, or null if no transaction specified
Throws:
java.lang.Exception

getTransactionStatus_impl

protected abstract java.lang.Object getTransactionStatus_impl()
                                                       throws java.lang.Exception
INTERNAL: Return the transaction status. This may be any type of status or value, depending upon the transaction system.

Returns:
The current transaction status
Throws:
java.lang.Exception

beginTransaction_impl

protected abstract void beginTransaction_impl()
                                       throws java.lang.Exception
INTERNAL: Begin an external transaction. Do this in a way appropriate to the transaction subsystem.

Throws:
java.lang.Exception

commitTransaction_impl

protected abstract void commitTransaction_impl()
                                        throws java.lang.Exception
INTERNAL: Commit the external transaction. Do this in a way appropriate to the transaction subsystem.

Throws:
java.lang.Exception

rollbackTransaction_impl

protected abstract void rollbackTransaction_impl()
                                          throws java.lang.Exception
INTERNAL: Roll back the external transaction. Do this in a way appropriate to the transaction subsystem.

Throws:
java.lang.Exception

markTransactionForRollback_impl

protected abstract void markTransactionForRollback_impl()
                                                 throws java.lang.Exception
INTERNAL: Mark the external transaction for rollback. Do this in a way appropriate to the transaction subsystem.

Throws:
java.lang.Exception

canBeginTransaction_impl

protected abstract boolean canBeginTransaction_impl(java.lang.Object status)
INTERNAL: Return true if the status indicates that a transaction can be started. This would normally mean that no transaction is currently active. The status is interpreted by the transaction subsystem.

Parameters:
status - The current transaction status
Returns:
true if the current state allows for a transaction to be started

canCommitTransaction_impl

protected abstract boolean canCommitTransaction_impl(java.lang.Object status)
INTERNAL: Return true if the status indicates that a transaction can be committed. This would normally mean that a transaction is currently active. The status is interpreted by the transaction subsystem.

Parameters:
status - The current transaction status
Returns:
true if the current state allows for a transaction to be committed

canRollbackTransaction_impl

protected abstract boolean canRollbackTransaction_impl(java.lang.Object status)
INTERNAL: Return true if the status indicates that a transaction can be rolled back. This would normally mean that a transaction is currently active. The status is interpreted by the transaction subsystem.

Parameters:
status - The current transaction status
Returns:
true if the current state allows for a transaction to be rolled back

canIssueSQLToDatabase_impl

protected abstract boolean canIssueSQLToDatabase_impl(java.lang.Object status)
INTERNAL: Return true if the status indicates that the SQL should be issued to the db. This would normally mean that a transaction was active and not being rolled back or marked for rollback. The status is interpreted by the transaction subsystem.

Parameters:
status - The current transaction status
Returns:
true if the current state allows for the SQL to be sent to the database

canMergeUnitOfWork_impl

protected abstract boolean canMergeUnitOfWork_impl(java.lang.Object status)
INTERNAL: Return true if the status indicates that the unit of work should be merged into the shared cache. This would normally mean that the transaction was committed successfully. The status is interpreted by the transaction subsystem.

Parameters:
status - The current transaction status
Returns:
true if the current state dictates that the unit of work should be merged

statusToString_impl

protected abstract java.lang.String statusToString_impl(java.lang.Object status)
INTERNAL: Convert the status to a string for tracing.


EclipseLink 2.2.0, build 'v20110202-r8913' API Reference