The three most commonly-performed persistence operations are:

Process deployment is normally undertaken directly from the Graphical Process Designer or from the deployprocess ant task. However, to do it directly from Java, use this code:

JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext();

try {

  ProcessDefinition processDefinition = ...;

  jbpmContext.deployProcessDefinition(processDefinition);

} finally {

  jbpmContext.close();

}

Create a new process execution by specifying the process definition of which it will be an instance. The most common way to do this is by referring to the name of the process. The jBPM will then find the latest version of that process in the database. Here is some demonstration code:

JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext();

try {

    String processName = ...;

    ProcessInstance processInstance = 

        jbpmContext.newProcessInstance(processName);

} finally {

    jbpmContext.close();

}

To continue a process execution, fetch the process instance, the token or the taskInstance from the database and invoke some methods on the POJO (Plain Old Java Object) jBPM objects. Afterwards, save the updates made to the processInstance into the database.

JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext();

try {

    long processInstanceId = ...;

    ProcessInstance processInstance = 

        jbpmContext.loadProcessInstance(processInstanceId);

        processInstance.signal();

        jbpmContext.save(processInstance);

} finally {

    jbpmContext.close();

}

Note that it is not necessary to explicitly invoke the jbpmContext.save method if the ForUpdate methods are used in the JbpmContext class. This is because the save process will run automatically when the jbpmContext class is closed. For example, one may wish to inform the jBPM that a taskInstance has completed. This can cause an execution to continue, so the processInstance related to the taskInstance must be saved. The most convenient way to do this is by using the loadTaskInstanceForUpdate method:

JbpmContext jbpmContext = jbpmConfiguration.createJbpmContext();

try {

    long taskInstanceId = ...;

    TaskInstance taskInstance = 

        jbpmContext.loadTaskInstanceForUpdate(taskInstanceId);

    taskInstance.end();

    } 

finally {

        jbpmContext.close();

}

When the jbpmConfiguration.createJbpmContext() class is invoked, only the JbpmContext is created. No further persistence-related initializations occur at this time. The JbpmContext manages a DbPersistenceService class, which is instantiated when it is first requested. The DbPersistenceService class manages the Hibernate session, which is also only instantiated the first time it is required. (In other words, a Hibernate session will only be opened when the first operation that requires persistence is invoked.)

The DbPersistenceServiceFactory class has three more configuration properties: isTransactionEnabled, sessionFactoryJndiName, and dataSourceJndiName. To specify any of these properties in the jbpm.cfg.xml file, specify the Service Factory as a bean within the factory element. This sample code demonstrates how to do so:

<jbpm-context>

  <service name="persistence">

    <factory>

      <bean class="org.jbpm.persistence.db.DbPersistenceServiceFactory">

        <field name="isTransactionEnabled"><false /></field>

        <field name="sessionFactoryJndiName">

          <string value="java:/myHibSessFactJndiName" />

        </field>

        <field name="dataSourceJndiName">

          <string value="java:/myDataSourceJndiName" />

        </field>

      </bean>

    </factory>

  </service>

...

</jbpm-context>

By default, jBPM delegates transactions to Hibernate by using the "session per transaction" pattern. jBPM will begin a Hibernate transaction when a session is opened the first time when a persistent operation is invoked on the jbpmContext. The transaction will be committed right before the Hibernate session is closed. That will happen inside the jbpmContext.close().

Use jbpmContext.setRollbackOnly() to mark a transaction for rollback. In doing so, the transaction will be rolled back imediately before the session is closed inside the jbpmContext.close() method.

Managed transactions are most commonly found when jBPM is used in conjuction with the JBoss Application Server. The following code sample shows a common way in which transactions are bound to JTA:

<jbpm-context>

  <service name="persistence">

    <factory>

      <bean class="org.jbpm.persistence.db.DbPersistenceServiceFactory">

        <field name="isTransactionEnabled"><false /></field>

        <field name="isCurrentSessionEnabled"><true /></field>

        <field name="sessionFactoryJndiName">

          <string value="java:/myHibSessFactJndiName" />

        </field>

      </bean>

    </factory>

  </service>

</jbpm-context>

Next, configure the Hibernate session factory to use a data-source and bind Hibernate itself to the Transaction Manager. If using more than one datasource, bind them to an XA datasource.

<hibernate-configuration>

    <session-factory>



        <!-- hibernate dialect -->

        <property name="hibernate.dialect">

            org.hibernate.dialect.HSQLDialect

        </property>



        <!-- DataSource properties (begin) -->

        <property name="hibernate.connection.datasource">

            java:/JbpmDS

        </property>



        <!-- JTA transaction properties (begin) -->

        <property name="hibernate.transaction.factory_class">

            org.hibernate.transaction.JTATransactionFactory

        </property>

    

        <property name="hibernate.transaction.manager_lookup_class">

            org.hibernate.transaction.JBossTransactionManagerLookup

        </property>



        <property name="jta.UserTransaction">

            java:comp/UserTransaction

        </property>



    </session-factory>

</hibernate-configuration>

All of the SQL queries that jBPM uses are found in one central configuration file. That resource file is referenced in the hibernate.cfg.xml configuration file:

<hibernate-configuration>

    <!-- hql queries and type defs -->

    <mapping resource="org/jbpm/db/hibernate.queries.hbm.xml" />

</hibernate-configuration>

To customize one or more of those queries, make a back-up of the original file. Next, place the customized version somewhere on the classpath, then update the reference to org/jbpm/db/hibernate.queries.hbm.xml in the hibernate.cfg.xml to point to the customized version.

The jBPM runs on any database that is supported by Hibernate.

The example configuration file, src/config.files, specifies the use of the Hypersonic in-memory database, which is ideal for development and testing purposes. (Hypersonic retains all data in memory and does not store anything on disk.)