Chapter 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:

  1. 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();

  2. Initialize the KieSession: 

    // get the KieSession
RuntimeManager manager = RuntimeManagerFactory.Factory.get().newPerProcessInstanceRuntimeManager(environment);
RuntimeEngine runtime = manager.getRuntimeEngine(ProcessInstanceIdContext.get());
KieSession ksession = runtime.getKieSession();

  3. 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 manager

    To use a different JTA transaction manager, edit the hibernate.transaction.manager_lookup_class, the transaction manager property, in the persistence.xml file to load your transaction manager.

    For example, if choosing JBoss Transaction Manager: 

    <property name="hibernate.transaction.manager_lookup_class" value="org.hibernate.transaction.JBossTransactionManagerLookup"/>

  4. 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).

Note

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.