JBoss Drools – Getting started

This post will be about me getting to grips with JBoss Drools. The reasoning behind it is: SAP bought out my company’s current rules engine and Drools is one alternative we will be looking into as soon as someone has the skills to get a proof of concept up.

Although there seems to be a fair amount of documentation, I always find it helps having walked through examples, which is what I am going to do here.Drools on first glance can be quite daunting, it is made up of :

Drools Expert (rule engine)
Being a developer this is where I will begin, the actual rules and implementation of them.

The other parts I’ll get to later are:
Drools Guvnor (BRMS/BPMS)
Drools Flow (process/workflow)
Drools Fusion (event processing/temporal reasoning)
Drools Planner (automated planning)

So to begin.
For start, I just want to get my feet wet, I download only the Eclipse plugin and the binaries

Need to install the Eclipse plugin, used the update site. Unzip the binaries to a directory and withing the Eclipse plugin settings point to that directory.

The eclipse plugin will allow you to create a Drools Project and that includes the “Drools Library”, but if you are using maven you need to point to the JBoss release repo for the Drools dependencies, The KnowledgeRuntimeLoggerFactory needs XStream which you can just get from the standard maven repo. Below is my POM:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
 <modelversion>4.0.0</modelVersion>
 <groupId>javaitzen.drools</groupId>
 <artifactid>LearningToDrool</artifactId>
 <version>0.0.1-SNAPSHOT</version>
 <build>
  <plugins>
   <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
     <source>1.6</source>
     <target>1.6</target>
    </configuration>
   </plugin>
  </plugins>
 </build>
 <properties>
  <drools.version>5.1.1</drools.version>
 </properties>
 <repositories>
  <repository>
   <name>JBoss</name>
   <id>JBoss</id>
   <url>http://repository.jboss.org/nexus/content/groups/public-jboss/</url>
  </repository>
 </repositories>
 <dependencies>
  <dependency>
   <groupId>org.drools</groupId>
   <artifactId>drools-core</artifactId>
   <version>${drools.version}</version>
  </dependency>
  <dependency>
   <groupId>org.drools</groupId>
   <artifactid>drools-compiler</artifactId>
   <version>${drools.version}</version>
  </dependency>
  <dependency>
   <groupId>org.drools</groupId>
   <artifactId>drools-api</artifactId>
   <version>${drools.version}</version>
  </dependency>
  <dependency>
   <groupId>com.thoughtworks.xstream</groupId>
   <artifactId>xstream</artifactId>
   <version>1.3.1</version>
  </dependency>
  <dependency>
   <groupId>junit</groupId>
   <artifactId>junit</artifactId>
   <version>4.8.1</version>
   <scope>test</scope>
  </dependency>
 </dependencies>
 
</project>

To add a rule, on src/main/rules, Right click -> New -> Other… Drools/Rule Resource, be sure to choose the “individual rule”. This leaves you with an empty drl file:

package javaitzen.drools.rules
 
rule "A stand alone rule"
  
 when
  #conditions
 then 
  #actions  
end

To understand and use the rule language, I read the Drools Documentation and the examples project.
What actually took me a little to grasp, was the basic syntax and how objects were handled in the rules and I did struggle to find anything that actually explains it simply so I will give it a shot.

A note on variable names.. they do not need to have the ‘$’ but it was used in the example and without it quickly gets quite confusing.

Now to step through the parts of a rule:

package javaitzen.drools.rules
 
import javaitzen.drools.RoolVO
 
rule "Basic Rule"
  
 when
 $vo : RoolVO( stringValue == "Learning to drool", 
                      $booleanVal : booleanValue )
 eval( $booleanVal )
 then 
        System.out.println( "First Rule" ); 
 $vo.setStringValue("Done."); 
end

The package, and import keyword are self explanatory, what happens after the when is not.
What is happening in “$vo : RoolVO( stringValue == “Learning to drool”, $booleanVal : booleanValue )” broken down actually is:

stringValue == “Learning to drool” – This is a constraint that allows us to find all RoolVO objects known to the knowledge base that have the getStringValue() value equals to “Learning to drool”. If there are multiple instances of RoolVO that comply we will run this rule more than once, these are also referred to as matched objects. You can also have multiple constraints separated by a “,”.

$booleanVal : booleanValue – We are declaring a new local variable of type boolean called $booleanVal and gets it value from isBooleanValue.

$vo : RoolVO – We are declaring a new local variable of type RoolVO called $vo.

The next line:
“eval( $booleanVal )” – Evaluates the boolean variable, this needs to evaluate to true for the ‘then’ part of the rule to be called.
Then:
System.out.println( “First Rule” ); – Standard sys out.
$vo.setStringValue(“Done.”); – Sets the String value on the current RoolVO object that matched the constraints to Done.

The main classes / interfaces needed for a basic rule execution seem to be the following:
org.drools.KnowledgeBase and it’s factory
org.drools.KnowledgeBaseFactory:
This is the repository of all the relevant knowledge definitions; it contains rules, processes, functions, type models.

org.drools.builder.KnowledgeBuilder and it’s factory org.drools.builder.KnowledgeBuilderFactory:
Transforms / parses a source file (.drl, .xsl) into a KnowledgePackage that a KnowledgeBase can understand.

StatefulKnowledgeSession created by the KnowledgeBase .newStatefulKnowledgeSession();
This session is used to communicate with the actual rules engine.

To quote the drools JavaDocs:
StatefulKnowledgeSession is the most common way to interact with a rules engine. A StatefulKnowledgeSession allows the application to establish an iterative conversation with the engine, where the reasoning process may be triggered multiple times for the same set of data.

I wrote a simple test for the rule I described earlier.

package javaitzen.drools;
 
import static org.junit.Assert.assertEquals;
 
import org.drools.KnowledgeBase;
import org.drools.KnowledgeBaseFactory;
import org.drools.builder.KnowledgeBuilder;
import org.drools.builder.KnowledgeBuilderError;
import org.drools.builder.KnowledgeBuilderErrors;
import org.drools.builder.KnowledgeBuilderFactory;
import org.drools.builder.ResourceType;
import org.drools.io.ResourceFactory;
import org.drools.logger.KnowledgeRuntimeLogger;
import org.drools.logger.KnowledgeRuntimeLoggerFactory;
import org.drools.runtime.StatefulKnowledgeSession;
import org.junit.Before;
import org.junit.Test;
 
public class TestBasicRules {
 
 private KnowledgeBase kbase;
  
 @Before
 public void setup() {
  KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
  kbuilder.add(ResourceFactory.newClassPathResource("basic.drl"), ResourceType.DRL);
  KnowledgeBuilderErrors errors = kbuilder.getErrors();
  if (errors.size() > 0) {
   for (KnowledgeBuilderError error: errors) {
    System.err.println(error);
   }
   throw new IllegalArgumentException("Could not parse knowledge.");
  }
  kbase = KnowledgeBaseFactory.newKnowledgeBase();
  kbase.addKnowledgePackages(kbuilder.getKnowledgePackages());
      
   
 }
  
 @Test
 public void testBasic() {
 
  StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();
  KnowledgeRuntimeLogger logger = KnowledgeRuntimeLoggerFactory.newFileLogger(ksession, "test");
 
  RoolVO vo = new RoolVO();
  vo.setStringValue("Learning to drool");
  vo.setBooleanValue(true);
  ksession.insert(vo);
  ksession.fireAllRules();
  for (Object o: ksession.getObjects()) {
   if(o instanceof RoolVO) {
    assertEquals("Done.", ((RoolVO) o).getStringValue());
   }
  } 
  logger.close();
   
 }
 
}

To be honest, Drools is not nearly as intuitive as Quickrules was from what I have seen in this first task. However, below, I will start looking at using the rule flows, decision table functionality as well as the guided rules:

Those in partnership with the DSL (Domain Specific Language) construct hopefully do allow for more intuitive rules creation.

Previously, i went through the basic syntax and requirements to get a rule developed and tested.
Now to extend that, the Drools documentation is actually quite good, there is just a ton of it, so I will try to just focus on some of the main topics.

First a little thing I had to do to get the rules to run from your tests using maven, the .drls are not in the classpath by default, a simple way around that was to add the following to the POM:

<build>
  <resources>
   <resource>
    <directory>src/main/rules</directory>
   </resource>
  </resources>
</build>

Now more rules scenarios and usages:

Collections:
Querying the contents of a can be done in 2 ways, contains and memberOf, the difference is that the collection used in conjunction with memberOf must be a variable.

The drl:

rule "Use a Collection"
 when
  $vo : RoolVO( listValue contains  "items" )
 then  
  $vo.setStringValue("Done.");
  logger.log(Level.INFO,"Used a collection");
end

Regular Expressions:
You can use a regex as a selection criteria as well with the key words Matches and Not Matches.

The drl:

rule "Use a Regular Expression"
 when
  $vo : RoolVO( stringValue matches  "(0?[1-9]|[12][0-9]|3[01])/(0?[1-9]|1[012])/((19|20)\\d\\d)")
 then  
  $vo.setStringValue("Done.");
  logger.log(Level.INFO,"Found the date with a regular expression dd/mm/yyyy");
end

Global Variables:
You can define global variables, they should not be used as the are sometimes in code, to pass information between methods or in this case rules. They should rather be used to provide data or services that the rules use. An example would be something like an application specific logger, or perhaps constant lookup data loaded when the application starts.

The test:

public class TestBasicRules {
 
 private KnowledgeBase kbase;
 private Logger javaLogger = Logger.getLogger("testLogger");
 @Test
 public void testGlobal() {
 
  StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();
 
  RoolVO vo = new RoolVO();
  vo.setStringValue("Global");
  ksession.insert(vo);
  ksession.setGlobal("logger", javaLogger);
  ksession.fireAllRules();
  checkDone(ksession);    
 }

The drl:

package javaitzen.drools.rules
 
import javaitzen.drools.RoolVO
import java.util.logging.Level
 
global java.util.logging.Logger logger;
 
rule "Use a Global "
  
 when
  $vo : RoolVO( stringValue == "Global")
 then  
  $vo.setStringValue("Done.");
  logger.log(Level.INFO,"Logging with a global"); 
end

Rule Attributes:
On a rule you can specify attribute, there are a number of these. I’ll just mention a couple handy ones (quoting the official documentation):

no-loop
default value: false
type: Boolean
When the rule’s consequence modifies a fact it may cause the Rule to activate again, causing recursion. Setting no-loop to true means the attempt to create the Activation for the current set of data will be ignored.

salience
default value : 0
type : integer
Salience is a form of priority where rules with higher salience values are given higher priority when ordered in the Activation queue.

dialect
default value: as specified by the package
type: String
possible values: “java” or “mvel”
The dialect species the language to be used for any code expressions in the LHS or the RHS code block. Currently two dialects are available, Java and MVEL. While the dialect can be specified at the package level, this attribute allows the package definition to be overridden for a rule.

date-effective
default value: N/A
type: String, containing a date and time definition
A rule can only activate if the current date and time is after date-effective attribute.

date-expires
default value: N/A
type: String, containing a date and time definition
A rule cannot activate if the current date and time is after the date-expires attribute.

Guided Rule:
The guided rule editor seems to allow for everything you can do in code, just visually, and potentially more intuitively for those non developers. Only thing you need to do is make sure to have the objects you want to use imported in a .package in the same location as the created .brl file.

Decision Tables:
In my opinion the world actually runs on spreadsheets. We all like to think that it only functions because of us and our fancy applications, but truth be told the world would miss spreadsheets more than any other single application.

The business people giving us our requirements understand spread sheets, some of them better than us developers and this is the biggest single bonus on decision tables. The Drools decision table at first glance did look as if it would not be as simple to hand over to business users as the Quickrules one, but it is actually split quite clearly into “code” and “data”

Now to breakdown a decision table into its parts…
When creating a decision table, the eclipse plugin gives you an example, I am going to work through that.

C2: Keyword ruleset, just to state that this spread sheet is a ruleset (package).
D2: The ruleset (package) name.
Under this row you can specify the following optional keywords:
Sequential – The cell to the right of this can be true or false. If true, then salience is used to ensure that rules fire from the top down.
Import – The cell to the right contains a comma separated list of classes to import.
Variables – The cell immediately to the right can contain global declarations which Drools supports. This is a type, followed by a variable name. (if multiple variables are needed, comma separate them).

C3/D4: Notes heading and the actual notes.

C5: The RuleTable keyword and name. The “RuleTable” keyword must appear on top of the first condition column. You can have multiple rule tables on a sheet, they must just be separated by a line.

C6: Marks the column as a CONDITION column, G6, does this for the ACTION. You need at least one of each for a table to be valid. If there is no data in a CONDITION column, then that condition does not apply.
Other column optional keywords are:
PRIORITY – This states that this column’s values will set the salience
DURATION – This will set the duration values for the rule row.
NO-LOOP – Same as in the drl, this specifies if rule is not allowed to loop.

C7: This and subsequent columns in the row, define the actual variables referenced in the rule table.

C8: This and subsequent columns in the row specifies where we are getting the data from.

Row 9 and Column B are just labels / headings making the data simpler to understand, all the other fields and columns before there can be hidden as not to scare the “less technical”. The table inside B9 is then were the specific rule data is defined, hopefully directly from the specification, by a non developer.

I have uploaded this project to my Google code project, incase anyone wants it. I had a little issue with the decision table because I run OpenOffice at home and not Microsoft Office, the plugin expects Excel, so it leaves a ugly little red X in my project, but it opens fine outside the IDE and still compiles in maven.

In the next post, i’ll have a look at the Rule Flow, and start tackling the monster that is Guvnor

Reference: Learning to Drool… Part 1 & Learning to Drool… Part 2  from our JCG partner Brian Du Preez at the Zen in the art of IT blog.