Chapter 3. Quick Start

Procedure 3.1. Task

1. Create a data model like the driver's license example below:

   public class Applicant {
       private String name;
       private int age;
       private boolean valid;
       // getter and setter methods here
   }
   

   Copy to Clipboard Toggle word wrap
2. Write the first rule. In this example, a rule is added to disqualify any applicant younger than 18:

   package com.company.license
   
   rule "Is of valid age"
   when
       $a : Applicant( age < 18 )
   then
       $a.setValid( false );
   end
   

   Copy to Clipboard Toggle word wrap
3. When the Applicant object is inserted into the rule engine, each rule's constraints evaluate it and search for a match. (There is always an implied constraint of "object type" after which there can be any number of explicit field constraints.)
   In the Is of valid age rule there are two constraints:

   • The fact being matched must be of type Applicant
   • The value of Age must be less than eighteen.

   $a is a binding variable. It exists to make possible a reference to the matched object in the rule's consequence (from which place the object's properties can be updated).

   Note

   Use of the dollar sign ($) is optional. It helps to differentiate between variable names and field names.

   Note

   If the rules are in the same folder as the classes, the classpath resource loader can be used to build the first knowledge base.
4. Use the KnowledgeBuilder to to compile the list of rules into a knowledge base as shown:

   KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
   kbuilder.add( ResourceFactory.newClassPathResource( "licenseApplication.drl", 
                 getClass() ), ResourceType.DRL );
   if ( kbuilder.hasErrors() ) {
       System.err.println( kbuilder.getErrors().toString() );
   }
   KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
   kbase.addKnowledgePackages( kbuilder.getKnowledgePackages() );
   

   Copy to Clipboard Toggle word wrap
   The above code snippet looks on the classpath for the licenseApplication.drl file, using the method newClassPathResource(). (The resource type is DRL, short for "Drools Rule Language".)
5. Check the KnowledgeBuilder for any errors. If there are none, you can build the session.
6. Execute the data against the rules. (Since the applicant is under the age of eighteen, their application will be marked as "invalid.")

   StatelessKnowledgeSession ksession = kbase.newStatelessKnowledgeSession();
   Applicant applicant = new Applicant( "Mr John Smith", 16 );
   assertTrue( applicant.isValid() );
   ksession.execute( applicant );
   assertFalse( applicant.isValid() );
   

   Copy to Clipboard Toggle word wrap

Procedure 3.2. Task

1. To execute rules against any object-implementing iterable (such as a collection), add another class as shown in the example code below:

   public class Applicant {
       private String name;
       private int age;
       // getter and setter methods here
   }
   
   public class Application {
       private Date dateApplied;
       private boolean valid;
       // getter and setter methods here
   }
   

   Copy to Clipboard Toggle word wrap
2. In order to check that the application was made within a legitimate time-frame, add this rule:

   package com.company.license
   
   rule "Is of valid age"
   when
       Applicant( age < 18 )
       $a : Application()     
   then
       $a.setValid( false );
   end
   
   rule "Application was made this year"
   when
       $a : Application( dateApplied > "01-jan-2009" )     
   then
       $a.setValid( false );
   end
   

   Copy to Clipboard Toggle word wrap
3. Use the JDK converter to implement the iterable interface. (This method commences with the line Arrays.asList(...).) The code shown below executes rules against an iterable list. Every collection element is inserted before any matched rules are fired:

   StatelessKnowledgeSession ksession = kbase.newStatelessKnowledgeSession();
   Applicant applicant = new Applicant( "Mr John Smith", 16 );
   Application application = new Application();
   assertTrue( application.isValid() );
   ksession.execute( Arrays.asList( new Object[] { application, applicant } ) );
   assertFalse( application.isValid() );
   

   Copy to Clipboard Toggle word wrap

   Note

   The execute(Object object) and execute(Iterable objects) methods are actually "wrappers" around a further method called execute(Command command) which comes from the BatchExecutor interface.
4. Use the CommandFactory to create instructions, so that the following is equivalent to execute( Iterable it ):

   ksession.execute( CommandFactory.newInsertIterable( new Object[] { application, applicant } ) );
   

   Copy to Clipboard Toggle word wrap
5. Use the BatchExecutor and CommandFactory when working with many different commands or result output identifiers:

   List<Command> cmds = new ArrayList<Command>();
   cmds.add( CommandFactory.newInsert( new Person( "Mr John Smith" ), "mrSmith" );
   cmds.add( CommandFactory.newInsert( new Person( "Mr John Doe" ), "mrDoe" );
   BatchExecutionResults results = ksession.execute( CommandFactory.newBatchExecution( cmds ) );
   assertEquals( new Person( "Mr John Smith" ), results.getValue( "mrSmith" ) );
   

   Copy to Clipboard Toggle word wrap

   Note

   CommandFactory supports many other commands that can be used in the BatchExecutor. Some of these are StartProcess, Query and SetGlobal.

Procedure 3.3. Task

1. Create a model of what you want to monitor. In this example involving fire alarms, the rooms in a house have been listed. Each has one sprinkler. A fire can start in any of the rooms:

   public class Room 
   {
   	private String name
   		// getter and setter methods here
   }
   
   public class Sprinkler 
   {
   	private Room room;
   	private boolean on;
   	// getter and setter methods here
   }
   
   public class Fire 
   {
   	private Room room;
   	// getter and setter methods here
   }
   
   public class Alarm 
   {
   }
   

   Copy to Clipboard Toggle word wrap
2. The rules must express the relationships between multiple objects (to define things such as the presence of a sprinkler in a certain room). To do this, use a binding variable as a constraint in a pattern. This results in a cross-product.
3. Create an instance of the Fire class and insert it into the session.
   The rule below adds a binding to Fire object's room field to constrain matches. This so that only the sprinkler for that room is checked. When this rule fires and the consequence executes, the sprinkler activates:

   rule "When there is a fire turn on the sprinkler"
   when
       Fire($room : room)
       $sprinkler : Sprinkler( room == $room, on == false )
   then
       modify( $sprinkler ) { setOn( true ) };
       System.out.println("Turn on the sprinkler for room "+$room.getName());
   end
   

   Copy to Clipboard Toggle word wrap
   Whereas the stateless session employed standard Java syntax to modify a field, the rule above uses the modify statement. (It acts much like a "with" statement.)

Procedure 3.4. Task

1. Configure a pattern featuring the keyword Not. First order logic ensures rules will only be matched when no other keywords are present. In this example, the rule turns the sprinkler off when the fire is extinguished:

   rule "When the fire is gone turn off the sprinkler"
   when
       $room : Room( )
       $sprinkler : Sprinkler( room == $room, on == true )
       not Fire( room == $room )
   then
       modify( $sprinkler ) { setOn( false ) };
       System.out.println("Turn off the sprinkler for room "+$room.getName());
   end
   

   Copy to Clipboard Toggle word wrap
2. An Alarm object is created when there is a fire, but only one Alarm is needed for the entire building no matter how many fires there might be. Not's complement, exists can now be introduced. It matches one or more instances of a category:

   rule "Raise the alarm when we have one or more fires"
   when
       exists Fire()
   then
       insert( new Alarm() );
       System.out.println( "Raise the alarm" );
   end
   

   Copy to Clipboard Toggle word wrap
3. If there are no more fires, the alarm must be deactivated. To turn it off, use Not again:

   rule "Cancel the alarm when all the fires have gone"
   when
       not Fire()
       $alarm : Alarm()
   then
       retract( $alarm );
       System.out.println( "Cancel the alarm" );
   end
   

   Copy to Clipboard Toggle word wrap
4. Use this code to print a general health status message when the application first starts and also when the alarm and all of the sprinklers have been deactivated:

   rule "Status output when things are ok"
   when
       not Alarm()
       not Sprinkler( on == true ) 
   then
       System.out.println( "Everything is ok" );
   end
   

   Copy to Clipboard Toggle word wrap
5. Store the rules in a file called fireAlarm.drl. Save this file in a sub-directory on the class-path.
6. Finally, build a knowledge base, using the new name, fireAlarm.drl:

   KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
   kbuilder.add( ResourceFactory.newClassPathResource( "fireAlarm.drl", 
   										getClass() ), ResourceType.DRL );
   										
   if ( kbuilder.hasErrors() )
   	System.err.println( kbuilder.getErrors().toString() );
   
   StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();
   

   Copy to Clipboard Toggle word wrap

Procedure 3.5. Task

1. Insert ksession.fireAllRules(). This grants the matched rules permission to run but, since there is no fire in this example, they will merely produce the health message:

   String[] names = new String[]{"kitchen","bedroom","office","livingroom"};
   Map<String,Room> name2room = new HashMap<String,Room>();
   
   for( String name: names )
   {
   	Room room = new Room( name );
   	name2room.put( name, room );
   	ksession.insert( room );
   	Sprinkler sprinkler = new Sprinkler( room );
   	ksession.insert( sprinkler );
   }
   
   ksession.fireAllRules();
   

   Copy to Clipboard Toggle word wrap
   The resulting message reads:

   > Everything is okay
   

   Copy to Clipboard Toggle word wrap
2. Create and insert two fires. (A fact handle will be kept.)
3. With the fires now in the engine, call fireAllRules(). The alarm will be raised and the respective sprinklers will be turned on:

   Fire kitchenFire = new Fire( name2room.get( "kitchen" ) );
   Fire officeFire = new Fire( name2room.get( "office" ) );
   
   FactHandle kitchenFireHandle = ksession.insert( kitchenFire );
   FactHandle officeFireHandle = ksession.insert( officeFire );
   
   ksession.fireAllRules();
   

   Copy to Clipboard Toggle word wrap
   The resulting message reads:

   > Raise the alarm
   > Turn on the sprinkler for room kitchen
   > Turn on the sprinkler for room office
   

   Copy to Clipboard Toggle word wrap
4. When the fires are extinguished, the fire objects are retracted and the sprinklers are turned off. At this point in time, the alarm is canceled and the health message displays once more:

   ksession.retract( kitchenFireHandle );
   ksession.retract( officeFireHandle );
   
   ksession.fireAllRules();
   

   Copy to Clipboard Toggle word wrap
   The resulting message reads:

   > Turn off the sprinkler for room office
   > Turn off the sprinkler for room kitchen
   > Cancel the alarm
   > Everything is okay       
   
   

   Copy to Clipboard Toggle word wrap