jBPM7 – Runtime Manager

Basically If we want to execute *.bpmn files, we should require jBPM runtime environment. For example, If we want to run java class files, we should require JRE like wise jBPM also requires runtime environment to execute a *.bpmn file. The jBPM runtime environment is called a Runtime Manager.

1. Runtime Manager Overview

Runtime Manager has been introduced to simplify and empower usage of knowledge API especially in context of processes. It provides configurable strategies that control actual runtime execution (how KieSessions are provided) and by default provides following:

• Singleton – runtime manager maintains single KieSession regardless of number of processes available
• Per Request – runtime manager delivers new KieSession for every request
• Per Process Instance – runtime manager maintains mapping between process instance and KieSession and always provides same KieSession whenever working with given process instance

Runtime Manager is primary responsible for mananging and delivering to the caller instances of RuntimeEngine. In turn RuntimeEngine encapsulates two the most important elements of jBPM engine:

• KieSession
• TaskService

2. Usage

Regular usage scenario for Runtime Manager is:

• At application startup
  • build RuntimeManager and keep it for entire life time of the application, it’s thread safe and can be (or even should be) accessed concurrently
• At request
  • get RuntimeEngine from RuntimeManager using proper context instance dedicated to strategy of RuntimeManager
  • get KieSession and/or TaskService from RuntimeEngine
  • perform operations on KieSession and/or TaskService such as startProcess, completeTask, etc
  • once done with processing dispose RuntimeEngine using RuntimeManager.disposeRuntimeEngine method
• At application shutdown
  • close RuntimeManager

When RuntimeEngine is obtained from RuntimeManager within active JTA transaction then there is no need to dispose RuntimeEngine at the end as RuntimeManager will automatically dipose the RuntimeEngine on transaction completion (regardless of the completion status commit or rollback)

3. Runtime Manager Example

We’ll use the JBPMHelper present in the org.jbpm.test package to build a sample runtime environment.

We require two things to create the environment: first, a data source to create the EntityManagerFactory, and second, our kbase.

JBPMHelper has methods to start an in-memory H2 server and set the data source. Using the same, we can create the EntityManagerFactory:

JBPMHelper.startH2Server();
JBPMHelper.setupDataSource();
EntityManagerFactory emf = Persistence.createEntityManagerFactory("org.jbpm.persistence.jpa");

Then, we can create our RuntimeEnvironment:

RuntimeEnvironmentBuilder builder = RuntimeEnvironmentBuilder.Factory.get()
                .newDefaultBuilder().entityManagerFactory(emf);
builder.knowledgeBase(kbase);

Using the RuntimeEnvironment, we can create our jBPM runtime manager

RuntimeManager runtimeManager = RuntimeManagerFactory.Factory.get().newSingletonRuntimeManager(builder.get());

Finally, we’ll use the RuntimeManager to get the RuntimeEngine

RuntimeEngine runtimeEngine = runtimeManager.getRuntimeEngine(EmptyContext.get());

Using RuntimeEngine, we’ll create a knowledge session and start the process:

KieSession ksession = runtimeEngine.getKieSession();
ksession.startProcess("com.hi.techpoints.helloworld");