13.3. Transactions

The JBoss BPM Suite engine supports JTA transactions. If you do not provide transaction boundaries inside your application, the engine automatically executes method invocation on the engine in a separate transaction. You can specify the transaction boundaries which enables you to combine multiple commands into one transaction.
You need to register a transaction manager at the environment before using user-defined transactions. The following sample code uses the Bitronix transaction manager. Next, the Java Transaction API (JTA) is used to specify transaction boundaries, as shown below: 
// create the entity manager factory and register it in the environment
EntityManagerFactory emf = Persistence.createEntityManagerFactory( "org.jbpm.persistence.jpa" );
Environment env = KnowledgeBaseFactory.newEnvironment();
env.set( EnvironmentName.ENTITY_MANAGER_FACTORY, emf );
env.set( EnvironmentName.TRANSACTION_MANAGER, TransactionManagerServices.getTransactionManager() );

// create a new knowledge session that uses JPA to store the runtime state

StatefulKnowledgeSession ksession = JPAKnowledgeService.newStatefulKnowledgeSession( kbase, null, env );

// start the transaction

UserTransaction ut = (UserTransaction) new InitialContext().lookup( "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();
If you use Bitronix as the transaction manager, you must add a jndi.properties file in your root classpath to register the Bitronix transaction manager in JNDI. If you are using the jbpm-test module, this is already included by default. If not, create a file called jndi.properties with the following content: 
java.naming.factory.initial=bitronix.tm.jndi.BitronixInitialContextFactory
In case you need to use a different JTA transaction manager, you can change the persistence.xml file to use your own transaction manager. You need to modify the transaction manager property in persistence.xml file as shown below: 
<property name="hibernate.transaction.jta.platform" value="org.hibernate.transaction.JBossTransactionManagerLookup" />
You can embed JBoss BPM Suite inside an application that executes in Container Managed Transaction (CMT) mode, such as EJB beans. To secure proper execution in CMT environments, a dedicated transaction manager implementation is provided: 
org.jbpm.persistence.jta.ContainerManagedTransactionManager

Note

To ensure that container is aware of any exceptions that happened during process instance execution, you must ensure that exceptions thrown by the engine are propagated up to the container to properly rollback transaction.
To configure the transaction manager, perform the following configuration:
  1. Insert transaction manager and persistence context manager into environment prior to creating or loading 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));
env.set(EnvironmentName.TASK_PERSISTENCE_CONTEXT_MANAGER, new JPATaskPersistenceContextManager(env));
  2. Configure JPA provider (example hibernate and WebSphere): 
    <property name="hibernate.transaction.factory_class" value="org.hibernate.transaction.CMTTransactionFactory"/>
<property name="hibernate.transaction.jta.platform" value="org.hibernate.service.jta.platform.internal.WebSphereJtaPlatform"/>