Chapter 20. The Java Rule Engine Application Programming Interface

Procedure 20.1. Task

1. Use the following code to load the JBoss Rules rule service provider:
   Class ruleServiceProviderClass = Class.forName("org.drools.jsr94.rules.RuleServiceProviderImpl");
2. Use the following code to register it:
   RuleServiceProviderManager.registerRuleServiceProvider( "http://jboss.com/products/rules", ruleServiceProviderClass);
3. Call to the RuleServiceProvider using the following code:
   RuleServiceProviderManager.getRuleServiceProvider("http://jboss.com/products/rules");
4. To stop the rule service, deregister it with this code:
   RuleServiceProviderManager.deregisterRuleServiceProvider( "http://jboss.com/products/rules");

Procedure 20.2. Task

1. Create a RuleExecutionSet. You can do so by using the RuleAdministrator which provides factory methods to return an empty LocalRuleExecutionSetProvider or RuleExecutionSetProvider.
2. Specify the name for the RuleExecutionSet.
3. Register the RuleExecutionSet as shown below:

   // Register the RuleExecutionSet with the RuleAdministrator
   String uri = ruleExecutionSet.getName();
   ruleAdministrator.registerRuleExecutionSet(uri, ruleExecutionSet, null);

4. Use the LocalRuleExecutionSetProvider to load a RuleExecutionSets from local sources that are not serializable, like Streams.
5. Use the RuleExecutionSetProvider to load RuleExecutionSets from serializable sources, like DOM Elements or Packages. Both the "ruleAdministrator.getLocalRuleExecutionSetProvider( null );" and the "ruleAdministrator.getRuleExecutionSetProvider( null );" (use null as a parameter).
6. The example below shoes you how to register the LocalRuleExecutionSet:

   // Get the RuleAdministration
   RuleAdministrator ruleAdministrator = ruleServiceProvider.getRuleAdministrator();
   LocalRuleExecutionSetProvider ruleExecutionSetProvider =
     ruleAdministrator.getLocalRuleExecutionSetProvider( null );
   
   // Create a Reader for the drl
   URL drlUrl = new URL("http://mydomain.org/sources/myrules.drl");
   Reader drlReader = new InputStreamReader(  drlUrl.openStream()  );
   
   // Create the RuleExecutionSet for the drl
   RuleExecutionSet ruleExecutionSet =
     ruleExecutionSetProvider.createRuleExecutionSet( drlReader, null );
   

7. You can use the "ruleExecutionSetProvider.createRuleExecutionSet( reader, null )" property to provide configuration for the incoming source. When null is passed the default is used to load the input as a drl. Allowed keys for a map are "source" and "dsl". The key "source" takes "drl" or "xml" as its value.
8. Set "source" to "drl" to load a DRL, or to "xml" to load an XML source. "xml" will ignore any "dsl" key/value settings. The "dsl" key can take a Reader or a String (the contents of the dsl) as a value. See the following dsl example:

   // Get the RuleAdministration
   RuleAdministration ruleAdministrator = ruleServiceProvider.getRuleAdministrator();
   LocalRuleExecutionSetProvider ruleExecutionSetProvider =
     ruleAdministrator.getLocalRuleExecutionSetProvider( null );
   
   // Create a Reader for the drl
   URL drlUrl = new URL("http://mydomain.org/sources/myrules.drl");
   Reader drlReader = new InputStreamReader(  drlUrl.openStream()  );
   
   // Create a Reader for the dsl and a put in the properties map
   URL dslUrl = new URL("http://mydomain.org/sources/myrules.dsl");
   Reader dslReader = new InputStreamReader( dslUrl.openStream()  );
   Map properties = new HashMap();
   properties.put( "source", "drl" );
   properties.put( "dsl", dslReader );
   
   // Create the RuleExecutionSet for the drl and dsl
   RuleExecutionSet ruleExecutionSet =
     ruleExecutionSetProvider.createRuleExecutionSet( reader, properties );
   

Procedure 20.3. Task

1. Get the runtime by accessing the RuleServiceProvider as shown:

   RuleRuntime ruleRuntime = ruleServiceProvider.getRuleRuntime();

2. To create a rule session, use one of the two RuleRuntime public constants. These are "RuleRuntime.STATEFUL_SESSION_TYPE" and "RuleRuntime.STATELESS_SESSION_TYPE", accompanying the URI to the RuleExecutionSet you wish to instantiate a RuleSession for.
3. Optionally, access the properties to specify globals.
4. The createRuleSession(...) method will return a RuleSession instance. You should cast it to StatefulRuleSession or StatelessRuleSession:

   (StatefulRuleSession) session =
     ruleRuntime.createRuleSession( uri,
                                    null,
                                    RuleRuntime.STATEFUL_SESSION_TYPE );
   session.addObject( new PurchaseOrder( "cheese" ) );
   session.executeRules();

5. When using a StatelessRuleSession, you can only call executeRules(List list) passing a list of objects, and an optional filter, the resulting objects are then returned:

   (StatelessRuleSession) session =
     ruleRuntime.createRuleSession( uri,
                                    null,
                                    RuleRuntime.STATELESS_SESSION_TYPE );
   List list = new ArrayList();
   list.add( new PurchaseOrder( "even more cheese" ) );
   
   List results = new ArrayList();
   results = session.executeRules( list );