Java Beans dot Asia - drools category

Enriching Rich Internet Applications with rule-based reasoning

Mon, 22 Feb 2010 14:00:00 GMT

I came across a Firefox Add-On today by Matthias Tylkowski, that lets user to modify the browser view of his/her preferred web pages. For example, user can modify the appearance of cnn.com to suit his/her needs.

The add-on or the web rules is a JSON-based rule language, where each rule is a JSON object. In addition, Javascript is used for method calls. The web rules use Drools-like condition language:

{"id":"rule101",
  "appliesTo": [
       "http://www.cnn.com"
     ],
 "condition":
  "$X:Element( class == 'note',
               $Y:firstChild
             )
             &&
             ($Y.nodeName == 'ul')",
 "actions":[
  "changeBackground($Y, 'blue')"
   ]
 }

For all elements of class note having as first child an ul, change the first child background color to blue.

I think its a quite cool add-on.

Resources:
JSON Rules

Social Bookmarks :

Related Posts
There are no related posts for this blog entry

Rule Engine Stress Testing

Sat, 05 Sep 2009 01:15:00 GMT

I came across a blog by a company called Illation. What those guys do is compare performance of several rule engines available on the market: Drools, ILog, OPSJ and Jess.

The stress tests cover different aspects, for example:

Rules firing time
Data load time
Memory usage
Pre-run memory used
Post-run memory used

The test results available on their blog for the wide public. The team also makes business rules, object model and datasets used in their stress tests available for download if someone wishes to repeat the tests. Some of the results look very interesting.

Social Bookmarks :

Drools 5 Case Study 2 - Complex Event Processing

Mon, 31 Aug 2009 14:45:00 GMT

In my previous post Drools 5 - Complex Event Processing, I gave introduction to Drools Fusion module. In the current post, I would like to demonstrate Drools Fusion capabilities.

As an example chosen for the current article, I decided to use a scenario when an insurance firm rewards its policy members. The members are rewarded when they keep a low average of claimed money under the threshold set on their account over a period of time.

In other words, if the policy member had last five claims average and average of claims during last ninety (90) days lower than the threshold limit - he/she will be eligible for a reward.

Drools allows us to test for these conditions by applying the sliding window concept. So to obtain a claim average for a particular period in time, I will use time based sliding window. To obtain an average of last five claims, I will use length based sliding window.

Before I begin, I would like to say that the source code for this article is available as attachment, the download link is at the bottom.

Ok, lets begin. Below is my POJO Account:

public class Account {
  private String number = "";
  private double threshold = 0.00;

  public Account() {
    super();
  }

  public String getNumber() {
    return number;
  }
  
  public void setNumber(String number) {
    this.number = number;
  }

  public double getThreshold() {
    return threshold;
  }

  public void setThreshold(double threshold) {
    this.threshold = threshold;
  }	
}

The following is my implementation of the claim event POJO:

public class ClaimApprovedEvent implements Serializable {

  private static final long serialVersionUID = 1L;

  private String accountNumber = "";
  private double amount = 0.00;

  public ClaimApprovedEvent(String accountNumber, 
                                   double amount) {
    this.accountNumber = accountNumber;
    this.amount = amount;
  }

  public String getAccountNumber() {
    return accountNumber;
  }

  public void setAccountNumber(String accountNumber) {
    this.accountNumber = accountNumber;
  }

  public double getAmount() {
    return amount;
  }

  public void setAmount(double amount) {
    this.amount = amount;
  }
}

This event represents a claim event when a policy member has claimed some money. Event contains policy member account number and the claim amount. These events, I will be "feeding" in to the KnowledgeSession as facts. Yes, they are play a role knowledge facts in Drools.

Having said that I want to point out that all events are facts, but not all facts are events. I know it maybe a little bit confusing, but if you read Drools 5.0 doco it will become more clearer to you.

To give some information about it - events almost never change state in Drools (almost means it is still possible to change the state of event), therefore they are immutable.

Events simply hold information about something that has already happened and because you cannot change what has already happened - events are immutable. Events also allow the use of sliding windows.

The following is implementation of a POJO, that plays a role of a common data structure for rules to use at run time. It is one of the new features that available in Drools 5. Keep in mind - that this is not a knowledge fact, but just a data structure.

This POJO is an internal type, therefore there is no need to create new instance of this class. The object will only be created at run time, when the knowledge package is compiled (In my tester class I show how to do it). For now, we just have to add POJOs declaration to DRL, and to have the source file present. Later on, you will see how the declaration in DRL is done:

public class AccountInfo {

  private String accountNumber = "";
  private double aveOfLastClaims = 0.00;
  private double aveForPeriod = 0.00;
  private boolean eligibleForBonusClaims = false;
  private boolean eligibleForPeriodicBonus = false;

  public AccountInfo() {
    super();
  }

  public String getAccountNumber() {
    return accountNumber;
  }

  public void setAccountNumber(String accountNumber) {
    this.accountNumber = accountNumber;
  }

  public double getAveOfLastClaims() {
    return aveOfLastClaims;
  }

  public void setAveOfLastClaims(
                  double aveOfLastClaims) {
    this.aveOfLastClaims = aveOfLastClaims;
  }

  public double getAveForPeriod() {
    return aveForPeriod;
  }

  public void setAveForPeriod(double aveForPeriod) {
    this.aveForPeriod = aveForPeriod;
  }

  public boolean isEligibleForBonusClaims() {
    return eligibleForBonusClaims;
  }

  public void setEligibleForBonusClaims(
             boolean eligibleForBonusClaims) {
    this.eligibleForBonusClaims = eligibleForBonusClaims;
  }

  public boolean isEligibleForPeriodicBonus() {
    return eligibleForPeriodicBonus;
  }

  public void setEligibleForPeriodicBonus(
                 boolean eligibleForPeriodicBonus) {
    this.eligibleForPeriodicBonus = 
                             eligibleForPeriodicBonus;
  }
}

...and the following is the DRL:

package net.javabeansdotasia.casestudy.pojo;

import net.javabeansdotasia.casestudy.pojo.ClaimApprovedEven
import net.javabeansdotasia.casestudy.pojo.Account;

declare ClaimApprovedEvent
  // declare a fact type as an event, default is 'fact'
  @role( event )
end

// Decalare common data structure for all rules to use
declare AccountInfo
  accountNumber : String
  aveOfLastClaims : Double
  aveForPeriod : Double
  eligibleForBonusClaims : Boolean
  eligibleForPeriodicBonus : Boolean
end

rule "FiveLastClaims"
  dialect "mvel"
  no-loop true
  salience 100

when
  $account : Account()

  //check if the average of last five claims is less 
  //than the account threshold
  $aveOfLastClaims : Number(
           $account.threshold > doubleValue ) 
  from accumulate(
    ClaimApprovedEvent(
      accountNumber == $account.number, 
      $amount : amount
    ) 
    over window:length( 5 ) from 
    entry-point ClaimStream, 
    average($amount)
  )

  //the member must not have received eligibility 
  //for last claim bonus yet 
  $accountInfo : AccountInfo( 
    accountNumber == $account.number, 
    eligibleForBonusClaims == false 
  )
then
  modify($accountInfo) {
    setAveOfLastClaims($aveOfLastClaims);
    setEligibleForBonusClaims(true);
  };
end

rule "NinetyDaysPeriod"
dialect "mvel"
no-loop true
salience 90

when
  $account : Account()

  //check if the average of claims for period is less 
  //than the account threshold
  $aveForPeriod : Number(
                $account.threshold > doubleValue ) 
  from accumulate(
    ClaimApprovedEvent(
      accountNumber == $account.number, 
      $amount : amount
    ) 
  over window:time( 90d ) from 
  entry-point ClaimStream, 
  average($amount)
)

//the member must have eligibility for last claim bonus and
//the member must not have received eligibility for 
//periodic bonus yet
  $accountInfo : AccountInfo( 
    accountNumber == $account.number, 
    eligibleForBonusClaims == true, 
    eligibleForPeriodicBonus == false 
  )
then
  modify($accountInfo) {
    setAveForPeriod($aveForPeriod);
    setEligibleForPeriodicBonus(true);
  };
end

rule "EligibleForVoucher"
dialect "mvel"
no-loop true
salience 80

when
  $account : Account()

//the member must have eligibility for last claim bonus and
//the member must have eligibility for periodic bonus
  $accountInfo : AccountInfo( 
    accountNumber == $account.number, 
    eligibleForBonusClaims == true, 
    eligibleForPeriodicBonus == true
  )
then
  System.out.println("Notifying policy member..."); 
  System.out.println("Dear member, you have claimed "
  + "in average $" +  $accountInfo.aveOfLastClaims + 
  " during last five claims, which is " + 
  "under the account threshold of $" + $account.threshold);

  System.out.println("Dear member, you have claimed " +
  "in average $" + $accountInfo.aveForPeriod + 
  " during last 90 days, which is "+ 
  "under the account threshold of $" + $account.threshold);

  System.out.println("You are eligible for a holiday!");
end

Lets have a look what does this DRL do:

Modifying existing type by specifying that ClaimApprovedEvent is an event (line 6). To allow Drools to process events, we have to set that the fact is of type event
Declaring new type that plays the role of a common data structure (line 12). This is the declaration that I was talking about previously.
rule "FiveLastClaims" obtains an average of last five event claims and compares it to the account threshold. If the rule return true, the AccountInfo is updated with new data for other rules to use.
rule "NinetyDaysPeriod" obtains an average claim totals over a period of ninety (90) days and compares it to the account threshold. If the rule return true, the AccountInfo is updated with new data for other rules to use
rule "EligibleForVoucher" checks if the account owner has both eligibility for a periodic bonus and last five claim bonus, if true - the policy member will be eligible for a reward

The following is the snippet code from my Tester class where I show how to I load claim events over a period of time into the Knowledge session entry point (once again to remind: please refer to the source code attached for more information):

SessionPseudoClock clock = session.getSessionClock();

WorkingMemoryEntryPoint claimStream = session
.getWorkingMemoryEntryPoint("ClaimStream");

claimStream.insert(
new ClaimApprovedEvent(account.getNumber(), 12.00));
clock.advanceTime(80, TimeUnit.DAYS);

claimStream.insert(
new ClaimApprovedEvent(account.getNumber(), 46.00));
clock.advanceTime(15, TimeUnit.DAYS);

claimStream.insert(
new ClaimApprovedEvent(account.getNumber(), 60.00));
clock.advanceTime(45, TimeUnit.DAYS);

claimStream.insert(
new ClaimApprovedEvent(account.getNumber(), 110.00));
clock.advanceTime(60, TimeUnit.DAYS);

claimStream.insert(
new ClaimApprovedEvent(account.getNumber(), 20.00));

session.insert(account);
session.insert(accountInfo);
session.fireAllRules();

Please note an entry point "ClaimStream". Entry point plays a role of a partition in KnowledgeSession in Drools. Partitioning is also a new concept in Drools that makes KnowledgeSession multithreaded. You can have multiple entry points and choose where to insert the fact.

In the current example, I use only one partition (or entry point). If I would to use more than one, than I would have to enable multi-partitioning with the following code:

KnowledgeBaseConfiguration config = 
KnowledgeBaseFactory.newKnowledgeBaseConfiguration();
config.setOption(MultithreadEvaluationOption.YES);

Have a read Drools Fusion manual, the team really gives a good cover of this concept.

I use SessionPseudoClock that allows me to test the rules by feeding claim events into the KnowledgeSession over a period of time. As you can see, after each event I move the clock forward, simulation submission of each claim event in different time.

The following is the program output:

Notifying policy member...

Dear member, you have claimed in average $49.6 
during last five claims, which is under the 
account threshold of $70.0

Dear member, you have claimed in average $65.0 
during last 90 days, which is under the account 
threshold of $70.0

You are eligible for a holiday!

That's it. In this example I showed how it is possible to process complex events over a period of time by applying sliding window concept.

Please note that the above example was tested by me and its working fine. I also included source files for the above example as Eclipse project. You can simply create a new Java project from this existing Ant build.xml file.

Also, I wanted to point out that in my Eclipse project setup my Drools binaries located under JAVA_HOME/lib/drools-5.0-bin/ (have a look at the build.xml)

I hope this was clear :)

Cheers

Resources:
Drools JBoss Rules 5.0 Developer's Guide July 2009

Social Bookmarks :

Drools 5 - Complex Event Processing

Mon, 31 Aug 2009 12:05:00 GMT

From Drools version 4 to version 5, the framework has undergone quite a few improvements. These include support for three additional business modeling techniques. So today, Drools is not only a rule engine, but much more than that.

One of these techniques is event processing. The module that added event processing capabilities to the framework is called Drools Fusion. It supports Complex Event Processing (CEP) and Event Stream Processing (ESP).

"...Complex Event Processing, or CEP, is primarily an event processing concept that deals with the task of processing multiple events with the goal of identifying the meaningful events within the event cloud. CEP employs techniques such as detection of complex patterns of many events, event correlation and abstraction, event hierarchies, and relationships between events such as causality, membership, and timing, and event-driven processes..."

http://en.wikipedia.org/wiki/Complex_Event_Processing

Drools Fusion utilizes event processing architecture that adds loose coupling to its components. In other words, one party can publish events and other party can listen to those events while unaware of the publishing party.

Event can represent a change in state, for example banking transaction or insurance claim that was processed. CEP deals with complex event processing. Complex event is a collection of simpler events. Please refer to the diagram below:

In my next post Drools 5 Case Study 2 - Complex Event Processing, I talk about CEP and how Drools applies its processing power to solve complex event problems.

Social Bookmarks :

Drools 5 Case Study 1- Writing DSL for DRL rule

Sat, 29 Aug 2009 07:20:00 GMT

One of the blog readers, who posted a comment in my previous post Drools - tutorial on writing DSL template asked to me to help him with creating DSL for the following rule, so I decided to use his example as a small case study:

For readability, I added some comments to the original rule:

rule 'Rank accomodation name'
salience 90
when
     /*
       Matches every AccomodationBase
     */
     $accBase: AccomodationBase()

     /* 
       Uses inline eval to evaluate that there is 
       no AccomodationBase of type AccomodationRank
       in the session. 
       
       To remind: inline eval evaluated only once 
       and then it is cached by Drools.
     */
     not AccomodationBase(eval($accBase 
                       instanceof AccomodationRank))

     /* 
       Matches every AccomodationRank that has the same 
       level and the description as the AccomodationBase
     */
     $accRank: AccomodationRank( 
            level == $accBase.level, 
	    description == $accBase.description)
then
     /*
	Increments the score
     */
     $accRank.setScore($accRank.getScore()+1);
end

For my solution, I created two POJOs, tester class DSL and DSLR files. The following is my DSL:

[when]AccomodationBaseObj = $accBase: AccomodationBase()
[when]There is Accomodation base object of type Accomodation rank = eval($accBase instanceof AccomodationRank)
[when]AccomodationRankObj = $accRank: AccomodationRank(level == $accBase.level, description == $accBase.description)
[then]IncrementScore = $accRank.setScore($accRank.score+1);
[then]PrintScore = System.out.println("Rank score: " + $accRank.score);
[then]PrintLevel = System.out.println("Base level: " + $accBase.level);

and this is the DSLR file:

package net.javabeansdotasia.casestudy;

expander accomodation.dsl

import net.javabeansdotasia.casestudy.pojo.AccomodationBase;
import net.javabeansdotasia.casestudy.pojo.AccomodationRank;

rule "Rank"  
dialect "mvel"
when  
   AccomodationBaseObj
   not (There is Accomodation base object of type Accomodation rank)
   AccomodationRankObj
then
   IncrementScore 
   PrintScore
   PrintLevel
end

In the following class I load DSL and DSLR files in to the KnowledgeBuilder and get a KnowledgeBase object. Once I have the KnowledgeBase object, I can get StatefulKnowledgeSession or StatelessKnowledgeSession, depends on what I want to do.

package net.javabeansdotasia.casestudy.utils;

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;

public class MyKnowledgeBaseFactory {
  public static KnowledgeBase 
                createKnowledgeBaseFromDSL(String dslr,
			String dsl) throws Exception {

   KnowledgeBuilder builder = 
            KnowledgeBuilderFactory
				.newKnowledgeBuilder();

     //Attention!!!!
     //Add DSL BEFORE DSLR
     builder.add(
              ResourceFactory.newClassPathResource(dsl),
						ResourceType.DSL);

     builder.add(
              ResourceFactory.newClassPathResource(dslr),
				ResourceType.DSLR);

     KnowledgeBuilderErrors errors = builder.getErrors();

      if (errors.size() > 0) {
	for (KnowledgeBuilderError error : errors) {
		System.err.println(error);
	}
	throw new IllegalArgumentException("Could not parse knowledge.");
      }
      KnowledgeBase knowledgeBase = 
                KnowledgeBaseFactory.newKnowledgeBase();
      knowledgeBase.addKnowledgePackages(
                    builder.getKnowledgePackages());
      return knowledgeBase;
   }
}

Below is my Tester class:

package net.javabeansdotasia.casestudy.test;

import net.javabeansdotasia.casestudy.pojo.AccomodationBase;
import net.javabeansdotasia.casestudy.pojo.AccomodationRank;
import net.javabeansdotasia.casestudy.utils.MyKnowledgeBaseFactory;

import org.drools.KnowledgeBase;
import org.drools.runtime.StatefulKnowledgeSession;

public class Test {

   public static final void main(String[] args) {
     try {
        KnowledgeBase kbase = 
               MyKnowledgeBaseFactory
		   .createKnowledgeBaseFromDSL(
                        "accomodation.dslr",
			 "accomodation.dsl");
	StatefulKnowledgeSession ksession = 
              kbase.newStatefulKnowledgeSession();
	AccomodationBase accomBase = 
                  new AccomodationBase(9, "Just Demo");
	AccomodationRank accomRank = 
                  new AccomodationRank(9, "Just Demo");
	ksession.insert(accomBase);
	ksession.insert(accomRank);
	ksession.fireAllRules();
      } catch (Throwable t) {
	 t.printStackTrace();
      }
    }
}

As you may have noticed, in Drools 5 the process of loading the rule files (DSL and DSLR) and getting a working session is different to Drools 4. In Drools 5 there is a whole new set of APIs. Basically, main change is that Drools now is knowledge oriented, instead of rule oriented. It was a real step forward in order to support other forms of logic, such as workflow and event processing. You can read about it in Drools 5.0 docs.

That it. Please note that the above example was tested by me and its working fine. I also included source files for the above example as Eclipse project. You can simply create a new Java project from this existing Ant build.xml file.

Also, I wanted to point out that in my Eclipse project setup my Drools binaries located under JAVA_HOME/lib/drools-5.0-bin/ (have a look at the build.xml)

Cheers

Social Bookmarks :

Feedback by the Drools Team

Sun, 23 Aug 2009 07:49:00 GMT

Today while checking my blog's referrers, to my pleasant surprise I discovered that few Drools articles I have published on this blog, were praised by Mark Proctor in Drools blog.

Mark is one of the Drools creators and I think at the moment the project lead. The following is the post where my articles were mentioned: Some articles form Java Beans dot Asia.

It was really nice to be noticed by the Drools guys and get positive feedback. It means I am actually doing something right ;)

Soon more articles to come on Drools 5.0 from yours truly ...

Social Bookmarks :

Brainteaser Drools: Testing Objects

Sat, 22 Aug 2009 12:50:00 GMT

This can be a hard one, since it requires from you to be familiar with Drools.

Consider the condition side of the following rules:

rule "object comparison one"
 no-loop
  when
     $customer1 : Customer( )
     $customer2 : Customer(this != $customer1)
  then
     System.out.println("Rule one - Objects are equal");
end

rule "object comparison two"
 no-loop
  when
     $customer1 : Customer( )
     $customer2 : Customer(eval(this != $customer1))
  then
     System.out.println("Rule two - Objects are equal");
end

Question(s):
Which of the two rules does valid comparison of the two Customer instances?
Which of the two rules is invalid? Why?

Looking forward for your answers dear readers

Resources:
Drools JBoss Rules 5.0 Developer's Guide July 2009

Social Bookmarks :

Drools - tutorial on writing DSL template

Fri, 24 Oct 2008 06:34:20 GMT

Few months ago I wrote a post that describes an example that uses source DRL in conjunction with DSL template. In the current post, I want to describe and show with few examples how to write DSL template - whats allowed and whats not.

Now, having said that, I want to say that I am not planning to repeat the whole JBoss Rules manual - the Drools team done a great job. I just want to share from my personal experience, what I have come across while working with Drools when writing DSLs.

There are few upcoming changes coming in the future release of Drools (version 5) in terms of DSL. For example DSL will become more powerful in terms of regular expressions - it will be possible to include regexp in the DSL tokens. Edson Tirelli posted an article written by Matt Geis on Drools Blog, that talks about it and gives few examples.

Since I am working with Drools 4.0.7 these days, I will describe in the current post how to write DSLs for Drools 4.0.7.

Within a scope of Drools, DSL's job to map (expand) DRL expressions written in natural language into underlying programming code.

When writing DSL there several basic DO's and DONT's you should be aware of:

Don’t put closing semi-column at the end of DSL expression line:
```
[when]Message status is {1} = m : Message(status == {1});
```
Avoid different token names on the left hand side (before the “=”) and right hand side (after the “=”) of the DSL expansion:
```
[when]Message status is {3} = m:Message(status == {1})
[then]Log "{message}" = System.out.println("{bobo}");
```

DSL expansion should be on one line. You can even have several expressions on the same line, but you cannot break the line. By putting expression on a new line will cause an exception during parsing:

[when]Message id is {id} = m:Message(id == {id})
[then]LogUpdate "{2}" = System.out.println("{2}");
update(m);
[when]Message status is {s} = m:Message(status == {s})
[then]Log "{2}" = 
System.out.println("{2}");

Avoid having DSLs with the same name. It can create a confusion. Remember that DSL is parsed from top to bottom, so when two DSLs with the same name exist, the top one will apply during expansion since it will be matched first:
```
[then]SetStatus {s} = System.out.println({s});
[then]SetStatus {s} = m.setStatus({s});
```
If token has quotes on the left hand side of the DSL, then the token must have quotes on the right hand side of the DSL:
```
[then]SetMessage "{msg}" = m.setStatus("{msg}");
```

There is no room for typos:

rule "set-hello"
   when
	True
   then
	SetMessage "Hello"
end

[then]SetMessag "{msg}" = m.setStatus("{msg}");

Token names can be literal or numeric characters, or both:

[then]Print1 "{1}" = System.out.println("{1}");
[then]Print2 "{msg}" = System.out.println("{msg}");
[then]Print3 "{23msg}" = System.out.println("{23msg}");

If token on the left hand side has no quotes, and expression/function on the right hand side can accept parameter of type String, then the token can be placed between quotes on the right hand side:
```
[then]PrintInteger {1} = System.out.println("{1}");
[then]PrintInteger2 {1} = printingFunction("{1}");
```
If you want to use declared variable in right hand side, make sure it is declared on the left hand side of the rule. Remember, DSL template is ONLY a template, it is a not a place to declare variables, declaration occurs only in DRL, DSL contains the expansion. Keep in mind that declaration and usage of the variable is per-rule basis:
```
rule "set-hello"
   when
	Message
   then
	SetMessage "Hello"
end
```
```
[when]Message = m : Message() //declare and initialize 'm'
[then]SetMessage "{msg}" = m.setStatus("{msg}");
```
White spaces before the “=” and after are allowed when writing a DSL line:
```
[then]SetMessage   "{msg}"  =    m.setStatus("{msg}");
```
If you are using a function in the right hand side of the DSL of the expansion, then make sure you provide necessary imports in DRL source for all the objects the function is using. For example if your function gets a proxy to a JMS Queue from JBoss, then you have to include imports for all the objects associated with this operation, like you normally would do it in normal Java class. Also the function itself must be present in source DRL.

Left hand side of the rule, can evaluate boolean function instead of expression:

rule "CheeseType"   
   when	
	Cheese is of type "silton"   
   then	
	DoSomething
end

function boolean 
	someEvaluatingFunction(Cheese cheese,String type) {
   if (cheese.getType().equals(type))
	return true;
   else
	return false;
}

[when]Cheese is of type "{1}" = 
chz:Cheese() eval(someEvaluatingFunction(chz, "{1}"))
[then]DoSomething = System.out.println("Something");

If you interested in additional examples of the DRL+DSL, you can have a look at another short example that I wrote sometime ago. Also, please dont forget to have a look at the JBoss Rules manual that i mentioned earlier.

Cheers

Social Bookmarks :

Drools - Stop executing current agenda group and all rules

Mon, 09 Jun 2008 06:36:00 GMT

Sometimes, depends on your business rules in your application, there is a need to stop current agenda group or all rules from continuing to execute. It wont help setting a focus to another agenda group, since previous agenda will still remain in a stack. So in this post I want to show how to prevent rules in a particular agenda group from continuing to execute by clearing the agenda and also how to stop all rules totally.

Please note, in this example I am using agenda-groups to drive execution flow.

I created a short DRL file and a DSL template to demonstrate how clearing agenda and stopping of all rules can be achieved.

The DRL file:

expander template.dsl;

/*****************************************
 First default rule to kick in
******************************************/
rule "baserule"
salience 100000 
auto-focus true
agenda-group "first-group"
when
      True
then

end


/*****************************************
 Second rule to kick in 
******************************************/
rule "1"
salience 1000 
agenda-group "first-group"
when
      True
then
      Goto agenda "second-group"
end


/*****************************************
 Third rule to kick in
******************************************/
rule "2"
salience 1000 
agenda-group "second-group"
when
      True
then
      Do something   
end


/*****************************************
 Fourth rule to kick in
 
 Current rule stops agenda "second-group" 
 from continuing to execute, and the 
 focus will be returned back to 
 agenda "first-group"
******************************************/
rule "3"
salience 900 
agenda-group "second-group"
when
      True
then
      Stop agenda "second-group" //clear current agenda  
end


/*****************************************
 This rule never kicks in, since agenda
 "second-group" was cleared by rule "3"
******************************************/
rule "4"
salience 800 
agenda-group "second-group"
when
      True
then
      Do something   
end


/*****************************************
 Fifth rule to kick in

 After clearing agenda "second-group", the
 focus will be returned here 
******************************************/
rule "5"
salience 900 
agenda-group "first-group"
when
      True
then
      Do something
end


/*****************************************
 Sixth rule to kick in
 Current rule stops execution of all rules
******************************************/
rule "6"
salience 800 
agenda-group "first-group"
when
      True
then
      Stop all
end


/*****************************************
 This rule never kicks in, since all rules
 execution was stopped by rule "6" 
******************************************/
rule "7"
salience 700 
agenda-group "first-group"
when
      True
then
      Do something
end

The DSL template:

[when]True=eval(true)
[then]Do something=
      System.out.println("Doing something");
[then]Stop all=drools.halt();
[then]Goto agenda "{agenda}"=
      drools.setFocus( "{agenda}" );
[then]Stop agenda "{agenda}"=
      drools.getWorkingMemory().
		clearAgendaGroup("{agenda}");

Basically what happens is: once the execution reaches rule "3", I am calling for clearAgendaGroup() method to clear agenda, hence to remove it from the stack. As a result of the clearing, rule "4" will never be executed.

When focus is returned back to agenda "first-group", it lands on rule "5". When the execution reaches rule "6", I am calling for drools.halt() method to stop execution of all rules.

Keep in mind that in Drools 3 there is no halt() method. It came with Drools 4. If you want to achieve the above result of stopping all rules in Drools 3, you can call for drools.clearAgenda();

You noticed that I am using "drools" object and calling some methods on that object in my DSL template. Well "drools" object is actually KnowledgeHelper class, which is part of Drools library. It provides several APIs, for example method halt(), setFocus() and getWorkingMemory().

Keep in mind that I did not actually tested these particular DRL and DSL, but this example is based on real scenario that I have tested.

Comments/questions/flames are welcomed

Social Bookmarks :

Drools - working with Stateless session

Sun, 11 May 2008 00:01:00 GMT

Drools (now it is also called JBoss Rules) is an amazing open source framework which allows you to create business rules management system for your application. I got introduced to Drools while working on a project at my current company.

It is very easy to use and implement it and it is very efficient. For example instead of having dozens of if-else statements for some application business rules, you can use Drools to create a rule engine with your defined rules and pass your objects through the rule engine.

For example, in your application that deals with student objects, you can create a rule that checks whether the student has paid his fees for the next semester, if not - send him/her reminder email... etc..

In this example i want to show how to work with Stateless drools session to retrieve results from the global variable. I know that at this point its a bit not clear, so i will try to explain as I go... or you can simply visit their website, the link is under "Useful Links" section on the right hand side...

In addition to that you can always join their IRC channel #drools, the drools team is very helpful and i owe my special thanks to a fellas name mic_hat and conan there, that had a lot of patience for me ;)

For my example i prepared a simple POJO, DRL and DSL files and a test client.
DRL is the file that contains my rules. DSL is the expandable template for DRL.

Drools allow you to write your rules using plain human language in DRL, and then in DSL template you can specify to what programming code the human sentence corresponds to. The following explains what I mean:

My DRL file with 2 rules in it:

package com.test.drools.rules;

expander mydsl.dsl; 

import com.test.drools.entities.Pojo;

global java.util.List list;


rule "1"
salience 1000
auto-focus true

when
      The blog name is "Java Beans dot Asia"	    
then
      Log "The blog name was matched"
end


rule "2"
salience 900

when
      This post was created in "May"	    
then
      Log "The blog post month was matched"
end

"expander mydsl.dsl" - file name of my DSL template.
"global java.util.List list" - a global variable, which is the type of List. Global variable you can use for storing some results, log messages and even objects.
"salience" - the priority which rules should be executed first.
"auto-focus" - the rule that has auto-focus will get executed first, basically the starting point of execution.

My DSL template file for my DRL:

[condition][]The blog name is "{name}"=
	poj : Pojo( blogName == "{name}")

[condition][]This post was created in "{month}"=
	poj : Pojo( postMonth == "{month}")

[consequence][]Log "{message}"=
	list.add(new String("{message}"));

As you can see "This post was created in "arg"" will expands into "poj : Pojo( postMonth == "{month}")", where the value of "arg" will be compared to the value of postMonth variable in my POJO.

Keep in mind that you do not have to use DSL template, you can use only DRL file if you want to and have your source code there. Using the template makes your rules very readable.

My POJO:

package com.test.drools.entities;

import java.io.Serializable;

public class Pojo implements Serializable {

	private String blogName;
	private String postMonth;

	public Pojo() {

	}

	public String getBlogName() {
		return blogName;
	}

	public void setBlogName(String blogName) {
		this.blogName = blogName;
	}

	public String getPostMonth() {
		return postMonth;
	}

	public void setPostMonth(String postMonth) {
		this.postMonth = postMonth;
	}
}

My client:

package com.test.drools.client;

import java.io.IOException;
import java.io.InputStreamReader;
import java.io.Reader;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;

import org.drools.RuleBase;
import org.drools.RuleBaseFactory;
import org.drools.StatelessSession;
import org.drools.StatelessSessionResult;
import org.drools.base.CopyIdentifiersGlobalExporter;
import org.drools.compiler.DroolsError;
import org.drools.compiler.DroolsParserException;
import org.drools.compiler.PackageBuilder;
import org.drools.compiler.PackageBuilderErrors;


import com.test.drools.entities.Pojo;

public class Client {

//path to the DRL file inside my JAR
final static String DRL_URL = 
		"/com/test/drools/rules/mydrl.drl";
//path to the DSL file inside my JAR
final static String DSL_URL = 
		"/com/test/drools/rules/mydsl.dsl";

public static void main(String[] args) {

   //Instantiate and initialize the POJO.
   Pojo p1 = new Pojo();
   p1.setBlogName("Java Beans dot Asia");
   p1.setPostMonth("May");

   //Calling for private method to compile a RuleBase
   RuleBase ruleBase = getRuleBase();

   //Instantiating StatelessSession
   StatelessSession session = 
			ruleBase.newStatelessSession();

   //Setting global variable:
   //the name 'list' is the same name mentioned in DRL:
   //global java.util.List list;
   session.setGlobal("list", list);

   //specifying the global name that should be exported
   session.setGlobalExporter( 
   new CopyIdentifiersGlobalExporter( 
				new String[]{"list"} ) );

   //executeWithResults() - stores execution results in 
   //StatelessSessionResult object. That objects will 
   //contain our global variable with results, that we 
   //can use after the execution of stateless 
   //session is finished.
   StatelessSessionResult result = 
			session.executeWithResults(p1);

   //get global variable and cast back to 
   //the type of List
   List retrievedList = (List) result.getGlobal("list");

   if (retrievedList != null && 
			retrievedList.size() > 0) {

   for (Iterator i = retrievedList.iterator(); 
					i.hasNext();) {
	System.out.println((String) i.next());
   }
}

}


private static RuleBase getRuleBase() {

//Create a new package builder
PackageBuilder builder = new PackageBuilder();

try {

//call for private method to get the DRL
Reader drl = getSourceDrl();

//call for private method to get the DSL
Reader dsl = getDsl();

//Add rule package to the builder using drl and 
//dsl Reader objects
builder.addPackageFromDrl(drl, dsl);

//Check whether our DRL and DSL files had any 
//errors when trying to create a rule package. 
//If DRL and/or DSL had any errors we wont be able 
//to create a rule package and a new RuleBase.
PackageBuilderErrors errors = builder.getErrors();

DroolsError[] error = errors.getErrors();

if (error.length > 0) {
for (DroolsError err : error) {
System.out.println("Errors are: " + err.getMessage());
}
}

} catch (DroolsParserException e1) {
e1.printStackTrace();
} catch (IOException e1) {
e1.printStackTrace();
}

//Get new RuleBase object. RuleBase is where 
//we will get Stateless session object from.
RuleBase ruleBase = RuleBaseFactory.newRuleBase();

try {
//Add package with our rules to the RuleBase.
//This is when the RuleBase is actually compiled
ruleBase.addPackage(builder.getPackage());
} catch (Exception e1) {
e1.printStackTrace();
}

return ruleBase;
}

private static Reader getDsl() 
			throws IOException {
return new InputStreamReader(Client.class
.getResourceAsStream(DSL_URL));
}

private static Reader getSourceDrl() 
			throws IOException {
return new InputStreamReader(Client.class
.getResourceAsStream(DRL_URL));
}

}

I will try to give now a brief explanation what is actually happening:
When session.executeWithResults(p1); is executes, rule engine will apply the rules on a p1 POJO object. If rules will be matched, then the result will be stored in the global variable.

For example:
If value of "blogName" variable inside my p1 POJO object will be equal to "Java Beans dot Asia", then the rule#1 in my DRL will be matched, and the result "The blog name was matched" will be stored in my global List.

The final output of the program will be as follows:

"The blog name was matched"
"The blog post month was matched"

This example was very simple, I had only two rules where i did comparison of String literals. But Drools definitely has the capability to create a friendly business rule system with thousands of rules if needed, while staying user friendly for both developers and business clients. I think its worth while checking it out :)

I've included a source code and jUnit test case for this tutorial if you want to have a look at it and try it your self.

Social Bookmarks :