12.4. Persistence configuration

12.4.1. Persistence configuration

Although persistence is not used by default, the dependencies needed are available in the runtime directory as jar files .
Persistence is defined per session and you can define it either using the JBPMHelper class after you create a session or using the JPAKnowledgeService to create your session. The latter option provides more flexibility, while JBPMHelper has a method to create a session, and uses a configuration file to configure this session.

12.4.2. Configuring persistence using JBPMHelper

To configure persistence of your session using JBPMHelper, do the following:
  1. Define your application to use an appropriate JBPMHelper session construtor:
    • KieSession ksession = JBPMHelper.newKieSession(kbase);
    • KieSession ksession = JBPMHelper.loadKieSession(kbase, sessionId);
  2. Configure the persistence in the jBPM.properties file.

    Example 12.1. A sample jBPM.properties file with persistence for the in-memory H2 database

    # 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
Any invocations on the session will now trigger the persistance process.
Make sure the datasource is up and running on engine start. If you are running the in-memory H2 database, you can start the database from your application using the JBPMHelper.startH2Server(); method call and register it with the engine using JBPMHelper.setupDataSource(); method call.

12.4.3. Configuring persistence using JPAKnowledgeService

To create your knowledge session and configure its persistence using JPAKnowledgeService, do the following:
  1. Define your application to use the knowledge session created by JPAKnowledgeService:
    • Define the session based on a knowledge base, a knowledge session configuration, and an environment. The environment must contain a reference to your Entity Manager Factory: 
      // 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 );

// create a new knowledge session that uses JPA to store the runtime state
KieSession ksession = JPAKnowledgeService.newKieSession( kbase, null, env );
int sessionId = ksession.getId();

// invoke methods on your method here
ksession.startProcess( "MyProcess" );
ksession.dispose();
    • Define the session based on a specific session id. 
      // recreate the session from database using the sessionId
ksession = JPAKnowledgeService.loadKieSession(sessionId, kbase, null, env );
  2. Configure the persistence in the META-INF/persistence.xml file: configure JPA to use Hibernate and the respective database.
    Information on how to configure data source on your application server should be available in the documentation delivered with the application server. For this information for JBoss Enterprise Application Platform, see the Administration and Configuration Guide for this product.

    Example 12.2. A sample persistence.xml file with persistence for an H2 data source jdbc/jbpm-ds

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<persistence
  version="1.0"
  xsi:schemaLocation=
    "http://java.sun.com/xml/ns/persistence
     http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd
     http://java.sun.com/xml/ns/persistence/orm
     http://java.sun.com/xml/ns/persistence/orm_1_0.xsd"
  xmlns:orm="http://java.sun.com/xml/ns/persistence/orm"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="http://java.sun.com/xml/ns/persistence">
  <persistence-unit name="org.jbpm.persistence.jpa" transaction-type="JTA">
    <provider>org.hibernate.ejb.HibernatePersistence</provider>
    <jta-data-source>jdbc/jbpm-ds</jta-data-source>
    <mapping-file>META-INF/JBPMorm.xml</mapping-file>
    <class>org.drools.persistence.info.SessionInfo</class>
    <class>org.jbpm.persistence.processinstance.ProcessInstanceInfo</class>
    <class>org.drools.persistence.info.WorkItemInfo</class>
    <properties>
      <property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/>
      <property name="hibernate.max_fetch_depth" value="3"/>
      <property name="hibernate.hbm2ddl.auto" value="update"/>
      <property name="hibernate.show_sql" value="true"/>
      <property name="hibernate.transaction.manager_lookup_class"
                value="org.hibernate.transaction.BTMTransactionManagerLookup"/>
    </properties>
  </persistence-unit>
</persistence>
Any invocations on the session will now trigger the persistance process.
Make sure the datasource is up and running on engine start. If you are running the in-memory H2 database, you can start the database from your application using the JBPMHelper.startH2Server(); method call and register it with the engine using JBPMHelper.setupDataSource(); method call.

Note

If you are running JBoss BPM Suite in a simple Java environment, your data source configuration will be similar to the following: 
PoolingDataSource ds = new PoolingDataSource();
ds.setUniqueName("jdbc/jbpm-ds");
ds.setClassName("bitronix.tm.resource.jdbc.lrc.LrcXADataSource");
ds.setMaxPoolSize(3);
ds.setAllowLocalTransactions(true);
ds.getDriverProperties().put("user", "sa");
ds.getDriverProperties().put("password", "sasa");
ds.getDriverProperties().put("URL", "jdbc:h2:tcp://localhost/~/jbpm-db");
ds.getDriverProperties().put("driverClassName", "org.h2.Driver");
ds.init();