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.