Chapter 20. Java APIs

The ProcessRuntime interface, which is extended by KieSession, defines methods for interacting with processes. See the interface below:

package org.kie.api.runtime.process;

interface ProcessRuntime {

/**
 * Start a new process instance.  The process (definition) that should
 * be used is referenced by the given process ID.
 *
 * @param processId The ID of the process that should be started
 * @return the ProcessInstance that represents the instance
 * of the process that was started
 */

ProcessInstance startProcess(String processId);

/**
 * Start a new process instance.  The process (definition) that should
 * be used is referenced by the given process id.  Parameters can be passed
 * to the process instance (as name-value pairs), and these will be set
 * as variables of the process instance.
 *
 * @param processId  the ID of the process that should be started
 * @param parameters  the process variables that should be set when
 * starting the process instance
 * @return the ProcessInstance that represents the instance
 * of the process that was started
 */

ProcessInstance startProcess(String processId, Map<String, Object> parameters);

/**
 * Signals the engine that an event has occurred. The type parameter defines
 * which type of event and the event parameter can contain additional information
 * related to the event.  All process instances that are listening to this type
 * of (external) event will be notified.  For performance reasons, this type of event
 * signaling should only be used if one process instance should be able to notify
 * other process instances. For internal event within one process instance, use the
 * signalEvent method that also include the processInstanceId of the process instance
 * in question.
 *
 * @param type the type of event
 * @param event the data associated with this event
 */

void signalEvent(String type, Object event);

/**
 * Signals the process instance that an event has occurred. The type parameter defines
 * which type of event and the event parameter can contain additional information
 * related to the event.  All node instances inside the given process instance that
 * are listening to this type of (internal) event will be notified.  Note that the event
 * will only be processed inside the given process instance.  All other process instances
 * waiting for this type of event will not be notified.
 *
 * @param type the type of event
 * @param event the data associated with this event
 * @param processInstanceId the id of the process instance that should be signaled
 */

void signalEvent(String type, Object event, long processInstanceId);

/**
 * Returns a collection of currently active process instances.  Note that only process
 * instances that are currently loaded and active inside the engine will be returned.
 * When using persistence, it is likely not all running process instances will be loaded
 * as their state will be stored persistently.  It is recommended not to use this
 * method to collect information about the state of your process instances but to use
 * a history log for that purpose.
 *
 * @return a collection of process instances currently active in the session
 */

Collection<ProcessInstance> getProcessInstances();

/**
 * Returns the process instance with the given id.  Note that only active process instances
 * will be returned.  If a process instance has been completed already,
 * this method will return null.
 *
 * @param id the id of the process instance
 * @return the process instance with the given id or null if it cannot be found
 */

ProcessInstance getProcessInstance(long processInstanceId);

/**
 * Aborts the process instance with the given id.  If the process instance has been completed
 * (or aborted), or the process instance cannot be found, this method will throw an
 * IllegalArgumentException.
 *
 * @param id the id of the process instance
 */

void abortProcessInstance(long processInstanceId);

/**
 * Returns the WorkItemManager related to this session.  This can be used to
 * register new WorkItemHandlers or to complete (or abort) WorkItems.
 *
 * @return the WorkItemManager related to this session
 */

WorkItemManager getWorkItemManager();

}

A knowledge session provides methods for registering and removing listeners.

The KieRuntimeEventManager interface is implemented by KieRuntime. KieRuntime provides two interfaces: RuleRuntimeEventManager and ProcessEventManager.

package org.kie.api.event.process;

public interface ProcessEventListener {

  void beforeProcessStarted(ProcessStartedEvent event);
  void afterProcessStarted(ProcessStartedEvent event);
  void beforeProcessCompleted(ProcessCompletedEvent event);
  void afterProcessCompleted(ProcessCompletedEvent event);
  void beforeNodeTriggered(ProcessNodeTriggeredEvent event);
  void afterNodeTriggered(ProcessNodeTriggeredEvent event);
  void beforeNodeLeft(ProcessNodeLeftEvent event);
  void afterNodeLeft(ProcessNodeLeftEvent event);
  void beforeVariableChanged(ProcessVariableChangedEvent event);
  void afterVariableChanged(ProcessVariableChangedEvent event);
}

import org.kie.api.runtime.process.EventListener;

ksession.addEventListener(new DefaultAgendaEventListener() {

  public void afterMatchFired(AfterMatchFiredEvent event) {
    super.afterMatchFired(event);
    System.out.println(event);
  }

});

ksession.addEventListener(new DebugRuleRuntimeEventListener());

Red Hat JBoss BPM Suite provides a listener for creating an audit log to the console or a file on the file system. You can use these logs for debugging purposes as it contains all the events occurring at runtime. Red Hat JBoss BPM Suite provides the following logger implementations:

See an example of using FileLogger logger:

import org.kie.api.KieServices;
import org.kie.api.logger.KieRuntimeLogger;

...
KieRuntimeLogger logger = KieServices.Factory
  .get().getLoggers().newFileLogger(ksession, "test");

// Add invocations to the process engine here,
// for example ksession.startProcess(processId);

...

logger.close();

KieRuntimeLogger uses the comprehensive event system in Red Hat JBoss BRMS to create an audit log that can be used to log the execution of an application for later inspection, using tools such as the Red Hat JBoss Developer Studio audit viewer.

When working with processes, you may require to assign a given process instance a business identifier for later reference without knowing the generated process instance ID. To provide such capabilities, Red Hat JBoss BPM Suite enables you to use the CorrelationKey interface that is composed of CorrelationProperties. CorrelationKey can have a single property describing it. Alternatively, CorrelationKey can be represented as multi-valued property set. Note that CorrelationKey is a unique identifier for an active process instance, and is not passed on to the subprocesses.

Correlation is usually used with long running processes and thus require persistence to be enabled in order to permanently store correlation information. Correlation capabilities are provided as part of the CorrelationAwareProcessRuntime interface.

The CorrelationAwareProcessRuntime interface exposes following methods:

package org.kie.internal.process;

interface CorrelationAwareProcessRuntime {

/**
 * Start a new process instance.  The process (definition) that should
 * be used is referenced by the given process id.  Parameters can be passed
 * to the process instance (as name-value pairs), and these will be set
 * as variables of the process instance.
 *
 * @param processId  the id of the process that should be started
 * @param correlationKey custom correlation key that can be used to identify process instance
 * @param parameters  the process variables that should be set
 *                    when starting the process instance
 * @return the ProcessInstance that represents the instance of the process that was started
 */

ProcessInstance startProcess(String processId, CorrelationKey correlationKey, Map<String, Object> parameters);

/**
 * Creates a new process instance (but does not yet start it).  The process
 * (definition) that should be used is referenced by the given process id.
 * Parameters can be passed to the process instance (as name-value pairs),
 * and these will be set as variables of the process instance.  You should only
 * use this method if you need a reference to the process instance before actually
 * starting it.  Otherwise, use startProcess.
 *
 * @param processId  the id of the process that should be started
 * @param correlationKey custom correlation key that can be used to identify process instance
 * @param parameters  the process variables that should be set
 *                    when creating the process instance
 * @return the ProcessInstance that represents the instance of the process
 *         that was created (but not yet started)
 */

ProcessInstance createProcessInstance(String processId, CorrelationKey correlationKey, Map<String, Object> parameters);

/**
 * Returns the process instance with the given correlationKey.
 * Note that only active process instances will be returned.
 * If a process instance has been completed already, this method will return null.
 *
 * @param correlationKey the custom correlation key assigned
 *                       when process instance was created
 * @return the process instance with the given id or null if it cannot be found
 */

ProcessInstance getProcessInstance(CorrelationKey correlationKey);

}

You can create and use a correlation key with single or multiple properties. In case of correlation keys with multiple properties, it is not necessary that you know all parts of the correlation key in order to search for a process instance. Red Hat JBoss BPM Suite enables you to set a part of the correlation key properties and get a list of entities that match the properties. That is, you can search for process instances even with partial correlation keys.

For example, consider a scenario when you have a unique identifier customerId per customer. Each customer can have many applications (process instances) running simultaneously. To retrieve a list of all the currently running applications and choose to continue any one of them, use a correlation key with multiple properties (such as customerId and applicationId) and use only customerId to retrieve the entire list.

Red Hat JBoss BPM Suite runtime provides the operations to find single process instance by complete correlation key and many process instances by partial correlation key. The following methods of RuntimeDataService can be used (see Section 20.3.4, “Runtime Data Service”):

/**
 * Returns active process instance description found for given correlation key
 * if found otherwise null. At the same time it will
 * fetch all active tasks (in status: Ready, Reserved, InProgress) to provide
 * information what user task is keeping instance and who owns them
 * (if were already claimed).
 *
 * @param correlationKey correlation key assigned to process instance
 * @return Process instance information, in the form of
 *         a {@link ProcessInstanceDesc} instance.
 */

ProcessInstanceDesc getProcessInstanceByCorrelationKey(CorrelationKey correlationKey);

/**
 * Returns process instances descriptions (regardless of their states)
 * found for given correlation key if found otherwise empty list.
 * This query uses 'like' to match correlation key so it allows to pass only partial keys,
 * though matching is done based on 'starts with'.
 *
 * @param correlationKey correlation key assigned to process instance
 * @return A list of {@link ProcessInstanceDesc} instances representing the process
 *         instances that match the given correlation key
 */

Collection<ProcessInstanceDesc> getProcessInstancesByCorrelationKey
  (CorrelationKey correlationKey);

Multi-threading is divided into technical and logical multi-threading.

The Red Hat JBoss BPM Suite engine supports logical multi-threading which is implemented using only one technical thread. The logical implementation was chosen because multiple technical threads need to communicate state information with each other, if they are working on the same process. While multi-threading provides performance benefits, the extra logic used to ensure the different threads work together well, means that this is not guaranteed. There is additional overhead of avoiding race conditions and deadlocks.

The Red Hat JBoss BPM Suite engine executes actions serially. For example, if a process encounters a parallel gateway, it sequentially triggers each of the outgoing branches, one after the other. This is possible since execution is usually instantaneous. As a result, you may not even notice this behaivor. Similarly, when the engine encounters a script task in a process, it synchronously executes that script and waits for it to complete before continuing execution.

For example, calling a Thread.sleep(…​) method as a part of a script does not make the engine continue execution elsewhere, but blocks the engine thread during that period. The same principle applies to service tasks.

When a service task is reached in a process, the engine invokes the handler of the service synchronously. The engine waits for the completeWorkItem(…​) method to return before continuing execution. It is important that your service handler executes your service asynchronously if its execution is not instantaneous. For example, a service task that invokes an external service. Since the delay in invoking the service remotely and waiting for the results can take too long, invoking this service asynchronously is advised. Asynchronous call invokes the service and notifies the engine later when the results are available. After invoking the service, the process engine continues execution of the process.

Human tasks are a typical example of a service that needs to be invoked asynchronously, as the engine does not have to wait until a human actor responds to the request. The human task handler only creates a new task when the human task node is triggered. The engine then is able to continue the execution of the process (if necessary) and the handler notifies the engine asynchronously when the user completes the task.

Globals are named objects that are visible to the engine differently from facts; changes in a global do not trigger reevaluation of rules. Globals are useful for providing static information, as an object offering services that are used in the RHS of a rule, or as a means to return objects from the rule engine. When you use a global on the LHS of a rule, make sure it is immutable, or, at least, do not expect changes to have any effect on the behavior of your rules.

A global must be declared as a Java object in a rules file:

global java.util.List list

With the Knowledge Base now aware of the global identifier and its type, it is now possible to call the ksession.setGlobal() method with the global’s name and an object, for any session, to associate the object with the global. Failure to declare the global type and identifier in DRL code will result in an exception being thrown from this call.

List list = new ArrayList();
ksession.setGlobal("list", list);

Set any global before it is used in the evaluation of a rule. Failure to do so results in a NullPointerException exception.

You can also initialize global variables while instantiating a process:

To access your global variable, use the getVariable() method:

processInstance.getContextInstance().getVariable("globalStatus");

Sometimes, for instance in an OSGi environment, the KieBase object needs to resolve types that are not in the default class loader. To do so, create a KieBaseConfiguration instance with an additional class loader and pass it to KieContainer when creating a new KieBase object. For example:

import org.kie.api.KieServices;
import org.kie.api.KieServices.Factory;
import org.kie.api.KieBaseConfiguration;
import org.kie.api.KieBase;
import org.kie.api.runtime.KieContainer;

KieServices kieServices = KieServices.Factory.get();
KieBaseConfiguration kbaseConf = kieServices
  .newKieBaseConfiguration( null, MyType.class.getClassLoader());
KieBase kbase = kieContainer.newKieBase(kbaseConf);

The KieBase object can create, and optionally keep references to, KieSession objects. When you modify KieBase, the modifications are applied against the data in the sessions. This reference is a weak reference and it is also optional, which is controlled by a boolean flag.

XML marshalling and unmarshalling of the JBoss BRMS Commands requires the use of special classes. This section describes these classes.

BatchExecutionHelper.newXStreamMarshaller().toXML(command);

BatchExecutionHelper.newXStreamMarshaller().fromXML(xml);

BatchExecutionHelper.newJSonMarshaller().toXML(command);

BatchExecutionHelper.newJSonMarshaller().fromXML(xml);

import org.kie.api.conf.Option;
import org.kie.api.KieBase;

Options xjcOpts = new Options();
xjcOpts.setSchemaLanguage(Language.XMLSCHEMA);
JaxbConfiguration jaxbConfiguration =
  KnowledgeBuilderFactory.newJaxbConfiguration( xjcOpts, "xsd");
kbuilder.add
  (ResourceFactory.newClassPathResource
    ("person.xsd", getClass()), ResourceType.XSD, jaxbConfiguration);
KieBase kbase = kbuilder.newKnowledgeBase();

List<String> classesName = new ArrayList<String>();
classesName.add("org.drools.compiler.test.Person");

JAXBContext jaxbContext = KnowledgeBuilderHelper
  .newJAXBContext(classesName.toArray(new String[classesName.size()]), kbase);

List<String> classNames = new ArrayList<String>();
classNames.add("org.drools.compiler.test.Person");

JAXBContext jaxbContext = DroolsJaxbHelperProviderImpl
  .createDroolsJaxbContext(classNames, null);
Marshaller marshaller = jaxbContext.createMarshaller();

Red Hat JBoss BRMS supports the following list of commands:

BatchExecutionCommand command = new BatchExecutionCommand();
command.setLookup("ksession1");

InsertObjectCommand insertObjectCommand = new InsertObjectCommand(new Person("john", 25));
FireAllRulesCommand fireAllRulesCommand = new FireAllRulesCommand();

command.getCommands().add(insertObjectCommand);
command.getCommands().add(fireAllRulesCommand);

ksession.execute(command);

<batch-execution lookup="ksession1">
  <insert>
    <org.drools.compiler.test.Person>
      <name>john</name>
      <age>25</age>
    </org.drools.compiler.test.Person>
  </insert>
  <fire-all-rules/>
</batch-execution>

{"batch-execution":{"lookup":"ksession1","commands":[{"insert":{"object":{"org.drools.compiler.test.Person":{"name":"john","age":25}}}},{"fire-all-rules":""}]}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-execution lookup="ksession1">
  <insert>
    <object xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <age>25</age>
      <name>john</name>
    </object>
  </insert>
  <fire-all-rules max="-1"/>
</batch-execution>

Command insertObjectCommand =
  CommandFactory.newInsert(new Person("john", 25), "john", false, null);

ksession.execute(insertObjectCommand);

<insert out-identifier="john" entry-point="my stream" return-object="false">
  <org.drools.compiler.test.Person>
    <name>john</name>
    <age>25</age>
  </org.drools.compiler.test.Person>
</insert>

{
    "insert": {
        "entry-point": "my stream",
        "object": {
            "org.drools.compiler.test.Person": {
                "age": 25,
                "name": "john"
            }
        },
        "out-identifier": "john",
        "return-object": false
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<insert out-identifier="john" entry-point="my stream" >
  <object xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <age>25</age>
    <name>john</name>
  </object>
</insert>

RetractCommand retractCommand = new RetractCommand();
retractCommand.setFactHandleFromString("123:234:345:456:567");

RetractCommand retractCommand = new RetractCommand(factHandle);

<retract fact-handle="0:234:345:456:567"/>

{
    "retract": {
        "fact-handle": "0:234:345:456:567"
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retract fact-handle="0:234:345:456:567"/>

ModifyCommand modifyCommand = new ModifyCommand();
modifyCommand.setFactHandleFromString("123:234:345:456:567");

List<Setter> setters = new ArrayList<Setter>();
setters.add(new SetterImpl("age", "30"));

modifyCommand.setSetters(setters);

<modify fact-handle="0:234:345:456:567">
  <set accessor="age" value="30"/>
</modify>

{
    "modify": {
        "fact-handle": "0:234:345:456:567",
        "setters": {
            "accessor": "age",
            "value": 30
        }
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<modify fact-handle="0:234:345:456:567">
  <set value="30" accessor="age"/>
</modify>

GetObjectCommand getObjectCommand = new GetObjectCommand();
getObjectCommand.setFactHandleFromString("123:234:345:456:567");
getObjectCommand.setOutIdentifier("john");

<get-object fact-handle="0:234:345:456:567" out-identifier="john"/>

{
    "get-object": {
        "fact-handle": "0:234:345:456:567",
        "out-identifier": "john"
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<get-object out-identifier="john" fact-handle="0:234:345:456:567"/>

List<Object> objects = new ArrayList<Object>();
objects.add(new Person("john", 25));
objects.add(new Person("sarah", 35));

Command insertElementsCommand = CommandFactory.newInsertElements(objects);

<insert-elements>
  <org.drools.compiler.test.Person>
    <name>john</name>
    <age>25</age>
  </org.drools.compiler.test.Person>
  <org.drools.compiler.test.Person>
    <name>sarah</name>
    <age>35</age>
  </org.drools.compiler.test.Person>
</insert-elements>

{
    "insert-elements": {
        "objects": [
            {
                "containedObject": {
                    "@class": "org.drools.compiler.test.Person",
                    "age": 25,
                    "name": "john"
                }
            },
            {
                "containedObject": {
                    "@class": "Person",
                    "age": 35,
                    "name": "sarah"
                }
            }
        ]
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<insert-elements return-objects="true">
  <list>
    <element xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <age>25</age>
      <name>john</name>
    </element>
    <element xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <age>35</age>
      <name>sarah</name>
    </element>
  <list>
</insert-elements>

FireAllRulesCommand fireAllRulesCommand = new FireAllRulesCommand();
fireAllRulesCommand.setMax(10);
fireAllRulesCommand.setOutIdentifier("firedActivations");

<fire-all-rules max="10" out-identifier="firedActivations"/>

{
    "fire-all-rules": {
        "max": 10,
        "out-identifier": "firedActivations"
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<fire-all-rules out-identifier="firedActivations" max="10"/>

StartProcessCommand startProcessCommand = new StartProcessCommand();
startProcessCommand.setProcessId("org.drools.task.processOne");

<start-process processId="org.drools.task.processOne"/>

{
    "start-process": {
        "process-id": "org.drools.task.processOne"
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<start-process processId="org.drools.task.processOne">
  <parameter/>
</start-process>

SignalEventCommand signalEventCommand = new SignalEventCommand();
signalEventCommand.setProcessInstanceId(1001);
signalEventCommand.setEventType("start");
signalEventCommand.setEvent(new Person("john", 25));

<signal-event process-instance-id="1001" event-type="start">
  <org.drools.pipeline.camel.Person>
    <name>john</name>
    <age>25</age>
  </org.drools.pipeline.camel.Person>
</signal-event>

{
    "signal-event": {
        "@event-type": "start",
        "event-type": "start",
        "object": {
            "org.drools.pipeline.camel.Person": {
                "age": 25,
                "name": "john"
            }
        },
        "process-instance-id": 1001
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<signal-event event-type="start" process-instance-id="1001">
  <event xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <age>25</age>
    <name>john</name>
  </event>
</signal-event>

CompleteWorkItemCommand completeWorkItemCommand = new CompleteWorkItemCommand();
completeWorkItemCommand.setWorkItemId(1001);

<complete-work-item id="1001"/>

{
    "complete-work-item": {
        "id": 1001
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<complete-work-item id="1001"/>

AbortWorkItemCommand abortWorkItemCommand = new AbortWorkItemCommand();
abortWorkItemCommand.setWorkItemId(1001);

<abort-work-item id="1001"/>

{
    "abort-work-item": {
        "id": 1001
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<abort-work-item id="1001"/>

QueryCommand queryCommand = new QueryCommand();
queryCommand.setName("persons");
queryCommand.setOutIdentifier("persons");

<query out-identifier="persons" name="persons"/>

{
    "query": {
        "name": "persons",
        "out-identifier": "persons"
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<query name="persons" out-identifier="persons"/>

SetGlobalCommand setGlobalCommand = new SetGlobalCommand();
setGlobalCommand.setIdentifier("helper");
setGlobalCommand.setObject(new Person("kyle", 30));
setGlobalCommand.setOut(true);
setGlobalCommand.setOutIdentifier("output");

<set-global identifier="helper" out-identifier="output">
  <org.drools.compiler.test.Person>
    <name>kyle</name>
    <age>30</age>
  </org.drools.compiler.test.Person>
</set-global>

{
    "set-global": {
        "identifier": "helper",
        "object": {
            "org.drools.compiler.test.Person": {
                "age": 30,
                "name": "kyle"
            }
        },
        "out-identifier": "output"
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<set-global out="true" out-identifier="output" identifier="helper">
  <object xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <age>30</age>
    <name>kyle</name>
  </object>
</set-global>

GetGlobalCommand getGlobalCommand = new GetGlobalCommand();
getGlobalCommand.setIdentifier("helper");
getGlobalCommand.setOutIdentifier("helperOutput");

<get-global identifier="helper" out-identifier="helperOutput"/>

{
    "get-global": {
        "identifier": "helper",
        "out-identifier": "helperOutput"
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<get-global out-identifier="helperOutput" identifier="helper"/>

GetObjectsCommand getObjectsCommand = new GetObjectsCommand();
getObjectsCommand.setOutIdentifier("objects");

<get-objects out-identifier="objects"/>

{
    "get-objects": {
        "out-identifier": "objects"
    }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<get-objects out-identifier="objects"/>

In some cases, it is possible to change the default severity of a type of build result. For instance, when a new rule with the same name of an existing rule is added to a package, the default behavior is to replace the old rule by the new rule and report it as an INFO. This is probably ideal for most use cases, but in some deployments the user might want to prevent the rule update and report it as an error.

Changing the default severity for a result type, configured like any other option in BRMS, can be done by API calls, system properties or configuration files. As of this version, BRMS supports configurable result severity for rule updates and function updates. To configure it using system properties or configuration files, the user has to use the following properties:

// Sets the severity of rule updates:
drools.kbuilder.severity.duplicateRule = <INFO|WARNING|ERROR>

// Sets the severity of function updates:
drools.kbuilder.severity.duplicateFunction = <INFO|WARNING|ERROR>

The StatelessKieSession wraps the KieSession, instead of extending it. Its main focus is on the decision service type scenarios. It avoids the need to call dispose(). Stateless sessions do not support iterative insertions and the method call fireAllRules() from Java code; the act of calling execute() is a single-shot method that will internally instantiate a KieSession, add all the user data and execute user commands, call fireAllRules(), and then call dispose(). While the main way to work with this class is via the BatchExecution (a subinterface of Command) as supported by the CommandExecutor interface, two convenience methods are provided for when simple object insertion is all that’s required. The CommandExecutor and BatchExecution are talked about in detail in their own section.

Our simple example shows a stateless session executing a given collection of Java objects using the convenience API. It will iterate the collection, inserting each element in turn.

import org.kie.api.runtime.StatelessKieSession;

StatelessKieSession ksession = kbase.newStatelessKieSession();
ksession.execute(collection);

If this was done as a single command it would be as follows:

ksession.execute(CommandFactory.newInsertElements(collection));

If you wanted to insert the collection itself, and the collection’s individual elements, then CommandFactory.newInsert(collection) would do the job.

Methods of the CommandFactory create the supported commands, all of which can be marshalled using XStream and the BatchExecutionHelper. BatchExecutionHelper provides details on the XML format as well as how to use BRMS Pipeline to automate the marshalling of BatchExecution and ExecutionResults.

StatelessKieSession supports globals, scoped in a number of ways. We cover the non-command way first, as commands are scoped to a specific execution call. Globals can be resolved in three ways.

The CommandExecutor interface also offers the ability to export data through "out" parameters. Inserted facts, globals and query results can all be returned.

import org.kie.api.runtime.ExecutionResults;

// Set up a list of commands:
List cmds = new ArrayList();
cmds.add(CommandFactory.newSetGlobal("list1", new ArrayList(), true));
cmds.add(CommandFactory.newInsert(new Person("jon", 102), "person"));
cmds.add(CommandFactory.newQuery("Get People" "getPeople"));

// Execute the list:
ExecutionResults results = ksession.execute(CommandFactory.newBatchExecution(cmds));

// Retrieve the ArrayList:
results.getValue("list1");
// Retrieve the inserted Person fact:
results.getValue("person");
// Retrieve the query as a QueryResults instance:
results.getValue("Get People");

The KieMarshallers are used to marshal and unmarshal KieSessions.

An instance of the KieMarshallers can be retrieved from the KieServices. A simple example is shown below:

import org.kie.api.runtime.KieSession;
import org.kie.api.KieBase;
import org.kie.api.marshalling.Marshaller;

// ksession is the KieSession
// kbase is the KieBase
ByteArrayOutputStream baos = new ByteArrayOutputStream();
Marshaller marshaller = KieServices.Factory.get().getMarshallers().newMarshaller(kbase);
marshaller.marshall( baos, ksession );
baos.close();

However, with marshalling, you will need more flexibility when dealing with referenced user data. To achieve this use the ObjectMarshallingStrategy interface. Two implementations are provided, but users can implement their own. The two supplied strategies are IdentityMarshallingStrategy and SerializeMarshallingStrategy. SerializeMarshallingStrategy is the default, as shown in the example above, and it just calls the Serializable or Externalizable methods on a user instance. IdentityMarshallingStrategy creates an integer id for each user object and stores them in a Map, while the id is written to the stream. When unmarshalling it accesses the IdentityMarshallingStrategy map to retrieve the instance. This means that if you use the IdentityMarshallingStrategy, it is stateful for the life of the Marshaller instance and will create ids and keep references to all objects that it attempts to marshal. Below is the code to use an Identity Marshalling Strategy.

import org.kie.api.marshalling.KieMarshallers;
import org.kie.api.marshalling.ObjectMarshallingStrategy;
import org.kie.api.marshalling.Marshaller;

ByteArrayOutputStream baos = new ByteArrayOutputStream();
KieMarshallers kMarshallers = KieServices.Factory.get().getMarshallers()
ObjectMarshallingStrategy oms = kMarshallers.newIdentityMarshallingStrategy()

Marshaller marshaller =
  kMarshallers.newMarshaller(kbase, new ObjectMarshallingStrategy[]{ oms });
marshaller.marshall(baos, ksession);
baos.close();

In most cases, a single strategy is insufficient. For added flexibility, the ObjectMarshallingStrategyAcceptor interface can be used. This Marshaller has a chain of strategies, and while reading or writing a user object it iterates the strategies asking if they accept responsibility for marshalling the user object. One of the provided implementations is ClassFilterAcceptor. This allows strings and wild cards to be used to match class names. The default is ., so in the above example the Identity Marshalling Strategy is used which has a default . acceptor.

Assuming that we want to serialize all classes except for one given package, where we will use identity lookup, we could do the following:

import org.kie.api.marshalling.KieMarshallers;
import org.kie.api.marshalling.ObjectMarshallingStrategy;
import org.kie.api.marshalling.Marshaller;

ByteArrayOutputStream baos = new ByteArrayOutputStream();
KieMarshallers kMarshallers = KieServices.Factory.get().getMarshallers()

ObjectMarshallingStrategyAcceptor identityAcceptor =
  kMarshallers.newClassFilterAcceptor(new String[] { "org.domain.pkg1.*" });
ObjectMarshallingStrategy identityStrategy =
  kMarshallers.newIdentityMarshallingStrategy(identityAcceptor);
ObjectMarshallingStrategy sms = kMarshallers.newSerializeMarshallingStrategy();

Marshaller marshaller =
  kMarshallers.newMarshaller
    (kbase, new ObjectMarshallingStrategy[]{ identityStrategy, sms });
marshaller.marshall( baos, ksession );

baos.close();

Note that the acceptance checking order is in the natural order of the supplied elements.

Also note that if you are using scheduled matches (for example some of your rules use timers or calendars) they are marshallable only if, before you use it, you configure your KieSession to use a trackable timer job factory manager as follows:

import org.kie.api.runtime.KieSessionConfiguration;
import org.kie.api.KieServices.Factory;
import org.kie.api.runtime.conf.TimerJobFactoryOption;

KieSessionConfiguration ksconf = KieServices.Factory.get().newKieSessionConfiguration();
ksconf.setOption(TimerJobFactoryOption.get("trackable"));
KSession ksession = kbase.newKieSession(ksconf, null);

Longterm out of the box persistence with Java Persistence API (JPA) is possible with BRMS. It is necessary to have some implementation of the Java Transaction API (JTA) installed. For development purposes the Bitronix Transaction Manager is suggested, as it’s simple to set up and works embedded, but for production use JBoss Transactions is recommended.

import org.kie.api.KieServices;
import org.kie.api.runtime.Environment;
import org.kie.api.runtime.EnvironmentName;
import org.kie.api.runtime.KieSessionConfiguration;

KieServices kieServices = KieServices.Factory.get();
Environment env = kieServices.newEnvironment();
env.set(EnvironmentName.ENTITY_MANAGER_FACTORY,
  Persistence.createEntityManagerFactory("emf-name"));
env.set(EnvironmentName.TRANSACTION_MANAGER,
  TransactionManagerServices.getTransactionManager());

// KieSessionConfiguration may be null, and a default will be used:
KieSession ksession =
  kieServices.getStoreServices().newKieSession(kbase, null, env);
int sessionId = ksession.getId();

UserTransaction ut =
  (UserTransaction) new InitialContext().lookup("java:comp/UserTransaction");

ut.begin();
ksession.insert(data1);
ksession.insert(data2);
ksession.startProcess("process1");
ut.commit();

To use a JPA, the Environment must be set with both the EntityManagerFactory and the TransactionManager. If rollback occurs the ksession state is also rolled back, hence it is possible to continue to use it after a rollback. To load a previously persisted KieSession you’ll need the id, as shown below:

import org.kie.api.runtime.KieSession;

KieSession ksession =
  kieServices.getStoreServices().loadKieSession(sessionId, kbase, null, env);

To enable persistence several classes must be added to your persistence.xml, as in the example below:

<persistence-unit name="org.drools.persistence.jpa" transaction-type="JTA">
  <provider>org.hibernate.ejb.HibernatePersistence</provider>
  <jta-data-source>jdbc/BitronixJTADataSource</jta-data-source>
  <class>org.drools.persistence.info.SessionInfo</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>

The JDBC JTA data source would have to be configured first. Bitronix provides a number of ways of doing this, and its documentation should be consulted for details. For a quick start, here is the programmatic approach:

PoolingDataSource ds = new PoolingDataSource();

ds.setUniqueName("jdbc/BitronixJTADataSource");
ds.setClassName("org.h2.jdbcx.JdbcDataSource");
ds.setMaxPoolSize(3);
ds.setAllowLocalTransactions(true);
ds.getDriverProperties().put("user", "sa");
ds.getDriverProperties().put("password", "sasa");
ds.getDriverProperties().put("URL", "jdbc:h2:mem:mydb");
ds.init();

Bitronix also provides a simple embedded JNDI service, ideal for testing. To use it, add a jndi.properties file to your META-INF folder and add the following line to it:

java.naming.factory.initial=bitronix.tm.jndi.BitronixInitialContextFactory

A stateless KIE session is a session without inference. A stateless session can be called like a function in that you can use it to pass data and then receive the result back.

Stateless KIE sessions are useful in situations requiring validation, calculation, routing, and filtering.

A stateful session allow you to make iterative changes to facts over time. As with the StatelessKnowledgeSession, the StatefulKnowledgeSession supports the BatchExecutor interface. The only difference is the FireAllRules command is not automatically called at the end.

Regular usage scenario for RuntimeManager is:

Here is how you can build RuntimeManager (with RuntimeEnvironment) and get RuntimeEngine (that encapsulates KieSession and TaskService) from it:

// First, configure environment that will be used by RuntimeManager:

RuntimeEnvironment environment = RuntimeEnvironmentBuilder.Factory.get()
  .newDefaultInMemoryBuilder()
  .addAsset(ResourceFactory.newClassPathResource
    ("BPMN2-ScriptTask.bpmn2"), ResourceType.BPMN2)
  .get();

// Next, create RuntimeManager - in this case singleton strategy is chosen:
RuntimeManager manager = RuntimeManagerFactory
  .Factory.get().newSingletonRuntimeManager(environment);

// Then, get RuntimeEngine out of manager - using empty context as singleton
// does not keep track of runtime engine as there is only one:
RuntimeEngine runtime = manager.getRuntimeEngine(EmptyContext.get());

// Get KieSession from runtime runtimeEngine - already initialized with all handlers,
// listeners, and others, that were configured on the environment:
KieSession ksession = runtimeEngine.getKieSession();

// Add invocations to the process engine here,
// for example ksession.startProcess(processId);
// and last dispose the runtime engine:
manager.disposeRuntimeEngine(runtimeEngine);

Runtime Manager Identifier

During runtime execution, the identifier of the runtime manager is deploymentId. If a task is persisted, the identifier of the task is persisted as deploymentId as well. The deploymentId of the task is then used to identify the runtime manager after the task is completed and its process instance is resumed. The deploymentId is also persisted as externalId in a history log.

If the identifier is not specified during the creation of the runtime manager, a default value is used. Therefore, the same deployment is used during the application’s lifecycle. It is possible to maintain multiple runtime managers in one application. However, it is required to specify their identifiers. For example, Deployment Service (see Section 20.3.1, “Deployment Service”) maintains more runtime managers with identifiers based on the kJAR’s GAV. The Business Central web application depends on Deployment Service, so it has multiple runtime managers as well.

This instructs the RuntimeManager to maintain single instance of RuntimeEngine and in turn single instance of KieSession and TaskService. Access to the RuntimeEngine is synchronized and the thread is safe although it comes with a performance penalty due to synchronization. This strategy is considered to be the easiest one and recommended to start with. It has the following characteristics:

This instructs the RuntimeManager to provide new instance of RuntimeEngine for every request. As the RuntimeManager request considers one or more invocations within single transaction. It must return same instance of RuntimeEngine within single transaction to ensure correctness of state as otherwise the operation in one call would not be visible in the other. This a kind of stateless strategy that provides only request scope state. Once the request is completed, the RuntimeEngine is permanently destroyed. The KieSession information is then removed from the database in case you used persistence. It has following characteristics:

This instructs the RuntimeManager to maintain a strict relationship between KieSession and ProcessInstance. That means that the KieSession will be available as long as the ProcessInstance that it belongs to is active. This strategy provides the most flexible approach to use advanced capabilities of the engine like rule evaluation in isolation (for given process instance only). It provides maximum performance and reduction of potential bottlenecks introduced by synchronization. Additionally, it reduces number of KieSessions to the actual number of process instances, rather than number of requests (in contrast to per request strategy). It has the following characteristics:

The implementation of RegisterableItemsFactory provides a dedicated mechanism to create your own handlers or listeners.

/**
 * Returns new instances of WorkItemHandler that will be registered on RuntimeEngine.
 *
 * @param runtime provides RuntimeEngine in case handler need to make use of it internally
 * @return map of handlers to be registered - in case of no handlers
 *         empty map shall be returned
 */

Map<String, WorkItemHandler> getWorkItemHandlers(RuntimeEngine runtime);

/**
 * Returns new instances of ProcessEventListener that will be registered on RuntimeEngine.
 *
 * @param runtime provides RuntimeEngine in case listeners need to make use of it internally
 * @return list of listeners to be registered - in case of no listeners
 *         empty list shall be returned
 */

List<ProcessEventListener> getProcessEventListeners(RuntimeEngine runtime);

/**
 * Returns new instances of AgendaEventListener that will be registered on RuntimeEngine.
 *
 * @param runtime provides RuntimeEngine in case listeners need to make use of it internally
 * @return list of listeners to be registered - in case of no listeners
 *         empty list shall be returned
 */

List<AgendaEventListener> getAgendaEventListeners(RuntimeEngine runtime);

/**
 * Returns new instances of WorkingMemoryEventListener that will be registered
 * on RuntimeEngine.
 *
 * @param runtime provides RuntimeEngine in case listeners need to make use of it internally
 * @return list of listeners to be registered - in case of no listeners
 *         empty list shall be returned
 */

List<WorkingMemoryEventListener> getWorkingMemoryEventListeners(RuntimeEngine runtime);

Extending out-of-the-box implementation and adding your own is a good practice. You may not always need extensions, as the default implementations of RegisterableItemsFactory provides a mechanism to define custom handlers and listeners. Following is a list of available implementations ordered in the hierarchy of inheritance:

Alternatively, you may also register simple (stateless or requiring only KieSession) work item handlers by defining them as part of CustomWorkItem.conf file and update the class path. To use this approach do the following:

These steps register the work item handlers for any KieSession created by the application, regardless of it using the RuntimeManager or not.

When you are using RuntimeManager in CDI environment, you can use the dedicated interfaces to provide custom WorkItemHandlers and EventListeners to the RuntimeEngine.

public interface WorkItemHandlerProducer {

  /**
   * Returns map of (key = work item name, value work item handler instance)
   * of work items to be registered on KieSession.
   * Parameters that might be given are as follows:
   * ksessiontaskService
   * runtimeManager
   *
   * @param identifier - identifier of the owner - usually RuntimeManager that allows
   *                     the producer to filter out and provide valid instances
   *                     for given owner
   * @param params - owner might provide some parameters, usually KieSession,
   *                 TaskService, RuntimeManager instances
   * @return map of work item handler instances (recommendation is to always
   *         return new instances when this method is invoked)
   */

  Map<String, WorkItemHandler> getWorkItemHandlers(String identifier,
    Map<String, Object> params);
}

The event listener producer is annotated with proper qualifier to indicate what type of listeners they provide. You can select one of the following to indicate the type:

public interface EventListenerProducer<T> {

  /**
   * Returns list of instances for given (T) type of listeners.
   * Parameters that might be given are as follows:
   * ksession
   * taskServiceruntimeManager
   *
   * @param identifier - identifier of the owner - usually RuntimeManager that allows
   *                     the producer to filter out and provide valid instances
   *                     for given owner
   * @param params - owner might provide some parameters, usually KieSession,
   *                 TaskService, RuntimeManager instances
   * @return list of listener instances (recommendation is to always return new
   *         instances when this method is invoked)
   */

  List<T> getEventListeners(String identifier, Map<String, Object>  params);

}

Package these interface implementations as bean archive that includes beans.xml inside META-INF folder and update the application classpath (for example, WEB-INF/lib for web application). This enables the CDI based RuntimeManager to discover them and register on every KieSession that is created or loaded from the data store.

All the components (KieSession, TaskService, and RuntimeManager) are provided to the producers to allow handlers or listeners to be more stateful and be able to do more advanced things with the engine. You can also apply filtering based on the identifier (that is given as argument to the methods) to decide if the given RuntimeManager can receive handlers or listeners or not.

The Query Service uses the following four classes describing queries and their results:

While using the QueryDefinition and QueryParam classes is straightforward, the QueryResultMapper and QueryParamBuilder classes are more advanced and require more attention to make use of their capabilities.

The Query Result Mapper maps data taken out from database (from data set) into object representation (like ORM providers such as Hibernate map tables to entities). As there can be many object types that you can use for representing data set results, it is almost impossible to provide them out of the box. Mappers are powerful and thus are pluggable. You can implement your own mapper to transform the result into any type. Red Hat JBoss BPM Suite comes with the following mappers out of the box:

Each mapper is registered under the given name to allow simple lookup by name instead of referencing its class name. This is especially important when using EJB remote flavor of services where it is important to reduce the number of dependencies and thus not relying on implementation on client side. Hence, to be able to reference the QueryResultMapper class by name, use the NamedQueryMapper class, which is a part of the KIE Services API. It acts as a delegate (lazy delegate) as it looks up the actual mapper when the query is performed.

queryService.query("my query def", new NamedQueryMapper<Collection<ProcessInstanceDesc>>("ProcessInstances"), new QueryContext());

The QueryParamBuilder class provides an advanced way of building filters for data sets. By default when using a query method of the Query Service (that accepts zero or more QueryParam instances), all of these parameters will be joined with an AND operator. Therefore, all of them must match. However, that is not always the case, hence you can use QueryParamBuilder to provide filters at the time the query is issued.

The QueryParamBuilder available out of the box is used to cover default QueryParams. The default QueryParams are based on core functions, which are SQL based conditions and includes following:

The QueryParamBuilder is a simple interface that is invoked as long as its build method returns a non-null value before the query is performed. So you can build up a complex filter options that could not be simply expressed by list of QueryParams. Here is a basic implementation of QueryParamBuilder to give you a jump start to implement your own (note that, it relies on the DashBuilder Data Set API):

public class TestQueryParamBuilder implements QueryParamBuilder<ColumnFilter> {

    private Map<String, Object> parameters;
    private boolean built = false;
    public TestQueryParamBuilder(Map<String, Object> parameters) {
        this.parameters = parameters;
    }

    @Override
    public ColumnFilter build() {
        // return null if it was already invoked
        if (built) {
            return null;
        }

        String columnName = "processInstanceId";

        ColumnFilter filter = FilterFactory.OR(
                FilterFactory.greaterOrEqualsTo((Long)parameters.get("min")),
                FilterFactory.lowerOrEqualsTo((Long)parameters.get("max")));
        filter.setColumnId(columnName);

        built = true;
        return filter;
    }

}

Once you have a QueryParamBuilder implemented, you can use its instance when performing query via QueryService:

queryService.query("my query def", ProcessInstanceQueryMapper.get(), new QueryContext(), paramBuilder);

First thing you need to do is to define a data set (the view of the data you want to work with), using QueryDefinition in the KIE Services API:

SqlQueryDefinition query = new SqlQueryDefinition("getAllProcessInstances", "java:jboss/datasources/ExampleDS");
query.setExpression("select * from processinstancelog");

This is the simplest possible query definition. The constructor takes a unique name that identifies it on runtime and data source JNDI name used when performing queries on this definition. The expression is the SQL statement that builds up the view to be filtered when performing queries.

Once you create the SQL query definition, you can register it to be used later for actual queries:

queryService.registerQuery(query);

From now on, you can use this query definition to perform actual queries (or data look-ups to use terminology from data sets). Following is the basic one that collects data as is, without any filtering:

Collection<ProcessInstanceDesc> instances = queryService.query("getAllProcessInstances", ProcessInstanceQueryMapper.get(), new QueryContext());

The above query uses defaults from QueryContext(paging and sorting). However, you can change these defaults:

QueryContext ctx = new QueryContext(0, 100, "start_date", true);

Collection<ProcessInstanceDesc> instances = queryService.query("getAllProcessInstances", ProcessInstanceQueryMapper.get(), ctx);

You can perform the data filtering in the following way:

// single filter parameter
Collection<ProcessInstanceDesc> instances = queryService.query("getAllProcessInstances", ProcessInstanceQueryMapper.get(), new QueryContext(), QueryParam.likeTo(COLUMN_PROCESSID, true, "org.jboss%"));

// multiple filter parameters (AND)
Collection<ProcessInstanceDesc> instances = queryService.query("getAllProcessInstances", ProcessInstanceQueryMapper.get(), new QueryContext(),
  QueryParam.likeTo(COLUMN_PROCESSID, true, "org.jboss%"),
  QueryParam.in(COLUMN_STATUS, 1, 3));

With this mechanism, you can define what data are retrieved and how they should be fetched, without being limited by JPA provider. This also promotes the use of tailored queries for a given environment, as in most of the cases, there may be a single database used. Thus, specific features of that database can be utilized to increase performance.

Migration is always concluded with a migration report for each process instance. The migration report provides the following information:

There are some process instance migration scenarios which are not supported at the moment:

Following is an example of how to invoke the migration:

// first deploy both versions
deploymentUnitV1 = new KModuleDeploymentUnit(MIGRATION_GROUP_ID, MIGRATION_ARTIFACT_ID, MIGRATION_VERSION_V1);
deploymentService.deploy(deploymentUnitV1);

// ... version 2
deploymentUnitV2 = new KModuleDeploymentUnit(MIGRATION_GROUP_ID, MIGRATION_ARTIFACT_ID, MIGRATION_VERSION_V2);
deploymentService.deploy(deploymentUnitV2);

// next start process instance in version 1
long processInstanceId = processService.startProcess(deploymentUnitV1.getIdentifier(), "processID-V1");

// and once the instance is active it can be migrated
MigrationReport report = migrationService.migrate(deploymentUnitV1.getIdentifier(), processInstanceId, deploymentUnitV2.getIdentifier(), "processID-V2");

// as last step check if the migration finished successfully
if (report.isSuccessful()) {
    // do something
}

The deployment service stores the deployed units in memory by default. To save deployments in the data store of your choice:

public void saveDeployment(@Observes @Deploy DeploymentEvent event) {

  DeployedUnit deployedUnit = event.getDeployedUnit();

  // store deployed unit info for further needs

}

To remove a saved deployment when undeployed:

public void removeDeployment(@Observes @Undeploy DeploymentEvent event) {

  // remove deployment with ID event.getDeploymentId()

}

You can use qualifiers to instruct the CDI container which deployment service to use. Red Hat JBoss BPM Suite contains the following Deployment Services:

Note that every implementation of deployment service must have a dedicated implementation of deployment unit as the services mentioned above.