JBoss.orgCommunity Documentation

Drools Fusion User Guide


In the Drools vision of a unified behavioral modelling platform, Drools Fusion is the module responsible for enabling event processing behavior.

Before we examine Drools Fusion, we need to define some terms. The terms "Event" and "Complex Event Processing" have multiple, overloaded, and sometimes confusing definitions. The goal of this guide is not to attempt to unify all the competing definitions for these terms, but before we start describing Complex Event Processing, we need to define, in informal terms, just what we mean when the guide refers to an "Event."

In the scope of this guide:

For example, in a stock brokerage application, when a sell operation is executed, the operation causes a change of state in the domain. This change of state can be observed on several entities in the domain, such as the price of the securities that changed to match the value of the operation, the owner of the individual traded assets that change from the seller to the buyer, the balance of the accounts from both seller and buyer that are credited and debited, etc. Depending on how the domain is modeled, this change of state may be represented by a single event, multiple independent (or "atomic") events or even hierarchies of correlated events. In this guide, the term "event" refers to the record of the change on a particular piece or pieces of data within the domain.

Events have been processed by computer systems since they were first invented. Throughout computer and software the history, systems responsible for event processing have referred to event processing with different names and and have used different methodologies. It wasn't until the 1990's however, that more focused work started on Event Driven Architecture (EDA) with a more formal definition on the requirements and goals for event processing. Older messaging systems started to change to address these requirements and new systems started to be developed with the single purpose of event processing. Two approaches for event processing developed: Event Stream Processing (ESP) and Complex Event Processing (CEP).

In the begining, Event Stream Processing was focused on the capabilities of processing streams of events in (near) real time, while, in contrast, the main focus of Complex Event Processing was on the correlation and composition of atomic events into complex (compound) events. An important milestone in the development of event processing was the publication of Dr. David Luckham's book The Power of Events in 2002. In this book, Dr Luckham introduced the concept of "Complex Event Processing" and how it could be used to enhance systems that deal with events. Over the years, both approaches have converged into a common understanding and today systems implementing either approach are all referred as "CEP systems."

A brief definition of Complex Event Processing is:

In other words, CEP is about detecting and selecting the interesting events (and only these events) from an event cloud, finding their relationships and inferring new data from them and their relationships.

Event Processing use cases, in general, share several requirements and goals with Business Rules use cases. These overlapping characteristics happen both on the business side and on the technical side.

On the Business side:

From a technical perspective:

Even though they share requirements and goals, historically, Event Processing and Business Rules were separate disciplines. Implementations of each tend to focus on on one discipline or the other.

In this context, Drools Fusion is the module responsible for adding event processing capabilities into the platform.

Supporting Complex Event Processing, though, involved much more than simply understanding what an event is. CEP scenarios share several common and distiguishing characteristics:

Based on these common characteristics, Drools Fusion has defined a set of requirements to be fulfilled in order to support Complex Event Processing appropriately:

In the Drools unified platform, all features of one module are leveraged by the other modules. This means that while the above of requirements that are not fulfilled by Drools Expert, Drools Fusion is able to take advantage of Drools Expert's features such as like Pattern Matching. In the same way, all features provided by Drools Fusion are leveraged by Drools Flow (and vice-versa) making process management aware of event processing and vice-versa.

In remainder of this guide, we will describe each of the features Drools Fusion adds to the Drools unified platform. All these features are available to support different use cases in the CEP world, and you are free to select and use the ones that will help you model your business use cases.

Events, from a Drools perspective are just a special type of fact, specifically, facts that record of a significant change of state in the application domain. While all events are facts, not all facts are events. In the next few sections the guide describes the specific differences that characterize events from other facts.

An event is a fact that has thes distinguishing characteristics:

Drools supports the declaration and usage of events with both semantics: point-in-time events and interval-based events.

All events have a set of metadata associated with them. While most of the metadata values have defaults that are automatically assigned to each event when they are inserted into the working memory, it is possible to change the default on an event type basis, using the metadata tags listed below.

In the following examples, we will assume you have the following class in the application domain model:


Reasoning over time requires a reference clock. To illustrate one example, if a rule reasons over the average price of a given stock over the last 60 minutes, how does the engine know what stock price changes happened over those 60 minutes in order to calculate the average? The obvious response is: by comparing the timestamp of the events with the "current time". How the engine knows what the time is now? Again, obviously, by querying the Session Clock.

The session clock implements a strategy pattern, allowing different types of clocks to be plugged and used by the engine. This is very important because the engine may be running in a set of different scenarios that may require different clock implementations. Soem examples are:

Drools 5 provides two clock implementations out of the box. The default is the real time clock, which is based on the system clock. There is also an optional pseudo clock, which is controlled by the application.

Most CEP use cases deal with streams of events. These streams can be provided to the application in various forms, such as JMS queues, flat text files, database tables, raw sockets, or even through web service calls. Regardless of the form they may take, the streams share a common set of characteristics:

Drools generalized the concept of a stream as an "entry point" into the engine. An entry point is for Drools a gate through which facts come. The facts may be regular facts or special facts such as events.

In Drools, facts from one or more entry point (stream) or event may join with facts from the working memory. They never mix in that they never lose the reference to the entry point through which they entered the engine. This is important to remember because while you may have the same type of facts coming into the engine through several entry points, but a fact that is inserted into the engine through entry point A will never match a pattern from a entry point B, etc.

Entry points are declared implicitly in Drools by directly making use of them in rules. Referencing an entry point in a rule will cause the engine, at compile time, to identify and create the proper internal structures to support that entry point.

For example, in a banking application, transactions are fed into the system coming from streams. One of the streams contains all the transactions executed in ATM machines. If one of the rules says: a withdraw is authorized if and only if the account balance is over the requested withdraw amount, the rule would look like:


In this example, the engine compiler will identify that the pattern is tied to the entry point "ATM Stream" and will both create all the necessary structures for the rulebase to support the "ATM Stream" and will only match WithdrawRequests coming from the "ATM Stream". In this example, the rule also joins the event from the stream with a fact from the main working memory (CheckingAccount).

Now, lets look at a second rule that states that a fee of $2 must be applied to any account for which a withdraw request is placed at a bank branch:


This second rule will match events of the exact same type as the first rule (WithdrawRequest), but from two different streams. An event inserted into "ATM Stream" will never be evaluated against the pattern on the second rule, because the rule states that it is only interested in patterns coming from the "Branch Stream".

Entry points, therefore, besides being a proper abstraction for streams, are also a way to scope facts in the working memory, and a valuable tool for reducing cross products errors.

Inserting events into an entry point is equally simple. Instead of inserting events directly into the working memory, you them into the entry point as shown in the example below:


This example shows how to manually insert facts into a given entry point. Applications will usually use one of the many adapters to plug a stream end point, like a JMS queue, directly into the engine entry point without having to code the inserts manually. The Drools pipeline API has several adapters and helpers to do that as well as examples on how to do it.

Temporal reasoning is another requirement of any CEP system as one of the distinguishing characteristics of events is their strong temporal relationships.

Temporal reasoning is an extensive field of research, from its roots on Temporal Modal Logic to its more practical applications in business systems. Hundreds of papers and thesis have been written and approaches have been described for several applications. Drools takes a pragmatic and simple approach based on several sources, including these:

Note that Drools implements the Interval-based Time Event Semantics described by Allen, and represents Point-in-Time Events as Interval-based evens with duration 0 (zero).

Drools implements all (13) operators defined by Allen and also their logical complement (negation). This section details each of the operators and their parameters. The operators are:

The "during" evaluator correlates two events and matches when the current event happens during the occurrence of the event being correlated.

For example:

$eventA : EventA( this during $eventB ) 

This pattern will match if and only if $eventA starts after $eventB starts and finishes before $eventB finishes.

In other words:

$eventB.startTimestamp < $eventA.startTimestamp <= $eventA.endTimestamp < $eventB.endTimestamp 

The during operator accepts 1, 2 or 4 optional parameters:

The "includes" evaluator correlates two events and matches when the event being correlated happens during the current event. It is the symmetrical opposite of during evaluator.

Lets look at an example:

$eventA : EventA( this includes $eventB ) 

The previous pattern will match if and only if $eventB starts after $eventA starts and finishes before $eventA finishes.

In other words:

$eventA.startTimestamp < $eventB.startTimestamp <= $eventB.endTimestamp < $eventA.endTimestamp 

The includes operator accepts 1, 2 or 4 optional parameters as follow:

Rules etngines in general have a well defined method of processing data and rules and providing the application with the results. There are not many requirements on how facts should be presented to the rules engine, because in general, the processing itself is time independent. While is may a good assumption for most scenarios, it is not universally true. When the requirements include the processing of real time or near real time events, then time becomes an important variable of the reasoning process.

The following sections explain the impact of time on rules reasoning in the context of the two modes (Cloud and Stream) provided by Drools for the reasoning process.

The CLOUD processing mode is the default processing mode. Users of rules engine are familiar with this mode because it behaves in exactly the same way as any pure forward chaining rules engine, including previous versions of Drools.

When running in CLOUD mode, the engine sees all facts in the working memory, regardless of whether they are regular facts or events, as a whole. There is no notion of the flow of time, although events have a timestamp. In other words, although the engine knows that a given event was created, for instance, on January 1st 2009, at 09:35:40.767, it is not possible for the engine to determine how "old" the event is, because there is no concept of "now."

In this mode, the engine will apply its usual many-to-many pattern matching algorithm, using the rules constraints to find the matching tuples, then activate and the fire rules.

This mode does not impose any kind of additional requirements on facts. For example:

On the other hand, since there are no time-based requirements, some benefits of Fusion are also not available. For example, in CLOUD mode, it is not possible to use sliding windows, because sliding windows are based on the concept of "now" and, as we stated earlier, there is no concept of "now" in CLOUD mode.

Since there is no ordering requirement for events, it is not possible for the engine to determine when events no longer match and as so, there is no automatic life-cycle management for events. In other words, the application must explicitly retract events when they are no longer necessary, in the same way the application does with regular facts.

Cloud mode is the default execution mode for Drools, but, it is possible to change this behavior either by setting a system property, using configuration property files or by using the API. The property to be set is:

KnowledgeBaseConfiguration config = KnowledgeBaseFactory.newKnowledgeBaseConfiguration();
config.setOption( EventProcessingOption.CLOUD );

The equivalent property is:

drools.eventProcessingMode = cloud

In contrast to CLOUD mode, the STREAM processing mode is used when the application needs to process streams of events. STREAM mode adds some usage requirements, but it enables features make stream event processing possible.

The additional requirements to use STREAM mode are:

When these requirements are met, the application may enable the STREAM mode using the following API call:

KnowledgeBaseConfiguration config = KnowledgeBaseFactory.newKnowledgeBaseConfiguration();
config.setOption( EventProcessingOption.STREAM );

Or, by setting the equivalent property:

drools.eventProcessingMode = stream

When using STREAM mode, the engine understands the concepts of flow of time and "now." In other words, the engine understands how old events are based on the current timestamp as read from the Session Clock. This characteristic allows the engine to provide the following additional features to the application:

These features are explained in the following sections:

Negative patterns behave differently in STREAM mode when compared to CLOUD mode. In CLOUD mode, the engine assumes that all facts and events are known in advance (remember that there is no concept of flow of time in CLOUD mode) and so, negative patterns are evaluated immediately.

When running in STREAM mode, however, negative patterns with temporal constraints may require the engine to wait for a time period before activating a rule. The time period is automatically calculated by the engine in such a way that you do not need to perform any additional steps to achieve the desired result.

For instance:


The above rule has no temporal constraints that would require delaying the rule, and so, the rule activates immediately. The following rule, on the other hand, must wait for 10 seconds before activating, since it may take up to 10 seconds for the sprinklers to activate:


This behaviour allows the engine to keep consistency when dealing with negative patterns and temporal constraints at the same time. The previous rule will have the same effect as the following fule, but it does not give you the additional tasks of having to calculate and explicitly write the appropriate duration parameter:


Sliding Window is an approach to scope events of interest as a the ones belonging to a window of time that is constantly moving. The two most common sliding window implementations are time based windows and length based windows.

The next sections in this guide describe these implementaitons.

The classic Rete algorithm is usually executed using a single thread. Although, as confirmed in by Dr. Forgy in his development of Rete, the algorithm itself is parallelizable. The Drools implementation of the ReteOO algorithm (RETE tailored for object-oriented systems) supports coarse grained parallelization through rulebase partitioning.

When this option is enabled, the rulebase will be partitioned into several independent partitions. A pool of worker threads will be used to propagate facts through the partitions. The implementation guarantees that at most one worker thread will be executing tasks for a given partition, but that multiple partitions may be "active" at a single point in time.

Everything involving knowledgebase partitioning should be transparent, except that all working memory actions (i.e., insert/retract/modify) are executed assynchronously.

One of the benefits of running the engine in STREAM mode is that the engine can detect when an event can no longer match any rule due to its temporal constraints. When that happens, the engine can safely retract the event from the session without side effects and release any resources used by that event.

There are 2 approaches for the engine to calculate the matching window for a given event: