5 Using JSR-94

This chapter includes the following sections:

Oracle Business Rules with JSR-94 Rule Execution Sets
Using the JSR-94 Interface with Oracle Business Rules

5.1 Oracle Business Rules with JSR-94 Rule Execution Sets

To use JSR-94 with rules created either with Rule Author or in RL Language text, you must map the rules to a JSR-94 rule execution set. A JSR-94 rule execution set (rule execution set) is a collection of rules that are intended to be executed together. You also must register a rule execution set before running it. A registration associates a rule execution set with a URI; using the URI, you can create a JSR-94 rule session.

This section includes the following topics:

Creating a JSR-94 Rule Execution Set from Rule Sets in a File Repository
Creating a JSR-94 Rule Execution Set from a WebDAV Repository
Creating a Rule Execution Set from Oracle Business Rules RL Language Text
Creating a Rule Execution Set from RL Language Text Specified in a URL
Creating Rule Execution Sets with Rule Sets from Multiple Sources

Note:

In Oracle Business Rules, a JSR-94 rule execution set registration is not persistent. Thus, you must register a rule execution set programmatically using a JSR-94 RuleExecutionSetProvider interface.

5.1.1 Creating a JSR-94 Rule Execution Set from Rule Sets in a File Repository

You can save rules created with Rule Author in a dictionary using the dictionary storage plug-in. To use JSR-94 with rules created with Rule Author, you must map a Rule Author dictionary and its contents to a JSR-94 rule execution set.

Perform the following steps to use a Rule Author dictionary with JSR-94:

Specify Rule Author dictionary mapping information in an XML document. Table 5-1 shows the mapping elements required to construct a rule execution set. Example 5-1 shows a sample XML mapping file.
You then use the XML document with the JSR-94 administration APIs to create a rule execution set. The resulting rule execution set is registered with a JSR-94 runtime (using a RuleAdministration instance).

Table 5-1 File Repository XML Mapping Elements for JSR-94

Element	Description
`<repository-location>`	The file repository path – the path may be absolute or relative to the current directory at the time of execution.
`<dictionary-name>`	The dictionary name.
`<dictionary-version>`	The dictionary version.
`<ruleset-list>`	A list of Rule Author rule sets to extract from the dictionary in the order in which they should be interpreted so that any interdependencies are resolved. Note: the rule set associated with data model is not included in the `<ruleset-list>` element. The JSR-94 implementation loads the data model rule set into the Rules Engine before any rule sets listed in this element.
`<ruleset-stack>`	Specifies a list of rule sets that make up the initial rule set stack. The order specified for the of rule sets in the list is from the top of the stack to the bottom of the stack.

Example 5-1 JSR-94 XML Mapping File for a File Repository

<rule-execution-set xmlns="http://xmlns.oracle.com/rules/jsr94/configuration" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
   <name>CarRentalDemo</name>
   <description>The Car Rental Demo</description>
   <rule-source>
      <file-repository>
         <repository-location>dict/CarRepository</repository-location>
         <dictionary-name>CarRental</dictionary-name>
         <dictionary-version>HowTo</dictionary-version>
         <ruleset-list>
            <ruleset-name>vehicleRent</ruleset-name>
         </ruleset-list>
      </file-repository>
   </rule-source>
   <ruleset-stack>
      <ruleset-name>vehicleRent</ruleset-name>
   </ruleset-stack>
</rule-execution-set>

5.1.2 Creating a JSR-94 Rule Execution Set from a WebDAV Repository

You can save rules created with Rule Author in a WebDAV repository using the dictionary storage plug-in. To use JSR-94 with rules stored in a WebDAV repository, you must map one or more rule sets from a WebDAV repository to a JSR-94 rule execution set.

Perform the following steps to use rules stored in a file repository with JSR-94:

Specify WebDAV repository mapping information in an XML document. Table 5-2 shows the mapping elements required to construct a rule execution set. Example 5-2 shows a sample XML mapping file.
You then use the XML document with the JSR-94 administration APIs to create a rule execution set. The resulting rule execution set is registered with a JSR-94 runtime (using a RuleAdministration instance).

Table 5-2 WebDAV Repository XML Mapping Elements for JSR-94

Element	Description
`<repository-url>`	The URL for the WebDAV repository.
`<proxy-host>`	The name of the proxy host if a proxy is present. This is an optional element.
`<proxy-port>`	The proxy port if a proxy is present. This is an optional element.
`<dictionary-name>`	The dictionary name.
`<dictionary-version>`	The dictionary version.
`<ruleset-list>`	A list of Rule Author rule sets to extract from the dictionary in the order in which they should be interpreted so that any interdependencies are resolved. Note: the rule set associated with data model is not included in the `<ruleset-list>` element. The JSR-94 implementation loads the data model rule set into the Rules Engine before any rule sets listed in this element.
`<ruleset-stack>`	Specifies a list of rule sets that make up the initial rule set stack. The order specified for the of rule sets in the list is from the top of the stack to the bottom of the stack.

Example 5-2 JSR-94 Mapping File for a WebDAV Repository

<rule-execution-set xmlns="http://xmlns.oracle.com/rules/jsr94/configuration" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
   <name>CarRentalDemo</name>
   <description>The Car Rental Demo</description>
   <rule-source>
      <webdav-repository>
         <repository-url>
            http://www.some_server.com/rules_repository
         </repository-url>
         <dictionary-name>CarRental</dictionary-name>
         <dictionary-version>HowTo</dictionary-version>
         <ruleset-list>
            <ruleset-name>vehicleRent</ruleset-name>
         </ruleset-list>
      </webdav-repository>
   </rule-source>
   <ruleset-stack>
      <ruleset-name>vehicleRent</ruleset-name>
   </ruleset-stack>
</rule-execution-set>

5.1.3 Creating a Rule Execution Set from Oracle Business Rules RL Language Text

You can use JSR-94 with RL Language rule sets saved as text, where the RL Language text is directly included in the rule execution set.

Perform the following steps to use RL Language specified rules with JSR-94:

Specify the RL Language mapping information in an XML document. Table 5-3 shows the mapping elements required to construct a rule execution set. Example 5-3 shows a sample XML document for mapping RL Language text to a JSR-94 rule execution set.
You then use the XML document with the JSR-94 administration APIs to create a rule execution set. The resulting rule execution set is registered with a JSR-94 runtime (using a RuleAdministration instance).

Table 5-3 Oracle Business Rules RL Language Text XML Mapping Elements for JSR-94

Element	Description
`<rule-source>`	Includes an `<rl-text>` tag containing explicit RL Language text containing an Oracle Business Rules rule set. Multiple `<rule-source>` tags can be used to specify multiple rule sets (specified in the order in which they are interpreted).
`<ruleset-stack>`	Specifies a list of rule sets that make up the initial rule set stack. The order of the rule sets in the list is from the top of the stack to the bottom of the stack.

Note:

In the <rl-text> element the contents must escape XML predefined entities. This includes the characters '&', '>', '<', '"', and '\''.

Example 5-3 XML Mapping File for Rule Sets Defined in an RL Program

<rule-execution-set xmlns="http://xmlns.oracle.com/rules/jsr94/configuration" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
   <name>CarRentalDemo</name>
   <description>The Car Rental Demo</description>
   <rule-source>
      <rl-text>
         ruleset DM {
            fact class carrental.Driver {
               hide property ableToDrive, driverLicNum, licIssueDate, licenceType,
               llicIssueDate, numPreAccidents, numPreConvictions,
               numYearsSinceLicIssued, vehicleType;
            };

               final String DeclineMessage = &quot;Rental declined &quot;;

               public class Decision  supports xpath {
                  public String driverName;
                  public String type;
                  public String message;
               }

               function assertXPath(String package,
                                    java.lang.Object element, String xpath) {
                  //RL literal statement
                  main.assertXPath( package, element, xpath );
               }

               function println(String message) {
                  //RL literal statement
                  main.println(message);
               }


               function showDecision(DM.Decision decision) {
                  //RL literal statement
                  DM.println( &quot;Rental decision is &quot; + decision.type +
                              &quot; for driver &quot; + decision.driverName +
                              &quot; for reason &quot; + decision.message);
               }
         }
      </rl-text>
   </rule-source>
   <rule-source>
      <rl-text>
         ruleset vehicleRent {
            rule UnderAge {
               priority = 0;
               if ((fact carrental.Driver v0_Driver &amp;&amp;
                  (v0_Driver.age &lt; 19))) {
                  DM.println( &quot;Rental declined: &quot; + v0_Driver.name +
                              &quot; Under age, age is: &quot; + v0_Driver.age);
                  retract(v0_Driver);
               }
            }
         }
      </rl-text>
   </rule-source>
   <ruleset-stack>
      <ruleset-name>vehicleRent</ruleset-name>
   </ruleset-stack>
</rule-execution-set>

5.1.4 Creating a Rule Execution Set from RL Language Text Specified in a URL

You can use JSR-94 with RL Language rule sets specified using a URL.

To use RL Language specified rules with JSR-94, do the following:

Specify the RL Language mapping information in an XML document. Table 5-4 shows the mapping elements required to construct a rule execution set. Example 5-4 shows a sample XML document for mapping RL Language text to a JSR-94 rule execution set.
You then use the XML document with the JSR-94 administration APIs to create a rule execution set. The resulting rule execution set is registered with a JSR-94 runtime (using a RuleAdministration instance).

Table 5-4 Oracle Business Rules RL Language URL XML Mapping Elements for JSR-94

Element	Description
`<rule-source>`	Includes an `<rl-url>` tag containing a URL that specifies the location of RL Language text. Multiple `<rule-source>` tags can be used to specify multiple rule sets (in the order in which they are interpreted).
`<ruleset-stack>`	Specifies a list of rule sets that make up the initial rule set stack. The order of the rule sets in the list is from the top of the stack to the bottom of the stack.

Example 5-4 XMP Mapping File for Rule Sets Defined in a URL

<?xml version="1.0" encoding="UTF-8"?>
<rule-execution-set xmlns="http://xmlns.oracle.com/rules/jsr94/configuration" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0">
   <name>CarRentalDemo</name>
   <description>The Car Rental Demo</description>
   <rule-source>
      <rl-url>
         file:rl/DM.r1
      </rl-url>
   </rule-source>
   <rule-source>
      <rl-url>
         file:r1/VehicleRent.r1
      </rl-url>
   </rule-source>
   <ruleset-stack>
      <ruleset-name>vehicleRent</ruleset-name>
   </ruleset-stack>
</rule-execution-set>

5.1.5 Creating Rule Execution Sets with Rule Sets from Multiple Sources

A rule execution set may contain rules that are derived from multiple sources and the sources may be a mix of Rule Author defined rule sets and RL Language rule sets. In this case, the XML element <rule-execution-set> set contains multiple <rule-source> elements, one for each source of rules. You must list each <rule-source> in the order in which they are to be interpreted in Rules Engine.

Note:

For this Oracle Business Rules release, a JSR-94 rule execution set can only reference one Rule Author dictionary.

5.2 Using the JSR-94 Interface with Oracle Business Rules

This section describes some Oracle Business Rules specific details for JSR-94 interfaces. This section includes the following topics:

Creating a Rule Execution Set with CreateRuleExecutionSet
Creating a Rule Session with createRuleSession
Working with JSR-94 Metadata
Using Oracle Business Rules JSR-94 Extensions

5.2.1 Creating a Rule Execution Set with CreateRuleExecutionSet

The RuleExecutionSetProvider and LocalRuleExecutionSetProvider interfaces in javax.rules.admin include the createRuleExecutionSet to create a RuleExecutionSet object.

For the remaining createRuleExecutionSet methods, the first argument is interpreted as shown in Table 5-5.

Table 5-5 First Argument Types for createRuleExecutionSet Method

Argument	Description
`org.w3c.dom.Element`	Specifies an instance of the `<rule-execution-set>` element from the configuration schema.
`java.lang.String`	Specifies a URL that specifies the location of an XML document that is an instance of the `<rule-execution-set>` element from the configuration schema.
`java.io.InputStream`	Specifies an input stream that is used to read an XML document that is an instance of the `<rule-execution-set>` element from the configuration schema.
`java.io.Reader`	Specifies a character reader that is used to read an XML document that is an instance of the `<rule-execution-set>` element from the configuration schema.

Note:

JSR-94 also includes createRuleExecutionSet methods that take a java.lang.Object argument, which is intended to be an abstract syntax tree for the rule execution set. In this release of Oracle Business Rules, using the method with this argument is not supported. Invoking these methods with a java.lang.Object argument gives a RuleExecutionSetCreateException exception.

The second argument to the createRuleExecutionSet methods is a java.util.Map of vendor-specific properties. The properties in Table 5-6 are valid for the Oracle JSR-94 implementation.

Table 5-6 createRuleExceptionSet Oracle Specific Properties

Property Key	Property Value
`oracle.rules.jsr94.sensitiveDataCallback`	This property is set when authentication is required by the selected repository such as a WebDAV server that is configured to require authentication. The property value must be an implementation of the `oracle.rules.sdk.repository.SensitiveDataCallback` interface.

5.2.2 Creating a Rule Session with createRuleSession

Clients create a JSR-94 rule session using the createRuleSession method in the RuleRuntime class. This method takes a java.util.Map argument of vendor-specific properties. This argument can be used to pass in any of the properties defined for the Oracle Business Rules oracle.rules.rl.RuleSession. If a rule execution set contains URL or repository rule sources, the rules from those sources are fetched on the creation of each new RuleSession.

5.2.3 Working with JSR-94 Metadata

JSR-94 allows for metadata for rule execution sets and rules within a rule execution set. The Oracle Business Rules implementation does not add any additional metadata beyond what is in the JSR-94 specification. The rule execution set description is an optional item and thus may not be present. If it is not present, the empty string is returned. For rules, only the rule name is available and the description is initialized with an empty string.

5.2.4 Using Oracle Business Rules JSR-94 Extensions

This section covers the following extensions provided in the JSR-94 implementation classes.

Using the Extended createRuleExecutionSet to Create a Rule Execution Set
Invoking an RL Language Function in JSR-94

5.2.4.1 Using the Extended createRuleExecutionSet to Create a Rule Execution Set

Oracle Business Rules provides a helper function to facilitate creating the XML control file required as input to create a RuleExecutionSet.

The helper method createRuleExecutionSet is available in the RLLocalRuleExecutionSetProvider class. The createRuleExecutionSet method has the following signature:

RuleExecutionSet createRuleExecutionSet(String name,
                                        String description,
                                        RuleSource[] sources,
                                        String[] rulesetStack,
                                        Map properties)

Table 5-7 describes the createRuleExecutionSet arguments.

Table 5-7 createRuleExecutionSet Arguments

Argument	Description
`name`	Specifies the name of the rule execution set.
`description`	Specifies the description of the rule execution set.
`sources`	Specifies an array of specifications for the sources of rules. In this release, four types of sources are supported: RL Language text, a URL to RL Language text, a file repository (.jar file), and a WebDAV repository. `RuleSource` is an interface that the classes `RLTextSource` (RL Language text), `RLUrlSource` (RL Language URL), `JarRepositorySource` (file repository), and `WebDAVRepositorySource` (WebDAV repository) implement. For more information, see the `oracle.rules.jsr94.admin` package in Oracle Business Rules Java API Reference.
`rulesetstack`	Specifies the initial contents of the RL Language rule set stack to be set prior to each time the rules are executed. The contents of the array should be ordered from the top of stack (0th element) to the bottom of stack (last element).
`properties`	Oracle specific properties. See Table 5-6.

5.2.4.2 Invoking an RL Language Function in JSR-94

In a stateful interaction with a JSR-94 rule session, a user may want the ability to invoke an arbitrary RL Language function. The class that implements the JSR-94 StatefulRuleSession interface provides access to the callFunction methods in the oracle.rules.rl.RuleSession class.

Example 5-5 shows how you can to invoke an RL Language function with no arguments in a JSR-94 StatefulRuleSession.

Example 5-5 Using CallFunction with a StatefulRuleSession

import javax.rules.*;
 ...
StatefulRuleSession session;
...
((oracle.rules.jsr94.RLStatefulRuleSession) session).callFunction("myFunction");