JBoss.orgCommunity Documentation

Chapter 5. Drools Flow API

5.1. Knowledge Base
5.2. Session
5.3. Events

The Drools Flow API should be used to (1) create a knowledge base that contains your process definitions, and to (2) create a session to start new process instances, signal existing ones, register listeners, etc.

Our knowledge-based API allows you to first create one Knowledge Base that contains all the necessary knowledge and can be reused across sessions. This knowledge base includes all your process definitions (and other knowledge types like for example rules). The following code snippet shows how to create a Knowledge Base consisting of only one process definition, using a Knowledge Builder to add the resource (from the classpath in this case).

KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
kbuilder.add(ResourceFactory.newClassPathResource("MyProcess.rf"), ResourceType.DRF);
KnowledgeBase kbase = kbuilder.newKnowledgeBase();

Note that the knowledge-based API allows users to add different types of resources, such as processes and rules, in almost identical ways into the same Knowledge Base. This enables a user who knows how to use Drools Flow to start using Drools Fusion almost instantaneously, and even to integrate these different types of Knowledge.

Next, you should create a session to interact with the engine. The following code snippet shows how easy it is to create a session based on the earlier created Knowledge Base, and to start a process (by id).

StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();
ProcessInstance processInstance = ksession.startProcess("com.sample.MyProcess");

The ProcessRuntime interface defines all the session methods for interacting with processes, as shown below. Consult the JavaDocs to get a detailed explanation for each of the methods.

ProcessInstance startProcess(String processId);
ProcessInstance startProcess(String processId, Map<String, Object> parameters);
void signalEvent(String type, Object event);
void signalEvent(String type, Object event, long processInstanceId);
Collection<ProcessInstance> getProcessInstances();
ProcessInstance getProcessInstance(long id);
void abortProcessInstance(long id);
WorkItemManager getWorkItemManager();

Both the stateful and stateless knowledge sessions provide methods for registering and removing listeners. ProcessEventListener objects can be used to listen to process-related events, like starting or completing a process, entering and leaving a node, etc. Below, the different methods of a ProcessEventListener are shown. An event object provides access to related information, like the process instance and node instance linked to the event.

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 );

}

An audit log can be created based on the information provided by these process listeners. We provide various default logger implementations:

The KnowledgeRuntimeLoggerFactory lets you add a logger to your session, as shown below. When creating a console logger, the knowledge session for which the logger needs to be created must be passed as an argument. The file logger also requires the name of the log file to be created, and the threaded file logger requires the interval (in milliseconds) after which the events should be saved.

KnowledgeRuntimeLogger logger =
    KnowledgeRuntimeLoggerFactory.newFileLogger( ksession, "test" );
// add invocations to the process engine here,
// e.g. ksession.startProcess(processId);
...
logger.close();

The log file can be opened in Eclipse, using the Audit View in the Drools Eclipse plugin, where the events are visualized as a tree. Events that occur between the before and after event are shown as children of that event. The following screenshot shows a simple example, where a process is started, resulting in the activation of the Start node, an Action node and an End node, after which the process was completed.