Interface TransactionHelper
-
- All Known Implementing Classes:
SunContainerHelper
,SunTransactionHelper
,TransactionHelperImpl
public interface TransactionHelper
Provide a Forte for Java implementation with information about the distributed transaction environment. This is an interface that a helper class implements that is specific to a managed environment.This interface is specific to Forte for Java, version 3.0, and is subject to change without notice. In particular, as additional experience is gained with specific application servers, this interface may have methods added and removed, even with patch releases. Therefore, this interface should be considered very volatile, and any class that implements it might have to be reimplemented whenever an upgrade to either the application server or Forte for Java occurs.
The class that implements this interface must register itself by a static method at class initialization time. For example,import com.sun.jdo.spi.persistence.support.sqlstore.ejb.*; class blackHerringTransactionHelper implements TransactionHelper { static EJBHelper.register(new blackHerringTransactionHelper()); ... }
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description Connection
getConnection(Object resource, String username, char[] password)
Called in a managed environment to get a Connection from the application server specific resource.String
getDDLNamePrefix(Object info)
Returns name prefix for DDL files extracted from the info instance by the application server specific code.jakarta.transaction.TransactionManager
getLocalTransactionManager()
Called in a managed environment to access a TransactionManager for managing local transaction boundaries and registering synchronization for call backs during completion of a local transaction.Connection
getNonTransactionalConnection(Object resource, String username, char[] password)
Called in a managed environment to get a non-transactional Connection from the application server specific resource.jakarta.transaction.Transaction
getTransaction()
Identify the Transaction context for the calling thread, and return a Transaction instance that can be used to register synchronizations, and used as the key for HashMaps.jakarta.transaction.UserTransaction
getUserTransaction()
Returns the UserTransaction associated with the calling thread.boolean
isManaged()
Identifies the managed environment behavior.void
notifyApplicationUnloaded(ClassLoader cl)
Called to notify a ApplicationLifeCycleEventListeners that an application is unloaded.void
postInvoke(Object im)
Called at the end of the Transaction.beforeCompletion() to de-register the component with the app server if necessary.Object
preInvoke(Object component)
Called at the beginning of the Transaction.beforeCompletion() to register the component with the app server if necessary.void
registerApplicationLifeCycleEventListener(ApplicationLifeCycleEventListener listener)
Called to register a ApplicationLifeCycleEventListener.void
registerSynchronization(jakarta.transaction.Transaction jta, jakarta.transaction.Synchronization sync)
Called in a managed environment to register internal Synchronization object with the Transaction Synchronization.PersistenceManagerFactory
replaceInternalPersistenceManagerFactory(PersistenceManagerFactory pmf)
Replace newly created instance of PersistenceManagerFactory with the hashed one if it exists.void
setPersistenceManagerFactoryDefaults(PersistenceManagerFactory pmf)
Set environment specific default values for the given PersistenceManagerFactory.int
translateStatus(int st)
Translate local representation of the Transaction Status to jakarta.transaction.Status value if necessary.Statement
unwrapStatement(Statement stmt)
This method unwrap given Statement and return the Statement from JDBC driver.
-
-
-
Method Detail
-
getUserTransaction
jakarta.transaction.UserTransaction getUserTransaction()
Returns the UserTransaction associated with the calling thread. If there is no transaction currently in progress, this method returns null.- Returns:
- the UserTransaction instance for the calling thread
-
getTransaction
jakarta.transaction.Transaction getTransaction()
Identify the Transaction context for the calling thread, and return a Transaction instance that can be used to register synchronizations, and used as the key for HashMaps. The returned Transaction must implementequals()
andhashCode()
based on the global transaction id.All Transaction instances returned by this method called in the same Transaction context must compare equal and return the same hashCode. The Transaction instance returned will be held as the key to an internal HashMap until the Transaction completes. If there is no transaction associated with the current thread, this method returns null.
- Returns:
- the Transaction instance for the calling thread
-
translateStatus
int translateStatus(int st)
Translate local representation of the Transaction Status to jakarta.transaction.Status value if necessary. Otherwise this method should return the value passed to it as an argument.This method is used during afterCompletion callbacks to translate the parameter value passed by the application server to the afterCompletion method. The return value must be one of:
jakarta.transaction.Status.STATUS_COMMITTED
orjakarta.transaction.Status.STATUS_ROLLED_BACK
.- Parameters:
st
- local Status value- Returns:
- the jakarta.transaction.Status value of the status
-
replaceInternalPersistenceManagerFactory
PersistenceManagerFactory replaceInternalPersistenceManagerFactory(PersistenceManagerFactory pmf)
Replace newly created instance of PersistenceManagerFactory with the hashed one if it exists. The replacement is necessary only if the JNDI lookup always returns a new instance. Otherwise this method returns the object passed to it as an argument. PersistenceManagerFactory is uniquely identified by ConnectionFactory.hashCode() if ConnectionFactory is not null; otherwise by ConnectionFactoryName.hashCode() if ConnectionFactoryName is not null; otherwise by the combination of URL.hashCode() + userName.hashCode() + password.hashCode() + driverName.hashCode();- Parameters:
pmf
- PersistenceManagerFactory instance to be replaced- Returns:
- the PersistenceManagerFactory known to the runtime
-
preInvoke
Object preInvoke(Object component)
Called at the beginning of the Transaction.beforeCompletion() to register the component with the app server if necessary. The component argument is an array of Objects. The first element is com.sun.jdo.spi.persistence.support.sqlstore.Transaction object responsible for transaction completion. The second element is com.sun.jdo.api.persistence.support.PersistenceManager object that has been associated with the Transaction context for the calling thread. The third element is jakarta.transaction.Transaction object that has been associated with the given instance of PersistenceManager. The return value is passed unchanged to the postInvoke method.- Parameters:
component
- an array of Objects- Returns:
- implementation-specific Object
-
postInvoke
void postInvoke(Object im)
Called at the end of the Transaction.beforeCompletion() to de-register the component with the app server if necessary. The parameter is the return value from preInvoke, and can be any Object.- Parameters:
im
- implementation-specific Object
-
registerSynchronization
void registerSynchronization(jakarta.transaction.Transaction jta, jakarta.transaction.Synchronization sync) throws jakarta.transaction.RollbackException, jakarta.transaction.SystemException
Called in a managed environment to register internal Synchronization object with the Transaction Synchronization. If available, this registration provides special handling of the registered instance, calling it after all user defined Synchronization instances.- Parameters:
jta
- the Transaction instance for the calling thread.sync
- the internal Synchronization instance to register.- Throws:
jakarta.transaction.SystemException
jakarta.transaction.RollbackException
-
getConnection
Connection getConnection(Object resource, String username, char[] password) throws SQLException
Called in a managed environment to get a Connection from the application server specific resource. In a non-managed environment throws an Exception as it should not be called.- Parameters:
resource
- the application server specific resource.username
- the resource username. If null, Connection is requested without username and password validation.password
- the password for the resource username.- Returns:
- a Connection.
- Throws:
SQLException
-
getNonTransactionalConnection
Connection getNonTransactionalConnection(Object resource, String username, char[] password) throws SQLException
Called in a managed environment to get a non-transactional Connection from the application server specific resource. In a non-managed environment throws an Exception as it should not be called.- Parameters:
resource
- the application server specific resource.username
- the resource username. If null, Connection is requested without username and password validation.password
- the password for the resource username.- Returns:
- a Connection.
- Throws:
SQLException
-
getLocalTransactionManager
jakarta.transaction.TransactionManager getLocalTransactionManager()
Called in a managed environment to access a TransactionManager for managing local transaction boundaries and registering synchronization for call backs during completion of a local transaction.- Returns:
- jakarta.transaction.TransactionManager
-
isManaged
boolean isManaged()
Identifies the managed environment behavior.- Returns:
- true if this implementation represents the managed environment.
-
unwrapStatement
Statement unwrapStatement(Statement stmt)
This method unwrap given Statement and return the Statement from JDBC driver.
-
setPersistenceManagerFactoryDefaults
void setPersistenceManagerFactoryDefaults(PersistenceManagerFactory pmf)
Set environment specific default values for the given PersistenceManagerFactory.- Parameters:
pmf
- the PersistenceManagerFactory.
-
getDDLNamePrefix
String getDDLNamePrefix(Object info)
Returns name prefix for DDL files extracted from the info instance by the application server specific code.- Parameters:
info
- the instance to use for the name generation.- Returns:
- name prefix as String.
-
registerApplicationLifeCycleEventListener
void registerApplicationLifeCycleEventListener(ApplicationLifeCycleEventListener listener)
Called to register a ApplicationLifeCycleEventListener. If ApplicationLifeCycle management is active (typically in managed environment), the registered listener will receive a call back for lifecycle events.- Parameters:
listener
- An instance of ApplicationLifeCycleEventListener.
-
notifyApplicationUnloaded
void notifyApplicationUnloaded(ClassLoader cl)
Called to notify a ApplicationLifeCycleEventListeners that an application is unloaded. If ApplicationLifeCycle management is active (typically in managed environment), the registered listener will handle the notification.- Parameters:
cl
- An instance of the ClassLoader that loaded the application.
-
-