Red Hat SummitChapter 18. Transactions
18.1. Transactions
The Process Engine supports JTA transactions: local transactions are only supported when using Spring. Pure local transactions are not supported.
By default, each method invocation is considered a transaction. To change this behavior, for example, to combine multiple commands into one transaction, you will need to specify transaction boundaries.
18.2. Defining transactions
To define a transaction, do the following:
Register the transaction manager in your environment:
Example 18.1. Code with transaction manager registration
// create the entity manager factory EntityManagerFactory emf = EntityManagerFactoryManager.get().getOrCreate("org.jbpm.persistence.jpa"); TransactionManager tm = TransactionManagerServices.getTransactionManager(); Environment env = EnvironmentFactory.newEnvironment(); env.set(EnvironmentName.ENTITY_MANAGER_FACTORY, emf); env.set(EnvironmentName.TRANSACTION_MANAGER, tm); // setup the runtime environment RuntimeEnvironment environment = RuntimeEnvironmentBuilder.Factory.get() .newDefaultBuilder() .addAsset(ResourceFactory.newClassPathResource("MyProcessDefinition.bpmn2"), ResourceType.BPMN2) .addEnvironmentEntry(EnvironmentName.TRANSACTION_MANAGER, tm) .addEnvironmentEntry(EnvironmentName.PERSISTENCE_CONTEXT_MANAGER, new JpaProcessPersistenceContextManager(env)) .addEnvironmentEntry(EnvironmentName.TASK_PERSISTENCE_CONTEXT_MANAGER, new JPATaskPersistenceContextManager(env)) .get();Initialize the KieSession:
// get the KieSession RuntimeManager manager = RuntimeManagerFactory.Factory.get().newPerProcessInstanceRuntimeManager(environment); RuntimeEngine runtime = manager.getRuntimeEngine(ProcessInstanceIdContext.get()); KieSession ksession = runtime.getKieSession();
Define the transaction manager in
jndi.properties:Example 18.2. Definition of Bitronix transaction manager in jndi.properties
java.naming.factory.initial=bitronix.tm.jndi.BitronixInitialContextFactory
Using another transaction managerTo use a different JTA transaction manager, edit the
hibernate.transaction.manager_lookup_class, the transaction manager property, in thepersistence.xmlfile to load your transaction manager.For example, if choosing JBoss Transaction Manager:
<property name="hibernate.transaction.manager_lookup_class" value="org.hibernate.transaction.JBossTransactionManagerLookup"/>
Define the start and the end of the transaction.
// start the transaction UserTransaction ut = InitialContext.doLookup("java:comp/UserTransaction"); ut.begin(); // perform multiple commands inside one transaction ksession.insert( new Person( "John Doe" ) ); ksession.startProcess("MyProcess"); // commit the transaction ut.commit();
18.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).
Even though the container manages transactions, the container should be made aware of any exceptions that happen during process instance execution. Exceptions thrown by the engine should be propagated up to the container to properly rollback transactions.
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));
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"/>
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, the ksession is disposed immediately.
