Skip Headers
Oracle® Fusion Middleware User's Guide for Oracle Business Rules
11g Release 1 (11.1.1.6.3)

Part Number E10228-11
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

E Working with Oracle Business Rules and JSR-94 Execution Sets

This appendix describes the Java Rule Engine API (JSR-94) specification that defines a standard Java runtime API to access a rule engine from a Java SE or Java EE client.

The appendix includes the following sections:

For more information, see:

E.1 Introduction to Oracle Business Rules and JSR-94 Execution Sets

Oracle Business Rules provides JSR-94 support. This allows you to create more portable rule-enabled applications.

You can create JSR-94 execution sets from Oracle Business Rules rulesets and you can create JSR-94 rule sessions from these execution sets. For more information, see Section E.2, "Creating JSR-94 Rule Execution Sets from Oracle Business Rules Rulesets".

You can access Oracle Business Rules rulesets and execute them against the Oracle Business Rules Engine using the JSR-94 API. For more information, see Section E.3, "Using the JSR-94 Interface with Oracle Business Rules".

Oracle Business Rules also provides extensions to the JSR-94 API that you may find useful. For more information, see Section E.3.4, "Using Oracle Business Rules JSR-94 Extensions".

E.2 Creating JSR-94 Rule Execution Sets from Oracle Business Rules Rulesets

To use JSR-94 with rules 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.

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.

For more information, see Section E.3.1, "Creating a Rule Execution Set with createRuleExecutionSet".

E.2.1 Creating Rule Execution Set with Oracle Business Rules RL Language Text

You can use JSR-94 with RL Language rulesets saved as text, where the Oracle RL text is directly included in the rule execution set. For more information, see "Using the Extended createRuleExecutionSet to Create a Rule Execution Set" for information about JSR-94 extensions that assist you in including RL Language text.

To create a rule execution set from Oracle Business Rules Oracle RL language text:

  1. Specify the RL Language mapping information in an XML document. Table E-1 shows the mapping elements required to construct a rule execution set. Example E-1 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 E-1 Oracle Business Rules Oracle 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 ruleset. Multiple <rule-source> tags can be used to specify multiple rulesets (specified in the order in which they are interpreted).

<ruleset-stack>

Specifies a list of rulesets that form the initial ruleset stack. The order of the rulesets 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 E-1 XML Mapping File for Rulesets Defined in an Oracle 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>

E.2.2 Creating a Rule Execution Set from Oracle RL Text Specified in a URL

You can use JSR-94 with Oracle RL rulesets specified using a URL. For more information, see "Using the Extended createRuleExecutionSet to Create a Rule Execution Set" for information about JSR-94 extensions that assist you in specifying a URL.

To create a rule execution set from Oracle RL text specified in a URL:

  1. Specify the Oracle RL mapping information in an XML document. Table E-2 shows the mapping elements required to construct a rule execution set. Example E-2 shows a sample XML document for mapping Oracle RL 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 E-2 Oracle Business Rules Oracle RL 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 rulesets (in the order in which they are interpreted).

<ruleset-stack>

Specifies a list of rulesets that form the initial ruleset stack. The order of the rulesets in the list is from the top of the stack to the bottom of the stack.


Example E-2 XMP Mapping File for Rulesets 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>

E.2.3 Creating Rule Execution Sets with Rulesets from Multiple Sources

A rule execution set may contain rules that are derived from multiple sources and the sources may be a mix of Rules Designer defined rulesets and RL Language rulesets. 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 Rules Designer dictionary.

E.3 Using the JSR-94 Interface with Oracle Business Rules

This section describes some Oracle Business Rules specific details for JSR-94 interfaces.

E.3.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 E-3.

Table E-3 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 Oracle Business Rules for Oracle Fusion Middleware 11g Release 1 (11.1.1), using these methods 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.

E.3.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.

E.3.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.

E.3.4 Using Oracle Business Rules JSR-94 Extensions

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

E.3.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 E-4 describes the createRuleExecutionSet arguments.

Table E-4 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. The RuleSource is an interface that the following classes implement:

  • RLTextSource: RL Language text for RL Language text.

  • RLUrlSource: RL Language URL for a URL to RL Language text.

For more information, see the oracle.rules.jsr94.admin package in Oracle Fusion Middleware Java API Reference for Oracle Business Rules.

rulesetstack

Specifies the initial contents of the RL Language ruleset stack to be set before 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.


E.3.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 E-3 shows how you can to invoke an RL Language function with no arguments in a JSR-94 StatefulRuleSession.

Example E-3 Using CallFunction with a StatefulRuleSession

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