Skip Headers

Oracle® Business Rules User's Guide 10g Release 3 (10.1.3) B15986-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 5 Using JSR-94

This chapter covers the following:

- 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 need to 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 need to register a rule execution set before running the rule execution set. A registration associates a rule execution set with a URI; using the URI you can create a JSR-94 rule session.

This section covers 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 Text Specified in a URL

- Creating Rule Execution Sets with Rule Sets from Multiple Sources

Note: Using Oracle Business Rules, a JSR-94 rule execution set registration is not persistent. Thus, you need to 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 need to 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:

1. 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.

2. 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 inter-dependencies 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>

See Also: The XSD file in `$ORACLE_HOME``/rules/lib/jsr94_obr.jar` at `oracle/rules/jsr94/admin/jsr94-runtime-configuration-1.0.xsd`.

### 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 need to 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:

1. 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.

2. 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 inter-dependencies 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:

1. 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.

2. 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>

See Also: "Using the Extended createRuleExecutionSet to Create a Rule Execution Set" for information on JSR-94 extensions that assist you in including RL Language text.

### 5.1.4 Creating a Rule Execution Set from RL 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:

1. 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.

2. 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>

See Also: "Using the Extended createRuleExecutionSet to Create a Rule Execution Set" for information on JSR-94 extensions that assist you in specifying a URL.

### 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 need to list each `<rule-source>` in the order in which they are to be interpreted in the 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 covers 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`.

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`.

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 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 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");