Chapter 8. Working With Rules

A rule file is typically a file with a .drl extension. In a DRL file you can have multiple rules, queries and functions, as well as some resource declarations like imports, globals, and attributes that are assigned and used by your rules and queries. However, you are also able to spread your rules across multiple rule files (in that case, the extension .rule is suggested, but not required) - spreading rules across files can help with managing large numbers of rules. A DRL file is simply a text file.

The overall structure of a rule file is the following:

package package-name

imports

globals

functions

queries

rules

package package-name

imports

globals

functions

queries

rules

The order in which the elements are declared is not important, except for the package name that, if declared, must be the first element in the rules file. All elements are optional, so you will use only those you need.

The working memory is a stateful object that provides temporary storage and enables manipulation of facts. The working memory includes an API that contains methods which enable access to the working memory from rule files. The available methods are:

Hard keywords are words which you cannot use when naming your domain objects, properties, methods, functions, and other elements that are used in the rule text. The hard keywords are true, false, and null.

Soft keywords can be used for naming domain objects, properties, methods, functions, and other elements. The rules engine recognizes their context and processes them accordingly.

Rule attributes can be both simple and complex properties that provide a way to influence the behavior of the rule. They are usually written as one attribute per line and can be optional to the rule. Listed below are various rule attributes:

Figure 8.1. Rule Attributes

View larger image

This is what a single line comment looks like. To create single line comments, you can use //. The parser will ignore anything in the line after the comment symbol:

rule "Testing Comments"
when
  // this is a single line comment
  eval(true) // this is a comment in the same line of a pattern
then
  // this is a comment inside a semantic code block
end

rule "Testing Comments"
when
  // this is a single line comment
  eval(true) // this is a comment in the same line of a pattern
then
  // this is a comment inside a semantic code block
end

This is what a multi-line comment looks like. This configuration comments out blocks of text, both in and outside semantic code blocks:

rule "Test Multi-Line Comments"
when
  /* this is a multi-line comment
     in the left hand side of a rule */
  eval( true )
then
  /* and this is a multi-line comment
     in the right hand side of a rule */
end

rule "Test Multi-Line Comments"
when
  /* this is a multi-line comment
     in the left hand side of a rule */
  eval( true )
then
  /* and this is a multi-line comment
     in the right hand side of a rule */
end

This is the standard error message format.

Figure 8.2. Error Message Format Example

View larger image

1st Block: This area identifies the error code.

2nd Block: Line and column information.

3rd Block: Some text describing the problem.

4th Block: This is the first context. Usually indicates the rule, function, template, or query where the error occurred. This block is not mandatory.

5th Block: Identifies the pattern where the error occurred. This block is not mandatory.

Import statements work like import statements in Java. You need to specify the fully qualified paths and type names for any objects you want to use in the rules. Red Hat JBoss BRMS automatically imports classes from the Java package of the same name, and also from the package java.lang.

In DRL files, globals represent global variables. To use globals in rules:

The from element allows you to pass a Hibernate session as a global. It also lets you pull data from a named Hibernate query.

In the following example, a static method Foo.hello() from a helper class is imported as a function. To import a method, enter the following into your DRL file:

import function my.package.Foo.hello

import function my.package.Foo.hello

Irrespective of the way the function is defined or imported, you use a function by calling it by its name, in the consequence or inside a semantic code block. This is shown below:

rule "Using a Static Function"
when
  eval(true)
then
  System.out.println(hello("Bob"));
end

rule "Using a Static Function"
when
  eval(true)
then
  System.out.println(hello("Bob"));
end

Type declarations have two main goals in the rules engine: to allow the declaration of new types, and to allow the declaration of metadata for types.

To declare a new type, the keyword declare is used, followed by the list of fields and the keyword end. A new fact must have a list of fields, otherwise the engine will look for an existing fact class in the classpath and raise an error if not found.

In this example, a new fact type called Address is used. This fact type will have three attributes: number, streetName and city. Each attribute has a type that can be any valid Java type, including any other class created by the user or other fact types previously declared:

declare Address
  number : int
  streetName : String
  city : String
end

declare Address
  number : int
  streetName : String
  city : String
end

This fact type declaration uses a Person example. dateOfBirth is of the type java.util.Date (from the Java API) and address is of the fact type Address.

declare Person
  name : String
  dateOfBirth : java.util.Date
  address : Address
end

declare Person
  name : String
  dateOfBirth : java.util.Date
  address : Address
end

To avoid using fully qualified class names, use the import statement:

import java.util.Date

declare Person
  name : String
  dateOfBirth : Date
  address : Address
end

import java.util.Date

declare Person
  name : String
  dateOfBirth : Date
  address : Address
end

When you declare a new fact type, Red Hat JBoss BRMS generates bytecode that implements a Java class representing the fact type. The generated Java class is a one-to-one Java Bean mapping of the type definition.

This is an example of a generated Java class using the Person fact type:

public class Person implements Serializable {
  private String name;
  private java.util.Date dateOfBirth;
  private Address address;

  // empty constructor
  public Person() {...}

  // constructor with all fields
  public Person(String name, Date dateOfBirth, Address address) {...}

  // if keys are defined, constructor with keys
  public Person( ...keys... ) {...}

  // getters and setters
  // equals/hashCode
  // toString
}

public class Person implements Serializable {
  private String name;
  private java.util.Date dateOfBirth;
  private Address address;

  // empty constructor
  public Person() {...}

  // constructor with all fields
  public Person(String name, Date dateOfBirth, Address address) {...}

  // if keys are defined, constructor with keys
  public Person( ...keys... ) {...}

  // getters and setters
  // equals/hashCode
  // toString
}

Since the generated class is a simple Java class, it can be used transparently in the rules like any other fact:

rule "Using a declared Type"
when
  $p : Person(name == "Bob")
then
  // Insert Mark, who is Bob's manager.
  Person mark = new Person();
  mark.setName("Mark");
  insert(mark);
end

rule "Using a declared Type"
when
  $p : Person(name == "Bob")
then
  // Insert Mark, who is Bob's manager.
  Person mark = new Person();
  mark.setName("Mark");
  insert(mark);
end

Metadata may be assigned to several different constructions in Red Hat JBoss BRMS, such as fact types, fact attributes and rules. Red Hat JBoss BRMS uses the at sign (@) to introduce metadata and it always uses the form:

@metadata_key(metadata_value)

@metadata_key(metadata_value)

The parenthesized metadata_value is optional.

Red Hat JBoss BRMS allows the declaration of any arbitrary metadata attribute. Some have special meaning to the engine, while others are available for querying at runtime. Red Hat JBoss BRMS allows the declaration of metadata both for fact types and for fact attributes. Any metadata that is declared before the attributes of a fact type are assigned to the fact type, while metadata declared after an attribute are assigned to that particular attribute.

This is an example of declaring metadata attributes for fact types and attributes. There are two metadata items declared for the fact type (@author and @dateOfCreation) and two more defined for the name attribute (@key and @maxLength). The @key metadata has no required value, and so the parentheses and the value were omitted:

import java.util.Date

declare Person
  @author(Bob)
  @dateOfCreation(01-Feb-2009)

  name : String @key @maxLength(30)
  dateOfBirth : Date
  address : Address
end

import java.util.Date

declare Person
  @author(Bob)
  @dateOfCreation(01-Feb-2009)

  name : String @key @maxLength(30)
  dateOfBirth : Date
  address : Address
end

The @position attribute can be used to declare the position of a field, overriding the default declared order. This is used for positional constraints in patterns.

This is what the @position attribute looks like in use:

declare Cheese
  name : String @position(1)
  shop : String @position(2)
  price : int @position(0)
end

declare Cheese
  name : String @position(1)
  shop : String @position(2)
  price : int @position(0)
end

Declaring an attribute as a key attribute has two major effects on generated types:

This is an example of @key declarations for a type. Red Hat JBoss BRMS generates equals() and hashCode() methods that checks the firstName and lastName attributes to determine if two instances of Person are equal to each other. It does not check the age attribute. It also generates a constructor taking firstName and lastName as parameters:

declare Person
  firstName : String @key
  lastName : String @key
  age : int
end

declare Person
  firstName : String @key
  lastName : String @key
  age : int
end

This is what creating an instance using the key constructor looks like:

Person person = new Person("John", "Doe");

Person person = new Person("John", "Doe");

Patterns support positional arguments on type declarations and are defined by the @position attribute.

Positional arguments are when you do not need to specify the field name, as the position maps to a known named field. That is, Person(name == "mark") can be rewritten as Person("mark";). The semicolon ; is important so that the engine knows that everything before it is a positional argument. You can mix positional and named arguments on a pattern by using the semicolon ; to separate them. Any variables used in a positional that have not yet been bound will be bound to the field that maps to that position.

Observe the example below:

declare Cheese
  name : String
  shop : String
  price : int
end

declare Cheese
  name : String
  shop : String
  price : int
end

The default order is the declared order, but this can be overridden using @position.

declare Cheese
  name : String @position(1)
  shop : String @position(2)
  price : int @position(0)
end

declare Cheese
  name : String @position(1)
  shop : String @position(2)
  price : int @position(0)
end

The @position annotation can be used to annotate original pojos on the classpath. Currently only fields on classes can be annotated. Inheritance of classes is supported, but not interfaces of methods.

These example patterns have two constraints and a binding. The semicolon ; is used to differentiate the positional section from the named argument section. Variables and literals and expressions using just literals are supported in positional arguments, but not variables:

Cheese("stilton", "Cheese Shop", p;)
Cheese("stilton", "Cheese Shop"; p : price)
Cheese("stilton"; shop == "Cheese Shop", p : price)
Cheese(name == "stilton"; shop == "Cheese Shop", p : price)

Cheese("stilton", "Cheese Shop", p;)
Cheese("stilton", "Cheese Shop"; p : price)
Cheese("stilton"; shop == "Cheese Shop", p : price)
Cheese(name == "stilton"; shop == "Cheese Shop", p : price)

Backward-Chaining is a feature recently added to the BRMS Engine. This process is often referred to as derivation queries, and it is not as common compared to reactive systems since BRMS is primarily reactive forward chaining. That is, it responds to changes in your data. The backward-chaining added to the engine is for product-like derivations.

Figure 8.3. Reasoning Graph

View larger image

The previous chart demonstrates a House example of transitive items. A similar reasoning chart can be created by implementing the following rules:

Red Hat JBoss BRMS allows the declaration of metadata attributes for existing types in the same way as when declaring metadata attributes for new fact types. The only difference is that there are no fields in that declaration.

This example shows how to declare metadata for an existing type:

import org.drools.examples.Person

declare Person
  @author(Bob)
  @dateOfCreation(01-Feb-2009)
end

import org.drools.examples.Person

declare Person
  @author(Bob)
  @dateOfCreation(01-Feb-2009)
end

This example shows how you can declare metadata using the fully qualified class name instead of using the import annotation:

declare org.drools.examples.Person
  @author(Bob)
  @dateOfCreation(01-Feb-2009)
end

declare org.drools.examples.Person
  @author(Bob)
  @dateOfCreation(01-Feb-2009)
end

For a declared type like the following:

declare Person
  firstName : String @key
  lastName : String @key
  age : int
end

declare Person
  firstName : String @key
  lastName : String @key
  age : int
end

The compiler will implicitly generate 3 constructors: one without parameters, one with the @key fields and one with all fields.

Person() // parameterless constructor
Person(String firstName, String lastName)
Person(String firstName, String lastName, int age)

Person() // parameterless constructor
Person(String firstName, String lastName)
Person(String firstName, String lastName, int age)

The @typesafe(BOOLEAN) annotation has been added to type declarations. By default all type declarations are compiled with type safety enabled. @typesafe(false) provides a means to override this behaviour by permitting a fall-back, to type unsafe evaluation where all constraints are generated as MVEL constraints and executed dynamically. This is useful when dealing with collections that do not have any generics or mixed type collections.

Sometimes applications need to access and handle facts from the declared types. In such cases, Red Hat JBoss BRMS provides a simplified API for the most common fact handling the application wishes to do. A declared fact belongs to the package where it is declared.

This illustrates the process of declaring a type:

package org.drools.examples

import java.util.Date

declare Address
  street : String
  city : String
  code : String
end

declare Person
  name : String
  dateOfBirth : Date
  address : Address
end

package org.drools.examples

import java.util.Date

declare Address
  street : String
  city : String
  code : String
end

declare Person
  name : String
  dateOfBirth : Date
  address : Address
end

This example illustrates the handling of declared fact types through the API:

import java.util.Date;

import org.kie.api.definition.type.FactType;
import org.kie.api.KieBase;
import org.kie.api.runtime.KieSession;

...

// Get a reference to a knowledge base with a declared type:
KieBase kbase = ...

// Get the declared FactType:
FactType personType = kbase.getFactType("org.drools.examples", "Person");

// Handle the type as necessary:
// Create instances:
Object bob = personType.newInstance();

// Set attributes values:
personType.set(bob, "name", "Bob" );
personType.set(bob, "dateOfBirth", new Date());
personType.set(bob, "address", new Address("King's Road","London","404"));

// Insert fact into a session:
KieSession ksession = ...
ksession.insert(bob);
ksession.fireAllRules();

// Read attributes:
String name = (String) personType.get(bob, "name");
Date date = (Date) personType.get(bob, "dateOfBirth");

import java.util.Date;

import org.kie.api.definition.type.FactType;
import org.kie.api.KieBase;
import org.kie.api.runtime.KieSession;

...

// Get a reference to a knowledge base with a declared type:
KieBase kbase = ...

// Get the declared FactType:
FactType personType = kbase.getFactType("org.drools.examples", "Person");

// Handle the type as necessary:
// Create instances:
Object bob = personType.newInstance();

// Set attributes values:
personType.set(bob, "name", "Bob" );
personType.set(bob, "dateOfBirth", new Date());
personType.set(bob, "address", new Address("King's Road","London","404"));

// Insert fact into a session:
KieSession ksession = ...
ksession.insert(bob);
ksession.fireAllRules();

// Read attributes:
String name = (String) personType.get(bob, "name");
Date date = (Date) personType.get(bob, "dateOfBirth");

For a list of Maven dependencies, see example Embedded jBPM Engine Dependencies. If you use Red Hat JBoss BRMS, see Embedded Drools Engine Dependencies.

The API also includes other helpful methods, like setting all the attributes at once, reading values from a Map, or reading all attributes at once, into a Map.

Type declarations support the extends keyword for inheritance. To extend a type declared in Java by a DRL declared subtype, repeat the supertype in a declare statement without any fields.

This illustrates the use of the extends annotation:

import org.people.Person

declare Person
end

declare Student extends Person
  school : String
end

declare LongTermStudent extends Student
  years : int
  course : String
end

import org.people.Person

declare Person
end

declare Student extends Person
  school : String
end

declare LongTermStudent extends Student
  years : int
  course : String
end

Traits allow you to model multiple dynamic types which do not fit naturally in a class hierarchy. A trait is an interface that can be applied (and eventually removed) to an individual object at runtime. To create a trait out of an interface, a @format(trait) annotation is added to its declaration in DRL.

declare GoldenCustomer
  @format(trait)
  // fields will map to getters/setters
  code     : String
  balance  : long
  discount : int
  maxExpense : long
end

declare GoldenCustomer
  @format(trait)
  // fields will map to getters/setters
  code     : String
  balance  : long
  discount : int
  maxExpense : long
end

In order to apply a trait to an object, the new don keyword is added:

when
  $c : Customer()
then
  GoldenCustomer gc = don($c, Customer.class);
end

when
  $c : Customer()
then
  GoldenCustomer gc = don($c, Customer.class);
end

When a core object dons a trait, a proxy class is created on the fly (one such class will be generated lazily for each core/trait class combination). The proxy instance, which wraps the core object and implements the trait interface, is inserted automatically and will possibly activate other rules. An immediate advantage of declaring and using interfaces, getting the implementation proxy for free from the engine, is that multiple inheritance hierarchies can be exploited when writing rules. The core classes, however, need not implement any of those interfaces statically, also facilitating the use of legacy classes as cores. Any object can don a trait. For efficiency reasons, however, you can add the @traitable annotation to a declared bean class to reduce the amount of glue code that the compiler will have to generate. This is optional and will not change the behavior of the engine.

This illustrates the use of the @traitable annotation:

declare Customer
  @traitable
  code    : String
  balance : long
end

declare Customer
  @traitable
  code    : String
  balance : long
end

The only connection between core classes and trait interfaces is at the proxy level. (That is, a trait is not specifically tied to a core class.) This means that the same trait can be applied to totally different objects. For this reason, the trait does not transparently expose the fields of its core object. When writing a rule using a trait interface, only the fields of the interface will be available, as usual. However, any field in the interface that corresponds to a core object field, will be mapped by the proxy class.

This example illustrates the trait interface being mapped to a field:

when
  $o: OrderItem($p : price, $code : custCode)
  $c: GoldenCustomer(code == $code, $a : balance, $d: discount)
then
  $c.setBalance( $a - $p*$d );
end

when
  $o: OrderItem($p : price, $code : custCode)
  $c: GoldenCustomer(code == $code, $a : balance, $d: discount)
then
  $c.setBalance( $a - $p*$d );
end

Hidden fields are fields in the core class not exposed by the interface.

The two-part proxy has been developed to deal with soft and hidden fields which are not processed intuitively. Internally, proxies are formed by a proper proxy and a wrapper. The former implements the interface, while the latter manages the core object fields, implementing a name/value map to supports soft fields. The proxy uses both the core object and the map wrapper to implement the interface, as needed.

The wrapper provides a looser form of typing when writing rules. However, it has also other uses. The wrapper is specific to the object it wraps, regardless of how many traits have been attached to an object. All the proxies on the same object will share the same wrapper. Additionally, the wrapper contains a back-reference to all proxies attached to the wrapped object, effectively allowing traits to see each other.

This is an example of using the wrapper:

when
  $sc : GoldenCustomer($c : code, // hard getter
                       $maxExpense : maxExpense > 1000 // soft getter)
then
  $sc.setDiscount( ... ); // soft setter
end

when
  $sc : GoldenCustomer($c : code, // hard getter
                       $maxExpense : maxExpense > 1000 // soft getter)
then
  $sc.setDiscount( ... ); // soft setter
end

This illustrates a wrapper in use with the isA annotation:

$sc : GoldenCustomer($maxExpense : maxExpense > 1000, this isA "SeniorCustomer")

$sc : GoldenCustomer($maxExpense : maxExpense > 1000, this isA "SeniorCustomer")

The business logic may require that a trait is removed from a wrapped object. There are two ways to do so:

This is what the timer attribute looks like:

timer(int: INITIAL_DELAY REPEAT_INTERVAL?)
timer(int: 30s)
timer(int: 30s 5m)

timer(cron: CRON_EXPRESSION)
timer(cron:* 0/15 * * * ?)

timer(int: INITIAL_DELAY REPEAT_INTERVAL?)
timer(int: 30s)
timer(int: 30s 5m)

timer(cron: CRON_EXPRESSION)
timer(cron:* 0/15 * * * ?)

The following timers are available in Red Hat JBoss BRMS:

A rule controlled by a timer becomes active when it matches, and once for each individual match. Its consequence is executed repeatedly, according to the timer’s settings. This stops as soon as the condition doesn’t match any more.

Consequences are executed even after control returns from a call to fireUntilHalt. Moreover, the Engine remains reactive to any changes made to the Working Memory. For instance, removing a fact that was involved in triggering the timer rule’s execution causes the repeated execution to terminate, or inserting a fact so that some rule matches will cause that rule to fire. But the Engine is not continually active, only after a rule fires, for whatever reason. Thus, reactions to an insertion done asynchronously will not happen until the next execution of a timer-controlled rule.

Disposing a session puts an end to all timer activity.

This is what the Cron timer looks like:

rule "Send SMS every 15 minutes"
  timer (cron:* 0/15 * * * ?)
when
  $a : Alarm(on == true)
then
  channels["sms"].insert(new Sms($a.mobileNumber, "The alarm is still on");
end

rule "Send SMS every 15 minutes"
  timer (cron:* 0/15 * * * ?)
when
  $a : Alarm(on == true)
then
  channels["sms"].insert(new Sms($a.mobileNumber, "The alarm is still on");
end

Calendars are used to control when rules can fire. Red Hat JBoss BRMS uses the Quartz calendar.

This is what the Quartz calendar looks like:

Calendar weekDayCal = QuartzHelper.quartzCalendarAdapter(org.quartz.Calendar quartzCal)

Calendar weekDayCal = QuartzHelper.quartzCalendarAdapter(org.quartz.Calendar quartzCal)

The Left Hand Side (LHS) is a common name for the conditional part of the rule. It consists of zero or more conditional elements. If the LHS is empty, it will be considered as a condition element that is always true and it will be activated once, when a new WorkingMemory session is created.

Conditional elements work on one or more patterns. The most common conditional element is and. It is implicit when you have multiple patterns in the LHS of a rule that is not connected in any way.

This is what a rule without a conditional element looks like:

rule "no CEs"
when
  // empty
then
  ... // actions (executed once)
end

// The above rule is internally rewritten as:

rule "eval(true)"
when
  eval( true )
then
  ... // actions (executed once)
end

rule "no CEs"
when
  // empty
then
  ... // actions (executed once)
end

// The above rule is internally rewritten as:

rule "eval(true)"
when
  eval( true )
then
  ... // actions (executed once)
end

This is what a pattern looks like:

rule "Two unconnected patterns"
when
  Pattern1()
  Pattern2()
then
    ... // actions
end

// The above rule is internally rewritten as:

rule "Two and connected patterns"
when
  Pattern1()
  and Pattern2()
then
  ... // actions
end

rule "Two unconnected patterns"
when
  Pattern1()
  Pattern2()
then
    ... // actions
end

// The above rule is internally rewritten as:

rule "Two and connected patterns"
when
  Pattern1()
  and Pattern2()
then
  ... // actions
end

A pattern matches against a fact of the given type. The type need not be the actual class of some fact object. Patterns may refer to superclasses or even interfaces, thereby potentially matching facts from many different classes. The constraints are defined inside parentheses.

Patterns can be bound to a matching object. This is accomplished using a pattern binding variable such as $p.

This is what pattern binding using a variable looks like:

rule ...
when
  $p : Person()
then
  System.out.println("Person " + $p);
end

rule ...
when
  $p : Person()
then
  System.out.println("Person " + $p);
end

A constraint is an expression that returns true or false. For example, you can have a constraint that states "five is smaller than six".

Any bean property can be used directly. A bean property is exposed using a standard Java bean getter: a method getMyProperty() (or isMyProperty() for a primitive boolean) which takes no arguments and return something.

Red Hat JBoss BRMS uses the standard JDK Introspector class to do this mapping, so it follows the standard Java bean specification.

This is what the bean property looks like:

Person(age == 50)

// this is the same as:
Person(getAge() == 50)

Person(age == 50)

// this is the same as:
Person(getAge() == 50)

When working with POJOs, a fallback method is applied. If the getter of a property cannot be found, the compiler will resort to using the property name as a method name and without arguments. Nested properties are also indexed.

This is what happens when a fallback is implemented:

Person(age == 50)

// If Person.getAge() does not exists, this falls back to:
Person(age() == 50)

Person(age == 50)

// If Person.getAge() does not exists, this falls back to:
Person(age() == 50)

This is what it looks like as a nested property:

Person(address.houseNumber == 50)

// this is the same as:
Person(getAddress().getHouseNumber() == 50)

Person(address.houseNumber == 50)

// this is the same as:
Person(getAddress().getHouseNumber() == 50)

The comma character (,) is used to separate constraint groups. It has implicit and connective semantics.

The comma operator is used at the top-level constraint as it makes them easier to read and the engine will be able to optimize them.

The following illustrates comma-separated scenarios in implicit and connective semantics:

// Person is at least 50 and weighs at least 80 kg.
Person(age > 50, weight > 80)

// Person is at least 50 and weighs at least 80 kg.
Person(age > 50, weight > 80)

// Person is at least 50, weighs at least 80 kg and is taller than 2 meter.
Person(age > 50, weight > 80, height > 2)

// Person is at least 50, weighs at least 80 kg and is taller than 2 meter.
Person(age > 50, weight > 80, height > 2)

You can bind properties to variables in Red Hat JBoss BRMS. It allows for faster execution and performance.

This is an example of a property bound to a variable:

// Two people of the same age:
Person($firstAge : age) // binding
Person(age == $firstAge) // constraint expression

// Two people of the same age:
Person($firstAge : age) // binding
Person(age == $firstAge) // constraint expression

// Not recommended:
Person($age : age * 2 < 100)

// Not recommended:
Person($age : age * 2 < 100)

// Recommended (separates bindings and constraint expressions):
Person(age * 2 < 100, $age : age)

// Recommended (separates bindings and constraint expressions):
Person(age * 2 < 100, $age : age)

You can unify arguments across several properties. While positional arguments are always processed with unification, the unification symbol, :=, exists for named arguments.

This is what unifying two arguments looks like:

Person($age := age)
Person($age := age)

Person($age := age)
Person($age := age)

This feature allows the pattern matching to only react to modification of properties actually constrained or bound inside of a given pattern. This helps with performance and recursion and avoid artificial object splitting.

Using these listeners means you do not need to implement the no-loop attribute to avoid an infinite recursion. The engine recognizes that the pattern matching is done on the property while the RHS of the rule modifies other the properties. On Java classes, you can also annotate any method to say that its invocation actually modifies other properties.

Annotating a pattern with @watch allows you to modify the inferred set of properties for which that pattern will react. The properties named in the @watch annotation are added to the ones automatically inferred. You can explicitly exclude one or more of them by beginning their name with a ! and to make the pattern to listen for all or none of the properties of the type used in the pattern respectively with the wildcards * and !*.

This is the @watch annotation in a rule’s LHS:

// Listens for changes on both firstName (inferred) and lastName:
Person(firstName == $expectedFirstName) @watch(lastName)

// Listens for all the properties of the Person bean:
Person(firstName == $expectedFirstName) @watch(*)

// Listens for changes on lastName and explicitly exclude firstName:
Person(firstName == $expectedFirstName) @watch(lastName, !firstName)

// Listens for changes on all the properties except the age one:
Person(firstName == $expectedFirstName) @watch(*, !age)

// Listens for changes on both firstName (inferred) and lastName:
Person(firstName == $expectedFirstName) @watch(lastName)

// Listens for all the properties of the Person bean:
Person(firstName == $expectedFirstName) @watch(*)

// Listens for changes on lastName and explicitly exclude firstName:
Person(firstName == $expectedFirstName) @watch(lastName, !firstName)

// Listens for changes on all the properties except the age one:
Person(firstName == $expectedFirstName) @watch(*, !age)

You can enable @watch by default or completely disallow it using the on option of the KnowledgeBuilderConfiguration. This new PropertySpecificOption can have one of the following 3 values:

Alternatively, you can use the drools.propertySpecific system property. For example, if you use Red Hat JBoss EAP, add the property into EAP_HOME/standalone/configuration/standalone.xml:

<system-properties>
  ...
  <property name="drools.propertySpecific" value="DISABLED"/>
  ...
</system-properties>

<system-properties>
  ...
  <property name="drools.propertySpecific" value="DISABLED"/>
  ...
</system-properties>

This element evaluates to true when all facts that match the first pattern match all the remaining patterns. It is a scope delimiter. Therefore, it can use any previously bound variable, but no variable bound inside it will be available for use outside of it.

forall can be nested inside other CEs. For instance, forall can be used inside a not CE. Only single patterns have optional parentheses, so with a nested forall parentheses must be used.

The conditional element from enables users to specify an arbitrary source for data to be matched by LHS patterns. This allows the engine to reason over data not in the Working Memory. The data source could be a sub-field on a bound variable or the results of a method call. It is a powerful construction that allows out of the box integration with other application components and frameworks. One common example is the integration with data retrieved on-demand from databases using hibernate named queries.

The expression used to define the object source is any expression that follows regular MVEL syntax. Therefore, it allows you to easily use object property navigation, execute method calls and access maps and collections elements.

The conditional element collect allows rules to reason over a collection of objects obtained from the given source or from the working memory. In First Oder Logic terms this is the cardinality quantifier.

The result pattern of collect can be any concrete class that implements the java.util.Collection interface and provides a default no-arg public constructor. You can use Java collections like ArrayList, LinkedList and HashSet or your own class, as long as it implements the java.util.Collection interface and provide a default no-arg public constructor.

Variables bound before the collect CE are in the scope of both source and result patterns and therefore you can use them to constrain both your source and result patterns. Any binding made inside collect is not available for use outside of it.

The conditional element accumulate is a more flexible and powerful form of the collect element and allows a rule to iterate over a collection of objects while executing custom actions for each of the elements. The accumulate element returns a result object.

The element accumulate supports the use of predefined accumulate functions, as well as the use of inline custom code. However, using inline custom code is not recommended, as it is harder to maintain and might lead to code duplication. On the other hand, accumulate functions are easier to test and reuse.

The conditional element accumulate supports multiple different syntaxes. The preferred is the top-level syntax (as noted below), but all other syntaxes are supported as well for backward compatibility.

Top-Level accumulate Syntax

The top-level accumulate syntax is the most compact and flexible. The simplified syntax is as follows:

accumulate(SOURCE_PATTERN ; FUNCTIONS [;CONSTRAINTS])

accumulate(SOURCE_PATTERN ; FUNCTIONS [;CONSTRAINTS])

rule "Raise Alarm"
when
  $s : Sensor()
  accumulate(Reading(sensor == $s, $temp : temperature);
    $min : min($temp),
    $max : max($temp),
    $avg : average($temp);
    $min < 20, $avg > 70)
then
  // raise the alarm
end

rule "Raise Alarm"
when
  $s : Sensor()
  accumulate(Reading(sensor == $s, $temp : temperature);
    $min : min($temp),
    $max : max($temp),
    $avg : average($temp);
    $min < 20, $avg > 70)
then
  // raise the alarm
end

In the example above, min, max, and average are accumulate functions that calculate the minimum, maximum, and average temperature values over all the readings for each sensor.

Built-in accumulate Functions

Only user-defined custom accumulate functions have to be explicitly imported. The following accumulate functions are imported automatically by the engine:

These common functions accept any expression as an input. For instance, if you want to calculate an average profit on all items of an order, you can write a rule using the average function as follows:

rule "Average Profit"
when
  $order : Order()
  accumulate(
    OrderItem(order == $order, $cost : cost, $price : price);
    $avgProfit : average(1 - $cost / $price))
then
  // average profit for $order is $avgProfit
end

rule "Average Profit"
when
  $order : Order()
  accumulate(
    OrderItem(order == $order, $cost : cost, $price : price);
    $avgProfit : average(1 - $cost / $price))
then
  // average profit for $order is $avgProfit
end

Accumulate Functions Pluggability

Accumulate functions are all pluggable; if needed, custom and domain-specific functions can be easily added to the engine and rules can start to use them without any restrictions.

To implement a new accumulate function, create a Java class that implements the org.kie.api.runtime.rule.AccumulateFunction interface. To use the function in the rules, import it using the import accumulate statement:

import accumulate CLASS_NAME FUNCTION_NAME

import accumulate CLASS_NAME FUNCTION_NAME

import accumulate some.package.VarianceFunction variance

rule "Calculate Variance"
when
  accumulate(Test($s : score), $v : variance($s))
then
  // variance of the test scores is $v
end

import accumulate some.package.VarianceFunction variance

rule "Calculate Variance"
when
  accumulate(Test($s : score), $v : variance($s))
then
  // variance of the test scores is $v
end

import java.io.Externalizable;
import java.io.IOException;
import java.io.ObjectInput;
import java.io.ObjectOutput;
import java.io.Serializable;

import org.kie.api.runtime.rule.AccumulateFunction;

/**
 * Implementation of an accumulator capable of calculating average values.
 */
public class AverageAccumulateFunction implements AccumulateFunction {

  public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException {}

  public void writeExternal(ObjectOutput out) throws IOException {}

  public static class AverageData implements Externalizable {
    public int    count = 0;
    public double total = 0;

    public AverageData() {}

    public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException {
      count = in.readInt();
      total = in.readDouble();
    }

    public void writeExternal(ObjectOutput out) throws IOException {
      out.writeInt(count);
      out.writeDouble(total);
    }
  }

  /* (non-Javadoc)
   * @see org.kie.base.accumulators.AccumulateFunction#createContext()
   */
  public Serializable createContext() {
    return new AverageData();
  }

  /* (non-Javadoc)
   * @see org.kie.base.accumulators.AccumulateFunction#init(java.lang.Object)
   */
  public void init(Serializable context) throws Exception {
    AverageData data = (AverageData) context;
    data.count = 0;
    data.total = 0;
  }

  /* (non-Javadoc)
   * @see org.kie.base.accumulators.AccumulateFunction#accumulate(java.lang.Object,
   * java.lang.Object)
   */
  public void accumulate(Serializable context, Object value) {
    AverageData data = (AverageData) context;
    data.count++;
    data.total += ((Number) value).doubleValue();
  }

  /* (non-Javadoc)
   * @see org.kie.base.accumulators.AccumulateFunction#reverse(java.lang.Object,
   * java.lang.Object)
   */
  public void reverse(Serializable context, Object value) throws Exception {
    AverageData data = (AverageData) context;
    data.count--;
    data.total -= ((Number) value).doubleValue();
  }

  /* (non-Javadoc)
   * @see org.kie.base.accumulators.AccumulateFunction#getResult(java.lang.Object)
   */
  public Object getResult(Serializable context) throws Exception {
    AverageData data = (AverageData) context;
    return new Double(data.count == 0 ? 0 : data.total / data.count);
  }

  /* (non-Javadoc)
   * @see org.kie.base.accumulators.AccumulateFunction#supportsReverse()
   */
  public boolean supportsReverse() {
    return true;
  }

  /**
   * {@inheritDoc}
   */
  public Class< ? > getResultType() {
    return Number.class;
  }
}

import java.io.Externalizable;
import java.io.IOException;
import java.io.ObjectInput;
import java.io.ObjectOutput;
import java.io.Serializable;

import org.kie.api.runtime.rule.AccumulateFunction;

/**
 * Implementation of an accumulator capable of calculating average values.
 */
public class AverageAccumulateFunction implements AccumulateFunction {

  public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException {}

  public void writeExternal(ObjectOutput out) throws IOException {}

  public static class AverageData implements Externalizable {
    public int    count = 0;
    public double total = 0;

    public AverageData() {}

    public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException {
      count = in.readInt();
      total = in.readDouble();
    }

    public void writeExternal(ObjectOutput out) throws IOException {
      out.writeInt(count);
      out.writeDouble(total);
    }
  }

  /* (non-Javadoc)
   * @see org.kie.base.accumulators.AccumulateFunction#createContext()
   */
  public Serializable createContext() {
    return new AverageData();
  }

  /* (non-Javadoc)
   * @see org.kie.base.accumulators.AccumulateFunction#init(java.lang.Object)
   */
  public void init(Serializable context) throws Exception {
    AverageData data = (AverageData) context;
    data.count = 0;
    data.total = 0;
  }

  /* (non-Javadoc)
   * @see org.kie.base.accumulators.AccumulateFunction#accumulate(java.lang.Object,
   * java.lang.Object)
   */
  public void accumulate(Serializable context, Object value) {
    AverageData data = (AverageData) context;
    data.count++;
    data.total += ((Number) value).doubleValue();
  }

  /* (non-Javadoc)
   * @see org.kie.base.accumulators.AccumulateFunction#reverse(java.lang.Object,
   * java.lang.Object)
   */
  public void reverse(Serializable context, Object value) throws Exception {
    AverageData data = (AverageData) context;
    data.count--;
    data.total -= ((Number) value).doubleValue();
  }

  /* (non-Javadoc)
   * @see org.kie.base.accumulators.AccumulateFunction#getResult(java.lang.Object)
   */
  public Object getResult(Serializable context) throws Exception {
    AverageData data = (AverageData) context;
    return new Double(data.count == 0 ? 0 : data.total / data.count);
  }

  /* (non-Javadoc)
   * @see org.kie.base.accumulators.AccumulateFunction#supportsReverse()
   */
  public boolean supportsReverse() {
    return true;
  }

  /**
   * {@inheritDoc}
   */
  public Class< ? > getResultType() {
    return Number.class;
  }
}

Alternative Syntax

Previous accumulate syntaxes are still supported for backward compatibility.

In case the rule uses a single accumulate function on a given accumulate element, you can add a pattern for the result object and use the from keyword to link it to the accumulate result. See the following example:

rule "Apply 10% Discount on Orders over US $100.00"
when
  $order : Order()
  $total : Number(doubleValue > 100)
    from accumulate(OrderItem(order == $order, $value : value), sum($value))
then
  # apply discount on $order
end

rule "Apply 10% Discount on Orders over US $100.00"
when
  $order : Order()
  $total : Number(doubleValue > 100)
    from accumulate(OrderItem(order == $order, $value : value), sum($value))
then
  # apply discount on $order
end

In this example, the element accumulate uses only one function – sum. In this case, it is possible to write a pattern for the result type of the accumulate function with the constraints inside.

accumulate with Inline Custom Code

Instead of using the accumulate functions, you can define inline custom code.

The general syntax of the accumulate with inline custom code is as follows:

RESULT_PATTERN from accumulate(
	SOURCE_PATTERN,
	init(INIT_CODE),
	action(ACTION_CODE),
	reverse(REVERSE_CODE),
	result(RESULT_EXPRESSION))

RESULT_PATTERN from accumulate(
	SOURCE_PATTERN,
	init(INIT_CODE),
	action(ACTION_CODE),
	reverse(REVERSE_CODE),
	result(RESULT_EXPRESSION))

rule "Apply 10% Discount on Orders over US $100.00"
when
  $order : Order()
  $total : Number(doubleValue > 100)
    from accumulate(OrderItem(order == $order, $value : value),
      init(double total = 0;),
      action(total += $value;),
      reverse(total -= $value;),
      result(total))
then
  # apply discount on $order
end

rule "Apply 10% Discount on Orders over US $100.00"
when
  $order : Order()
  $total : Number(doubleValue > 100)
    from accumulate(OrderItem(order == $order, $value : value),
      init(double total = 0;),
      action(total += $value;),
      reverse(total -= $value;),
      result(total))
then
  # apply discount on $order
end

In this example, the engine executes the INIT_CODE for each Order in the working memory, initializing the total variable to zero. The engine then iterates over all OrderItem objects for that Order, executing the action for each one. After the iteration, the engine returns the value corresponding to the RESULT_EXPRESSION (in this case, a value of the total variable). Finally, the engine tries to match the result with the Number pattern. If the doubleValue is greater than 100, the rule fires.

The example is using Java programming language as a semantic dialect. In this case, a semicolon as a statement delimiter is mandatory in the init, action, and reverse code blocks. However, since the result is an expression, it does not require a semicolon. If you want to use any other dialect, note that you have to observe the principles of its specific syntax.

Custom Objects

The accumulate conditional element can be used to execute any action on source objects. The following example instantiates and populates a custom object:

rule "accumulate Using Custom Objects"
when
  $person : Person($likes : likes)
  $cheesery : Cheesery(totalAmount > 100)
    from accumulate($cheese : Cheese(type == $likes),
      init(Cheesery cheesery = new Cheesery();),
      action(cheesery.addCheese($cheese);),
      reverse(cheesery.removeCheese($cheese);),
      result(cheesery));
then
  // do something
end

rule "accumulate Using Custom Objects"
when
  $person : Person($likes : likes)
  $cheesery : Cheesery(totalAmount > 100)
    from accumulate($cheese : Cheese(type == $likes),
      init(Cheesery cheesery = new Cheesery();),
      action(cheesery.addCheese($cheese);),
      reverse(cheesery.removeCheese($cheese);),
      result(cheesery));
then
  // do something
end

The conditional element eval is essentially a catch-all which allows any semantic code (that returns a primitive boolean) to be executed. This code can refer to variables that were bound in the LHS of the rule, and functions in the rule package. Overuse of eval reduces the declarativeness of your rules and can result in a poorly performing engine. While eval can be used anywhere in the patterns, the best practice is to add it as the last conditional element in the LHS of a rule.

Evals cannot be indexed and thus are not as efficient as field constraints. However this makes them ideal for being used when functions return values that change over time, which is not allowed within field constraints.

This is what eval looks like in use:

p1 : Parameter()
p2 : Parameter()
eval(p1.getList().containsKey( p2.getItem()))

p1 : Parameter()
p2 : Parameter()
eval(p1.getList().containsKey( p2.getItem()))

p1 : Parameter()
p2 : Parameter()
// call function isValid in the LHS
eval(isValid( p1, p2))

p1 : Parameter()
p2 : Parameter()
// call function isValid in the LHS
eval(isValid( p1, p2))

The Right Hand Side (RHS) is a common name for the consequence part of a rule. The main purpose of the RHS is to insert, retract (delete), or modify working memory data. The RHS usually contains a list of actions to be executed and should be kept small, thus keeping it declarative and readable.

See the following list of the RHS convenience methods:

For more information, see Section 8.2.1, “Accessing Working Memory”.

We iterate over the returned QueryResults using a standard for loop. Each element is a QueryResultsRow which we can use to access each of the columns in the tuple. These columns can be accessed by bound declaration name or index position:

QueryResults results = ksession.getQueryResults("people over the age of 30");
System.out.println("we have " + results.size() + " people over the age  of 30");

System.out.println("These people are are over 30:");

for (QueryResultsRow row : results) {
  Person person = (Person) row.get("person");
  System.out.println(person.getName() + "\n");
}

QueryResults results = ksession.getQueryResults("people over the age of 30");
System.out.println("we have " + results.size() + " people over the age  of 30");

System.out.println("These people are are over 30:");

for (QueryResultsRow row : results) {
  Person person = (Person) row.get("person");
  System.out.println(person.getName() + "\n");
}

Queries can call other queries. This combined with optional query arguments provides derivation query style backward chaining. Positional and named syntax is supported for arguments. It is also possible to mix both positional and named, but positional must come first, separated by a semi colon. Literal expressions can be passed as query arguments, but you cannot mix expressions with variables.

Red Hat JBoss BRMS supports unification for derivation queries. This means that arguments are optional. It is possible to call queries from Java leaving arguments unspecified using the static field org.drools.runtime.rule.Variable.v. You must use v and not an alternative instance of Variable. These are referred to as out arguments.

Queries are used to retrieve fact sets based on patterns, as they are used in rules. Patterns may make use of optional parameters. Queries can be defined in the Knowledge Base, from where they are called up to return the matching results. While iterating over the result collection, any identifier bound in the query can be used to access the corresponding fact or fact field by calling the get method with the binding variable’s name as its argument. If the binding refers to a fact object, its FactHandle can be retrieved by calling getFactHandle, again with the variable’s name as the parameter. Illustrated below is a query example:

QueryResults results = ksession.getQueryResults("my query", new Object[] {"string"});
for (QueryResultsRow row : results) {
  System.out.println(row.get("varName"));
}

QueryResults results = ksession.getQueryResults("my query", new Object[] {"string"});
for (QueryResultsRow row : results) {
  System.out.println(row.get("varName"));
}

Invoking queries and processing the results by iterating over the returned set is not a good way to monitor changes over time.

To alleviate this, Red Hat JBoss BRMS provides live queries, which have a listener attached instead of returning an iterable result set. These live queries stay open by creating a view and publishing change events for the contents of this view. To activate, start your query with parameters and listen to changes in the resulting view. The dispose method terminates the query and discontinues this reactive scenario.

The DSL editor provides a tabular view of the mapping of Language to Rule Expressions. The Language Expression feeds the content assistance for the rule editor so that it can suggest Language Expressions from the DSL configuration. The rule editor loads the DSL configuration when the rule resource is loaded for editing.

DSLs can serve as a layer of separation between rule authoring (and rule authors) and the technical intricacies resulting from the modeling of domain object and the rule engine’s native language and methods. A DSL hides implementation details and focuses on the rule logic proper. DSL sentences can also act as "templates" for conditional elements and consequence actions that are used repeatedly in your rules, possibly with minor variations. You may define DSL sentences as being mapped to these repeated phrases, with parameters providing a means for accommodating those variations.

[when]Something is {colour}=Something(colour=="{colour}")

[when]Something is {colour}=Something(colour=="{colour}")

[when] indicates the scope of the expression (that is, whether it is valid for the LHS or the RHS of a rule).

The part after the bracketed keyword is the expression that you use in the rule.

The part to the right of the equal sign (=) is the mapping of the expression into the rule language. The form of this string depends on its destination, RHS or LHS. If it is for the LHS, then it ought to be a term according to the regular LHS syntax; if it is for the RHS then it might be a Java statement.

Whenever the DSL parser matches a line from the rule file written in the DSL with an expression in the DSL definition, it performs three steps of string manipulation:

The DSL compiler transforms DSL rule files line by line. If you do not wish for this to occur, ensure that the captures are surrounded by characteristic text (words or single characters). As a result, the matching operation done by the parser plucks out a substring from somewhere within the line. In the example below, quotes are used as distinctive characters. The characters that surround the capture are not included during interpolation, just the contents between them.

DSL expressions can be chained together one one line to be used at once. It must be clear where one ends and the next one begins and where the text representing a parameter ends. Otherwise you risk getting all the text until the end of the line as a parameter value. The DSL expressions are tried, one after the other, according to their order in the DSL definition file. After any match, all remaining DSL expressions are investigated, too.