Documentation Spring jBPM integration

Any project, especially open source projects, rise or fall with proper documentation. Following post serves a dual purpose, it’s a blog post (duh) but also a first draft for the devguide documentation of jBPM4. Things might sound a little weird, but that’s the reason.

Design

Transaction Management

A typical Spring application defines transaction management and ORM definition.  It follows following scheme:

Applications are accessed from the web tier and enter the transactional boundary by invoking service beans. These service beans will access the jBPM services. Spring users expect that all these operations run in a single transaction, which as we’ll see makes testing a lot easier.

In reality, we replace the standard-transaction-interceptor by a spring-transaction interceptor. Instead of starting and committing transactions, we want to reuse any existing transactions (which was already started by Spring).

The same is true for the hibernate session, which will be available through Spring.

Spring Context

JBPM4 comes with multiple contexts, which contains beans. With the SpringContext, we add the Spring Application Context to this set of contexts.

Configuration

Replace the standard-transaction-interceptor with the spring-transaction-interceptor.

The hibernate session needs the attribute current=”true”. This forces jBPM to search for the current session, which will be provided by Spring.

For the Spring context to be known, we created a SpringConfiguration. This extends the JbpmConfiguration but will add itself as a context. The single constructor take the location of the jBPM configuration.

<bean id="jbpmConfiguration" class=”org.jbpm.pvm.internal.cfg.SpringConfiguration”>
   <constructor-arg value="be/inze/spring/demo/jbpm.cfg.xml" />
</bean>

The services can also be defined in the Spring applicationContext, as following:

<bean id="processEngine" factory-bean="jbpmConfiguration" factory-method="buildProcessEngine" />
<bean id="repositoryService" factory-bean="processEngine" factory-method="getRepositoryService" />
<bean id="executionService" factory-bean="processEngine" factory-method="getExecutionService" />

For accessing Spring beans from a process, we need to register the Spring applicationContext. This can be done as following:

<script-manager default-expression-language="juel"
 default-script-language="juel"
 read-contexts="execution, environment, process-engine, spring"
 write-context="">
 <script-language name="juel"
 factory="org.jbpm.pvm.internal.script.JuelScriptEngineFactory" />
 </script-manager>

Use

In jBPM4 most development will happen through the client API aka the services. Simple inject these beans into your transactional service methods and start using them.

Invoking Spring beans from a process can be done as following:

<java name="echo" expr="#{echoService}" method="sayHello" >
    <transition name="to accept" to="join1"/>
 </java>

The scripting engine will look into all contexts from the bean named echoService. If you configured the ScriptManager as above, Spring will be the last context to search for. A good practice is to use unique names for the beans.

Testing

With the AbstractTransactionalJbpmTestCase we can test the process in isolation. Extending from AbstractTransactionalDataSourceSpringContextTests we can test like we test our DAO’s.

Any feedback is appreciated.

KR,
Andries