16.3. Container Managed Transactions

In cases where JBoss BPM Suite is embedded inside an application that is in a container that can manage transactions by itself (Container Managed Transactions - CMT), a special dedicated transaction manager is provided using the org.jbpm.persistence.jta.ContainerManagerTransactionManager class. This is because the default implementation of the transaction manager in JBoss BPM Suite is based on the UserTransaction class getting the transaction status. However, some application servers in a CMT mode do not allow accessing the UserTransaction instance from JNDI.

Operations executed on this manager are all no-op because they cannot affect the underlying CMT. The ContainerManagedTransactionManager class expects that the transaction is always active (returning ACTIVE to the getStatus() method).

Configuring the Transaction Manager

To configure and use the ContainerManagedTransactionManager, it needs to be inserted into the environment before you create or load a session:

Environment env = EnvironmentFactory.newEnvironment();
env.set(EnvironmentName.ENTITY_MANAGER_FACTORY, emf);
env.set(EnvironmentName.TRANSACTION_MANAGER, new ContainerManagedTransactionManager());
env.set(EnvironmentName.PERSISTENCE_CONTEXT_MANAGER, new JpaProcessPersistenceContextManager(env));

Environment env = EnvironmentFactory.newEnvironment();
env.set(EnvironmentName.ENTITY_MANAGER_FACTORY, emf);
env.set(EnvironmentName.TRANSACTION_MANAGER, new ContainerManagedTransactionManager());
env.set(EnvironmentName.PERSISTENCE_CONTEXT_MANAGER, new JpaProcessPersistenceContextManager(env));

Next, setup the JPA Provider in your persistence.xml file. For example, if using IBM WebSphere:

<property name="hibernate.transaction.factory_class" value="org.hibernate.transaction.CMTTransactionFactory"/>
<property name="hibernate.transaction.manager_lookup_class" value="org.hibernate.transaction.WebSphereExtendedJTATransactionLookup"/>

<property name="hibernate.transaction.factory_class" value="org.hibernate.transaction.CMTTransactionFactory"/>
<property name="hibernate.transaction.manager_lookup_class" value="org.hibernate.transaction.WebSphereExtendedJTATransactionLookup"/>

Disposing the KSession in a CMT

In a CMT, you should not dispose the ksession directly (by using the dispose() method). Doing so will cause exceptions on transaction completion as the Process Engine needs to clean up the state after the invocation has finished.

Instead, use the specialized class org.jbpm.persistence.jta.ContainerManagedTransactionDisposeCommand's execute() method. Using this command ensures that the ksession will be disposed when the transaction is actually complete.

This method checks to see if the transaction is active. If it is, it delegates the actual disposal to the afterDisposal phase of the transaction instead of executing it directly. If there is no active transaction or if there is no active transaction, the ksession is disposed immediately.