JBoss Rules 5 Reference Guide

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

Procedure 3.6. Task

• To prevent a rule from outputting a huge amount of cross-products, you should constrain the cross-products themselves. Do this using the variable constraint seen below:

  rule
  when
      $room : Room()
      $sprinkler : Sprinkler( room == $room )
  then
      System.out.println( "room:" + $room.getName() +
                          " sprinkler:" + $sprinkler.getRoom().getName() );
  end
  

  Copy to Clipboard Toggle word wrap
  The following output will be displayed:

  room:office sprinkler:office
  room:kitchen sprinkler:kitchen
  room:livingroom sprinkler:livingroom
  room:bedroom sprinkler:bedroom

  Copy to Clipboard Toggle word wrap

Procedure 3.7. Task

1. In this example we will use a bus pass issuing system. See the code snippet below:

   rule "Issue Child Bus Pass" when
     $p : Person( age < 16 )
   then
     insert(new ChildBusPass( $p ) );
   end
    
   rule "Issue Adult Bus Pass" when
     $p : Person( age >= 16 )
   then
     insert(new AdultBusPass( $p ) );
   end

   Copy to Clipboard Toggle word wrap
2. Insert the insertLogical property to provide inference:

   rule "Infer Child" when
       $p : Person( age < 16 )
   then
       insertLogical( new IsChild( $p ) )
   end
   rule "Infer Adult" when
       $p : Person( age >= 16 )
   then
       insertLogical( new IsAdult( $p ) )
   end

   Copy to Clipboard Toggle word wrap
3. Re-enter the code to issue the passes. These two configurations can also be logically inserted, as the TMS supports chaining of logical insertions for a cascading set of retracts:

   rule "Issue Child Bus Pass" when
     $p : Person( )
          IsChild( person == $p )
   then
       insertLogical(new ChildBusPass( $p ) );
   end
    
   rule "Issue Adult Bus Pass" when
     $p : Person( age >= 16 )
          IsAdult( person =$p )
   then
       insertLogical(new AdultBusPass( $p ) );
   end

   Copy to Clipboard Toggle word wrap
   Now when the person changes from being 15 to 16, both the IsChild fact and the person's ChildBusPass fact are automatically retracted.
4. Optionally, insert the not conditional element to handle notifications. (In this example, a request for the returning of the pass.) When the TMS automatically retracts the ChildBusPass object, this rule triggers and sends a request to the person:

   rule "Return ChildBusPass Request "when
     $p : Person( )
          not( ChildBusPass( person == $p ) )
   then
       requestChildBusPass( $p );
   end

   Copy to Clipboard Toggle word wrap

Procedure 5.1. Task

1. Open the integration code that is calling the rule engine.
2. Obtain your emailService object and then set it in the working memory.
3. In the DRL, declare that you have a global of type emailService and give it the name "email".
4. In your rule consequences, you can use things like email.sendSMS(number, message).

   Warning

   Globals are not designed to share data between rules and they should never be used for that purpose. Rules always reason and react to the working memory state, so if you want to pass data from rule to rule, assert the data as facts into the working memory.

   Important

   Do not set or change a global value from inside the rules. We recommend to you always set the value from your application using the working memory interface.

Procedure 5.2. Task

1. Open the KnowledgeBuilderFactory.
2. Create a new default configuration.
3. Enter this into the configuration:

   KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();

   Copy to Clipboard Toggle word wrap
   The first parameter is for properties and is optional. If left blank, the default options will be used. The options parameter can be used for things like changing the dialect or registering new accumulator functions.
4. To add a KnowledgeBuilder with a custom ClassLoader, use this code:

   KnowledgeBuilderConfiguration kbuilderConf = KnowledgeBuilderFactory.newKnowledgeBuilderConfiguration(null, classLoader );
   KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder(kbuilderConf);
   

   Copy to Clipboard Toggle word wrap

Procedure 5.3. Task

1. Resources of any type can be added iteratively. Below, a DRL file is added. The Knowledge Builder can handle multiple namespaces, so you can combine resources regardless of their namespace:

   kbuilder.add( ResourceFactory.newFileResource( "/project/myrules.drl" ),
                 ResourceType.DRL);
   

   Copy to Clipboard Toggle word wrap
2. Check the compilation results after each resource addition. The KnowledgeBuilder can report compilation results of 3 different severities: ERROR, WARNING and INFO.
   • An ERROR indicates that the compilation of the resource failed. You should not add more resources or retrieve the Knowledge Packages if there are errors. getKnowledgePackages() returns an empty list if there are errors.
   • WARNING and INFO results can be ignored, but are available for inspection nonetheless.

Procedure 5.4. Task

1. Use the API to load your ChangeSet.
2. Use this code to access the ChangeSet XML:

   kbuilder.add( ResourceFactory.newUrlResource( url ), ResourceType.CHANGE_SET );
   

   Copy to Clipboard Toggle word wrap

Procedure 6.1. Task

1. To configure it using system properties or configuration files, insert the following properties:

   // sets the severity of rule updates
   drools.kbuilder.severity.duplicateRule = <INFO|WARNING|ERROR>
   // sets the severity of function updates
   drools.kbuilder.severity.duplicateFunction = <INFO|WARNING|ERROR>
   

   Copy to Clipboard Toggle word wrap
2. To use the API to change the severities, use this code:

   KnowledgeBuilderConfiguration kbconf = ...
   
   // sets the severity of rule updates to error
   kbconf.setOption( KBuilderSeverityOption.get( "drools.kbuilder.severity.duplicateRule", ResultSeverity.ERROR ) ); 
   // sets the severity of function updates to error
   kbconf.setOption( KBuilderSeverityOption.get( "drools.kbuilder.severity.duplicateFunction", ResultSeverity.ERROR ) );
   

   Copy to Clipboard Toggle word wrap

Procedure 6.2. Task

1. Use this default configuration to create a new KnowledgeBase:

   KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();

   Copy to Clipboard Toggle word wrap
2. If a custom class loader was used with the KnowledgeBuilder to resolve types not in the default class loader, then that must also be set on the KnowledgeBase. The technique for this is the same as with the KnowledgeBuilder and is shown below:

   KnowledgeBaseConfiguration kbaseConf =
       KnowledgeBaseFactory.createKnowledgeBaseConfiguration( null, cl );
   KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase( kbaseConf );

   Copy to Clipboard Toggle word wrap

Procedure 6.3. Task

• To add KnowledgePackages to a KnowledgeBase, use this code:

  Collection<KnowledgePackage> kpkgs = kbuilder.getKnowledgePackages();
  
  KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
  kbase.addKnowledgePackages( kpkgs );

  Copy to Clipboard Toggle word wrap
  The addKnowledgePackages(kpkgs) method can be called iteratively to add additional knowledge.