You can use RL Language classes in a rules program to supplement a Java application's object model, without having to change the application code for the Java application that supplies Java Objects.

See Adding Facts to Working Memory with Assert for more details.

Example 1-5 shows the goldCust rule uses a Java class containing customer data, cust; the rule's action asserts an instance of the GoldCustomer RL class, representing a customer that spends more than 500 dollars in a three month period. The Java Customer class includes a method SpentInLastMonths that is supplied an integer representing a number of months of customer data to add.

Example 1-6 shows the goldDiscount rule uses the RL fact GoldCustomer to infer that if a customer spent $500 within the past 3 months, then the customer is eligible for a 10% discount.

Example 1-7 shows the declaration for the GoldCustomer RL class (this assumes that you also have the Customer class available in the classpath).

You can use asserted Java objects as facts in an RL Language program. You are not required to explicitly define or declare the Java classes. However, you must include the Java classes in the classpath when you run the program. This lets you use the Java classes in rules, and allows a rules program to access and use the public attributes, public methods, and bean properties defined in the Java class (bean properties are preferable for some applications because the Oracle Rules Engine can detect that a Java object supports PropertyChangeListener; in this case it uses that mechanism to be notified when the object changes).

In addition, Fact class declarations can fine tune the properties available to use in an RL program, and may be required for certain multiple inheritance situations.

Java fact types allow methods with and without side effects to be imported. Side effects refer to expensive operations such as I/O, Database Query or web service and so on. When using Java classes as facts, remember the following about side effects.

• Rule and Decision Table conditions do not use methods with side effects.

• Actions can use all methods. Though side effects are not recommended, are permissible.

When you work with Java classes, using the import statement lets you omit the package name (see Example 1-8).

To understand the ordering algorithm for firing rule activations on the agenda, we introduce the ruleset stack. Each RuleSession includes one ruleset stack. The RuleSession's ruleset stack contains the top of the stack, called the focus ruleset, and any non focus rulesets that are also on the ruleset stack. You place additional rulesets on the ruleset stack using either the pushRuleset or setRulesetStack built-in functions. You can manage the rulesets on the ruleset stack with the clearRulesetStack, popRuleset, and setRulesetStack functions. In this case, the focus of the ruleset stack is the current top ruleset in the ruleset stack.

RuleSet Stack

           Focus Ruleset  -->     Top_Ruleset          
                                  Next_down_Ruleset    
                                  Lower_Ruleset        
                                  Bottom_Ruleset       

When activations are on the agenda, the Oracle Rules Engine fires rules when run, runUntilHalt, or step executes. The Oracle Rules Engine sequentially selects a rule activation from all of the activations on the agenda, using the following ordering algorithm:

1. The Oracle Rules Engine selects all the rule activations for the focus ruleset, that is the ruleset at the top of the ruleset stack (see the pushRuleset and setRulesetStack built-in functions).

2. Within the set of activations associated with the focus ruleset, rule priority specifies the firing order, with the higher priority rule activations selected to be fired ahead of lower priority rule activations (the default priority level is 0).

3. Within the set of rule activations of the same priority, within the focus ruleset, the most recently added rule activation is the next rule to fire. However, note that in some cases multiple activations may be added to the agenda at the same time, the ordering for such activations is not defined.

4. When all of the rule activations in the current focus fire, the Oracle Rules Engine pops the ruleset stack, and the process returns to Step 1, with the current focus.

If a set of rules named R1 must all fire before any rule in a second set of rules named R2, then you have two choices:

• Use a single ruleset and set the priority of the rules in R1 higher than the priority of rules in R2.

• Use two rulesets R1 and R2, and push R2 and then R1 on the ruleset stack.

Generally, using two rulesets with the ruleset stack is more flexible than using a single ruleset and setting the priority to control when rules fire. For example if some rule R in R1 must trigger a rule in R2 before all rules in R1 fire, a return in R pops the ruleset stack and allows rules in R2 to fire.

If execution must alternate between two sets of rules, for example, rules to produce facts and rules to consume facts, it is easier to alternate flow with different rulesets than by using different priorities.

The following code example shows that the priority of the keepGaryOut rule is set to high, this is higher than the priority of the sayHello rule (the default priority is 0). If the activations of both rules are on the agenda, the higher priority rule fires first. Notice that just before calling run, sayHello has two activations on the agenda. Because keepGaryOut fires first, it retracts the enterRoom(who: "Gary") fact, which removes the corresponding sayHello activation, resulting in only one sayHello firing.

The rule shown in the following code example illustrates two additional RL Language features.

1. The fact operator, also known as a fact set pattern, uses the optional var keyword to define a variable, in this case the variable g, that is bound to the matching facts.

2. You can remove facts in working memory using the retract function.

RL> final int low = -10;
RL> final int high = 10;
RL> rule keepGaryOut {
  priority = high;
  if (fact enterRoom(who: "Gary") var g) {
    retract(g);
  }
}
RL> assert(new enterRoom(who: "Gary"));
==> f-4 main.enterRoom(who: "Gary")
==> Activation: main.sayHello : f-4
==> Activation: main.keepGaryOut : f-4
RL> assert(new enterRoom(who: "Mary"));
==> f-5 main.enterRoom(who: "Mary")
==> Activation: main.sayHello : f-5
RL> run();
Fire 1 main.keepGaryOut f-4
<== f-4 main.enterRoom(who: "Gary")
<== Activation: main.sayHello : f-4
Fire 2 main.sayHello f-5
Hello Mary
RL>

Example 1-10 shows the sayHello rule that includes a condition that matches the asserted enterRoom fact; this match adds an activation to the agenda. Example 1-10 demonstrates the following RL Language programming features.

1. The Oracle Rules Engine matches facts against the rule conditions (fact-set-conditions) of all rules as the state of working memory changes. Thus, it does not matter whether facts are asserted before the rule is defined, or after.

2. The run function processes any activations on the agenda. No activations on the agenda are processed before calling run.

Example 1-11 shows the Java source for a simple bean. Use the javac command to compile the bean, example.Person shown in Example 1-11 into a directory tree.

The following shows how an RL Language command-line can be started that can access this Java bean:

java -classpath $ORACLE_HOME/soa/modules/oracle.rules_11.1.1/rl.jar;BeanPath oracle.rules.rl.session.CommandLine -p "RL> "

Where BeanPath is the classpath component to any supplied Java Bean classes.

Java programs can use the RuleSession interface to execute rulesets, invoke RL Language functions passing Java objects as arguments, and redirect RL Language watch and println output. Example 1-14 and Example 1-15 each contain a Java program fragment that uses a RuleSession that prints "hello world". Like many Java program fragments, these examples are also legal RL Language programs.

The RL Language environment provides multiple rule sessions. Each rule session can be used by multiple threads, but rules are fired by a single thread at a time.

Each rule RuleSession has its own copy of facts and rules. To create a fact from a Java Object, use a call such as:

rs.callFunctionWithArgument("assert", Object;);

To create a rule, a function, or an RL Language class, define a string containing a ruleset, and use the executeRuleset method.