7 Working with Rules SDK Decision Point API

7.1.1 Introduction to Decision Point API

The Decision Point API provides a concise way to execute rules. Most users create Oracle Business Rules artifacts, including data model elements, rules, Decision Tables, and rulesets using the Rules Designer extension to Oracle JDeveloper. Thus, most users do not need to work directly with the engine, storage, or editing parts of Rules SDK.

To work with the Rules SDK Decision Point package you need to understand three important classes:

• DecisionPoint: is a helper class that follows the factory design pattern to create instances of DecisionPointInstance. In most applications there should be one DecisionPoint object that is shared by all application threads. A caller uses the getInstance() method of DecisionPoint to get an instance of DecisionPointInstance which can be used to call the defined Decision Point.

• DecisionPointBuilder: follows the Builder design pattern to construct a Decision Point.

• DecisionPointInstance: users call invoke() in this class to assert facts and execute a decision function.

The DecisionPoint classes support a fluent interface model so that methods can be chained together. For more information, see

http://www.martinfowler.com/bliki/FluentInterface.html

A Decision Point manages several aspects of rule execution, including:

• Use of oracle.rules.rl.RuleSession objects

• Reloading of a dictionary when the dictionary is updated

To create a Decision Point in a Java application you need the following:

• Either the name of a dictionary to be loaded from an MDS repository or a pre-loaded oracle.rules.sdk2.dictionary.RuleDictionary instance.

• The name of a decision function stored in the specified dictionary.

7.1.2 How to Obtain the Car Rental Sample Application

This chapter shows a car rental application that demonstrates the use of Rules SDK and the Decision Point API. You can obtain the sample application in a ZIP file, CarRentalApplication.zip. This ZIP contains a complete JDeveloper application and project.

The source code for Oracle Business Rules-specific samples is available online at

http://www.oracle.com/technology/sample_code/products/rules

For SOA samples online visit

http://www.oracle.com/technology/sample_code/products/soa

To work with the sample unzip CarRentalApplication.zip into an appropriate directory. The car rental application project contains a rules dictionary and several Java examples using Rules SDK.

7.1.3 How to Open the Car Rental Sample Application and Project

The Car Rental sample application shows you how to work with the Rules SDK Decision Point API.

To open the car rental sample application:

1. Start Oracle JDeveloper.

2. Open the car rental application in the directory where you unzipped the sample. For example, from the File menu select Open... and in the Open dialog navigate to the CarRentalApplication folder.

3. In the Open dialog select CarRentalApplication.jws and click Open.

4. In the Application Navigator, expand the CarRentalApplication, expand Application Sources and Resources. This displays the Oracle Business Rules dictionary named CarRental.rules and several Java source files.

7.2.1 How to Create Data Model Elements for Use with a Decision Point

You need the following to add to a decision function when you create an application with a Decision Point.

• A dictionary containing data model elements that you use to create rules or Decision Tables and when working with ADF Business Components fact types, you need to add links for the Decision Point support dictionary. For more information, see Chapter 2, "Working with Data Model Elements". For more information, see Chapter 10, "Working with Oracle Business Rules and ADF Business Components".

• A dictionary containing fact definitions. For more information, see Chapter 3, "Working with Facts and Bucketsets".

To view the data model in the supplied car rental sample application:

1. In Rules Designer, click the Facts navigation tab.

2. Select the Java Facts tab, as shown in Figure 7-1.

   The Java Facts tab shows four fact types imported, in addition to the fact types provided as built-in to the dictionary.

   The Driver Java Fact is imported from the Driver Java class in the project.

   The Denial Java Fact is imported from Denial Java class in the project.

   The LicenseType and VehicleType facts are imported from the nested enum classes defined in the Driver class.

   Figure 7-1 Defined Java Facts for the Car Rental Sample Application

   
   Description of "Figure 7-1 Defined Java Facts for the Car Rental Sample Application"
   
   

When you use a Decision Point with Rules SDK, you call a decision function in a specified dictionary. The decision function that you call can contain one or more rulesets that are executed as part of the Decision Point.

To view the ruleset in the supplied car rental sample application:

1. In Rules Designer, expand the CarRentalApplication.

2. In the CarRentalApplication, expand Resources.

3. Double-click the CarRental.rules.

7.2.2 How to View a Decision Function to Call from the Decision Point

When you work with the Decision Point API you use decision functions to expose an Oracle Business Rules dictionary. For more information on decision functions, see Chapter 6, "Working with Decision Functions".

To view the decision function in the car rental sample application:

1. In Rules Designer, click the Decision Functions navigation tab. This displays the available decision functions in the CarRental dictionary, as shown in Figure 7-2.

   Figure 7-2 Car Rental Sample Decision Function

   
   Description of "Figure 7-2 Car Rental Sample Decision Function"
   
   

2. Select the row with CarRentalDecisionFunction and double-click the decision function icon. This opens the Edit Decision Function dialog as shown in Figure 7-3.

   The decision function Inputs table includes a single argument for a Driver fact type.

   The decision function Outputs table includes a single argument for a Denial fact type.

   The decision function Rulesets and Decision Functions area shows Denial Rules:if-then in the Selected box.

   Figure 7-3 Car Rental Decision Function for the Car Rental Sample Application

   
   Description of "Figure 7-3 Car Rental Decision Function for the Car Rental Sample Application"
   
   

7.2.3 How to Create Rules or Decision Tables for the Decision Function

The car rental sample includes two rulesets, one with IF/THEN rules and another containing a Decision Table. You can use either IF/THEN rules or Decision Tables or both in your application if you are using a Decision Point.

To view the rules in the car rental sample application:

1. In Rules Designer click the Denial Rules:if-then ruleset, as shown in Figure 7-4.

   Figure 7-4 Ruleset with IF/THEN Rules for the Car Rental Sample Application

   
   Description of "Figure 7-4 Ruleset with IF/THEN Rules for the Car Rental Sample Application"
   
   

The Denial Rules:if-then ruleset includes two rules:

• under age: this rule defines the minimum age of the driver. The rule compares the Driver instance age property to the global Minimum driver age. If the driver is under this age, then a new Denial fact is asserted. A call to the decision function collects this Denial fact, as defined in its output. The rule also calls a user-defined function, audit, to provide some auditing output about why the Denial is created.

• too many accidents: this rule defines an upper threshold for the number of accidents a driver can have before a rental for the driver is denied. The rule also calls a user-defined function, audit, to provide some auditing output about why the Denial is created.

To view the Decision Table in the car rental application:

1. In Rules Designer, click the Denial Rules:decision table ruleset, as shown in Figure 7-5.

Figure 7-5 Ruleset with Decision Table for the Car Rental Sample Application

Description of "Figure 7-5 Ruleset with Decision Table for the Car Rental Sample Application"

7.2.4 What You Need to Know About Using Car Rental Sample with a Decision Table

The car rental sample application includes the Denial Rules: decision table ruleset. To switch to use a Decision Table in the supplied decision function sample, move the Denial Rules:if-then from the Selected area in the decision function and add the Denial Rules: decision table ruleset, which uses a Decision Table to define similar rules, as shown in Figure 7-6.

Figure 7-6 Decision Function for Car Rental Sample with Decision Table Ruleset

Description of "Figure 7-6 Decision Function for Car Rental Sample with Decision Table Ruleset"

7.3.1 How to Add a Decision Point Using Decision Point Builder

To use a Decision Point you create a DecisionPoint instance using DecisionPointBuilder, as shown in Example 7-1.

    static {
        try {
            // specifying the Decision Function and a pre-loaded
            // RuleDictionary instance 
            m_decisionPoint =  new DecisionPointBuilder()
                                .with(DF_NAME)
                                .with(loadRuleDictionary())
                                .build();
        } catch (SDKException e) {
            System.err.println("Failed to build Decision Point: " + e.getMessage());
            e.printStackTrace();
        }
    }

Example 7-1 shows the DecisionPointBuilder supports a fluent interface pattern, so all methods can easily be chained together when you create a Decision Point. The three most common methods for configuring the Decision Point with DecisionPointBuilder are overloaded to have the name with(). Each with() method takes a single argument of type RuleDictionary, DictionaryFQN, or String. The DecisionPointBuilder also supports similar set and get methods: getDecisionFunction(), setDecisionFunction(), getDictionary(), setDictionary(), getDictionaryFQN(), setDictionaryFQN().

This chain shown in Example 7-1 includes the following steps:

1. The first step is to create a DecisionPointBuilder instance with code such as the following:

   new DecisionPointBuilder()
   

2. The with() method using a String argument defines the name of the decision function that the Decision Point executes. Calling this method is mandatory.

   .with(DF_NAME)
   

   The DF_NAME specifies the name of the decision function you define for your application. For example for the sample car rental application DF_NAME is defined in CarRental.java as CarRentalDecisionFunction.

3. Call only one of the other two with() methods. In this case the sample code uses a pre-loaded Rule Dictionary instance, containing the specified decision function. The loadDictionary() method loads an instance of RuleDictionary from a file. Example 7-2 shows the loadDictionary() method. For more information, see Section 7.3.2, "How to Use a Decision Point with a Pre-loaded Dictionary".

   .with(loadRuleDictionary())
   

4. Call the build() method to construct and return a DecisionPoint instance.

The DecisionPoint instance is shared among all instances of the application, which is why it is a static attribute and created in a static block. Another way of initializing the DecisionPoint would be to initialize the m_decisionPoint attribute with a static method that created and returned a DecisionPoint instance.

7.3.2 How to Use a Decision Point with a Pre-loaded Dictionary

Example 7-2 shows the loadRuleDictionary() method that loads an instance of RuleDictionary from a file.

When reading or writing a dictionary directly from a file as shown in Example 7-2, ensure to set the encoding to UTF-8. If this is not done, Unicode characters used in the dictionary are corrupted. The UTF-8 option must be set explicitly in the FileInputStream or OutputStreamWriter constructor. Do not use Java classes such as FileReader and FileWriter, as these classes always use the platform default encoding which is usually an ASCII variant rather than a Unicode variant.

private static RuleDictionary loadRuleDictionary(){ 
        RuleDictionary dict = null; 
        BufferedReader reader = null; 
        try { 
            reader = new BufferedReader( 
                        new InputStreamReader( 
                            new FileInputStream( 
                                new File(DICT_LOCATION)), "UTF-8")); 
            dict = RuleDictionary.readDictionary(reader, 
                                                 new 
DecisionPointDictionaryFinder(null)); 
 
            List<SDKWarning> warnings = new ArrayList<SDKWarning>(); 
 
            dict.update(warnings); 
            if (warnings.size() > 0) { 
                System.err.println("Validation warnings: " + warnings); 
            } 
        } catch (SDKException e){ 
            System.err.println(e); 
        } catch (FileNotFoundException e){ 
            System.err.println(e); 
        } catch (IOException e){ 
            System.err.println(e); 
        } finally { 
            if (reader != null) { try { reader.close(); } catch (IOException 
ioe) {ioe.printStackTrace();}} 
        } 
        return dict; 
    } 

7.3.3 How to Use Executor Service to Run Threads with Decision Point

The car rental sample allows you to use Oracle Business Rules and simulate multiple concurrent users. Example 7-3 shows use of the Java ExecutorService interface to execute multiple threads that invoke the Decision Point. The ExecutorService is not part of the Rules SDK Decision Point API.

        ExecutorService exec = Executors.newCachedThreadPool();
        List<Driver> drivers = createDrivers();
 
        for (int i = 0; i < NUM_CONCURRENT; i++) {
            Driver driver = drivers.get(i % drivers.size());
            exec.execute(new DriverCheckerRunnable(driver));
        }

Example 7-3 includes the following code for the sample application:

• Create the Executor Service:

  ExecutorService exec = Executors.newCachedThreadPool();
  

• Call method createDrivers(), defined in CarRental.java, to create a list of Driver instances.

  List<Driver> drivers = createDrivers();
  

• A loop through a list of Driver instances to fill the driver list with drivers.

• A loop to start multiple threads from DriverCheckerRunnable instances. These instances open a Decision Point and run the rules on each driver. For information on this code, see Section 7.3.4, "How to Create and Use Decision Point Instances".

Example 7-4 shows the code that waits for the threads to complete.

        try {
            exec.awaitTermination(5, TimeUnit.SECONDS);
        } catch (InterruptedException e) {
            e.printStackTrace();
        }
        exec.shutdown();
    }

7.3.4 How to Create and Use Decision Point Instances

The DriverCheckerRunnable instances call the checkDriver() method. Example 7-5 shows the checkDriver() method that is defined in CarRentalWithDecisionPoint. The checkDriver() method handles invoking Decision Point with a Driver instance.

public class CarRentalWithDecisionPoint extends CarRental {
 
    protected static DecisionPoint m_decisionPoint;
    
    public static void checkDriver(final Driver driver) {
        try {
            DecisionPointInstance instance = m_decisionPoint.getInstance();
            instance.setInputs(new ArrayList<Object>() {
                    {
                        add(driver);
                    }
                });
            List<Object> outputs = instance.invoke();
 
            if (outputs.isEmpty())
                System.err.println("Oops, no results");
 
            java.util.List<Denial> denials =
                (java.util.List<Denial>)outputs.get(0);
            if (denials.isEmpty()) {
                System.out.println("Rental is allowed for " +
                                   driver.getName());
            } else {
                for (Denial denial : denials) {
                    System.out.println("Rental is denied for " +
                                       denial.getDriver().getName() +
                                       " because " + denial.getReason());
                }
            }
        } catch (RLException e) {
            e.printStackTrace();
        } catch (SDKException e) {
            e.printStackTrace();
        }
    }
    
}

Example 7-5 shows the following:

• Getting a DecisionPointInstance from the static DecisionPoint defined with the DecisionPointBuilder, with the following code.

   DecisionPointInstance instance = m_decisionPoint.getInstance();
  

• Add inputs according to the signature of the decision function associated with the Decision Point. This defines one argument of type List as the input. This List contains the Driver instances:

              instance.setInputs(new ArrayList<Object>() {
                      {
                          add(driver);
                      }
                  });
  

• Invoke the Decision Point and store the return value. The return type follows the same pattern as the decision function which is being called in the Decision Point.

   List<Object> outputs = instance.invoke();
  

  In this case the invoke() returns a List of length one, containing a List of Denial instances.

• If the return is a List of any other size than one, then this is an error:

  if (outputs.isEmpty())
    System.err.println("Oops, no results");
  

• The first entry that is returned from the Decision Point is caste it to a List of type List<Denial>:

              java.util.List<Denial> denials =
                  (java.util.List<Denial>)outputs.get(0);
  

• If the denials list is empty, then no Denial instances were asserted by the rules. This indicates that it is OK to rent a car to the driver. Otherwise, print the reasons why the driver rental was rejected:

              if (denials.isEmpty()) {
                  System.out.println("Rental is allowed for " +
                                     driver.getName());
              } else {
                  for (Denial denial : denials) {
                      System.out.println("Rental is denied for " +
                                         denial.getDriver().getName() +
                                         " because " + denial.getReason());
                  }
              }