http://www.developer.com/

Back to article

Rev Up the Drools 5 Java Rule Engine


May 19, 2009

You can talk for hours and hours about how to implement a web/enterprise Java application. You can talk about layers, architectures, frameworks, tools, patterns, and so on, but you probably will skip a sore subject: structuring the business logic! As much as you may hate to admit it, I am sure that you have something like the following somewhere in your code:

//a vote system deciding the proper message depending on the votes average
if average < 0.0 
   { average = 0.0;  }
if average > 10.0 
   { average = 10.0;  }
if (average>=0.0 && average<=3)
   { System.out.println("Bad!");  }
if (average>3.0 && average<=6.0)
   { System.out.println("Good!");  }
if (average>6.0 && average<=9.0)
   { System.out.println("Very Good!");  }
if (average>9.0 && average<=10.0)
   { System.out.println("Excellent!");  }
All those if ... then statements not only look bad but they do nothing for configurability or readability. Just ask yourself a few questions about the above spaghetti code:
  • After a small change in this code, does the application work without recompilation/redeploying?
  • Do you want to be the person who has to maintain this code?
  • Supposing that this code is getting bigger and bigger, can you easily test it and be sure that it is correct?
  • Are you ready to rewrite everything from scratch when you add new rules or different dependencies?
  • After a few months, will you recognize and understand the meaning of this code?

If you answered no more than you answered yes, keep reading to find how to turning those no's into yeses. The solution is Drools, a Java rule engine framework for organizing business logic. Drools allows you to focus on things that are known to be true, rather than on making decisions about low-level mechanics. Using this framework, you will be able to transform the above code into something readable, verifiable, reusable, configurable, scalable, and flexible.

Downloading and Installing Drools 5

At the time of writing, Drools had reached version 5.0 CR 1 (released on March 10, 2009). For this tutorial, download the Drools 5.0.0.CR1 Binaries distribution and extract it in your favorite location. You can use it as you would any set of JARs or you can use it from an IDE such as Eclipse or NetBeans.

Author's Note: Under the JBoss Tools 3 release, you can find a set of dedicated tools for Drools. You can install them under Eclipse and configure a Drools runtime in just a few minutes. The result will be a fully compatible and visual approach to Drools. According to the Drools homepage, "[the] Eclipse plug-in makes it easier than ever to use Drools, with intelligent auto-completion and Debug views, rule flow GUIs, and more." However, this is just a suggestion, not a requirement for this article.

Define a Rule Resource

Drools is based on rule resources. Most of the time, the rules are mapped in files with the .drl extension or in a spreadsheet format as decision tables (supported formats are Excel and CSV). A basic .drl file is a list of rules written in a file like this:
#package name
#list any import classes here.
#declare any global variables here
 
rule "Your First Rule"
     
     when
          #conditions
     then 
          #actions
 
end
 
rule "Your Second Rule"
     #include attributes such as "salience" here...
     when
          #conditions
     then 
          #actions
          
end

As you can see, every rule is encapsulated between the rule and end keywords. A rule has a name and a when-then pair that represents the condition and the action. The optional parts are marked with pound signs (#). For a better understanding of what goes on in the code, consider the following code sample written as a .drl file (vote.drl):

Listing vote.drl
 
package com.sample
 
import com.sample.DroolsTest.Vote;
 
rule "WrongValue – less than 0"
     when
          m : Vote( average < 0.0, vote : vote )
     then          
          m.setAverage(0.0f);
          update( m );               
end
 
rule "WrongValue – bigger than 10"
     when
          m : Vote( average > 10.0, vote : vote )
     then          
          m.setAverage(10.0f);
          update( m );               
end
 
rule "BadValue – between 0-3"
     when
          m : Vote( average >= 0.0 && average <=3.0, vote : vote )
     then
           m.setVote("Bad!");
          System.out.println( m.getVote() );
end
 
rule "GoodValue – between 3-6"
     when
          m : Vote( average >3.0 && average <=6.0, vote : vote )
     then
           m.setVote("Good!");
          System.out.println( m.getVote() );
end
 
rule "VeryGoodValue – between 6-9"
     when
          m : Vote( average >6.0 && average <=9.0, vote : vote )
     then
           m.setVote("Very Good!");
          System.out.println( m.getVote() );
end
 
rule "ExcellentValue – between 9-10"
     when
          m : Vote( average >9.0 && average <=10.0, vote : vote )
     then
           m.setVote("Excellent!");
          System.out.println( m.getVote() );
end

The getVote, setVote, getAverage, and setAverage functions are provided by a simple POJO like this (Vote.java):

Vote.java
 
public static class Vote {
          
            private String vote;
          private float average;
 
          public String getVote() {
               return this.vote;
          }
 
          public void setVote(String vote) {
               this.vote = vote;
          }
 
          public float getAverage() {
               return this.average;
          }
 
          public void setAverage(float average) {
               this.average = average;
          }
          
     }

As to decision tables, consider them if you have rules that can be expressed as rule templates plus data. In each row of a decision table, you collect data and combine it with the templates to generate a rule.

Author's Note: Keep in mind that in a decision table, each row is a rule and each column in that row is either a condition or an action for that rule.
In practice, you build decision tables on a set of keywords that you place in the right rows and columns. For example, the RuleTable keyword indicates the start of a rule table (both the starting row and column). Usually under the starting row, you will have a row that contains the keywords CONDITION and/or ACTION. Be sure to indicate that the data in the columns below are for either the LHS (Left Hand Side) or the RHS (Right Hand Side) parts of a rule. The next row will contain declarations of ObjectTypes. When you use this row, the values in the cells below become constraints on that object type.

Further down, you have the rule templates themselves. Here you can use the $param placeholder to indicate where data from the cells below will be populated (or $1, $2, $3, etc. to indicate parameters from a comma-separated list in a cell below). Finally, the last two rows will contain data, which are interpolated with templates, to generate rules. Figure 1 shows a table for the voting example (vote.xls).



Click here for larger image

Figure 1: Decision Table for the Voting Example

Table 1 lists more keywords (this table is available in the Drools Reference Manual).

Table 1. Drools Keywords

Keyword Description Required
RuleSet The cell to the right of RuleSet contains the ruleset name. One only (or default)
Sequential The cell to the right of Sequential can be true or false. If true, then "salience" is used to ensure that rules fire from the top down. Optional
Import The cell to the right of Import contains a comma-separated list of Java classes to import. Optional
RuleTable A cell starting with RuleTable indicates the start of a definition of a rule table. The actual rule table starts the next row down. The rule table is read left to right and top down until there is one blank row. At least one. If there are more, then they are all added to the one ruleset.
CONDITION This keyword indicates that this column will be for rule conditions. At least one per rule table
ACTION This keyword indicates that this column will be for rule consequences. At least one per rule table
PRIORITY This keyword indicates that this column's values will set the "salience" values for the rule row. It overrides the 'Sequential' flag. Optional
DURATION This keyword indicates that this column's values will set the duration values for the rule row. Optional
NAME This keyword indicates that this column's values will set the name for the rule generated from that row. Optional
Functions The cell immediately to the right of Functions can contain functions, which can be used in the rule snippets. Drools supports functions defined in the DRL, allowing logic to be embedded in the rule, and changed without hard coding. Use with care and with the same syntax as regular DRL. Optional
Variables The cell immediately to the right of Variables can contain global declarations, which Drools supports. This is a type, followed by a variable name. (If multiple variables are required, comma-separate them). Optional
UNLOOP This keyword indicates that if there are cell values in this column, the no-loop attribute should be set. Optional
XOR-GROUP Cell values in this column mean that the rule-row belongs to the given XOR/activation group. An activation group means that only one rule in the named group will fire (i.e., the first one to fire cancels the other rule activations). Optional
Worksheet By default, only the first worksheet is looked at for decision tables. N/A

Source: Drools Reference Manual

Main Classes of the Drools API

At first, Drools was rules oriented. The API was hard to understand, poorly documented, and didn't cover things like event processing properly. In time, Drools became knowledge oriented and much easier to use and implement in projects. Before seeing Drools in action, get to know the main classes of the Drools API (you will recognize these classes later in a real example that will transform the spaghetti code from the introduction):
  • org.drools.builder.KnowledgeBuilder – Transforms a source file into a KnowledgePackage of rule and process definitions that a KnowledgeBase can consume. (Later, you will see how to create a source file, like a .drl or .xls file.)
  • org.drools.KnowledgeBase – A repository of all the application's knowledge definitions; contains rules, processes, functions, type models.
  • org.drools.agent.KnowledgeAgent – Provides automatic loading, caching, and re-loading of resources, and is configured from a properties file.
  • org.drools.runtime.StatefulKnowledgeSession – The most common way to interact with a rule 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. After the application finishes using the session, though, it must call the dispose() method in order to free the resources and used memory.
  • org.drools.runtime.StatelessKnowledgeSession – A convenience API that wraps a StatefulKonwledgeSession. It removes the need to call dispose(). Stateless sessions do not support iterative insertions and fireAllRules from Java code. The act of calling execute(...) is a single shot method that will internally instantiate a StatefullKnowledgeSession, add all the user data and execute user commands, call fireAllRules, and then call dispose().

These interfaces are sustained by a set of factory classes:

  • org.drools.builder.KnowledgeBuilderFactory – This factory is used to build the knowledge base definitions that are held collectively in KnowledgePackages. The KnowledgePackage also provides the role of "namespacing." You can supply an optional KnowlegeBuilderConfiguration, which is itself created from this factory. The KnowledgeBuilderConfiguration allows you to set the ClassLoader to be used along with other settings like the default dialect and compiler, as well as many other options.
  • org.drools.io.ResourceFactory – A convenience factory to provide resource implementations for the desired IO resource.
  • org.drools.KnowledgeBaseFactory – This factory will create and return a KnowledgeBase instance. An optional KnowledgeBaseConfiguration can be provided. The KnowlegeBaseConfiguration is also itself created from this factory.
  • org.drools.agent.KnowledgeAgentFactory – The KnowlegeAgent is created by the KnowlegeAgentFactory. The KnowlegeAgent provides automatic loading, caching, and re-loading of resources, and is configured from a properties file. The KnowledgeAgent can update or rebuild this KnowlegeBase as the resources it uses change. The configuration given to the factory determines the strategy for this, but it is typically pull based using regular polling.

The above descriptions are available in the official Javadoc for Drools 5 (see bottom of that page for download information).

Loading a Rule Resource Using Drools API

With an understanding of the Drools API descriptions in the previous section, you are ready to follow a conventional set of steps to load a rule resource and make a test. For this exercise, you will load the vote.drl rule resource:
  1. Create a KnowledgeBuilder to add a resource (you will add the vote.drl, but in the same manner you can load a decision table):
    KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
    kbuilder.add(ResourceFactory.newClassPathResource("vote.drl"), ResourceType.DRL);
  2. Check for potential errors:
    KnowledgeBuilderErrors errors = kbuilder.getErrors();
         if (errors.size() > 0) {
              for (KnowledgeBuilderError error: errors) {
                   System.err.println(error);
              }
              throw new IllegalArgumentException("Could not parse knowledge.");
         }
  3. Create a KnowledgeBase that contains all the relevant process definitions and other knowledge types like rules:
    KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
    kbase.addKnowledgePackages(kbuilder.getKnowledgePackages());
  4. You need to create a session to interact with the engine:
    StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();
  5. Obtain a logger for getting the generated events (you will use a file logger, but a console logger is also available):
    KnowledgeRuntimeLogger logger = KnowledgeRuntimeLoggerFactory.newFileLogger(ksession, "log");
  6. Provide a test case to the vote.drl. Here you will provide a Vote instance, but you can adjust this according to your DRL:
    ksession.insert(vote);
    Where, for example, vote is:
    Vote vote = new Vote();
    vote.setAverage(8.4f);
  7. "Fire all rules," so that all the rules from your DRL will be checked against your test case:
    ksession.fireAllRules();
  8. Clean up.
    logger.close();
    ksession.dispose();

Now, you can put everything together in a complete functional application (DroolsTest.java). You can execute this as you would any Java application, as long as the vote.drl and Drools libraries are available.

DroolsTest.java
 
package com.sample;
 
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;
 
/**
 * This is a sample class to launch a rule.
 */
public class DroolsTest {
     public static final void main(String[] args) {
          try {
               // load up the knowledge base
               KnowledgeBase kbase = readKnowledgeBase();
               StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();
               KnowledgeRuntimeLogger logger = KnowledgeRuntimeLoggerFactory.newFileLogger(ksession, "log");
               
               // go !
               Vote vote = new Vote();
               vote.setAverage(8.4f);
               
               //insert the "vote"
               ksession.insert(vote);
               
               //"fire all rules"
               ksession.fireAllRules();
               
               //clean up
               logger.close();
               ksession.dispose();
               
          } catch (Throwable t) {
               t.printStackTrace();
          }
     }
 
     private static KnowledgeBase readKnowledgeBase() throws Exception {
          KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
          kbuilder.add(ResourceFactory.newClassPathResource("vote.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.");
          }
          KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
          kbase.addKnowledgePackages(kbuilder.getKnowledgePackages());
          return kbase;
     }
 
     public static class Vote {
          
         private String vote;
          private float average;
 
          public String getVote() {
               return this.vote;
          }
 
          public void setVote(String vote) {
               this.vote = vote;
          }
 
          public float getAverage() {
               return this.average;
          }
 
          public void setAverage(float average) {
               this.average = average;
          }
          
     }
 
}

The output, conforming to vote.drl, will be the text "Excellent!"

Brief Overview of Drools Flow

Drools Flow is based on flow charts. It represents a process engine that sustains the integration of processes and rules. Practically, a flow chart will allocate ruleflow groups to rules so that you can include or exclude rules. (A ruleflow is a process that describes the order in which a series of steps need to be executed, using a flow chart). In addition, you may run rules in loops, execute rules in parallel, use timers, use events, and so on. Figure 2 shows the set of components that can construct a flow chart, as presented in the Drools plug-in for Eclipse IDE.



Click here for larger image

Figure 2: Flow Chart Components in Drools Plug-in for Eclipse

For the voting example, you will build a simple flow chart that will force the engine to avoid checking the "WrongValue – less than 0" and "WrongValue – bigger than 10" rules. For this, you will place these two rules in a group named IgnoreGroup, while the rest of the rules will be under a group named ValidGroup. For this, you should edit the vote.drl by using the ruleflow-group keyword, like this:

vote.drl
 
package com.sample
 
import com.sample.DroolsTest.Vote;
 
rule "WrongValue – less than 0"
ruleflow-group "IgnoreGroup"
     when
          m : Vote( average < 0.0, vote : vote )
     then          
          m.setAverage(0.0f);
          update( m );               
end
 
rule "WrongValue – bigger than 10"
ruleflow-group "IgnoreGroup"
     when
          m : Vote( average > 10.0, vote : vote )
     then          
          m.setAverage(10.0f);
          update( m );               
end
 
rule "BadValue – between 0-3"
ruleflow-group "ValidGroup"
     when
          m : Vote( average >= 0.0 && average <=3.0, vote : vote )
     then
           m.setVote("Bad!");
          System.out.println( m.getVote() );
end
 
rule "GoodValue – between 3-6"
ruleflow-group "ValidGroup"
     when
          m : Vote( average >3.0 && average <=6.0, vote : vote )
     then
           m.setVote("Good!");
          System.out.println( m.getVote() );
end
 
rule "VeryGoodValue – between 6-9"
ruleflow-group "ValidGroup"
     when
          m : Vote( average >6.0 && average <=9.0, vote : vote )
     then
         m.setVote("Very Good!");
          System.out.println( m.getVote() );
end
 
rule "ExcellentValue – between 9-10"
ruleflow-group "ValidGroup"
     when
          m : Vote( average >9.0 && average <=10.0, vote : vote )
     then
           m.setVote("Excellent!");
          System.out.println( m.getVote() );
end

Now, you can construct the flow chart. If you use the Drools plug-in for Eclipse, you can use its graphical editor to view/design this flow chart (see Figure 3).



Click here for larger image

Figure 3: A Flow Chart Example

In the background, this is an XML document. Therefore, you can manually edit it.

Every flow chart starts with a Start node and ends with an End node. Between these nodes, you have the flow components. In this case, you have a single component (a RuleFlowGroup component). This component will indicate the ValidGroup group of rules.

Next, you have to set some properties for the RuleFlowGroup and for the flow chart. First, though, you should know that a flow chart exposes the following properties:

  • Id – The unique id of the process
  • Name – The display name of the process
  • Version – The version number of the process
  • Package – The package (namespace) in which the process is defined
  • Variables – Can be defined to store data during the execution of your process
  • Swimlanes – Specify the actor responsible for the execution of human tasks
  • Exception Handlers – Specify the behavior when a fault occurs in the process
  • Connection Layout – Specify how the connections are visualized on the canvas using the connection layout property:
    • 'Manual' – always draws your connections as lines going straight from their start points to their end points (although it's possible to use intermediate break points)
    • 'Shortest path' – similar to 'Manual', but tries to go around any obstacles it might encounter between the start and end points to avoid lines crossing nodes
    • 'Manhattan' – draws connections by using only horizontal and vertical lines

In addition, a RuleFlowGroup node exposes the following properties:

  • Id – The id of the node (which is unique within one node container)
  • Name – The display name of the node
  • RuleFlowGroup – The name of the ruleflow group that represents the set of rules of this RuleFlowGroup node
  • Timers – Timers that are linked to this node

In the case of the RuleFlowGroup component, the properties that you want to set are Name and RuleFlowGroup. For the Name property, use the VoteFlow value. For the RuleFlowGroup property, use the ValidGroup value (as you can see, it corresponds to the value of ruleflow-group from vote.drl).

For the flow chart, you should set Connection Layout to Shortest Path, Id to votes, Name to ruleflow, and Package to com.sample.

You can accomplish these tasks from the Drools plug-in for Eclipse or by entering them manually. The result is an XML document with the .rf extension. It should look like this:

vote.rf
 

<?xml version="1.0" encoding="UTF-8"?> 
<process xmlns="http://drools.org/drools-5.0/process"
         xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
         xs:schemaLocation="http://drools.org/drools-5.0/process drools-processes-5.0.xsd"
         type="RuleFlow" name="ruleflow" id="votes" package-name="com.sample" version="1" routerLayout="2" >
 
  <header>
  </header>
 
  <nodes>
    <start id="1" name="Start" x="16" y="16" />
    <end id="3" name="End" x="240" y="16" />
    <ruleSet id="4" name="VoteFlow" x="125" y="17" width="80" height="40" ruleFlowGroup="ValidGroup" />
  </nodes>
 
  <connections>
    <connection from="4" to="3" />
    <connection from="1" to="4" />
  </connections>
 
</process>

Save this file as vote.rf in the project directory. Now you can use the Drools API to connect the flow chart (vote.rf) with the rule resource (vote.drl) and test it. For this, you will make two small modifications to the DroolsTest.java application:

  1. Load the flow chart as you have loaded the rule resource.
  2. Call the StatefulKnowledgeSession.startProcess before you fire any rules.

This method gets a String argument that represents the ruleflow id (in this case, votes). After making these modifications, you get the following application:

RuleFlowTest.java
 
package com.sample;
 
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;
 
/**
 * This is a sample file to launch a process.
 */
public class RuleFlowTest {
 
     public static final void main(String[] args) {
          try {
               // load up the knowledge base
               KnowledgeBase kbase = readKnowledgeBase();
               StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();
               KnowledgeRuntimeLogger logger = KnowledgeRuntimeLoggerFactory.newFileLogger(ksession, "log");
          
               // go !
               Vote vote = new Vote();
               vote.setAverage(8.4f);
               
               //insert the "vote"
               ksession.insert(vote);                                   
                    
               //start the "votes" process
               ksession.startProcess("votes");
               
               //"fire all rules"
               ksession.fireAllRules();
 
               //clean up
               logger.close();
               ksession.dispose();
                              
          } catch (Throwable t) {
               t.printStackTrace();
          }
     }
 
     private static KnowledgeBase readKnowledgeBase() throws Exception {
          KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
          kbuilder.add(ResourceFactory.newClassPathResource("vote.drl", RuleFlowTest.class), ResourceType.DRL);
          kbuilder.add(ResourceFactory.newClassPathResource("vote.rf", RuleFlowTest.class), ResourceType.DRF);
          KnowledgeBuilderErrors errors = kbuilder.getErrors();
          if (errors.size() > 0) {
               for (KnowledgeBuilderError error: errors) {
                    System.err.println(error);
               }
               throw new IllegalArgumentException("Could not parse knowledge.");
          }
          KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
          kbase.addKnowledgePackages(kbuilder.getKnowledgePackages());
          return kbase;
     }
          
     public static class Vote {
          
         private String vote;
          private float average;
 
          public String getVote() {
               return this.vote;
          }
 
          public void setVote(String vote) {
               this.vote = vote;
          }
 
          public float getAverage() {
               return this.average;
          }
 
          public void setAverage(float average) {
               this.average = average;
          }
          
     }
 
}

The output, conforming to vote.drl, will be the text "Excellent!" As an exercise, you may want to try a value that is in IgnoreGroup.

Author’s Note: For a complete tutorial on Drools Flow, check out this write-up.

Flexibility, Readability, and Functionality

Drools 5 provides access to many powerful new features that, although not very easy to use, can bring your Java projects to a new level of flexibility, readability, and functionality. This article was just a brief introduction to get you familiar with Drools; there is much more to explore than you have seen here. With the basic knowledge you now have, you are ready to rev up this rule engine.

Sitemap | Contact Us

Thanks for your registration, follow us on our social networks to keep up-to-date