jBPM6 samples with RuntimeManager

jBPM6 introduces new module - jbpm-runtime-manager - that aims at significantly simplify management of:

• KnowledgeBase (KieBase)
• KnowledgeSession (KieSession)

Moreover it allows to use predefined strategies for handling knowledge sessions and its relation to process instance. By default jBPM6 comes with three strategies:

• Singleton - single knowledge session that will execute all process instances
• Per Request - every request (which is in fact call to getRuntimeEngine) will get new knowledge session
• Per Process Instance - every process instance will have its dedicated knowledge session for the entire life time

To make use of the strategy it's enough to create proper type of RuntimeManager. jBPM6 allows to obtain instance of the RuntimeManager in various ways, this article will provide hands on information on how it can be achieved. 

With jBPM6 a whole new way of building application has been provided - Context and Dependency Injection is now available for users to build application and bring the power of jBPM to next level. Obviously CDI is not the only way to make use of jBPM - the regular API based approach is still available and fully functional.

CDI integration

jBPM6 tooling (like jbpm console or kie-wb) is built on CDI and thanks to that set of services has been provided to ease the development for custom applications that are based on CDI. These services are bundled as part of jbpm-kie-services and provides compact solution to most of the required operations to put BPM into your application:

• deployment service - deploys and undeploys units (kjars) into the process engine
• runtime service - gives access to state of the process engine, like retrieve process definitions, process instances, history log, etc
• bpmn2 data service - gives access to details of the process definition taken from BPMN2 xml
• form provider service - gives access to forms for processes and tasks

So whenever custom application is built with CDI these services are recommended way to go to get most of the power of CDI and jBPM. Moreover it's the safest way too as it is used in jBPM tooling so it got fair amount of testing to secure it does what is expected.

Using jbpm-kie-services is not a mandatory to be able to use jBPM6 in CDI environment but it does have some advantages:

- allow to maintain multiple RuntimeManagers within single execution environment

- allow independent deploy and undeploy of units (kjar) without server/application restart

- allow to select different strategies for different units

See jbpm-sample-cdi-services project for details.

while these are all appealing add-ons they are not always needed, especially if application requires only single RuntimeManager instance to be included in the application. If that's the case we can let CDI container to create the RuntimeManager instance for us. That is considered second approach to CDI integration where only single instance of RuntimeManager is active and it's managed completely by the CDI container. Application needs to provide environment that RuntimeManager will be based on. 

See jbpm-sample-cdi project for details.

API approach

Last but not least is the regular API based approach to jBPM6 and RuntimeManager. It expects to be built by the application and in fact provides all configuration options. Moreover this is the simplest way to extend the functionality of RuntimeManager that comes out of the box.

See jbpm-sample project for details.

This article is just an introduction to the way jBPM6 and RuntimeManager can be used. More detailed articles will follow to provide in-depth information on every option given here (cdi with services, pure cdi, api).

If you have any aspects that you would like to see in next articles (regarding runtime manager and CDI) just drop a comment here and I'll do by best to include them.

Dispose session in CMT environment

Since jBPM5 is flexible process engine it can be deployed in various flavours. One of them is to embed it into you enterprise application running on application server, regardless of its vendor (JBoss, WebSphere, WebLogic, etc).
One option among many others is to make use of it as part of you business logic implemented as EJB. If you choose to use bean managed transaction (BMT) you do not need to take any additional steps as your business logic maintains transaction boundaries. Although when you use container managed transaction (CMT) situation is little bit different as it is container (application server) responsibility to manage transaction.

Before we jump into details what needs to be done for CMT based application, let's mention one important and common for both types (BMT and CMT) practice:

Session must be disposed outside transaction, meaning transaction must be committed/rolledback before session could be disposed.

Obviously this applies to situation when session should be disposed as part of business logic, for instance with session per process instance architecture this could be desired. But not when we have single centralized session.

If session will be disposed before transaction is completed, exception will be thrown on transaction completion, complaining that session is already disposed:

IllegalStateException
("Illegal method call. This session was previously disposed.")

Having this in mind, let's take a look at how this can be done in CMT based implementations. Since we do not control transaction how we could dispose session after transaction is completed?
A simple answer to this is to use dedicated Command that will register transaction synchronization object that will be called on transaction completion so we could safely dispose session.

Here is an example of such command's execute method:
    
public Void execute(Context context) {
       
  final StatefulKnowledgeSession ksession =     
                ((KnowledgeCommandContext)context).getStatefulKnowledgesession();
  try {
      TransactionManager tm = 
      (TransactionManager) new InitialContext().lookup(tmLookupName);
      tm.getTransaction().registerSynchronization(new Synchronization() {
               
          @Override
          public void beforeCompletion() {
              // not used here         
          }
               
          @Override
          public void afterCompletion(int arg0) {
              ksession.dispose();           
          }
      });
  } catch (Exception e) {
      e.printStackTrace();
  }  
       
    return null
}

so, instead of calling default ksession.dispose() method at the end of you business logic, simply call ksession.execute(new CMTDisposeCommand());
That will ensure session is disposed as part of transaction completion.

Here is complete CMT dispose command