Introduction Into Oracle Business Rules and Rule Based Programming

I was asked the other day by a colleague who wanted to get an introduction into Oracle Business Rules if I had some tips & pointers in order to get started, so I thought I'd might put the answer here; perhaps some more people can use it as well.

For a short, but good introduction to what rule based programming is, please check:

http://www.webreference.com/programming/rule/

The article describes short and concise what rule base programming is all about.

OK, so now you know what it is, but how to get started using it? If you are using the Oracle SOA Suite, then you already have a rule engine in place, so why not start using it?

To see a viewlet on how-to use it, go to the Rules section in OTN: http://www.oracle.com/technology/products/ias/business_rules/index.html

It is available under the 'Viewlets and Tutorials' section. After that, it is time to start learning more about it.

If you have a developer's background, I would suggest that you start with the 'Oracle Business Rules Language Reference' (available at: http://download.oracle.com/docs/cd/B32110_01/web.1013/b28964/toc.htm), this will give you a feel for how the Rule language works; after all this is really the foundation. When going through this document, you will of course need the API, it's available here: http://download.oracle.com/docs/cd/B32110_01/web.1013/b28966/toc.htm.

The document contains many small examples that will help you to get started and get familiar with the language. The examples are run using a command line interface that ships with the product. An alternative is to download the RulesTools extension for JDeveloper 10.1.3.x. This will give you the option to execute script files written in the Rules Language directly in JDeveloper, as well as some other stuff that will ease programming in the Rules Language.

Once you are familiar with the Rule language, or if you are coming from a more business oriented background, you should start to have a look into the Oracle Business Rules Rule Author; it is the GUI that is used for creating the rules. The documentation for it is available here: http://download.oracle.com/docs/cd/B32110_01/web.1013/b28965/toc.htm.

In the previous given link to the Rules section on OTN you will find even more demos and tutorials to help you get started with the Oracle Business Rules.

I hope this will help you to take your first steps down the road of Oracle Business Rules and rule based programming. Good luck!

About Rules and Execution Order

A question that pops-up from time to time is about Rules and execution order, i.e., is there a way to control the execution order of rules? There are technically two ways of doing this. The first way of obtaining this is by using rule priorities, the second is to use the ruleset stack.

However, I believe that using rule priorities in general should really be avoided, and is usually discouraged for two reasons; first, if will impact performance negative with respect to the built-in conflict resolution strategies. Secondly, it is considered bad style to use priorities in rule based programming to try to force a specific order. If you find yourself using priorities for most of your rules, then you should consider if using a rule based approach is really the best solution for your problem. If you want strict control over execution order, then you are really using procedural programming and not rule based programming.

If you still want to execution order, you should use the ruleset stack. This will be a more flexible solution than using a single ruleset and using rule priorities. How to do this is described in the Oracle Business Rules Language Reference, section 1.4.3 'Ordering Rule Firing'.

Recursion in Rules

Long time since I wrote something about Rules, so, here is a small sample for using recursion in Rules. Implementing recursion in Rules is fairly easy, just assert a new fact in the action-block of a rule, that's it. By asserting a new fact to the system, the system will re-evaluate, and recursion has taken place.

Below is an example that will illustrate this, it will find and print all ancestor relationships that are the result of three parent relationships. Andy is a parent of Betty, Betty is a parent of Charlie and Charlie is a parent of Donna. Which are the resulting ancestor relationships?

Running this program will reveal the result...

ruleset main {

class Parent {
String a;
String b;
}

class Ancestor {
String a;
String b;
}

// Convert a Parent relationship to an Ancestor relationship
rule parentToAncestor {
if ( (fact Parent p) ) {
assert(new Ancestor(a: p.a, b: p.b));
}
}

// If A is parent of B and B is an Ancestor of C, then A is an Ancestor of C
rule parentAndAncestorToAncestor {
if (
(fact Parent p) &&
(fact Ancestor a) &&
p.b.equals(a.a)
) {
assert(new Ancestor(a: p.a , b: a.b));
}
}

// Printout all Ancestors relationships
rule printAncestors {
if (fact Ancestor a) {
println(a.a + " is an ancestor of " + a.b);
}
}

// Setup some parent relations...
{
assert(new Parent(a: "Andy" , b: "Betty"));
assert(new Parent(a: "Betty" , b: "Charlie"));
assert(new Parent(a: "Charlie", b: "Donna"));
}

// Evaluate the ruleset
run();
}

below is the result:

Andy is an ancestor of Donna
Betty is an ancestor of Donna
Charlie is an ancestor of Donna
Andy is an ancestor of Charlie
Betty is an ancestor of Charlie
Andy is an ancestor of Betty

RuleAuthor Fails to Start with Strange Error Message

An interesting problem that has appeared recentley is that I've seen the RuleAuthor fail with an exception:

java.io.FileNotFoundException: Could not find RuleHome.uix.uix

on a few occasions recently. It is possible to get to the login screen, but once you have logged in, this error appears.

It turned out; that this was caused by that the Oracle HTTP Server (OHS) was started by using apachectl instead of via OPMN. This led to inconsistency between the OHS to OC4J mapping in the mod_oc4j mappings. Could be worth keeping in mind...

Recursion in RL Functions

Today I was thinking if it were possible to create recursive functions in the RL Language, so I made a small test by calculating factorials. I started by defining the function as:

  function factorial(long  x) returns long {
    if( x == 1) {
           return 1;
    } else {
           return x*(factorial( x-1 ));
       }
   }

Next, I just ran it by using:

  println("The factorial of 12 is: " + factorial(12) + ".");

and this gave me the expected result of:

  The factorial of 12 is: 479001600.

so, this seems to work fine.

Next thing will be to try recursion for facts, and of course for rules... More about that later.

RL Language Rules Extension for JDeveloper

I have created an extension for JDeveloper, which makes it a bit easier to work with the Oracle Business Rules Language, RL Language within JDeveloper. Read more about it on OTN at:
http://www.oracle.com/technology/products/jdev/htdocs/partners/addins/exchange/rules/howto.html

Callout from within Oracle Business Rules

Within Oracle Business Rules you sometimes need to make callouts to an external Object within the action part of your rule. This is very easy to achieve. Suppose that you have a class with an external method similar to:

  package myPackage;
  public class CallOut {
   public CallOut() { }
  
      public void test(String myVariable) {
           System.out.println("Callout from Rules with argument: " + myVariable);
   }
   }

and you would like to call upon this method from within the action part of a rule. The first thing you need to do is also to import this class into your dictionary. Once done, you need to define a new RLFunction. This function needs to have 2 variables defined, one for the class itself, and one for the argument. The argument should have the argument type String, while the class needs to have the Type CallOut, or whatever your class is named. Within the function body you then define the actual function like:

    TestCallOut.test(message);

Now you have a Rules function that you cal call upon from the action part of any rule within your ruleset(s), like:

   Call callOut( Passenger.name, new CallOut () )

The RL code that is generated for such a task will look like:

   function callOut(String message, myPackage.CallOut TestCallOut)
   {
      //RL literal statement
      TestCallOut.test(message);
   }// DM.callOut

for the function, this will be defined in the DM ruleset. The call will look like:

   rule myRule
   {
      priority = 0;
      if
   (
      (
       fact myPackage.SomeFactObject v0_SomeFactObject && (
         (v0_SomeFactObject.anAttribute <>
      )
      {
         DM.callOut(v0_SomeFactObject.someArgument, new myPackage.CallOut());
      }
  } //end rule myRule;

I hope this will have shown you how-to make a callout from Oracle Business Rules to a method within an Object.

Installing Rule Author on a standalone OC4J 10.1.3

It is possible to install the Rule Author on a standalone OC4J 10.1.3. Below is one way of achieving this.

1. Copy the ruleauthor.ear from a AS installation on Linux, located in /rules/webapps to the windows machine, for example to d:\tmp\ruleauthor.ear

2. Startup a standalone OC4J 10.1.3 on the windows machine.

3. Deploy the Rule Author to it using:

java -jar admin.jar ormi://localhost:23791 oc4jadmin  
     -deploy -file D:/tmp/ruleauthor.ear -deploymentName ruleauthor

and

java -jar admin.jar ormi://localhost:23791 oc4jadmin  
     -bindWebApp ruleauthor ruleauthor default-web-site ruleauthor

4. Add the default user, goto http://localhost:8888/em/ and follow the steps given in the Oracle Business Rules User's Guide, section 2.1:

http://download-uk.oracle.com/docs/cd/B25221_01/web.1013/b15986/guistart.htm#sthref76

don't forget to restart the ruleautor application after defining the user.

5. Now you can use the Rule Author at the URL http://localhost:8888/ruleauthor/RuleHome.uix by using the user created in previous step.

Combining TopLink with Oracle Business Rules

This sample will show you how you retrieve some objects by using TopLink and then use Oracle Business Rules to do some selection upon these objects. I am not using neither a file based nor a WebDAV based rule repository for this sample, instead I create the ruleset on the fly.

Suppose you have a table, PERSON, that has the following structure:

  PERSON
  ------
  PID      NUMBER
  NAME     VARCHAR2(32)
  SEX    CHAR(1)
  EYECOLOR VARCHAR2(8)
  INCOME   NUMBER

and this is mapped to a Person object which has corresponding fields and accessors. I will also assume that you have setup a TopLink mapping between the table and the object.


Now, we first need to retrieve the objects from the DB, assuming we are working with a 2-tier here, we do this as follows:

  SessionManager sessionManager = SessionManager.getManager();
  Session session = sessionManager.getSession("default");
  Vector v = session.readAllObjects(Person.class);

This will read all persons in the database and put them into a Vector. Now, we have a vector, v, that holds our persons. The next step is to initiate the RuleSession, as mentioned before, this is done on the fly with one simple rule:

  RuleSession rs = new RuleSession();
  String rset = 
  "ruleset main {" +
  "   import ruleexample1.bo.Person;" +
  "   rule blueEyeFemaleWithIncomeOver40000 {" +
  "     if (fact Person p && p.getEye_color().equals(\"Blue\") && p.getSex().equals(\"F\") && p.getIncome()>40000 ) {" +
  "       println(p.getName() + \" is a female with blue eyes and an income over 400000.\");" +
  "     }" +
  "   }" +
  "}";
  rs.executeRuleset(rset);

this rule will fire for females with blue eyes and has an income over 40000. Once done, we can assign the persons as facts, this is done by:

  for (int i=0;i<v.size();i++) {
    rs.callFunctionWithArgument( "assert", (Person)v.elementAt(i) );
  }

once the facts are in place, we can run this by calling:

  rs.callFunction( "run" );

That's it! This will print out a list of objects that matches the conditions set out in the rule set.

Functions in Oracle Business Rules RL Language

The Oracle Business Rules RL Language syntax is very similar to Java, so it should be very easy for a Java programmer to get a grasp on the syntax quickly. If you have a background working with Jess, you will however notice that the syntax differs a bit. I will give a quick demonstration on the differences concerning functions.

In Jess you create a function like:

  Jess> (deffunction max (?x ?y)
    (if (> ?x ?y) then
        (return ?x)
    else
        (return ?y)))

and you call upon it with the following statement:

  Jess> (printout t "The biggest number of 5 and 7 is: " (max 5 7) "." crlf)

In RL Language you create a similar function like:

  RL> function max(long x, long y) returns long {
        if (x<=y) { return y; }
        else { return x; }
      }

and you call upon it with the following statement:

  RL> println("The biggest number of 5 and 7 is: " + max(5,7) + ".");

So, as you can see, with respect to functions, Jess and RL Language looks quite the same, however, there are syntactical differences for the programmer to be aware of.

Oracle Business Rules not Installed by Default

I downloaded and installed the Oracle AS 10.1.3 today in order to get going with the Oracle Business Rules. As indicated on the OTN page it says that this should be included with the installation. It is included, but the Rule Author it is not installed by default.

So, once you have installed the Oracle AS 10.1.3, you also need to deploy the ruleauthor.ear file to the OC4J instance where you want your Rule Author to run. The file is located in the /rules/webapps directory.

Once deployed, the Rule Author came up nicely.