Object models, vocabularies, and parameters from a Java XOM

Business Rules Embedded supports generation of BOMs from JAR files. It can also use the BOM to generate a vocabulary for a locale.

A Java XOM works by defining the object model as Java classes that are then placed in a JAR. This JAR file is loaded into the ObjectModelBuilder to create the default BOM against which rules can be written. The JAR file must be on the class path of the calling application, and also on the class path of the embedded rule engine in order for the object model to be executed.

In Business Rules Embedded, to generate a BOM from a JAR file, you describe the application domain model through Java classes in a JAR file. You then pass this file to ObjectModelBuilder by calling the ObjectModelBuilder.addJarFile method, which takes a JAR file as a parameter. Only JAR files (standard Java archive files with the .jar file name extension) are supported. ObjectModelBuilder makes a Java XOM from the JAR file, and from this generates a BOM. The Business Rules Embedded can also generate a vocabulary for a locale (VOC) from the BOM.

Example

Here is a sample JAR file to use as the basis of a Java XOM:

package com.company.rules.customer;
public class Customer {
   String name = "";
		
   public String getName() {
      return name;
   }
   public void setName(String name) {
      this.name = name;
   }
}

You pass the JAR file to ObjectModelBuilder by using the addJarFile method. Given the example JAR file shown here, the Business Rules Embedded API creates the BOM class com.company.rules.customer.Customer. The default vocabulary locale, Locale.US, for this class defines the concept com.company.rules.customer.Customer that contains the fact of type name. The Business Rules Embedded API automatically generates the name of the concept and the fact types from the BOM class name and instance variable names. This generation is not specific to a locale. In a French business rule, for example, name as defined in the Customer class would be used, and not the local word nom.

Parameters

You use the RuleLanguageService API to add parameters.

Here is an example for the Customer class:

// Define a parameter specifying the parameter type, parameter name, 
// verbalization and locale in RuleLanguageService.
ruleLanguageService.addParameter("com.company.rules.customer.Customer",
         "cust", "the customer", locale);

You author rulesets in the same way as you do with models that are based on an XML schema.

Parameters serve two related purposes:

They define the variables that the rules can reference and reason about.
They determine the signature of the ruleset. The signature describes the list of parameters that are required to execute the ruleset.
Business Rules Embedded supports only INOUT parameters: the client instantiates parameters, rules in the rule engine might modify the parameters, and the parameters return to the client.

Deployment and execution

Use IlrRuleService to deploy and execute rulesets from a Java XOM. XMLRuleService can be used only for a model with an XML schema.

// Create the rule service (do not use XMLRuleService implementation).
// The rule service is recommended to be a singleton in the runtime
// environment.
   IlrRuleService ruleService = new IlrRuleService(new PrintWriter(System.out));

The deployment of models that are based on a Java XOM follows the same logic as for models that are based on an XML schema.

To execute a rule that is based on a Java XOM, the code must pass an instance of the Java XOM class.

Consider a rule that is based on the Customer class:

if the name of 'the customer' contains "Smith" 
then print "Hello John!";

The code that calls the IlrRuleService instance for execution must pass in an instance of the Customer Java class, and state that the object is bound to the parameter name cust.

// Ruleset execution needs to have access to the same object model.
// Create the parameter for execution.
Customer cust = new Customer();
cust.setName("John Smith");
// Instantiate input parameters as Map
Map <String, Object>  params = new HashMap<String, Object>();

params.put( "cust", cust);

The code that executes the ruleset and retrieves the execution session response is same as when you use a model that is based on an XML schema.

// Execute with Rule Service by specifying the ruleset path,
// the input parameter which is a Map of user-supplied
// input request to executable name.  In this sample, we also set
// true for trace argument to enable trace.

// The execution result is returned as a session response.
IlrSessionResponse response = ruleService.executeRuleset(path, params, true);

The session response returns the INOUT parameter of the Customer instance for the parameter name cust. The instance can be modified by rules, but in this example, the rule issues a print statement instead.

The execution output returns the system console output where the rule prints the response "Hello John!"

// Retrieve the output parameters from response for the parameter name 
cust = (Customer) response.getOutputParameters().get("cust");
// Retrieve ruleset execution output from response
String output = response.getRulesetExecutionOutput();


// Should get a response "Hello John!" for customer "John Smith" after rule execution
System.out.println("Customer name: " + cust.getName());
System.out.println("Response     : " + output);

Remember: It is important to add the Java XOM classes to the class path, and also to synchronize the Java XOM JAR file that is passed to the ObjectModelBuilder. addJarFile method if the Java XOM changes.

Parameter usage analysis

Business Rules Embedded supports parameter usage analysis. The user can declare a set of parameters as available for rule authoring, but only the parameters that are used by the rules are declared in the ruleset signature.

Sample Java API test

A sample file, JavaApiTest, is delivered under the <InstallDir>/rules-sdk/test directory. It demonstrates the end to end lifecycle of a ruleset that is based on a Java XOM when you use the Business Rules Embedded API.