Name: State Example
Main class: org.drools.examples.StateExampleUsingSalience
Type: java application
Rules file: StateExampleUsingSalience.drl
Objective: Demonstrates basic rule use and Conflict Resolution for rule firing priority.

Each State class has fields for its name and its current state (see org.drools.examples.State class). The two possible states for each objects are:

public class State {
    public static final int       NOTRUN   = 0;
    public static final int       FINISHED = 1;

    private final PropertyChangeSupport changes  = new PropertyChangeSupport( this );

    private String                name;
    private int                   state;

    ... setters and getters go here...
}

Ignore the PropertyChangeSupport for now, that will be explained later. In the example we create four State objects with names: A, B, C and D. Initially all are set to state NOTRUN, which is default for the used constructor. Each instance is asserted in turn into the session and then fireAllRules() is called.

State a = new State( "A" );
State b = new State( "B" );
State c = new State( "C" );
final State d = new State( "D" );

// By setting dynamic to TRUE, Drools will use JavaBean
// PropertyChangeListeners so you don't have to call update().
boolean dynamic = true;

session.insert( a,
                dynamic );
session.insert( b,
                dynamic );
session.insert( c,
                dynamic );
session.insert( d,
                dynamic );

session.fireAllRules();
session.dispose(); // Stateful rule session must always be disposed when finished

To execute the application:

And you will see the following output in the Eclipse console output:

A finished
B finished
C finished
D finished

There are four rules in total, first a Bootstrap rule fires setting A to state FINISHED which then causes B to change to state FINISHED. C and D are both dependent on B - causing a conflict which is resolved by setting salience values. First lets look at how this was executed

The best way to understand what is happening is to use the "Audit Log" feature to graphically see the results of each operation. The Audit log was generated when the example was previously run. To view the Audit log in Eclipse:

After that, the "Audit view" will look like the following screenshot.

Figure 10.4. Salience State Example Audit View

Reading the log in the "Audit View", top to down, we see every action and the corresponding changes in the working memory. This way we see that the assertion of the State "A" object with the "NOTRUN" state activates the "Bootstrap" rule, while the assertions of the other state objects have no immediate effect.

rule Bootstrap
    when
        a : State(name == "A", state == State.NOTRUN )
    then
        System.out.println(a.getName() + " finished" );
        a.setState( State.FINISHED );
end

The execution of "Bootstrap" rule changes the state of "A" to "FINISHED", that in turn activates the "A to B" rule.

rule "A to B"
    when
        State(name == "A", state == State.FINISHED )
        b : State(name == "B", state == State.NOTRUN )
    then
        System.out.println(b.getName() + " finished" );
        b.setState( State.FINISHED );
end

The execution of "A to B" rule changes the state of "B" to "FINISHED", which activates both rules "B to C" and "B to D", placing both Activations onto the Agenda. In this moment the two rules may fire and are said to be in conflict. The conflict resolution strategy allows the engine's Agenda to decide which rule to fire. As the "B to C" rule has a higher salience value (10 versus the default salience value of 0), it fires first, modifying the "C" object to state "FINISHED". The Audit view above shows the modification of the State object in the rule "A to B" which results in two highlighted activations being in conflict. The Agenda view can also be used to investigate the state of the Agenda, debug points can be placed in the rules themselves and the Agenda view opened; the screen shot below shows the break point in the rule "A to B" and the state of the Agenda with the two conflicting rules.

Figure 10.5. State Example Agenda View

rule "B to C"
        salience 10
    when
        State(name == "B", state == State.FINISHED )
        c : State(name == "C", state == State.NOTRUN )
    then
        System.out.println(c.getName() + " finished" );
        c.setState( State.FINISHED );
end

The "B to D" rule fires last, modifying the "D" object to state "FINISHED".

rule "B to D"
    when
        State(name == "B", state == State.FINISHED )
        d : State(name == "D", state == State.NOTRUN )
    then
        System.out.println(d.getName() + " finished" );
        d.setState( State.FINISHED );
end

There are no more rules to execute and so the engine stops.

Another notable concept in this example is the use of dynamic facts, which is the PropertyChangeListener part. As mentioned previously in the documentation, in order for the engine to see and react to fact's properties change, the application must tell the engine that changes occurred. This can be done explicitly in the rules, by calling the update() memory action, or implicitly by letting the engine know that the facts implement PropertyChangeSupport as defined by the Javabeans specification. This example demonstrates how to use PropertyChangeSupport to avoid the need for explicit update() calls in the rules. To make use of this feature, make sure your facts implement the PropertyChangeSupport as the org.drools.example.State class does and use the following code to insert the facts into the working memory:

// By setting dynamic to TRUE, Drools will use JavaBean
// PropertyChangeListeners so you don't have to call update().
final boolean dynamic = true;

session.insert( fact,
                dynamic );

When using PropertyChangeListeners each setter must implement a little extra code to do the notification, here is the state setter for thte org.drools.examples.State class:

public void setState(final int newState) {
    int oldState = this.state;
    this.state = newState;
    this.changes.firePropertyChange( "state",
                                     oldState,
                                     newState );
}

There are two other State examples: StateExampleUsingAgendGroup and StateExampleWithDynamicRules. Both execute from A to B to C to D, as just shown, the StateExampleUsingAgendGroup uses agenda-groups to control the rule conflict and which one fires first and StateExampleWithDynamicRules shows how an additional rule can be added to an already running WorkingMemory with all the existing data applying to it at runtime.

Agenda groups are a way to partition the agenda into groups and controlling which groups can execute. All rules by default are in the "MAIN" agenda group, by simply using the "agenda-group" attribute you specify a different agenda group for the rule. A working memory initially only has focus on the "MAIN" agenda group, only when other groups are given the focus can their rules fire; this can be achieved by either using the method setFocus() or the rule attribute "auto-focus". "auto-focus" means that the rule automatically sets the focus to it's agenda group when the rule is matched and activated. It is this "auto-focus" that enables "B to C" to fire before "B to D".

rule "B to C"
      agenda-group "B to C"
      auto-focus true       
  when
      State(name == "B", state == State.FINISHED )      
      c : State(name == "C", state == State.NOTRUN )
  then
      System.out.println(c.getName() + " finished" );
      c.setState( State.FINISHED );
      drools.setFocus( "B to D" );
end

The rule "B to C" calls "drools.setFocus( "B to D" );" which gives the agenda group "B to D" focus allowing its active rules to fire; which allows the rule "B to D" to fire.

rule "B to D"
      agenda-group "B to D"
  when
      State(name == "B", state == State.FINISHED )      
      d : State(name == "D", state == State.NOTRUN )
  then
      System.out.println(d.getName() + " finished" );
      d.setState( State.FINISHED );
end

The example StateExampleWithDynamicRules adds another rule to the RuleBase after fireAllRules(), the rule it adds is just another State transition.

rule "D to E"
  when
      State(name == "D", state == State.FINISHED )      
      e : State(name == "E", state == State.NOTRUN )
  then
      System.out.println(e.getName() + " finished" );
      e.setState( State.FINISHED );
end

It gives the following expected output:

A finished
B finished
C finished
D finished
E finished

The problem is written as a riddle:

The immediate thing about this riddle, is that a solution is not obvious (of course ! it wouldn't be a riddle otherwise !). It also isn't obvious how to write an algorithm to solve it (if it is for you - then you can take a break now, go have a coffee or someting to reward your uber intellect).

Instead of thinking about how to solve it, we can be lazy and use rules instead. So we don't attempt to solve it, we just state the problem in rules, and let the engine derive the solution.

The supporting code is in the GolfingExample.java class. There is an inner class "Golfer" which represents a golf player, it has their name, position (1 to 4 meaning left to right), and their pants color, as simple properties.

String[] names = new String[] { "Fred", "Joe", "Bob", "Tom" };
String[] colors = new String[] { "red", "blue", "plaid", "orange" };
int[] positions = new int[] { 1, 2, 3, 4 };
        
for ( int n = 0; n < names.length; n++ ) {
    for ( int c = 0; c < colors.length; c++ ) {
        for ( int p = 0; p < positions.length; p++ ) {
            session.insert( new Golfer( names[n], colors[c], positions[p]) );
        }                
    }            
}      

The above listing shows the interesting part of the supporting code. Note that we have arrays representing each name, color, and position. We then go through a nested loop inserting instances of Golfer - so in the working memory we will have all combinations of name, color and position. It is then the job of the rules to find the appropriate one.

Launching the code as a java application should yield the following output:

Fred 1 orange
Joe 2 blue
Bob 4 plaid
Tom 3 red     

This shows that the rule(s) have found a suitable solution.

The solution in rules is quite simple, it is a single rule which expresses the constraints as stated in the riddle. Effectively, we can interpret the riddle as a series of constraints on our object model. Given that we have enough "combinations" in the working memory, all we have to do is express the constraints in a rule and the engine will match it with a solution (we don't really care how it does it, as long as it works !).

There is one rule in the solution, in golf.drl, called "find solution". The rule is made up of 5 patterns, with constraints that map to items in the riddle.

$fred : Golfer( name == "Fred" )      

In the above pattern, we are simply matching a Golfer who is called fred, and binding it to a variable called $fred. All that we know is that there is a golfer called fred.

$joe : Golfer( name == "Joe",
               position == 2,
               position != $fred.position,
               color != $fred.color )      

The next pattern says that we have a golfer named Joe, in position 2 ("second in line"). Now, we also know that he must NOT be in the same position as fred (of course !) and have different color pants. So far, nothing that amazing.

$bob : Golfer( name == "Bob",
               position != $fred.position,
               position != $joe.position,
               color == "plaid",
               color != $fred.color,
               color != $joe.color )      

Refering to the above, we also know there is a golfer called Bob, who wears plaid pants - once again that all we know about him. but of course, we add in the constraints that he must be in a different position to fred, joe, and also have different colored pants.

$tom : Golfer( name == "Tom",
               position != 1,
               position != 4,
               position != $fred.position,
               position != $joe.position,
               position != $bob.position,
               color != "orange,               
               color != $fred.color,
               color != $joe.color,
               color != $bob.color )      

(referring to the above) We also know that there is a guy called Tom, who doesn't wear the Orange pants, AND he is not in position 1, or 4. Of course we also add in the other constraints (he must be in a different position to the others so far, and have a different color).

Golfer( position == ( $fred.position + 1 ),
        color == "blue",
        this in ( $joe, $bob, $tom ) )      

Finally, we know that the golfer on the right of Fred (position + 1), is in blue pants. We also add in the constraint that he must be either Joe, Bob or Tom (as Fred can't be beside himself, well he can I guess, but not in the sense we mean here !) - note the use of "this" to refer to the current pattern, we don't really care who "this" is, just who they are not. Maybe if Fred was really really happy they this wouldn't work, but lets assume otherwise for now.

Thats it ! We have expressed the rule as constraints that map to the ones expressed in the riddle, yet we haven't had to solve the riddle, the engine does that for us.

This simple example shows how you can express a problem declaratively, and let the engine solve the problem for you, by making use of combinations. This is an often useful technique, as it allows you to express rules as a statement of the problem you are trying to solve.

Of course, care must be taken. Using combinatorics like this can cause performance problems when there are large numbers of facts (eg in this case, if there were a larger number of golfers, or colors/positions etc - possibilities). When the fact count grows, the combinations the engine has to deal with can explode exponentially, making this not very efficient. However, in cases where the rules are perhaps complex, the problem is hard, but the fact numbers are relatively low, this approach can be very very useful and help you solve problems that would otherwise be very hard.

The example creates 4 customers, with their name and subscription class, it then creates 4 tickets for each of the customers, note that the ticket takes the customer in the constructor (that sets up the object relationship. The tickets and the customers are then inserted. Notice that we keep a fact handle - which we will use to notify the engine that that specific ticket changed later on. The last line has the all important fireAllRules(), which tells the engine to take action on the data it has.

Customer a = new Customer( "A",
                           "Gold" );
Customer b = new Customer( "B",
                           "Platinum" );
Customer c = new Customer( "C",
                           "Silver" );
Customer d = new Customer( "D",
                           "Silver" );

Ticket t1 = new Ticket( a );
Ticket t2 = new Ticket( b );
Ticket t3 = new Ticket( c );
Ticket t4 = new Ticket( d );

session.insert( a );
session.insert( b );
session.insert( c );
session.insert( d );

session.insert( t1 );
session.insert( t2 );
FactHandle ft3 = session.insert( t3 );
session.insert( t4 );

session.fireAllRules();

We have the "New Ticket" rule which has the highest priority (salience of 10 - the default is zero), The purpose of this is simply to log the fact that a new ticket has arrived in the system:

rule "New Ticket"
 salience 10
 when
  customer : Customer( )
  ticket : Ticket( customer == customer, status == "New" )
  then
 System.out.println( "New : " + ticket );
end    

Note that we are "joining" the ticket fact with the customer fact. It's not really needed in this case, as we don't do anything (yet) with the customer fact. If you look in the TroubleTicketExample.java, you will also see that the facts are being inserted into the engine - note that we assert BOTH Customer and Ticket object (even though the ticket belongs to a customer - this allows the engine to join the objects together how it wants - this is what is meant by "relational" programming - we let the rule engine define what the relationships are. For instance, although the code is structured so that a ticket belongs to a customer, we may be interested in looking at tickets from different customers of the same type in the future).

If we run the rules, we should expect that the "New Ticket" rule will be activated for all tickets, so looking at the audit log view (by opening the file which was saved automatically when the rules were run):

Figure 10.10. Audit view

Referring to the above audit log, we can see each customer asserted, but nothing happens. As soon as the first ticket gets asserted, it joins it with the customer, and creates some activations: one is the "new ticket" rule, the other is for the appropriate priority (which we will show below). Note that items in the above view do not mean the rule fired at that point.

Also, don't forget to use "fireAllRules()" - a common mistake ! (In this case we are using a statefull session, so this is necessary).

If we run the rules, we should expect that the "New Ticket" rule will be activated for all tickets, so looking at the audit log view (by opening the file which was saved automatically when the rules were run):

Figure 10.11. Audit view

Referring to the above audit log, we can see each customer asserted, but nothing happens. As soon as the first ticket gets asserted, it joins it with the customer, and creates some activations: one is the "new ticket" rule, the other is for the appropriate priority (which we will show below). Note that items in the above view do not mean the rule fired at that point.

All the wonderful platinum customers have to get great service, so first thing to note is that as soon as a ticket arrives, we escalate if it is for a platinum customer:

rule "Platinum Priority"
 when
  customer : Customer( subscription == "Platinum" )
  ticket : Ticket( customer == customer, status == "New" )
 then;
  ticket.setStatus( "Escalate" );
  update( ticket );
end      

Here we are joining Ticket to customer again (customer == customer), but we are also checking that the customer is "Platinum". When this is the case, we set the ticket status to "Escalate" and call update (which tells the engine that the ticket has changed).

For silver and gold class, its a similar story to platinum:

rule "Silver Priority"
 duration 3000
 when
  customer : Customer( subscription == "Silver" )
  ticket : Ticket( customer == customer, status == "New" )
 then
  ticket.setStatus( "Escalate" );
  update( ticket );
end

rule "Gold Priority"
 duration 1000
 when
  customer : Customer( subscription == "Gold" )
  ticket : Ticket( customer == customer, status == "New" )
 then
  ticket.setStatus( "Escalate" );
  update( ticket );
end   

In this case, note the use of "duration XXX" - XXX is the number of milliseconds to wait to check that this rule holds true. Should it do so, after XXX milliseconds, then the action takes effect. So in the above case, after 3 seconds the "Silver" priority kicks in, but after 1 second "Gold" does. In both cases the tickets are escalated (just like with platinum. This is what we mean by temporal rules (rules that take effect over time).

The actual escalation of a ticket happens in a rule:

rule "Escalate"
 when
  customer : Customer( )
  ticket : Ticket( customer == customer, status == "Escalate" )
 then
  sendEscalationEmail( customer, ticket );
end     

In this case, the action is to call a function which sends an email (the function is defined down the bottom of the drl file). This rule reacts to the rules which update the ticket and set its status to escalate.

Running the example (by launching the TroubleTicket.java class as an application) should yield the output:

New : [Ticket [Customer D : Silver] : New]
New : [Ticket [Customer C : Silver] : New]
New : [Ticket [Customer B : Platinum] : New]
New : [Ticket [Customer A : Gold] : New]
Email : [Ticket [Customer B : Platinum] : Escalate]
[[ Sleeping 5 seconds ]]
Email : [Ticket [Customer A : Gold] : Escalate]
Done : [Ticket [Customer C : Silver] : Done]
Email : [Ticket [Customer D : Silver] : Escalate]
[[ awake ]]    

Figure 10.12. Audit log

Referring to the above audit log, we can see the events as they happen. Once the rules start firing, the first items are the "Activation Executed" for the new tickets, as expected (they do nothing, just log the fact). Note the "Activation executed" item for the platinum ticket - that is the next one to go (remember it has the default salience, so it happens after the "New ticket" rule, but otherwise it is immediate - there is no "duration" delay for it). The platinum activation results in a Object modification (which is the escalation) - this in turn creates an activation record for the "escalate ticket" rule - which is what we wanted. Straight after that it executes the action to escalate the ticket.

The next event to occur is due to the:

t3.setStatus( "Done" );

session.update( ft3,
                t3 );

in the code (outside of rules) - this simulates a customer service officer maarking a ticket as done (and of course, uses the fact handle we kept from before). This results in a cancelled activation (as we no longer have a New Silvert customer ticket - it is done) and a new activation to log the fact it was done.

In all the excitement, in parallel the engine has been watching the time pass, and it happens that the Gold tickets start to escalate, and then silver (as expected).

Open the PricingRuleDTExample.java and execute it as a Java application. It should produce the following console output:

Cheapest possible
BASE PRICE IS: 120
DISCOUNT IS: 20     

The code to the execute the example is very similar to the other examples. The rules are loaded, the facts inserted and a stateless session is used. What is different is how the rules are obtained:

SpreadsheetCompiler compiler = new SpreadsheetCompiler();
String drl = compiler.compile(getSpreadsheetStream(), InputType.XLS);

Note the use of the SpreadsheetCompiler class. It is what takes the XLS (as a binary InputStream to the XLS file), and outputs ordinary DRL (which is then dealt with in the usual way). You can (if you like) also print out the DRL. If you use the BRMS, all this is of course taken care of for you.

There are 2 facts used in this example, Driver, and Policy. Both are used with their default values. The Driver is 30 years old, has had no prior claims and currently has a risk profile of LOW. The Policy being applied for is COMPREHENSIVE, and the policy has not yet been approved.

In this decision table, each row is a rule, and each column is a condition or an action.

Figure 10.13. Decision table configuration

Referring to the above, we have the RuleSet declaration, which provides the package name. There are also other optional items you can have here, such as Variables for global variables, and Imports for importing classes. In this case, the namespace of the rules is the same as the fact classes we are using, so we can omit it.

Moving further down, we can see the RuleTable declaration. The name after this (Pricing bracket) is used as the prefix for all the generated rules. Below that, we have CONDITION or ACTION - this indicates the purpose of the column (ie does it form part of the condition, or an action of a rule that will be generated).

You can see there is a Driver which is spanned across 3 cells, this means the template expressions below it apply to that fact. So we look at the drivers age range (which uses $1 and $2 with comma separated values), locationRiskProfile, and priorClaims in the respective columns. In the action columns, we are setting the policy base price, and then logging a message.

Figure 10.14. Base price calculation

Referring to the above, we can see there are broad category brackets (indicated by the comment in the left most column). As we know the details of our driver and their policy, we can tell (with a bit of thought) that they should match row number 18, as they have no prior accidents, and are 30 years old. This gives us a base price of 120.

Figure 10.15. Discount calculation

Referring to the above, we are seeing if there is any discount we can give our driver. Based on the Age bracket, number of priot claims, and the policy type, a discount is provided. In our case, the drive is 3, with no priors, and they are applying for COMPREHENSIVE, this means we can give a discount of 20%. Note that this is actually a separate table, but in the same worksheet. This different templates apply.

It is important to note that decision tables generate rules, this means they aren't simply top down logic, but more a means to capture data that generate rules (this is a subtle difference that confuses some people). The evaluation of the rules is not "top down" necessarily, all the normal indexing and mechanics of the rule engine still apply.

The following is a listing of the interesting parts that are used to launch the example:

Customer mark = new Customer( "mark",
                              0 );
session.insert( mark );
Product shoes = new Product( "shoes",
                             60 );
session.insert( shoes );
Product hat = new Product( "hat",
                           60 );
session.insert( hat );
session.insert( new Purchase( mark,
                              shoes ) );
FactHandle hatPurchaseHandle = session.insert( new Purchase( mark,
                                                             hat ) );
session.fireAllRules();
session.retract( hatPurchaseHandle );
System.out.println( "Customer mark has returned the hat" );
session.fireAllRules();      

Refering the the above listing, we can see there is a Customer ("mark"), and there are 2 Products ("shoes" and "hat") which are available for Purchase. In this case, a Purchase combines a customer with a product (and a product has a price attribute).

Note that after we fireAllRules(), we then retract the purchase of a hat (but leave the purchase of shoes in). Running the example as a java application should see the following output:

Customer mark just purchased hat
Customer mark just purchased shoes
Customer mark now has a shopping total of 120.0
Customer mark now has a discount of 10
Customer mark has returned the hat
Customer mark now has a discount of 0      

We want to give discounts to customers who purchase stuff of enough value. This discount could also be removed should the customer decide not to purchase enough to fall within the threshold.

rule "Purchase notification"
    salience 10

 when
  $c : Customer()
  $p : Purchase( customer == $c)	    
 then
     System.out.println( "Customer " + $c.name + " just purchased " + $p.product.name );
end 

rule "Discount removed notification"
 when
     $c : Customer()
  not Discount( customer == $c )
 then
  $c.discount = 0 ;
  System.out.println( "Customer " + $c.name + " now has a discount of " + $c.discount );
end

rule "Discount awarded notification"
 when
     $c : Customer()
     $d : Discount( customer == $c )
 then
  System.out.println( "Customer " + $c.name + " now has a discount of " + $d.amount );
end      

The "Purchase notification" rule simply makes note of the purchase event for a given customer. The "Discount removed notification" rule removes the customer discount (by checking for the non existence of a discount for that customer). The "Discount awarded notification" simply makes not of the fact that the discount was applied.

Calculating the discount is done with a single rule, using the higher order logic of "accumulate".

rule "Apply 10% discount if total purcahses is over 100"
 no-loop true
 dialect "java"
    when
      $c : Customer()
      $i : Double(doubleValue  > 100) from accumulate ( Purchase( customer == $c, $price : product.price ), 
                                                            sum( $price ) )
    then
      $c.setDiscount( 10 );
      insertLogical( new Discount($c, 10) );
      System.out.println( "Customer " + $c.getName() + " now has a shopping total of " + $i );
end      

An interesting part of this rule is the "accumulate": this is saying to accumulate a total (sum) of the $price of a product (product.price) for all Purchase facts that belong to the customer ($c). The result of this is a Double. The rule then checks to see if this total is greater then 100. If it is, it applies the discount (of 10), and then inserts a logical fact of the Discount object.

The purpose of the logical insertion of the Discount, is to automatically retract the Discount object should the total of the purchases not add up to > 100 (when the LHS is no longer satisified, restract the resulting logical assertions - this is what is meant by "truth maintenance"). The act of inserting the Discount, causes the "Discount awarded notification" rule to activate. However, should the discount fact be retracted, the "Discount removed notification" will activate, resulting in the customers discount being wiped out. In the example you can see this happen, as after the first fireAllRules(), a purchase is retracted, causing the total to fall below 100, which means the conditions that satisfied the "Apply 10% discount..." rule no longer apply, hence the logical fact of "Discount" is automatically retracted.

Name: Pet Store 
Main class: org.drools.examples.PetStore
Type: Java application
Rules file: PetStore.drl
Objective: Demonstrate use of Agenda Groups, Global Variables and integration with a GUI (including callbacks from within the Rules)

The Pet Store example shows how to integrate Rules with a GUI (in this case a Swing based Desktop application). Within the rules file, it shows how to use agenda groups and auto-focus to control which of a set of rules is allowed to fire at any given time. It also shows mixing of Java and MVEL dialects within the rules, the use of accumulate functions and calling of Java functions from within the ruleset.

Like the rest of the the samples, all the Java Code is contained in one file. The PetStore.java contains the following principal classes (in addition to several minor classes to handle Swing Events)

Much of the Java code is either JavaBeans (simple enough to understand) or Swing based. We will touch on some Swing related points in the this tutorial , but a good place to get more Swing component information is http://java.sun.com/docs/books/tutorial/uiswing/available at the Sun Swing website.<citebiblioid></citebiblioid>

There are two important Rules related pieces of Java code in Petstore.java.

PackageBuilder builder = new PackageBuilder();
builder.addPackageFromDrl( new InputStreamReader( 
PetStore.class.getResourceAsStream( "PetStore.drl" ) ) );
RuleBase ruleBase = RuleBaseFactory.newRuleBase();
ruleBase.addPackage( builder.getPackage() );

//RuleB
Vector stock = new Vector();
stock.add( new Product( "Gold Fish",5 ) );
stock.add( new Product( "Fish Tank", 25 ) );
stock.add( new Product( "Fish Food", 2 ) );

//The callback is responsible for populating working memory and
// fireing all rules
PetStoreUI ui = new PetStoreUI( stock, new CheckoutCallback( ruleBase ) );
ui.createAndShowGUI();

This code above loads the rules (drl) file from the classpath. Unlike other examples where the facts are asserted and fired straight away, this example defers this step to later. The way it does this is via the second last line where the PetStoreUI is created using a constructor the passes in the Vector called stock containing products , and an instance of the CheckoutCallback class containing the RuleBase that we have just loaded.

The actual Javacode that fires the rules is within the CheckoutCallBack.checkout() method. This is triggered (eventually) when the 'Checkout' button is pressed by the user.

public String checkout(JFrame frame, List items) throws FactException {           
    Order order = new Order();

    //Iterate through list and add to cart
    for ( int i = 0; i < items.size(); i++ ) {
        order.addItem( new Purchase( order, (Product) items.get( i ) ) );
    }

    //add the JFrame to the ApplicationData to allow for user interaction
    WorkingMemory workingMemory = ruleBase.newStatefulSession();
    workingMemory.setGlobal( "frame", frame );
    workingMemory.setGlobal( "textArea",  this.output );

    workingMemory.insert( new Product( "Gold Fish", 5 ) );
    workingMemory.insert( new Product( "Fish Tank", 25 ) );
    workingMemory.insert( new Product( "Fish Food",  2 ) );
    workingMemory.insert( new Product( "Fish Food Sample", 0 ) );            
           
    workingMemory.insert( order );
    workingMemory.fireAllRules();

    //returns the state of the cart
    return order.toString();
}

Two items get passed into this method; A handle to the JFrame Swing Component surrounding the output text frame (bottom of the GUI if / when you run the component). The second item is a list of order items; this comes from the TableModel the stores the information from the 'Table' area at the top right section of the GUI.

The for() loop transforms the list of order items coming from the GUI into the Order JavaBean (also contained in the PetStore.java file). Note that it would be possible to refer to the Swing dataset directly within the rules, but it is better coding practice to do it this way (using Simple Java Objects). It means that we are not tied to Swing if we wanted to transform the sample into a Web application.

It is important to note that all state in this example is stored in the Swing components, and that the rules are effectively stateless. Each time the 'Checkout' button is pressed, this code copies the contents of the Swing TableModel into the Session / Working Memory.

Within this code, there are nine calls to the working memory. The first of these creates a new workingMemory (statefulSession) from the Rulebase - remember that we passed in this Rulebase when we created the CheckoutCallBack class in the main() method. The next two calls pass in two objects that we will hold as Gl obal variables in the rules - the Swing text area and Swing frame that we will use for writing messages later.

More inserts put information on products into the working memory, as well as the order list. The final call is the standard e fireAllRules(). Next, we look at what this method causes to happen within the Rules file.

package org.drools.examples

import org.drools.WorkingMemory
import org.drools.examples.PetStore.Order
import org.drools.examples.PetStore.Purchase
import org.drools.examples.PetStore.Product
import java.util.ArrayList
import javax.swing.JOptionPane;

import javax.swing.JFrame 
        
global JFrame frame 
global javax.swing.JTextArea textArea
 
dialect "mvel"

The first part of the PetStore.drl file contains the standard package and import statement to make various Java classes available to the rules. We've seen the dialect been defaulted to "mvel" before in other examples. What is new are the two globals frame and textArea. These hold references to the Swing JFrame and Textarea components that were previous passed by the Java code calling the setGlobal() method. Unlike normal variables in Rules , which expire as soon as the rule has fired, Global variables retain their value for the lifetime of the (Stateful in this case) Session.

The next extract (below) is from the end of the PetStore.drl file. It contains two functions that are referenced by the rules that we will look at shortly.

function void doCheckout(JFrame frame, WorkingMemory workingMemory) {
    Object[] options = {"Yes",
                        "No"};
                            
    int n = JOptionPane.showOptionDialog(frame,
                                         "Would you like to checkout?",
                                         "",
                                         JOptionPane.YES_NO_OPTION,
                                         JOptionPane.QUESTION_MESSAGE,
                                         null,
                                         options,
                                         options[0]);

    if (n == 0) {
        workingMemory.setFocus( "checkout" );
    }   
}

function boolean requireTank(JFrame frame, WorkingMemory workingMemory, Order order, Product fishTank, int total) {
    Object[] options = {"Yes",
                        "No"};
                            
    int n = JOptionPane.showOptionDialog(frame,
                                         "Would you like to buy a tank for your " + total + " fish?",
                                         "Purchase Suggestion",
                                         JOptionPane.YES_NO_OPTION,
                                         JOptionPane.QUESTION_MESSAGE,
                                         null,
                                         options,
                                         options[0]);
                                             
    System.out.print( "SUGGESTION: Would you like to buy a tank for your "
                      + total + " fish? - " );

    if (n == 0) {
        Purchase purchase = new Purchase( order, fishTank );
        workingMemory.insert( purchase );
        order.addItem( purchase );
        System.out.println( "Yes" );
    } else {
        System.out.println( "No" );
    }      
    return true;
}

Having these functions in the rules file makes the PetStore sample more compact - in real life you probably have the functions in a file of their own (within the same rules package), or as a static method on a standard Java class (and import them using the import function my.package.Foo.hello syntax).

The above functions are

We'll see later the rules that call these functions.The next set of examples are from the PetStore rules themselves. The first extract is the one that happens to fire first (partly because it has the auto-focus attibute set to true).

// insert each item in the shopping cart into the Working Memory 
rule "Explode Cart"
    agenda-group "init"
    auto-focus true    
    salience 10
    dialect "java"
when
    $order : Order( grossTotal == -1 )
    $item : Purchase() from $order.items
then
   insert( $item );
   drools.setFocus( "show items" );
   drools.setFocus( "evaluate" );
end

This rule matches against all orders that do not yet have an Order.grossTotal calculated . It loops for each purchase item in that order. Some of the Explode Cart Rule should be familiar ; the rule name, the salience (suggesting of the order that the rules should be fired in) and the dialect set to java. There are three new items:

The next two listings shows the rules within the show items and evaluate agenda groups. We look at them in the order that they are called.

rule "Show Items"
    agenda-group "show items"
    dialect "mvel"
when
    $order : Order( )
    $p : Purchase( order == $order )
then
   textArea.append( $p.product + "\n");
end

The show items agenda-group has only one rule, also called Show Items (note the difference in case). For each purchase on the order currently in the working memory (session) it logs details to the text area (at the bottom of the GUI). The textArea variable used to do this is one of the Global Variables we looked at earlier.

The evaluate Agenda group also gains focus from the explode cart rule above. This Agenda group has two rules (below) Free Fish Food Sample and Suggest Tank.

// Free Fish Food sample when we buy a Gold Fish if we haven't already  bought 
// Fish Food and dont already have a Fish Food Sample
rule "Free Fish Food Sample"
    agenda-group "evaluate"
    dialect "mvel"
when
    $order : Order()
    not ( $p : Product( name == "Fish Food") && Purchase( product == $p ) )
    not ( $p : Product( name == "Fish Food Sample") && Purchase( product == $p ) )
    exists ( $p : Product( name == "Gold Fish") && Purchase( product == $p ) )
    $fishFoodSample : Product( name == "Fish Food Sample" );
then
    System.out.println( "Adding free Fish Food Sample to cart" );
    purchase = new Purchase($order, $fishFoodSample);
    insert( purchase );
    $order.addItem( purchase ); 
end

// Suggest a tank if we have bought more than 5 gold fish and dont already have one
rule "Suggest Tank"
    agenda-group "evaluate"
    dialect "java"
when
    $order : Order()
    not ( $p : Product( name == "Fish Tank") && Purchase( product == $p ) )
    ArrayList( $total : size > 5 ) from collect( Purchase( product.name == "Gold Fish" ) )
    $fishTank : Product( name == "Fish Tank" )
then
    requireTank(frame, drools.getWorkingMemory(), $order, $fishTank, $total); 
end

The Free Fish Food Sample rule will only fire if

If the rule does fire, it creates a new product (Fish Food Sample), and adds it to the Order in working memory.

The Suggest Tank rule will only fire if

If the rule does fire, it calls the requireTank() function that we looked at earlier (showing a Dialog to the user, and adding a Tank to the order / working memory if confirmed). When calling the requireTank() function the rule passes the global frame variable so that the function has a handle to the Swing GUI.

The next rule we look at is do checkout.

rule "do checkout"
    dialect "java"
    when
    then
        doCheckout(frame, drools.getWorkingMemory());
end

The do checkout rule has no agenda-group set and no auto-focus attribute. As such, is is deemed part of the default (MAIN) agenda-group - the same as the other non PetStore examples where agenda groups are not used. This group gets focus by default when all the rules/agenda-groups that explicity had focus set to them have run their course.

There is no LHS to the rule, so the RHS will always call the doCheckout() function. When calling the doCheckout() function the rule passes the global frame variable so the function has a handle to the Swing GUI. As we saw earlier, the doCheckout() function shows a confirmation dialog to the user. If confirmed, the function sets the focus to the checkout agenda-group, allowing the next lot of rules to fire.

rule "Gross Total"
    agenda-group "checkout"
    dialect "mvel"
when
   $order : Order( grossTotal == -1)
   Number( total : doubleValue ) from accumulate( Purchase( $price : product.price ),
                 sum( $price ) )
then
    modify( $order ) { grossTotal = total };
    textArea.append( "\ngross total=" + total + "\n" );
end

rule "Apply 5% Discount"
    agenda-group "checkout"
dialect "mvel"
when
   $order : Order( grossTotal >= 10 && < 20 )
then
   $order.discountedTotal = $order.grossTotal * 0.95;
   textArea.append( "discountedTotal total=" + $order.discountedTotal + "\n" );
end


rule "Apply 10% Discount"
    agenda-group "checkout"
dialect "mvel"
when
   $order : Order( grossTotal >= 20 )
then
   $order.discountedTotal = $order.grossTotal * 0.90;
   textArea.append( "discountedTotal total=" + $order.discountedTotal + "\n" );
end

There are three rules in the checkout agenda-group

Now we've run through what happens in the code, lets have a look at what happens when we run the code for real. The PetStore.java example contains a main() method, so it can be run as a standard Java application (either from the command line or via the IDE). This assumes you have your classpath set correctly (see the start of the examples section for more information).s.

The first screen that we see is the Pet Store Demo. It has a List of available products (top left) , an empty list of selected products (top right), checkout and reset buttons (middle) and an empty system messages area (bottom).

Figure 10.16. Figure 1 - PetStore Demo just after Launch

To get to this point, the following things have happened:

Clicking on various products from the list might give you a screen similar to the one below.

Figure 10.17. Figure 2 - PetStore Demo with Products Selected

Note that no rules code has been fired here. This is only swing code, listening for the mouse click event, and added the clicked product to the TableModel object for display in the top right hand section (as an aside , this is a classic use of the Model View Controller - MVC - design pattern).

It is only when we press the Checkout that we fire our business rules, in roughly the same order that we walked through the code earlier.

Figure 10.18. Figure 3 - Do we want to buy a fish tank?

Figure 10.19. Figure 4 - Petstore Demo after all rules have fired.

Should we choose, we could add more System.out calls to demonstrate this flow of events. The current output of the console fo the above sample is as per the listing below.

Adding free Fish Food Sample to cart 
SUGGESTION: Would you like to buy a tank for your 6 fish? - Yes

Todo : Add Audit and Agenda Views for this sample.

Sudoku is a logic-based number placement puzzle. The objective is to fill a 9x9 grid so that each column, each row, and each of the nine 3x3 zones contains the digits from 1 to 9 once and only once.

The puzzle setter provides a partially completed grid and the puzzle solver's task is to complete the grid with these constraints.

The general strategy to solve the problem is to ensure that when you insert a new number it should be unique in that particular region(blocks) and also in that particular row and column.

See

URL: http://en.wikipedia.org/wiki/Sudoku

for a more detailed description.

Download and install drools-examples as described above and then execute java org.drools.examples.sudoku.Main (this example requires Java 5).

A window will be displayed with a relatively simple partially filled grid.

Click on the Solve button and the Drools-based engine will fill out the remaining values. The console will display detailed information of the rules which are executing to solve the puzzle in a human readable form.

Rule #3 determined the value at (4,1) could not be 4 as this value already exists in the same column at (8,1) Rule #3 determined the value at (5,5) could not be 2 as this value already exists in the same row at (5,6) Rule #7 determined (3,5) is 2 as this is the only possible cell in the column that can have this value Rule #1 cleared the other PossibleCellValues for (3,5) as a ResolvedCellValue of 2 exists for this cell. Rule #1 cleared the other PossibleCellValues for (3,5) as a ResolvedCellValue of 2 exists for this cell. ... Rule #3 determined the value at (1,1) could not be 1 as this value already exists in the same zone at (2,1) Rule #6 determined (1,7) is 1 as this is the only possible cell in the row that can have this value Rule #1 cleared the other PossibleCellValues for (1,7) as a ResolvedCellValue of 1 exists for this cell. Rule #6 determined (1,1) is 8 as this is the only possible cell in the row that can have this value

Once all of the activated rules for the solving logic have executed, the engine executes a second rule base to check that the solution is complete and valid. In this case it is, and the "Solve" button is disabled and displays the text "Solved (1052ms)".

The example comes with a number of grids which can be loaded and solved. Click on File->Samples->Medium to load a more challenging grid. Note that the solve button is enabled when the new grid is loaded.

Click on the "Solve" button again to solve this new grid.

Now, let us load a Sudoku grid that is deliberately invalid. Click on File->Samples->!DELIBERATELY BROKEN!. Note that this grid starts with some issues, for example the value 5 appears twice in the first row.

Nevertheless, click on the "Solve" button to apply the solving rules to this invalid Grid. Note that the "Solve" button is relabelled to indicate that the resulting solution is invalid.

In addition, the validation rule set outputs all of the issues which are discovered to the console.

There are two cells on the same column with the same value at (6,0) and (4,0)
There are two cells on the same column with the same value at (4,0) and (6,0)
There are two cells on the same row with the same value at (2,4) and (2,2)
There are two cells on the same row with the same value at (2,2) and (2,4)
There are two cells on the same row with the same value at (6,3) and (6,8)
There are two cells on the same row with the same value at (6,8) and (6,3)
There are two cells on the same column with the same value at (7,4) and (0,4)
There are two cells on the same column with the same value at (0,4) and (7,4)
There are two cells on the same row with the same value at (0,8) and (0,0)
There are two cells on the same row with the same value at (0,0) and (0,8)
There are two cells on the same column with the same value at (1,2) and (3,2)
There are two cells on the same column with the same value at (3,2) and (1,2)
There are two cells in the same zone with the same value at (6,3) and (7,3)
There are two cells in the same zone with the same value at (7,3) and (6,3)
There are two cells on the same column with the same value at (7,3) and (6,3)
There are two cells on the same column with the same value at (6,3) and (7,3)   
      

We will look at the solving rule set later in this section, but for the moment we should note that some theoretically solvable solutions can not be solved by the engine as it stands. Click on File->Samples->Hard 3 to load a sparsely populated Grid.

Now click on the "Solve" button and note that the current rules are unable to complete the grid, even though (if you are a Sudoku afficiando) you may be able to see a way forward with the solution.

At the present time, the solving functionality has been achieved by the use of ten rules. This rule set could be extended to enable the engine to tackle more complex logic for filling grids such as this.

The Java source code can be found in the /src/main/java/org/drools/examples/sudoku directory, with the two DRL files defining the rules located in the /src/main/rules/org/drools/examples/sudoku directory.

org.drools.examples.sudoku.swing contains a set of classes which implement a framework for Sudoku puzzles. Note that this package does not have any dependencies on the Drools libraries. SudokuGridModel defines an interface which can be implemented to store a Sudoku puzzle as a 9x9 grid of Integer values, some of which may be null, indicating that the value for the cell has not yet been resolved. SudokuGridView is a Swing component which can visualise any implementation of SudokuGridModel. SudokuGridEvent and SudokuGridListener are used to communicate state changes between the model and the view, events are fired when a cell's value is resolved or changed. If you are familiar with the model-view-controller patterns in other Swing components such as JTable then this pattern should be familiar. SudokuGridSamples provides a number of partially filled Sudoku puzzles for demo purposes.

org.drools.examples.sudoku.rules contains an implementation of SudokuGridModel which is based on Drools. Two POJOs are used, both of which extend AbstractCellValue and represent a value for a specific cell in the grid, including the row and column location of the cell, an index of the 3x3 zone the cell is contained in and the value of the cell. PossibleCellValue indicates that we do not currently know for sure what the value in a cell is. There can be 2-9 PossibleCellValues for a given cell. ResolvedCellValue indicates that we have determined what the value for a cell must be. There can only be 1 ResolvedCellValue for a given cell. DroolsSudokuGridModel implements SudokuGridModel and is responsible for converting an initial two dimensional array of partially specified cells into a set of CellValue POJOs, creating a working memory based on solverSudoku.drl and inserting the CellValue POJOs into the working memory. When the solve() method is called it calls fireAllRules() on this working memory to try to solve the puzzle. DroolsSudokuGridModel attaches a WorkingMemoryListener to the working memory, which allows it to be called back on insert() and retract() events as the puzzle is solved. When a new ResolvedCellValue is inserted into the working memory, this call back allows the implementation to fire a SudokuGridEvent to its SudokuGridListeners which can then update themselves in realtime. Once all the rules fired by the solver working memory have executed, DroolsSudokuGridModel runs a second set of rules, based on validatorSudoku.drl which works with the same set of POJOs to determine if the resulting grid is a valid and full solution.

org.drools.examples.sudoku.Main implements a Java application which hooks the components desribed above together.

org.drools.examples.sudoku contains two DRL files. solverSudoku.drl defines the rules which attempt to solve a Sudoku puzzle and validator.drl defines the rules which determin whether the current state of the working memory represents a valid solution. Both use PossibleCellValue and ResolvedCellValue POJOs as their facts and both output information to the console as their rules fire. In a real-world situation we would insert() logging information and use the WorkingMemoryListener to display this information to a user rather than use the console in this fashion.

We start with the validator rules as this rule set is shorter and simpler than the solver rule set.

The first rule simply checks that no PossibleCellValue objects remain in the working memory. Once the puzzle is solved, only ResolvedCellValue objects should be present, one for each cell.

The other three rules each match all of the ResolvedCellValue objects and store them in thenew_remote_sitetes instance variable $resolved. They then look respectively for ResolvedCellValues that contain the same value and are located, respectively, in the same row, column or 3x3 zone. If these rules are fired they add a message to a global List of Strings describing the reason the solution is invalid. DroolsSudokoGridModel injects this List before it runs the rule set and checks whether it is empty or not having called fireAllRules(). If it is not empty then it prints all the Strings in the list and sets a flag to indicate that the Grid is not solved.

Now let us look at the more complex rule set used to solve Sudoku puzzles.

Rule #1 is basically a "book-keeping" rule. Several of the other rules insert() ResolvedCellValues into the working memory at specific rows and columns once they have determined that a given cell must have a certain value. At this point, it is important to clear the working memory of any inserted PossibleCellValues at the same row and column with invalid values. This rule is therefore given a higher salience than the remaining rules to ensure that as soon as the LHS is true, activations for the rule move to the top of the agenda and are fired. In turn this prevents the spurious firing of other rules due to the combination of a ResolvedCellValue and one or more PossibleCellValues being present in the same cell. This rule also calls update() on the ResolvedCellValue, even though its value has not in fact been modified to ensure that Drools fires an event to any WorkingMemoryListeners attached to the working memory so that they can update themselves - in this case so that the GUI can display the new state of the grid.

Rule #2 identifies cells in the grid which have only one possible value. The first line of the when caluse matches all of the PossibleCellValue objects in the working memory. The second line demonstrates a use of the not keyword. This rule will only fire if no other PossibleCellValue objects exist in the working memory at the same row and column but with a different value. When the rule fires, the single PossibleCellValue at the row and column is retracted from the working memory and is replaced by a new ResolvedCellValue at the same row and column with the same value.

Rule #3 removes PossibleCellValues with a given value from a row when they have the same value as a ResolvedCellValue. In other words, when a cell is filled out with a resolved value, we need to remove the possibility of any other cell on the same row having this value. The first line of the when clause matches all ResolvedCellValue objects in the working memory. The second line matches PossibleCellValues which have both the same row and the same value as these ResolvedCellValue objects. If any are found, the rule activates and, when fired retracts the PossibleCellValue which can no longer be a solution for that cell.

Rules #4 and #5 act in the same way as Rule #3 but check for redundant PossibleCellValues in a given column and a given zone of the grid as a ResolvedCellValue respectively.

Rule #6 checks for the scenario where a possible cell value only appears once in a given row. The first line of the LHS matches against all PossibleCellValues in the working memory, storing the result in a number of local variables. The second line checks that no other PossibleCellValues with the same value exist on this row. The third to fifth lines check that there is not a ResolvedCellValue with the same value in the same zone, row or column so that this rule does not fire prematurely. Interestingly we could remove lines 3-5 and give rules #3,#4 and #5 a higher salience to make sure they always fired before rules #6,#7 and #8. When the rule fires, we know that $possible must represent the value for the cell so, as in Rule #2 we retract $possible and replace it with the equivalent, new ResolvedCellValue.

Rules #7 and #8 act in the same way as Rule #2 but check for single PossibleCellValues in a given column and a given zone of the grid respectively.

Rule #9 represents the most complex currently implemented rule. This rule implements the logic that, if we know that a pair of given values can only occur in two cells on a specific row, (for example we have determined the values of 4 and 6 can only appear in the first row in cells 0,3 and 0,5) and this pair of cells can not hold other values then, although we do not know which of the pair contains a four and which contains a six we know that the 4 and the 6 must be in these two cells and hence can remove the possibility of them occuring anywhere else in the same row (phew!). TODO: more detail here and I think the rule can be cleaned up in the DRL file before fully documenting it.

Rules #10 and #11 act in the same way as Rule #9 but check for the existance of only two possible values in a given column and zone respectively.

To solve harder grids, the rule set would need to be extended further with more complex rules that encapsulated more complex reasoning.

There are a number of ways in which this example could be developed. The reader is encouraged to consider these as excercises.

Name: Number Guess 
Main class: org.drools.examples.NumberGuessExample
Type: java application
Rules file: NumberGuess.drl
Objective: Demonstrate use of Rule Flow to organise Rules

The "Number Guess" example shows the use of RuleFlow, a way of controlling the order in which rules are fired. It uses widely understood workflow diagrams to make clear the order that groups of rules will be executed.

final PackageBuilder builder = new PackageBuilder();

builder.addPackageFromDrl( new InputStreamReader( 
         ShoppingExample.class.getResourceAsStream( "NumberGuess.drl" ) ) );
builder.addRuleFlow( new InputStreamReader( 
         ShoppingExample.class.getResourceAsStream( "NumberGuess.rfm" ) ) );

final RuleBase ruleBase = RuleBaseFactory.newRuleBase();
ruleBase.addPackage( builder.getPackage() );

The creation of the package, and the loading of the rules (using the addPackageFromDrl() method ) is the same as the previous examples. There is a additional line to add the RuleFlow (NumberGuess.rfm) as you have the option of specifying different ruleflows for the same RuleBase. Otherwise the RuleBase is created in the same manner as before .

final StatefulSession session = ruleBase.newStatefulSession();

session.insert( new GameRules( 100,  5 ) );
session.insert( new RandomNumber() );
session.insert( new Game() );

session.startProcess( "Number Guess" );
session.fireAllRules();

session.dispose();

Once we have a RuleBase we can use it to obtain a stateful session. Into our session we insert our facts (standard Java Objects). For simplicity in this sample, these classes are all contained within our NumberGuessExample.java file. The GameRules class provides the maximum range and the number of guesses allowed. The RandomNumber class automatically generates a number between 0 and 100 and makes it available to our rules after insertion (via the getValue() method). The Game class keeps track of the guesses we have made before, and the number of guesses we have made.

Note that before we call the standard fireAllRules() method, we also start the process that we loaded earlier (via the startProcess() method). We explain where to obtain the parameter we pass ("Number Guess" - the id of the ruleflow) when we talk about the RuleFlow file and the graphical RuleFlow editor below.

Before we finish we our Java code , we note that In 'real life' we would examine the final state of the objects (e.g. how many guesses it took, so that we could add it to a high score table). For this example we are content to ensure the working memory session is cleared by calling the dispose() method.

Figure 10.21. RuleFlow for the NumberGuess Example

If you open the NumberGuess.rf file open in the Drools IDE (and have the JBoss Rules extensions installed correctly in Eclipse) you should see the above diagram, similar to a standard flowchart. Its icons are similar (but not exactly the same) as the JBoss jBPM workflow product. Should you wish to edit the diagram, a menu of available components should be available to the left of the diagram in the IDE, which is call the pallete. This diagram is saved in a (almost human) readable xml format, using xstream.

If it is not already open, ensure the properties view is visible in the IDE. It can opened by selecting Window -> Show View -> Other and then select the Properties view. If you do this before you select any item on the RuleFlow (or click on blank space in the RuleFlow) you should be presented with the following set of properties.

Figure 10.22. Properties for the Number Guess RuleFlow

Keep an eye on the properties view as we progress through the example RuleFlow as it gives valuable information. In this case it provides us with the ID of the RuleFlow process that we used in our earlier code example when we called session.startprocess().

To give an overview of each of the node types (boxes) in the NumberGuess RuleFlow.

These various nodes work together with the Rules to make the Number Guess game work. For example, the "Guess" RuleFlowGroup allows only the rule "Get user Guess" to fire (details below) as only that Rule has a matching attribute of ruleflow-group "Guess"

rule "Get user Guess"
 ruleflow-group "Guess"
 no-loop
 when    
     $r : RandomNumber()
     rules : GameRules( allowed : allowedGuesses )
     game : Game( guessCount < allowed )
     not ( Guess() )
 then
     System.out.println( "You have " + ( rules.allowedGuesses - game.guessCount ) 
     + " out of " + rules.allowedGuesses + " guesses left.\nPlease enter your guess 
     from 0 to " + rules.maxRange );
        br = new BufferedReader( new InputStreamReader( System.in ) );
        modify ( game ) { guessCount = game.guessCount + 1 }
        i = br.readLine();        
    insert( new Guess( i ) );
end

The rest of this rule is fairly standard : The LHS (when) section of the rule states that it will be activated for each RandomNumber object inserted into the working memory where guessCount is less than the allowedGuesses ( read from the GameRules Class) and where the user has not guessed the correct number.

The RHS (consequence, then) prints a message to the user, then awaits user input from System.in. After getting this input (as System.in blocks until the <return> key is pressed) it updates/modifes the guess count, the actual guess and makes both available in the working memory.

The rest of the Rules file is fairly standard ; the package declares the dialect is set to MVEL, various Java classes are imported. In total, there are five rules in this file:

One point of integration between the standard Rules and the RuleFlow is via the 'ruleflow-group' attribute on the rules (as dicussed above). A second point of integration between the Rules File (drl) and the Rules Flow .rf files is that the Split Nodes (the blue ovals) can use values in working memory (as updated by the Rules) to decide which flow of action to take. To see how this works click on the "Guess Correct Node" ; then within the properties view, open the constraints editor (the button at the right that appears once you click on the 'Constraints' property line). You should see something similar to the Diagram below.

Figure 10.23. Edit Constraints for the GuessCorrect Node

Click on 'Edit' beside 'To node Too High' and you see a dialog like the one below. The values in the 'Textual Editor' follow the standard Rule Format (LHS) and can refer to objects in working memory. The consequence (RHS) is that the flow of control follows this node (i.e. To node Too high') if the LHS expression evaluates to true.

Figure 10.24. Constraints Editor for the GuessCorrect Node / value too high

Since the NumberGuess.java example contains a main() method, it can be run as a standard Java application (either from the command line or via the IDE). A typical game might result in the interaction below (the numbers in bold are typed in by the user).

You have 5 out of 5 guesses left.
Please enter your guess from 0 to 100
50
Your guess was too high
You have 4 out of 5 guesses left.
Please enter your guess from 0 to 100
25
Your guess was too low
You have 3 out of 5 guesses left.
Please enter your guess from 0 to 100
37
Your guess was too low
You have 2 out of 5 guesses left.
Please enter your guess from 0 to 100
44
Your guess was too low
You have 1 out of 5 guesses left.
Please enter your guess from 0 to 100
47
Your guess was too low
You have no more guesses
The correct guess was 48 

A summary of what is happening in this sample is:

Miss Manners is throwing a party and being the good host she wants to arrange good seating. Her initial design arranges everyone in male female pairs, but then she worries about people have things to talk about; what is a good host to do? So she decides to note the hobby of each guest so she can then arrange guests in not only male and female pairs but also ensure that a guest has someone to talk about a common hobby, from either their left or right side.

Figure 10.25. Miss Manners' Guests

10.1.13.1.2. Miss Manners Execution Flow

After the first Seating arrangement has been assigned a depth-first recursion occurs which repeatedly assigns correct Seating arrangements until the last seat is assigned. Manners uses a Context instance to control execution flow; the activity diagram is partitioned to show the relation of the rule execution to the current Context state.

Figure 10.26. Manners Activity Diagram

The BRMS has many GUI editors, and textual editors. This discusses a few example rules using some of the GUI features:

Figure 10.31. Guided editor

The above example shows the guided editor in action. This is a slightly more complex example, as a few bound variables are used. We are binding "$driver" to the Driver fact, and also binding driverId to the id field of the driver (which is then used in the SupplementalInfo fact - to join the driverId with the actual driver id). Note the use of the ruleflow-group to specify what step of the processing this rule applies to.

Figure 10.32. DSL Editor

The above shows the editor using a DSL. In this case the "guided editor" was used - this is not a text area, but only provides text boxes to "fill in the blanks" as specified in the DSL configuration. Note you can also use text based DSLs where there is not this restriction.

Insurance, in law and economics, is a form of risk management primarily used to hedge against the risk of a contingent loss. Insurance is defined as the equitable transfer of the risk of a loss, from one entity to another, in exchange for a premium. Insurer, in economics, is the company that sells the insurance. Insurance rate is a factor used to determine the amount, called the premium, to be charged for a certain amount of insurance coverage. Risk management, the practice of appraising and controlling risk, has evolved as a discrete field of study and practice.

If you have a poor driving record, you may need to look into high risk auto insurance. Accidents increase these rates as well. If you have a low experience for example less than 3 years as a licensed driver, insurance companies believe that the chances that you will be involved in a traffic accident are higher than someone more expert.

Who you are also plays a factor. Men are considered more of a risk than women. Teens are considered more of a risk than adults as well if you have some younger driver in family like your 20 years old son.

rule "Young male single driver"
ruleflow-group "risk assessment"
when
 $driver : Driver( genre == Driver.MALE, age < 25, maritalState == Driver.SINGLE )
then 
 $driver.updateInsuranceFactor(1.6);
end

rule "no expert driver"
ruleflow-group "risk assessment"
when
 $driver : Driver ( licenceYears < 3 )
then
 $driver.updateInsuranceFactor(1.2);
end

Extra coverage over glasses, additional car and accessories, like your expansive "pimped" sound system will increase your insurance final price, not the risk factor.

ruleflow-group "insurancecalcule"
salience 20
when
 not Rejection()
 $driver : Driver ( driverID : id )
 $access : AccessoriesCoverage ( driverId == driverID)
 $policy : Policy( approved == true )
then
 $policy.setInsurancePrice( $policy.getInsurancePrice() + 
  ($access.getAlarmSystemValue() * 0.10) + 
  ($access.getArmorValue() * 0.20) +
  ($access.getSoundSystemValue() * 0.30 ));

This example uses the previously explained RuleFlow feature, the following diagram gives you an overview of the insurance factor and calculate logic: As you can see, we first calculate the insurance factor, if the driver matches with some rejection condition we don't execute the group that contains the Policy price calculus, just returning and not approved policy

ruleflow-group "insurancecalcule"
salience 10
when
 not Rejection()
 $driver : Driver(ifactor : insuranceFactor)
 $policy : Policy( approved == true, bp : basePrice, ip : insurancePrice )
then
 $policy.setInsurancePrice((bp * ifactor) + ip);

Figure 10.33. The insurance rule flow

After running and packing you are able to deploy the war into your application server, just following the previous instructions for BRMS, then point your browser to the example url, that should be something like this http://localhost:8080/drools-insurance. Just play around the example and change some values and press the execute button, after the rules fired the result will be displayed in the bottom of the page.

Figure 10.34. The insurance web page