7.3. Configuring Persistence

7.3.1. Configuring Persistence

Persistence is configured by default for JBoss BRMS 5.3 standalone; however, it must be configured for customers deploying JBoss BRMS 5.3 as a deployable web app by adding the jar files to the classpath.

7.3.2. Adding Dependencies

The following packages are required for manual persistence configuration:
  • JBoss BRMS 5.3 Deployable Package.
  • The database vendor's JDBC driver.
  • A transaction manager.
To manually add the necessary dependencies, copy the required jar files from the jboss-jbpm-engine.zip archive included with the BRMS 5.3 Deployable archive and make them available on the application classpath.
The following jar files are required when using a combination of Hibernate as the JPA persistence provider with an H2 in-memory database and Bitronix for JTA-based transactions management:

Note

This list is for demonstration purposes only. Supported configurations can be found at the following site, http://www.redhat.com/resourcelibrary/articles/jboss-enterprise-brms-supported-configurations.
  • jbpm-test
  • jbpm-persistence-jpa
  • drools-persistence-jpa
  • persistence-api
  • hibernate-entitymanager
  • hibernate-annotations
  • hibernate-commons-annotations
  • hibernate-core
  • commons-collections
  • dom4j
  • jta
  • btm
  • javassist
  • slf4j-api
  • slf4j-jdk14
  • h2

7.3.3. Configure the Engine to use Persistence

The JBPMHelper class of the jbpm-test module has a method to create a session and uses a configuration file to configure the session. The information below shows an example jBPM.properties file that uses an H2 in-memory database with persistence enabled.

Example 7.1. Example jBPM.properties File

# for creating a datasource
persistence.datasource.name=jdbc/jbpm-ds
persistence.datasource.user=sa
persistence.datasource.password=
persistence.datasource.url=jdbc:h2:tcp://localhost/~/jbpm-db
persistence.datasource.driverClassName=org.h2.Driver

# for configuring persistence of the session
persistence.enabled=true
persistence.persistenceunit.name=org.jbpm.persistence.jpa
persistence.persistenceunit.dialect=org.hibernate.dialect.H2Dialect

# for configuring the human task service
taskservice.enabled=true
taskservice.datasource.name=org.jbpm.task
taskservice.transport=mina
taskservice.usergroupcallback=org.jbpm.task.service.DefaultUserGroupCallbackImpl
The JBPMHelper class can be used to register the datasource:
JBPMHelper.setupDataSource();
The JBPMHelper class can be used to create sessions (after the knowledge base has been created):
StatefulKnowledgeSession ksession = JBPMHelper.newStatefulKnowledgeSession(kbase);
Methods can now be called on this ksession (for instance, startProcess) and the engine will persist all runtime state in the created datasource.
The JBPMHelper class can be used to recreate sessions by restoring their state from the database by passing in the session ID. The session ID is retrieved using ksession.getId().
StatefulKnowledgeSession ksession = 
    JBPMHelper.loadStatefulKnowledgeSession(kbase, sessionId);

7.3.4. Session ID

7.3.4.1. Session ID

The session ID of the most recently used persistent session is also stored in the jbpmSessionId.ser file. If the jbpmSessionId.ser file does not exist, it will be created and the session ID stored in the file. If the file exists, the session ID is read from the file and the session is loaded from the database, enabling the session to be reloaded after the server has been restarted.
By default the jbpmSessionId.ser file is located in jboss-as/server/profile/tmp/ directory; however, this can be changed by modifying the jbpm.console.tmp.dir property in jbpm.console.properties located in the jboss-as/server/profile/deploy/business-central-server.war/WEB-INF/classes/ directory.

7.3.5. Transactions

By default, when transaction boundaries are not provided inside an application, the engine will automatically execute each method invocation on the engine in a separate transaction. Transaction boundaries can be specified, allowing, for example, multiple commands to be combined into one transaction.
The following sample code uses the Bitronix transaction manager.
// 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();
For Persistence and Concurrency, see Section 3.12.1, “Multi-threading” for more information.