[jboss-svn-commits] JBL Code SVN: r26260 - labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Sat Apr 25 17:15:41 EDT 2009
Author: laune
Date: 2009-04-25 17:15:40 -0400 (Sat, 25 Apr 2009)
New Revision: 26260
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-BankingExample.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-FibonacciExample.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-PricingExample.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-StateExample.xml
Log:
improvements
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-BankingExample.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-BankingExample.xml 2009-04-25 17:35:09 UTC (rev 26259)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-BankingExample.xml 2009-04-25 21:15:40 UTC (rev 26260)
@@ -1,28 +1,37 @@
-<?xml version="1.0" encoding="UTF-8"?>
- <section version="5.0" xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xmlns:svg="http://www.w3.org/2000/svg"
- xmlns:m="http://www.w3.org/1998/Math/MathML"
- xmlns:html="http://www.w3.org/1999/xhtml"
- xmlns:db="http://docbook.org/ns/docbook" xml:base="../../">
- <title>Banking Tutorial</title>
-
- <screen><emphasis role="bold">Name:</emphasis> BankingTutorial
-<emphasis role="bold">Main class:</emphasis> org.drools.tutorials.banking.*
-<emphasis role="bold">Type:</emphasis> java application
-<emphasis role="bold">Rules file:</emphasis> org.drools.tutorials.banking.*
-<emphasis role="bold">Objective:</emphasis> tutorial that builds up knowledge of pattern matching, basic sorting and calculation rules.</screen>
-
- <para>This tutorial will demonstrate the process of developing a complete personal banking application that will handle credits, debits, currencies and that will use a set of design patterns that have been created for the process. In order to make the examples documented here clear and modular, I will try and steer away from re-visiting existing code to add new functionality, and will instead extend and inject where appropriate.</para>
-
- <para>The RuleRunner class is a simple harness to execute one or more drls against a set of data. It compiles the Packages and creates the KnowledgeBase for each execution, this allows us to easy execute each scenario and see the outputs. In reality this is not a good solution for a production system where the KnowledgeBase should be built just once and cached, but for the purposes of this tutorial it shall suffice.</para>
-
- <example>
- <title>Banking Tutorial : RuleRunner</title>
-
- <programlisting><![CDATA[public class RuleRunner {
+<?xml version="1.0" encoding="UTF-8"?>
+ <section version="5.0" xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns:m="http://www.w3.org/1998/Math/MathML"
+ xmlns:html="http://www.w3.org/1999/xhtml"
+ xmlns:db="http://docbook.org/ns/docbook" xml:base="../../">
+ <title>Banking Tutorial</title>
+ <screen><emphasis role="bold">Name:</emphasis> BankingTutorial
+<emphasis role="bold">Main class:</emphasis> org.drools.tutorials.banking.Example*.java
+<emphasis role="bold">Type:</emphasis> Java application
+<emphasis role="bold">Rules file:</emphasis> org.drools.tutorials.banking.*.drl
+<emphasis role="bold">Objective:</emphasis> Demonstrate pattern matching, basic sorting and calculation rules.</screen>
+
+ <para>This tutorial demonstrates the process of developing a
+ complete personal banking application to handle credits and debits on
+ multiple accounts. It uses a set of design patterns that have
+ been created for the process.</para>
+
+ <para>The class <code>RuleRunner</code> is a simple harness to execute
+ one or more DRL files against a set of data. It compiles the Packages
+ and creates the Knowledge Base for each execution, allowing us to
+ easily execute each scenario and inspect the outputs. In reality this
+ is not a good solution for a production system, where the Knowledge Base
+ should be built just once and cached, but for the purposes of this
+ tutorial it shall suffice.</para>
+
+ <example>
+ <title>Banking Tutorial: RuleRunner</title>
+
+ <programlisting><![CDATA[public class RuleRunner {
+
public RuleRunner() {
}
@@ -36,8 +45,8 @@
String ruleFile = rules[i];
System.out.println( "Loading file: " + ruleFile );
kbuilder.add( ResourceFactory.newClassPathResource( ruleFile,
- RuleRunner.class ),
- ResourceType.DRL );
+ RuleRunner.class ),
+ ResourceType.DRL );
}
Collection<KnowledgePackage> pkgs = kbuilder.getKnowledgePackages();
@@ -52,549 +61,620 @@
ksession.fireAllRules();
}
-}]]></programlisting>
- </example>
-
- <para>This is our first Example1.java class it loads and executes a single drl file "Example.drl" but inserts no data.</para>
-
- <example>
- <title>Banking Tutorial : Java Example1</title>
-
- <programlisting>public class Example1 {
- public static void main(String[] args) throws Exception {
- new RuleRunner().runRules( new String[] { "Example1.drl" },
- new Object[0] );
- }
-}</programlisting>
- </example>
-
- <para>And this is the first simple rule to execute. It has a single "eval" condition that will alway be true, thus this rul will always match and fire.</para>
-
- <example>
- <title>Banking Tutorial : Rule Example1</title>
-
- <programlisting>rule "Rule 01"
- when
- eval (1==1)
- then
- System.out.println("Rule 01 Works");
-endh</programlisting>
- </example>
-
- <para>The output for the rule is below, the rule matches and executes the single print statement.</para>
-
- <example>
- <title>Banking Tutorial : Output Example1</title>
-
- <programlisting>Loading file: Example1.drl
-Rule 01 Works</programlisting>
- </example>
-
- <para>The next step is to assert some simple facts and print them out. </para>
-
- <example>
- <title>Banking Tutorial : Java Example2</title>
-
- <programlisting>public class Example2 {
- public static void main(String[] args) throws Exception {
- Number[] numbers = new Number[] {wrap(3), wrap(1), wrap(4), wrap(1), wrap(5)};
- new RuleRunner().runRules( new String[] { "Example2.drl" },
- numbers );
- }
-
- private static Integer wrap(int i) {
- return new Integer(i);
- }
-}</programlisting>
- </example>
-
- <para>This doesn’t use any specific facts but instead asserts a set of java.lang.Integer’s. This is not considered "best practice" as a number of a collection is not a fact, it is not a thing. A Bank acount has a number, its balance, thus the Account is the fact; but to get started asserting Integers shall suffice for demonstration purposes as the complexity is built up.</para>
-
- <para>Now we will create a simple rule to print out these numbers.</para>
-
- <example>
- <title>Banking Tutorial : Rule Example2</title>
-
- <programlisting>rule "Rule 02"
- when
- Number( $intValue : intValue )
- then
- System.out.println("Number found with value: " + $intValue);
-end</programlisting>
- </example>
-
- <para>Once again, this rule does nothing special. It identifies any facts that are Numbers and prints out the values. Notice the user of interfaces here, we inserted Integers but the pattern matching engine is able to match the interfaces and super classes of the asserted objects.</para>
-
- <para>The output shows the drl being loaded, the facts inserted and then the matched and fired rules. We can see that each inserted number is matched and fired and thus printed.</para>
-
- <example>
- <title>Banking Tutorial : Output Example2</title>
-
- <programlisting>Loading file: Example2.drl
-Inserting fact: 3
-Inserting fact: 1
-Inserting fact: 4
-Inserting fact: 1
-Inserting fact: 5
-Number found with value: 5
-Number found with value: 1
-Number found with value: 4
-Number found with value: 1
-Number found with value: 3
-</programlisting>
- </example>
-
- <para>here are probably a hundred and one better ways to sort numbers; but we will need to apply some cashflows in date order when we start looking at banking rules so let’s look at a simple rule based example.</para>
-
- <example>
- <title>Banking Tutorial : Java Example3</title>
-
- <programlisting>public class Example3 {
- public static void main(String[] args) throws Exception {
- Number[] numbers = new Number[] {wrap(3), wrap(1), wrap(4), wrap(1), wrap(5)};
- new RuleRunner().runRules( new String[] { "Example3.drl" },
- numbers );
- }
-
- private static Integer wrap(int i) {
- return new Integer(i);
- }
-}</programlisting>
- </example>
-
- <para>Again we insert our Integers as before, this time the rule is slightly different:</para>
-
- <example>
- <title>Banking Tutorial : Rule Example3</title>
-
- <programlisting>rule "Rule 03"
- when
- $number : Number( )
- not Number( intValue < $number.intValue )
- then
- System.out.println("Number found with value: " + $number.intValue() );
- retract( $number );
-end</programlisting>
- </example>
-
- <para>The first line of the rules identifies a Number and extracts the value. The second line ensures that there does not exist a smaller number than the one found. By executing this rule, we might expect to find only one number - the smallest in the set. However, the retraction of the number after it has been printed, means that the smallest number has been removed, revealing the next smallest number, and so on. </para>
-
- <para>So, the output we generate is, notice the numbers are now sorted numerically.</para>
-
- <example>
- <title>Banking Tutorial : Output Example3</title>
-
- <programlisting>Loading file: Example3.drl
-Inserting fact: 3
-Inserting fact: 1
-Inserting fact: 4
-Inserting fact: 1
-Inserting fact: 5
-Number found with value: 1
-Number found with value: 1
-Number found with value: 3
-Number found with value: 4
-Number found with value: 5
-</programlisting>
- </example>
-
- <para>Now we want to start moving towards our personal accounting rules. The first step is to create a Cashflow POJO.</para>
-
- <example>
- <title>Banking Tutoria : Class Cashflow</title>
-
- <programlisting>public class Cashflow {
- private Date date;
- private double amount;
-
- public Cashflow() {
- }
-
- public Cashflow(Date date,
- double amount) {
- this.date = date;
- this.amount = amount;
- }
-
- public Date getDate() {
- return date;
- }
-
- public void setDate(Date date) {
- this.date = date;
- }
-
- public double getAmount() {
- return amount;
- }
-
- public void setAmount(double amount) {
- this.amount = amount;
- }
-
- public String toString() {
- return "Cashflow[date=" + date + ",amount=" + amount + "]";
- }
-}</programlisting>
- </example>
-
- <para>The Cashflow has two simple attributes, a date and an amount. I have added a toString method to print it and overloaded the constructor to set the values. The Example4 java code inserts 5 Cashflow objecst with varying dates and amounts.</para>
-
- <example>
- <title>Banking Tutorial : Java Example4</title>
-
- <programlisting>public class Example4 {
- public static void main(String[] args) throws Exception {
- Object[] cashflows = {
- new Cashflow(new SimpleDate("01/01/2007"), 300.00),
- new Cashflow(new SimpleDate("05/01/2007"), 100.00),
- new Cashflow(new SimpleDate("11/01/2007"), 500.00),
- new Cashflow(new SimpleDate("07/01/2007"), 800.00),
- new Cashflow(new SimpleDate("02/01/2007"), 400.00),
- };
-
- new RuleRunner().runRules( new String[] { "Example4.drl" },
- cashflows );
- }
-}</programlisting>
- </example>
-
- <para>SimpleDate is a simple class that extends Date and takes a String as input. It allows for pre-formatted Data classes, for convienience. The code is listed below</para>
-
- <example>
- <title>Banking Tutorial : Java SimpleDate</title>
-
- <programlisting>public class SimpleDate extends Date {
- private static final SimpleDateFormat format = new SimpleDateFormat("dd/MM/yyyy");
-
- public SimpleDate(String datestr) throws Exception {
- setTime(format.parse(datestr).getTime());
- }
-}</programlisting>
- </example>
-
- <para>Now, let’s look at rule04.drl to see how we print the sorted Cashflows:</para>
-
- <example>
- <title>Banking Tutorial : Rule Example4</title>
-
- <programlisting>rule "Rule 04"
- when
- $cashflow : Cashflow( $date : date, $amount : amount )
- not Cashflow( date < $date)
- then
- System.out.println("Cashflow: "+$date+" :: "+$amount);
- retract($cashflow);
-end</programlisting>
- </example>
-
- <para>Here, we identify a Cashflow and extract the date and the amount. In the second line of the rules we ensure that there is not a Cashflow with an earlier date than the one found. In the consequences, we print the Cashflow that satisfies the rules and then retract it, making way for the next earliest Cashflow. So, the output we generate is:</para>
-
- <example>
- <title>Banking Tutorial : Output Example4</title>
-
- <programlisting>Loading file: Example4.drl
-Inserting fact: Cashflow[date=Mon Jan 01 00:00:00 GMT 2007,amount=300.0]
-Inserting fact: Cashflow[date=Fri Jan 05 00:00:00 GMT 2007,amount=100.0]
-Inserting fact: Cashflow[date=Thu Jan 11 00:00:00 GMT 2007,amount=500.0]
-Inserting fact: Cashflow[date=Sun Jan 07 00:00:00 GMT 2007,amount=800.0]
-Inserting fact: Cashflow[date=Tue Jan 02 00:00:00 GMT 2007,amount=400.0]
-Cashflow: Mon Jan 01 00:00:00 GMT 2007 :: 300.0
-Cashflow: Tue Jan 02 00:00:00 GMT 2007 :: 400.0
-Cashflow: Fri Jan 05 00:00:00 GMT 2007 :: 100.0
-Cashflow: Sun Jan 07 00:00:00 GMT 2007 :: 800.0
-Cashflow: Thu Jan 11 00:00:00 GMT 2007 :: 500.0
-</programlisting>
- </example>
-
- <para>Here we extend our Cashflow to give a TypedCashflow which can be CREDIT or DEBIT. Ideally, we would just add this to the Cashflow type, but so that we can keep all the examples simple, we will go with the extensions.</para>
-
- <example>
- <title>Banking Tutoria : Class TypedCashflow</title>
-
- <programlisting>public class TypedCashflow extends Cashflow {
- public static final int CREDIT = 0;
- public static final int DEBIT = 1;
-
- private int type;
-
- public TypedCashflow() {
- }
-
- public TypedCashflow(Date date,
- int type,
- double amount) {
- super( date,
- amount );
- this.type = type;
- }
-
- public int getType() {
- return type;
- }
-
- public void setType(int type) {
- this.type = type;
- }
-
- public String toString() {
- return "TypedCashflow[date=" + getDate() + ",type=" + (type == CREDIT ? "Credit" : "Debit") + ",amount=" + getAmount() + "]";
- }
-}</programlisting>
- </example>
-
- <para>There are lots of ways to improve this code, but for the sake of the example this will do.</para>
-
- <para>Nows lets create the Example5 runner.</para>
-
- <example>
- <title>Banking Tutorial : Java Example5</title>
-
- <programlisting>public class Example5 {
- public static void main(String[] args) throws Exception {
- Object[] cashflows = {
- new TypedCashflow(new SimpleDate("01/01/2007"),
- TypedCashflow.CREDIT, 300.00),
- new TypedCashflow(new SimpleDate("05/01/2007"),
- TypedCashflow.CREDIT, 100.00),
- new TypedCashflow(new SimpleDate("11/01/2007"),
- TypedCashflow.CREDIT, 500.00),
- new TypedCashflow(new SimpleDate("07/01/2007"),
- TypedCashflow.DEBIT, 800.00),
- new TypedCashflow(new SimpleDate("02/01/2007"),
- TypedCashflow.DEBIT, 400.00),
- };
-
- new RuleRunner().runRules( new String[] { "Example5.drl" },
- cashflows );
- }
-}</programlisting>
- </example>
-
- <para>Here, we simply create a set of Cashflows which are either CREDIT or DEBIT Cashflows and supply them and rule05.drl to the RuleEngine. </para>
-
- <para>Now, let’s look at rule0 Example5.drl to see how we print the sorted Cashflows:</para>
-
- <example>
- <title>Banking Tutorial : Rule Example5</title>
-
- <programlisting>rule "Rule 05"
- when
- $cashflow : TypedCashflow( $date : date,
- $amount : amount,
- type == TypedCashflow.CREDIT )
- not TypedCashflow( date < $date,
- type == TypedCashflow.CREDIT )
- then
- System.out.println("Credit: "+$date+" :: "+$amount);
- retract($cashflow);
-end</programlisting>
- </example>
-
- <para>Here, we identify a Cashflow with a type of CREDIT and extract the date and the amount. In the second line of the rules we ensure that there is not a Cashflow of type CREDIT with an earlier date than the one found. In the consequences, we print the Cashflow that satisfies the rules and then retract it, making way for the next earliest Cashflow of type CREDIT.</para>
-
- <para>So, the output we generate is</para>
-
- <example>
- <title>Banking Tutorial : Output Example5</title>
-
- <screen>Loading file: Example5.drl
-Inserting fact: TypedCashflow[date=Mon Jan 01 00:00:00 GMT 2007,type=Credit,amount=300.0]
-Inserting fact: TypedCashflow[date=Fri Jan 05 00:00:00 GMT 2007,type=Credit,amount=100.0]
-Inserting fact: TypedCashflow[date=Thu Jan 11 00:00:00 GMT 2007,type=Credit,amount=500.0]
-Inserting fact: TypedCashflow[date=Sun Jan 07 00:00:00 GMT 2007,type=Debit,amount=800.0]
-Inserting fact: TypedCashflow[date=Tue Jan 02 00:00:00 GMT 2007,type=Debit,amount=400.0]
-Credit: Mon Jan 01 00:00:00 GMT 2007 :: 300.0
-Credit: Fri Jan 05 00:00:00 GMT 2007 :: 100.0
-Credit: Thu Jan 11 00:00:00 GMT 2007 :: 500.0
-</screen>
- </example>
-
- <para>Here we are going to process both CREDITs and DEBITs on 2 bank accounts to calculate the account balance. In order to do this, I am going to create two separate Account Objects and inject them into the Cashflows before passing them to the Rule Engine. The reason for this is to provide easy access to the correct Bank Accounts without having to resort to Helper classes. Let’s take a look at the Account class first. This is a simple POJO with an account number and balance:</para>
-
- <example>
- <title>Banking Tutoria : Class Account</title>
-
- <programlisting>public class Account {
- private long accountNo;
- private double balance = 0;
-
- public Account() {
- }
-
- public Account(long accountNo) {
- this.accountNo = accountNo;
- }
-
- public long getAccountNo() {
- return accountNo;
- }
-
- public void setAccountNo(long accountNo) {
- this.accountNo = accountNo;
- }
-
- public double getBalance() {
- return balance;
- }
-
- public void setBalance(double balance) {
- this.balance = balance;
- }
-
- public String toString() {
- return "Account[" + "accountNo=" + accountNo + ",balance=" + balance + "]";
- }
-}</programlisting>
- </example>
-
- <para>Now let’s extend our TypedCashflow to give AllocatedCashflow (allocated to an account).</para>
-
- <example>
- <title>Banking Tutoria : Class AllocatedCashflow</title>
-
- <programlisting>public class AllocatedCashflow extends TypedCashflow {
- private Account account;
-
- public AllocatedCashflow() {
- }
-
- public AllocatedCashflow(Account account,
- Date date,
- int type,
- double amount) {
- super( date,
- type,
- amount );
- this.account = account;
- }
-
- public Account getAccount() {
- return account;
- }
-
- public void setAccount(Account account) {
- this.account = account;
- }
-
- public String toString() {
- return "AllocatedCashflow[" + "account=" + account + ",date=" + getDate() +
- ",type=" + (getType() == CREDIT ? "Credit" : "Debit") +
- ",amount=" + getAmount() + "]";
- }
-}</programlisting>
- </example>
-
- <para>Now, let’s java code for Example5 execution. Here we create two Account objects and inject one into each cashflow as appropriate. For simplicity I have simply included them in the constructor.</para>
-
- <example>
- <title>Banking Tutorial : Java Example5</title>
-
- <programlisting>public class Example6 {
- public static void main(String[] args) throws Exception {
- Account acc1 = new Account(1);
- Account acc2 = new Account(2);
-
- Object[] cashflows = {
- new AllocatedCashflow(acc1,new SimpleDate("01/01/2007"),
- TypedCashflow.CREDIT, 300.00),
- new AllocatedCashflow(acc1,new SimpleDate("05/02/2007"),
- TypedCashflow.CREDIT, 100.00),
- new AllocatedCashflow(acc2,new SimpleDate("11/03/2007"),
- TypedCashflow.CREDIT, 500.00),
- new AllocatedCashflow(acc1,new SimpleDate("07/02/2007"),
- TypedCashflow.DEBIT, 800.00),
- new AllocatedCashflow(acc2,new SimpleDate("02/03/2007"),
- TypedCashflow.DEBIT, 400.00),
- new AllocatedCashflow(acc1,new SimpleDate("01/04/2007"),
- TypedCashflow.CREDIT, 200.00),
- new AllocatedCashflow(acc1,new SimpleDate("05/04/2007"),
- TypedCashflow.CREDIT, 300.00),
- new AllocatedCashflow(acc2,new SimpleDate("11/05/2007"),
- TypedCashflow.CREDIT, 700.00),
- new AllocatedCashflow(acc1,new SimpleDate("07/05/2007"),
- TypedCashflow.DEBIT, 900.00),
- new AllocatedCashflow(acc2,new SimpleDate("02/05/2007"),
- TypedCashflow.DEBIT, 100.00)
- };
-
- new RuleRunner().runRules( new String[] { "Example6.drl" },
- cashflows );
- }
-}</programlisting>
- </example>
-
- <para>Now, let’s look at rule Example06.drl to see how we apply each cashflow in date order and calculate and print the balance. </para>
-
- <example>
- <title>Banking Tutorial : Rule Example6</title>
-
- <programlisting>rule "Rule 06 - Credit"
- when
- $cashflow : AllocatedCashflow( $account : account,
- $date : date, $amount : amount,
- type==TypedCashflow.CREDIT )
- not AllocatedCashflow( account == $account, date < $date)
- then
- System.out.println("Credit: " + $date + " :: " + $amount);
- $account.setBalance($account.getBalance()+$amount);
- System.out.println("Account: " + $account.getAccountNo() +
- " - new balance: " + $account.getBalance());
- retract($cashflow);
-end
-
-rule "Rule 06 - Debit"
- when
- $cashflow : AllocatedCashflow( $account : account,
- $date : date, $amount : amount,
- type==TypedCashflow.DEBIT )
- not AllocatedCashflow( account == $account, date < $date)
- then
- System.out.println("Debit: " + $date + " :: " + $amount);
- $account.setBalance($account.getBalance() - $amount);
- System.out.println("Account: " + $account.getAccountNo() +
- " - new balance: " + $account.getBalance());
- retract($cashflow);
-end</programlisting>
- </example>
-
- <para>Here, we have separate rules for CREDITs and DEBITs, however we do not specify a type when checking for earlier cashflows. This is so that all cashflows are applied in date order regardless of which type of cashflow type they are. In the rule section we identify the correct account to work with and in the consequences we update it with the cashflow amount.</para>
-
- <example>
- <title>Banking Tutorial : Output Example6</title>
-
- <programlisting>Loading file: Example6.drl
-Inserting fact: AllocatedCashflow[account=Account[accountNo=1,balance=0.0],date=Mon Jan 01 00:00:00 GMT 2007,type=Credit,amount=300.0]
-Inserting fact: AllocatedCashflow[account=Account[accountNo=1,balance=0.0],date=Mon Feb 05 00:00:00 GMT 2007,type=Credit,amount=100.0]
-Inserting fact: AllocatedCashflow[account=Account[accountNo=2,balance=0.0],date=Sun Mar 11 00:00:00 GMT 2007,type=Credit,amount=500.0]
-Inserting fact: AllocatedCashflow[account=Account[accountNo=1,balance=0.0],date=Wed Feb 07 00:00:00 GMT 2007,type=Debit,amount=800.0]
-Inserting fact: AllocatedCashflow[account=Account[accountNo=2,balance=0.0],date=Fri Mar 02 00:00:00 GMT 2007,type=Debit,amount=400.0]
-Inserting fact: AllocatedCashflow[account=Account[accountNo=1,balance=0.0],date=Sun Apr 01 00:00:00 BST 2007,type=Credit,amount=200.0]
-Inserting fact: AllocatedCashflow[account=Account[accountNo=1,balance=0.0],date=Thu Apr 05 00:00:00 BST 2007,type=Credit,amount=300.0]
-Inserting fact: AllocatedCashflow[account=Account[accountNo=2,balance=0.0],date=Fri May 11 00:00:00 BST 2007,type=Credit,amount=700.0]
-Inserting fact: AllocatedCashflow[account=Account[accountNo=1,balance=0.0],date=Mon May 07 00:00:00 BST 2007,type=Debit,amount=900.0]
-Inserting fact: AllocatedCashflow[account=Account[accountNo=2,balance=0.0],date=Wed May 02 00:00:00 BST 2007,type=Debit,amount=100.0]
-Debit: Fri Mar 02 00:00:00 GMT 2007 :: 400.0
-Account: 2 - new balance: -400.0
-Credit: Sun Mar 11 00:00:00 GMT 2007 :: 500.0
-Account: 2 - new balance: 100.0
-Debit: Wed May 02 00:00:00 BST 2007 :: 100.0
-Account: 2 - new balance: 0.0
-Credit: Fri May 11 00:00:00 BST 2007 :: 700.0
-Account: 2 - new balance: 700.0
-Credit: Mon Jan 01 00:00:00 GMT 2007 :: 300.0
-Account: 1 - new balance: 300.0
-Credit: Mon Feb 05 00:00:00 GMT 2007 :: 100.0
-Account: 1 - new balance: 400.0
-Debit: Wed Feb 07 00:00:00 GMT 2007 :: 800.0
-Account: 1 - new balance: -400.0
-Credit: Sun Apr 01 00:00:00 BST 2007 :: 200.0
-Account: 1 - new balance: -200.0
-Credit: Thu Apr 05 00:00:00 BST 2007 :: 300.0
-Account: 1 - new balance: 100.0
-Debit: Mon May 07 00:00:00 BST 2007 :: 900.0
-Account: 1 - new balance: -800.0
-</programlisting>
- </example>
-
- </section>
+}]]></programlisting>
+ </example>
+
+ <para>The first of our sample Java classes loads and executes a single
+ DRL file, <filename>Example.drl</filename>, but without inserting any
+ data.</para>
+
+ <example>
+ <title>Banking Tutorial : Java Example1</title>
+
+ <programlisting>public class Example1 {
+ public static void main(String[] args) throws Exception {
+ new RuleRunner().runRules( new String[] { "Example1.drl" },
+ new Object[0] );
+ }
+}</programlisting>
+ </example>
+
+ <para>The first simple rule to execute has a single <kw>eval</kw>
+ condition that will alway be true, so that this rule will match and
+ fire, once, after the start.</para>
+
+ <example>
+ <title>Banking Tutorial: Rule in Example1.drl</title>
+
+ <programlisting>rule "Rule 01"
+ when
+ eval( 1==1 )
+ then
+ System.out.println( "Rule 01 Works" );
+endh</programlisting>
+ </example>
+
+ <para>The output for the rule is below, showing that the rule matches
+ and executes the single print statement.</para>
+
+ <example>
+ <title>Banking Tutorial: Output of Example1.java</title>
+
+ <programlisting>Loading file: Example1.drl
+Rule 01 Works</programlisting>
+ </example>
+
+ <para>The next step is to assert some simple facts and print them
+ out.</para>
+
+ <example>
+ <title>Banking Tutorial: Java Example2</title>
+
+ <programlisting>public class Example2 {
+ public static void main(String[] args) throws Exception {
+ Number[] numbers = new Number[] {wrap(3), wrap(1), wrap(4), wrap(1), wrap(5)};
+ new RuleRunner().runRules( new String[] { "Example2.drl" },
+ numbers );
+ }
+
+ private static Integer wrap( int i ) {
+ return new Integer(i);
+ }
+}</programlisting>
+ </example>
+
+ <para>This doesn’t use any specific facts but instead asserts a set
+ of <code>java.lang.Integer</code> objects. This is not considered
+ "best practice" as a number is not a useful fact, but we use it here
+ to demonstrate basic techniques before more complexity is added.</para>
+
+ <para>Now we will create a simple rule to print out these numbers.</para>
+
+ <example>
+ <title>Banking Tutorial: Rule in Example2.drl</title>
+
+ <programlisting>rule "Rule 02"
+ when
+ Number( $intValue : intValue )
+ then
+ System.out.println( "Number found with value: " + $intValue );
+end</programlisting>
+ </example>
+
+ <para>Once again, this rule does nothing special. It identifies any
+ facts that are <code>Number</code> objects and prints out the values.
+ Notice the use of the abstract class <code>Number</code>: we inserted
+ <code>Integer</code> objects but we now look for any kind of number.
+ The pattern matching engine is able to match interfaces and
+ superclasses of asserted objects.</para>
+
+ <para>The output shows the DRL being loaded, the facts inserted and
+ then the matched and fired rules. We can see that each inserted number
+ is matched and fired and thus printed.</para>
+
+ <example>
+ <title>Banking Tutorial: Output of Example2.java</title>
+
+ <programlisting>Loading file: Example2.drl
+Inserting fact: 3
+Inserting fact: 1
+Inserting fact: 4
+Inserting fact: 1
+Inserting fact: 5
+Number found with value: 5
+Number found with value: 1
+Number found with value: 4
+Number found with value: 1
+Number found with value: 3
+</programlisting>
+ </example>
+
+ <para>There are certainly many better ways to sort numbers than using
+ rules, but since we will need to apply some cashflows in date order
+ when we start looking at banking rules we'll develop simple rule
+ based sorting technique.</para>
+
+ <example>
+ <title>Banking Tutorial: Example3.java</title>
+
+ <programlisting>public class Example3 {
+ public static void main(String[] args) throws Exception {
+ Number[] numbers = new Number[] {wrap(3), wrap(1), wrap(4), wrap(1), wrap(5)};
+ new RuleRunner().runRules( new String[] { "Example3.drl" },
+ numbers );
+ }
+
+ private static Integer wrap(int i) {
+ return new Integer(i);
+ }
+}</programlisting>
+ </example>
+
+ <para>Again we insert our <code>Integer</code> objects, but this time the
+ rule is slightly different:</para>
+
+ <example>
+ <title>Banking Tutorial: Rule in Example3.drl</title>
+
+ <programlisting>rule "Rule 03"
+ when
+ $number : Number( )
+ not Number( intValue < $number.intValue )
+ then
+ System.out.println("Number found with value: " + $number.intValue() );
+ retract( $number );
+end</programlisting>
+ </example>
+
+ <para>The first line of the rule identifies a <code>Number</code> and
+ extracts the value. The second line ensures that there does not exist
+ a smaller number than the one found by the first pattern. We might
+ expect to match only one number - the smallest in the set. However,
+ the retraction of the number after it has been printed means that the
+ smallest number has been removed, revealing the next smallest number,
+ and so on. </para>
+
+ <para>The resulting output shows that the numbers are now
+ sorted numerically.</para>
+
+ <example>
+ <title>Banking Tutorial: Output of Example3.java</title>
+
+ <programlisting>Loading file: Example3.drl
+Inserting fact: 3
+Inserting fact: 1
+Inserting fact: 4
+Inserting fact: 1
+Inserting fact: 5
+Number found with value: 1
+Number found with value: 1
+Number found with value: 3
+Number found with value: 4
+Number found with value: 5
+</programlisting>
+ </example>
+
+ <para>We are ready to start moving towards our personal accounting
+ rules. The first step is to create a <code>Cashflow</code> object.</para>
+
+ <example>
+ <title>Banking Tutorial: Class Cashflow</title>
+
+ <programlisting>public class Cashflow {
+ private Date date;
+ private double amount;
+
+ public Cashflow() {
+ }
+
+ public Cashflow(Date date, double amount) {
+ this.date = date;
+ this.amount = amount;
+ }
+
+ public Date getDate() {
+ return date;
+ }
+
+ public void setDate(Date date) {
+ this.date = date;
+ }
+
+ public double getAmount() {
+ return amount;
+ }
+
+ public void setAmount(double amount) {
+ this.amount = amount;
+ }
+
+ public String toString() {
+ return "Cashflow[date=" + date + ",amount=" + amount + "]";
+ }
+}</programlisting>
+ </example>
+
+ <para>Class <code>Cashflow</code> has two simple attributes, a date
+ and an amount. (Note that using the type <code>double</code> for
+ monetary units is generally <emphasis>not</emphasis> a good idea
+ because floating point numbers cannot represent most numbers accurately.)
+ There is also an overloaded constructor to set the values, and a
+ method <code>toString</code> to print a cashflow. The Java code of
+ <filename>Example4.java</filename> inserts five Cashflow objects,
+ with varying dates and amounts.</para>
+
+ <example>
+ <title>Banking Tutorial: Example4.java</title>
+
+ <programlisting>public class Example4 {
+ public static void main(String[] args) throws Exception {
+ Object[] cashflows = {
+ new Cashflow(new SimpleDate("01/01/2007"), 300.00),
+ new Cashflow(new SimpleDate("05/01/2007"), 100.00),
+ new Cashflow(new SimpleDate("11/01/2007"), 500.00),
+ new Cashflow(new SimpleDate("07/01/2007"), 800.00),
+ new Cashflow(new SimpleDate("02/01/2007"), 400.00),
+ };
+
+ new RuleRunner().runRules( new String[] { "Example4.drl" },
+ cashflows );
+ }
+}</programlisting>
+ </example>
+
+ <para>The convenience class <code>SimpleDate</code> extends
+ <code>java.util.Date</code>, providing a constructor taking
+ a String as input and defining a date format. The code is
+ listed below</para>
+
+ <example>
+ <title>Banking Tutorial: Class SimpleDate</title>
+
+ <programlisting>public class SimpleDate extends Date {
+ private static final SimpleDateFormat format = new SimpleDateFormat("dd/MM/yyyy");
+
+ public SimpleDate(String datestr) throws Exception {
+ setTime(format.parse(datestr).getTime());
+ }
+}</programlisting>
+ </example>
+
+ <para>Now, let’s look at <filename>Example4.drl</filename> to see how
+ we print the sorted <code>Cashflow</code> objects:</para>
+
+ <example>
+ <title>Banking Tutorial: Rule in Example4.drl</title>
+
+ <programlisting>rule "Rule 04"
+ when
+ $cashflow : Cashflow( $date : date, $amount : amount )
+ not Cashflow( date < $date)
+ then
+ System.out.println("Cashflow: "+$date+" :: "+$amount);
+ retract($cashflow);
+end</programlisting>
+ </example>
+
+ <para>Here, we identify a <code>Cashflow</code> and extract the date
+ and the amount. In the second line of the rule we ensure that there
+ is no Cashflow with an earlier date than the one found. In the
+ consequence, we print the <code>Cashflow</code> that satisfies the
+ rule and then retract it, making way for the next earliest
+ <code>Cashflow</code>. So, the output we generate is:</para>
+
+ <example>
+ <title>Banking Tutorial: Output of Example4.java</title>
+
+ <programlisting>Loading file: Example4.drl
+Inserting fact: Cashflow[date=Mon Jan 01 00:00:00 GMT 2007,amount=300.0]
+Inserting fact: Cashflow[date=Fri Jan 05 00:00:00 GMT 2007,amount=100.0]
+Inserting fact: Cashflow[date=Thu Jan 11 00:00:00 GMT 2007,amount=500.0]
+Inserting fact: Cashflow[date=Sun Jan 07 00:00:00 GMT 2007,amount=800.0]
+Inserting fact: Cashflow[date=Tue Jan 02 00:00:00 GMT 2007,amount=400.0]
+Cashflow: Mon Jan 01 00:00:00 GMT 2007 :: 300.0
+Cashflow: Tue Jan 02 00:00:00 GMT 2007 :: 400.0
+Cashflow: Fri Jan 05 00:00:00 GMT 2007 :: 100.0
+Cashflow: Sun Jan 07 00:00:00 GMT 2007 :: 800.0
+Cashflow: Thu Jan 11 00:00:00 GMT 2007 :: 500.0
+</programlisting>
+ </example>
+
+ <para>Next, we extend our <code>Cashflow</code>, resulting in a
+ <code>TypedCashflow</code> which can be a credit or a debit operation.
+ (Normally, we would just add this to the <code>Cashflow</code> type, but
+ we use extension to keep the previous version of the class intact.)</para>
+
+ <example>
+ <title>Banking Tutorial: Class TypedCashflow</title>
+
+ <programlisting>public class TypedCashflow extends Cashflow {
+ public static final int CREDIT = 0;
+ public static final int DEBIT = 1;
+
+ private int type;
+
+ public TypedCashflow() {
+ }
+
+ public TypedCashflow(Date date, int type, double amount) {
+ super( date, amount );
+ this.type = type;
+ }
+
+ public int getType() {
+ return type;
+ }
+
+ public void setType(int type) {
+ this.type = type;
+ }
+
+ public String toString() {
+ return "TypedCashflow[date=" + getDate() +
+ ",type=" + (type == CREDIT ? "Credit" : "Debit") +
+ ",amount=" + getAmount() + "]";
+ }
+}</programlisting>
+ </example>
+
+ <para>There are lots of ways to improve this code, but for the sake
+ of the example this will do.</para>
+
+ <para>Now let's create Example5, a class for running our code.</para>
+
+ <example>
+ <title>Banking Tutorial: Example5.java</title>
+
+ <programlisting>public class Example5 {
+ public static void main(String[] args) throws Exception {
+ Object[] cashflows = {
+ new TypedCashflow(new SimpleDate("01/01/2007"),
+ TypedCashflow.CREDIT, 300.00),
+ new TypedCashflow(new SimpleDate("05/01/2007"),
+ TypedCashflow.CREDIT, 100.00),
+ new TypedCashflow(new SimpleDate("11/01/2007"),
+ TypedCashflow.CREDIT, 500.00),
+ new TypedCashflow(new SimpleDate("07/01/2007"),
+ TypedCashflow.DEBIT, 800.00),
+ new TypedCashflow(new SimpleDate("02/01/2007"),
+ TypedCashflow.DEBIT, 400.00),
+ };
+
+ new RuleRunner().runRules( new String[] { "Example5.drl" },
+ cashflows );
+ }
+}</programlisting>
+ </example>
+
+ <para>Here, we simply create a set of <code>Cashflow</code> objects
+ which are either credit or debit operations. We supply them and
+ <filename>Example5.drl</filename> to the RuleEngine. </para>
+
+ <para>Now, let’s look at a rule printing the sorted
+ <code>Cashflow</code> objects.</para>
+
+ <example>
+ <title>Banking Tutorial: Rule in Example5.drl</title>
+
+ <programlisting>rule "Rule 05"
+ when
+ $cashflow : TypedCashflow( $date : date,
+ $amount : amount,
+ type == TypedCashflow.CREDIT )
+ not TypedCashflow( date < $date,
+ type == TypedCashflow.CREDIT )
+ then
+ System.out.println("Credit: "+$date+" :: "+$amount);
+ retract($cashflow);
+end</programlisting>
+ </example>
+
+ <para>Here, we identify a <code>Cashflow</code> fact with a type
+ of <code>CREDIT</code> and extract the date and the amount. In the
+ second line of the rule we ensure that there is no <code>Cashflow</code>
+ of the same type with an earlier date than the one found. In the
+ consequence, we print the cashflow satisfying the patterns and then
+ retract it, making way for the next earliest cashflow of type
+ <code>CREDIT</code>.</para>
+
+ <para>So, the output we generate is</para>
+
+ <example>
+ <title>Banking Tutorial: Output of Example5.java</title>
+
+ <screen>Loading file: Example5.drl
+Inserting fact: TypedCashflow[date=Mon Jan 01 00:00:00 GMT 2007,type=Credit,amount=300.0]
+Inserting fact: TypedCashflow[date=Fri Jan 05 00:00:00 GMT 2007,type=Credit,amount=100.0]
+Inserting fact: TypedCashflow[date=Thu Jan 11 00:00:00 GMT 2007,type=Credit,amount=500.0]
+Inserting fact: TypedCashflow[date=Sun Jan 07 00:00:00 GMT 2007,type=Debit,amount=800.0]
+Inserting fact: TypedCashflow[date=Tue Jan 02 00:00:00 GMT 2007,type=Debit,amount=400.0]
+Credit: Mon Jan 01 00:00:00 GMT 2007 :: 300.0
+Credit: Fri Jan 05 00:00:00 GMT 2007 :: 100.0
+Credit: Thu Jan 11 00:00:00 GMT 2007 :: 500.0
+</screen>
+ </example>
+
+ <para>Continuing our banking exercise, we are now going to process both
+ credits and debits on two bank accounts, calculating the account balance.
+ In order to do this, we create two separate <code>Account</code> objects
+ and inject them into the <code>Cashflows</code> objects before passing
+ them to the Rule Engine. The reason for this is to provide easy access
+ to the correct account without having to resort to helper classes. Let’s
+ take a look at the <code>Account</code> class first. This is a simple
+ Java object with an account number and balance:</para>
+
+ <example>
+ <title>Banking Tutorial: Class Account</title>
+
+ <programlisting>public class Account {
+ private long accountNo;
+ private double balance = 0;
+
+ public Account() {
+ }
+
+ public Account(long accountNo) {
+ this.accountNo = accountNo;
+ }
+
+ public long getAccountNo() {
+ return accountNo;
+ }
+
+ public void setAccountNo(long accountNo) {
+ this.accountNo = accountNo;
+ }
+
+ public double getBalance() {
+ return balance;
+ }
+
+ public void setBalance(double balance) {
+ this.balance = balance;
+ }
+
+ public String toString() {
+ return "Account[" + "accountNo=" + accountNo + ",balance=" + balance + "]";
+ }
+}</programlisting>
+ </example>
+
+ <para>Now let’s extend our <code>TypedCashflow</code>, resulting in
+ <code>AllocatedCashflow</code>, to include an <code>Account</code>
+ reference.</para>
+
+ <example>
+ <title>Banking Tutorial: Class AllocatedCashflow</title>
+
+ <programlisting>public class AllocatedCashflow extends TypedCashflow {
+ private Account account;
+
+ public AllocatedCashflow() {
+ }
+
+ public AllocatedCashflow(Account account, Date date, int type, double amount) {
+ super( date, type, amount );
+ this.account = account;
+ }
+
+ public Account getAccount() {
+ return account;
+ }
+
+ public void setAccount(Account account) {
+ this.account = account;
+ }
+
+ public String toString() {
+ return "AllocatedCashflow[" +
+ "account=" + account +
+ ",date=" + getDate() +
+ ",type=" + (getType() == CREDIT ? "Credit" : "Debit") +
+ ",amount=" + getAmount() + "]";
+ }
+}</programlisting>
+ </example>
+
+ <para>The Java code of <filename>Example5.java</filename> creates
+ two <code>Account</code> objects and passes one of them into each
+ cashflow, in the constructor call.</para>
+
+ <example>
+ <title>Banking Tutorial: Example5.java</title>
+
+ <programlisting>public class Example6 {
+ public static void main(String[] args) throws Exception {
+ Account acc1 = new Account(1);
+ Account acc2 = new Account(2);
+
+ Object[] cashflows = {
+ new AllocatedCashflow(acc1,new SimpleDate("01/01/2007"),
+ TypedCashflow.CREDIT, 300.00),
+ new AllocatedCashflow(acc1,new SimpleDate("05/02/2007"),
+ TypedCashflow.CREDIT, 100.00),
+ new AllocatedCashflow(acc2,new SimpleDate("11/03/2007"),
+ TypedCashflow.CREDIT, 500.00),
+ new AllocatedCashflow(acc1,new SimpleDate("07/02/2007"),
+ TypedCashflow.DEBIT, 800.00),
+ new AllocatedCashflow(acc2,new SimpleDate("02/03/2007"),
+ TypedCashflow.DEBIT, 400.00),
+ new AllocatedCashflow(acc1,new SimpleDate("01/04/2007"),
+ TypedCashflow.CREDIT, 200.00),
+ new AllocatedCashflow(acc1,new SimpleDate("05/04/2007"),
+ TypedCashflow.CREDIT, 300.00),
+ new AllocatedCashflow(acc2,new SimpleDate("11/05/2007"),
+ TypedCashflow.CREDIT, 700.00),
+ new AllocatedCashflow(acc1,new SimpleDate("07/05/2007"),
+ TypedCashflow.DEBIT, 900.00),
+ new AllocatedCashflow(acc2,new SimpleDate("02/05/2007"),
+ TypedCashflow.DEBIT, 100.00)
+ };
+
+ new RuleRunner().runRules( new String[] { "Example6.drl" },
+ cashflows );
+ }
+}</programlisting>
+ </example>
+
+ <para>Now, let’s look at the rule in <filename>Example6.drl</filename>
+ to see how we apply each cashflow in date order and calculate and print
+ the balance. </para>
+
+ <example>
+ <title>Banking Tutorial: Rule in Example6.drl</title>
+
+ <programlisting>rule "Rule 06 - Credit"
+ when
+ $cashflow : AllocatedCashflow( $account : account,
+ $date : date,
+ $amount : amount,
+ type == TypedCashflow.CREDIT )
+ not AllocatedCashflow( account == $account, date < $date)
+ then
+ System.out.println("Credit: " + $date + " :: " + $amount);
+ $account.setBalance($account.getBalance()+$amount);
+ System.out.println("Account: " + $account.getAccountNo() +
+ " - new balance: " + $account.getBalance());
+ retract($cashflow);
+end
+
+rule "Rule 06 - Debit"
+ when
+ $cashflow : AllocatedCashflow( $account : account,
+ $date : date,
+ $amount : amount,
+ type == TypedCashflow.DEBIT )
+ not AllocatedCashflow( account == $account, date < $date)
+ then
+ System.out.println("Debit: " + $date + " :: " + $amount);
+ $account.setBalance($account.getBalance() - $amount);
+ System.out.println("Account: " + $account.getAccountNo() +
+ " - new balance: " + $account.getBalance());
+ retract($cashflow);
+end</programlisting>
+ </example>
+
+ <para>Although we have separate rules for credits and debits, but we do
+ not specify a type when checking for earlier cashflows. This is so that
+ all cashflows are applied in date order, regardless of the cashflow type.
+ In the conditions we identify the account to work with, and in the
+ consequences we update it with the cashflow amount.</para>
+
+ <example>
+ <title>Banking Tutorial: Output of Example6.java</title>
+
+ <programlisting>Loading file: Example6.drl
+Inserting fact: AllocatedCashflow[account=Account[accountNo=1,balance=0.0],date=Mon Jan 01 00:00:00 GMT 2007,type=Credit,amount=300.0]
+Inserting fact: AllocatedCashflow[account=Account[accountNo=1,balance=0.0],date=Mon Feb 05 00:00:00 GMT 2007,type=Credit,amount=100.0]
+Inserting fact: AllocatedCashflow[account=Account[accountNo=2,balance=0.0],date=Sun Mar 11 00:00:00 GMT 2007,type=Credit,amount=500.0]
+Inserting fact: AllocatedCashflow[account=Account[accountNo=1,balance=0.0],date=Wed Feb 07 00:00:00 GMT 2007,type=Debit,amount=800.0]
+Inserting fact: AllocatedCashflow[account=Account[accountNo=2,balance=0.0],date=Fri Mar 02 00:00:00 GMT 2007,type=Debit,amount=400.0]
+Inserting fact: AllocatedCashflow[account=Account[accountNo=1,balance=0.0],date=Sun Apr 01 00:00:00 BST 2007,type=Credit,amount=200.0]
+Inserting fact: AllocatedCashflow[account=Account[accountNo=1,balance=0.0],date=Thu Apr 05 00:00:00 BST 2007,type=Credit,amount=300.0]
+Inserting fact: AllocatedCashflow[account=Account[accountNo=2,balance=0.0],date=Fri May 11 00:00:00 BST 2007,type=Credit,amount=700.0]
+Inserting fact: AllocatedCashflow[account=Account[accountNo=1,balance=0.0],date=Mon May 07 00:00:00 BST 2007,type=Debit,amount=900.0]
+Inserting fact: AllocatedCashflow[account=Account[accountNo=2,balance=0.0],date=Wed May 02 00:00:00 BST 2007,type=Debit,amount=100.0]
+Debit: Fri Mar 02 00:00:00 GMT 2007 :: 400.0
+Account: 2 - new balance: -400.0
+Credit: Sun Mar 11 00:00:00 GMT 2007 :: 500.0
+Account: 2 - new balance: 100.0
+Debit: Wed May 02 00:00:00 BST 2007 :: 100.0
+Account: 2 - new balance: 0.0
+Credit: Fri May 11 00:00:00 BST 2007 :: 700.0
+Account: 2 - new balance: 700.0
+Credit: Mon Jan 01 00:00:00 GMT 2007 :: 300.0
+Account: 1 - new balance: 300.0
+Credit: Mon Feb 05 00:00:00 GMT 2007 :: 100.0
+Account: 1 - new balance: 400.0
+Debit: Wed Feb 07 00:00:00 GMT 2007 :: 800.0
+Account: 1 - new balance: -400.0
+Credit: Sun Apr 01 00:00:00 BST 2007 :: 200.0
+Account: 1 - new balance: -200.0
+Credit: Thu Apr 05 00:00:00 BST 2007 :: 300.0
+Account: 1 - new balance: 100.0
+Debit: Mon May 07 00:00:00 BST 2007 :: 900.0
+Account: 1 - new balance: -800.0
+</programlisting>
+ </example>
+
+ </section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-FibonacciExample.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-FibonacciExample.xml 2009-04-25 17:35:09 UTC (rev 26259)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-FibonacciExample.xml 2009-04-25 21:15:40 UTC (rev 26260)
@@ -1,176 +1,259 @@
-<?xml version="1.0" encoding="UTF-8"?>
- <section version="5.0" xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xmlns:svg="http://www.w3.org/2000/svg"
- xmlns:m="http://www.w3.org/1998/Math/MathML"
- xmlns:html="http://www.w3.org/1999/xhtml"
- xmlns:db="http://docbook.org/ns/docbook" xml:base="../../">
- <title>Fibonacci Example</title>
-
- <screen><emphasis role="bold">Name:</emphasis> Fibonacci
-<emphasis role="bold">Main class:</emphasis> org.drools.examples.FibonacciExample
-<emphasis role="bold">Type:</emphasis> java application
-<emphasis role="bold">Rules file:</emphasis> Fibonacci.drl
-<emphasis role="bold">Objective:</emphasis> Demonsrates Recursion, 'not' CEs and Cross Product Matching</screen>
-
- <para>The Fibonacci Numbers, <ulink url="http://en.wikipedia.org/wiki/Fibonacci_number">http://en.wikipedia.org/wiki/Fibonacci_number</ulink>, invented by Leonardo of Pisa, <ulink url="http://en.wikipedia.org/wiki/Fibonacci">http://en.wikipedia.org/wiki/Fibonacci</ulink>, are obtained by starting with 0 and 1, and then produce the next Fibonacci number by adding the two previous Fibonacci numbers. The first Fibonacci numbers for n = 0, 1,... are: * 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987, 1597, 2584, 4181, 6765, 10946... The Fibonacci Example demonstrates recursion and conflict resolution with Salience values.</para>
-
- <para>A single fact Class is used in this example, Fibonacci. It has two fields, sequence and value. The sequence field is used to indicate the position of the object in the Fibonacci number sequence and the value field shows the value of that Fibonacci object for that sequence position.</para>
-
- <example>
- <title>Fibonacci Class</title>
-
- <programlisting>public static class Fibonacci {
- private int sequence;
- private long value;
-
- ... setters and getters go here...
-}</programlisting>
- </example>
-
- <para>Execute the example:</para>
-
- <orderedlist>
- <listitem>
- <para>Open the class <classname>org.drools.examples.FibonacciExample</classname> in your Eclipse IDE</para>
- </listitem>
-
- <listitem>
- <para>Right-click the class an select "Run as..." -> "Java application"</para>
- </listitem>
- </orderedlist>
-
- <para>And Eclipse shows the following output in its console, "...snip..." shows repeated bits removed to save space:</para>
-
- <example>
- <title>Fibonacci Example Console Output</title>
-
- <programlisting>recurse for 50
-recurse for 49
-recurse for 48
-recurse for 47
-...snip...
-recurse for 5
-recurse for 4
-recurse for 3
-recurse for 2
-1 == 1
-2 == 1
-3 == 2
-4 == 3
-5 == 5
-6 == 8
-...snip...
-47 == 2971215073
-48 == 4807526976
-49 == 7778742049
-50 == 12586269025
-</programlisting>
- </example>
-
- <para>To kick this off from java we only insert a single Fibonacci object, with a sequence of 50, a recurse rule is then used to insert the other 49 Fibonacci objects. This example doesn't use PropertyChangeSupport and uses the MVEL dialect, this means we can use the <emphasis role="bold">modify</emphasis> keyword, which allows a block setter action which also notifies the engine of changes.</para>
-
- <example>
- <title>Fibonacci Example Execution</title>
-
- <programlisting>ksession.insert( new Fibonacci( 50 ) );
-ksession.fireAllRules();</programlisting>
- </example>
-
- <para>The recurse rule is very simple, it matches each asserted Fibonacci object with a value of -1, it then creates and asserts a new Fibonacci object with a sequence of one less than the currently matched object. Each time a Fibonacci object is added, as long as one with a "sequence == 1" does not exist, the rule re-matches again and fires; causing the recursion. The 'not' conditional element is used to stop the rule matching once we have all 50 Fibonacci objects in memory. The rule also has a salience value, this is because we need to have all 50 Fibonacci objects asserted before we execute the Bootstrap rule.</para>
-
- <example>
- <title>Fibonacci Example : Rule "Recurse"</title>
-
- <programlisting>rule Recurse
- salience 10
- when
- f : Fibonacci ( value == -1 )
- not ( Fibonacci ( sequence == 1 ) )
- then
- insert( new Fibonacci( f.sequence - 1 ) );
- System.out.println( "recurse for " + f.sequence );
-end</programlisting>
- </example>
-
- <para>The audit view shows the original assertion of the Fibonacci object with a sequence of 50, this was done from Java land. From there the audit view shows the continual recursion of the rule, each asserted Fibonacci causes the "Recurse" rule to become activate again, which then fires.</para>
-
- <figure>
- <title>Fibonacci Example "Recurse" Audit View 1</title>
-
- <mediaobject>
- <imageobject>
- <imagedata width="100%"
- fileref="images/Chapter-Examples/FibonacciExample/fibonacci1.png" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>When a Fibonacci with a sequence of 2 is asserted the "Bootstrap" rule is matched and activated along with the "Recurse" rule.</para>
-
- <example>
- <title>Fibonacci Example : Rule "Bootstrap"</title>
-
- <programlisting>rule Bootstrap
- when
- f : Fibonacci( sequence == 1 || == 2, value == -1 ) // this is a multi-restriction || on a single field
- then
- modify ( f ){ value = 1 };
- System.out.println( f.sequence + " == " + f.value );
-end</programlisting>
- </example>
-
- <para>At this point the Agenda looks like the figure shown below. However the "Bootstrap" rule does not fire as the "Recurse" rule has a higher salience.</para>
-
- <figure>
- <title>Fibonacci Example "Recurse" Agenda View 1</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/Chapter-Examples/FibonacciExample/fibonacci_agenda1.png" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>When a Fibonacci with a sequence of 1 is asserted the "Bootstrap" rule is matched again, causing two activations for this rule; note that the "Recurse" rule does not match and activate because the 'not conditional element stops the rule matching when a Fibonacci with a sequence of 1 exists.</para>
-
- <figure>
- <title>Fibonacci Example "Recurse" Agenda View 2</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/Chapter-Examples/FibonacciExample/fibonacci_agenda2.png" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Once we have two Fibonacci objects both with values not equal to -1 the "calculate" rule is able to match; remember it was the "Bootstrap" rule that set the Fibonacci's with sequences 1 and 2 to values of 1. At this point we have 50 Fibonacci objects in the Working Memory and we some how need to select the correct ones to calculate each of their values in turn. With three Fibonacci patterns in a rule with no field constriants to correctly constrain the available cross products we have 50x50x50 possible permutations, thats 125K possible rule firings. The "Calculate" rule uses the field constraints to correctly constraint the thee Fibonacci patterns and in the correct order; this technique is called "cross product matching". The first pattern finds any Fibonacci with a value != -1 and binds both the pattern and the field. The second Fibonacci does too but it adds an additional field constraint to make sure that its sequence is one greater than the Fibonacci bound to f!
1. When this rule first fires we know that only sequences 1 and 2 have values of 1 and the two constraints ensure that f1 references sequence 1 and f2 references sequence2. The final pattern finds the Fibonacci of a value == -1 with a sequence one greater than f2. At this point we have three Fibonacci objects correctly selected from the available cross products and we can do the maths calculating the value for Fibonacci sequence = 3.</para>
-
- <example>
- <title>Fibonacci Example : Rule "Calculate"</title>
-
- <programlisting>rule Calculate
- when
- f1 : Fibonacci( s1 : sequence, value != -1 ) // here we bind sequence
- f2 : Fibonacci( sequence == (s1 + 1 ), value != -1 ) // here we don't, just to demonstrate the different way bindings can be used
- f3 : Fibonacci( s3 : sequence == (f2.sequence + 1 ), value == -1 )
- then
- modify ( f3 ) { value = f1.value + f2.value };
- System.out.println( s3 + " == " + f3.value ); // see how you can access pattern and field bindings
-end
-</programlisting>
- </example>
-
- <para>The MVEL modify keyword updated the value of the Fibonacci object bound to f3, this means we have a new Fibonacci object with a value != -1, this allows the "Calculate" rule to rematch and calculate the next Fibonacci number. The Audit view below shows the how the firing of the last "Bootstrap" modifies the Fibonacci object enabling the "Calculate" rule to match, which then modifies another Fibonacci object allowing the "Calculate" rule to rematch. This continues till the value is set for all Fibonacci objects.</para>
-
- <figure>
- <title>Fibonacci Example "Bootstrap" Audit View 1</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/Chapter-Examples/FibonacciExample/fibonacci4.png" />
- </imageobject>
- </mediaobject>
- </figure>
- </section>
+<?xml version="1.0" encoding="UTF-8"?>
+ <section version="5.0" xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns:m="http://www.w3.org/1998/Math/MathML"
+ xmlns:html="http://www.w3.org/1999/xhtml"
+ xmlns:db="http://docbook.org/ns/docbook" xml:base="../../">
+ <title>Fibonacci Example</title>
+
+ <screen><emphasis role="bold">Name:</emphasis> Fibonacci
+<emphasis role="bold">Main class:</emphasis> org.drools.examples.FibonacciExample
+<emphasis role="bold">Type:</emphasis> Java application
+<emphasis role="bold">Rules file:</emphasis> Fibonacci.drl
+<emphasis role="bold">Objective:</emphasis> Demonstrates Recursion,
+ the CE <kw>not</kw> and cross product matching</screen>
+
+ <para>The Fibonacci Numbers (see <ulink url="http://en.wikipedia.org/wiki/Fibonacci_number">http://en.wikipedia.org/wiki/Fibonacci_number</ulink>)
+ discovered by Leonardo of Pisa (see <ulink url="http://en.wikipedia.org/wiki/Fibonacci">http://en.wikipedia.org/wiki/Fibonacci</ulink>) is a sequence
+ that starts with 0 and 1. The next Fibonacci number is obtained by adding
+ the two preceding Fibonacci numbers. The Fibonacci sequence begins with
+ 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987, 1597,
+ 2584, 4181, 6765, 10946,... The Fibonacci Example demonstrates recursion
+ and conflict resolution with salience values.</para>
+
+ <para>The single fact class <code>Fibonacci</code> is used in this
+ example. It has two fields, sequence and value. The sequence field
+ is used to indicate the position of the object in the Fibonacci
+ number sequence. The value field shows the value of that
+ Fibonacci object for that sequence position, using -1 to indicate
+ a value that still needs to be computed.</para>
+
+ <example>
+ <title>Fibonacci Class</title>
+
+ <programlisting>public static class Fibonacci {
+ private int sequence;
+ private long value;
+
+ public Fibonacci( final int sequence ) {
+ this.sequence = sequence;
+ this.value = -1;
+ }
+
+ ... setters and getters go here...
+}</programlisting>
+ </example>
+
+ <para>Execute the example:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Open the class <classname>org.drools.examples.FibonacciExample</classname> in your Eclipse IDE.</para>
+ </listitem>
+
+ <listitem>
+ <para>Right-click the class and select "Run as..." and then
+ "Java application"</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Eclipse shows the following output in its console window (with
+ "...snip..." indicating lines that were removed to save space):</para>
+
+ <example>
+ <title>Fibonacci Example Console Output</title>
+
+ <programlisting>recurse for 50
+recurse for 49
+recurse for 48
+recurse for 47
+...snip...
+recurse for 5
+recurse for 4
+recurse for 3
+recurse for 2
+1 == 1
+2 == 1
+3 == 2
+4 == 3
+5 == 5
+6 == 8
+...snip...
+47 == 2971215073
+48 == 4807526976
+49 == 7778742049
+50 == 12586269025
+</programlisting>
+ </example>
+
+ <para>To kick this off from Java we only insert a single Fibonacci
+ object, with a sequence field of 50. A recursive rule is then used
+ to insert the other 49 Fibonacci objects. This example doesn't use
+ <code>PropertyChangeSupport</code>. It uses the MVEL dialect, which
+ means we can use the <kw>modify</kw> keyword, which allows a block
+ setter action which also notifies the engine of changes.</para>
+
+ <example>
+ <title>Fibonacci Example Execution</title>
+
+ <programlisting>ksession.insert( new Fibonacci( 50 ) );
+ksession.fireAllRules();</programlisting>
+ </example>
+
+ <para>The rule Recurse is very simple. It matches each asserted
+ <code>Fibonacci</code> object with a value of -1, creating and
+ asserting a new <code>Fibonacci</code> object with a sequence of
+ one less than the currently matched object. Each time a Fibonacci
+ object is added while the one with a sequence field equal to 1
+ does not exist, the rule re-matches and fires again. The
+ <kw>not</kw> conditional element is used to stop the rule's matching
+ once we have all 50 Fibonacci objects in memory. The rule also has a
+ salience value, because we need to have all 50 Fibonacci objects
+ asserted before we execute the Bootstrap rule.</para>
+
+ <example>
+ <title>Fibonacci Example : Rule "Recurse"</title>
+
+ <programlisting>rule Recurse
+ salience 10
+ when
+ f : Fibonacci ( value == -1 )
+ not ( Fibonacci ( sequence == 1 ) )
+ then
+ insert( new Fibonacci( f.sequence - 1 ) );
+ System.out.println( "recurse for " + f.sequence );
+end</programlisting>
+ </example>
+
+ <para>The Audit view shows the original assertion of the
+ <code>Fibonacci</code> object with a sequence field of 50, done from
+ Java code. From there on, the Audit view shows the continual
+ recursion of the rule, where each asserted <code>Fibonacci</code>
+ object causes the Recurse rule to become activate and fire again.</para>
+
+ <figure>
+ <title>Fibonacci Example "Recurse" Audit View 1</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/FibonacciExample/fibonacci1.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>When a <code>Fibonacci</code> object with a sequence field of 2 is
+ asserted the "Bootstrap" rule is matched and activated along with the
+ "Recurse" rule. Note the multi-restriction on field
+ <code>sequence</code>, testing for equality with 1 or 2.</para>
+
+ <example>
+ <title>Fibonacci Example : Rule "Bootstrap"</title>
+
+ <programlisting>rule Bootstrap
+ when
+ f : Fibonacci( sequence == 1 || == 2, value == -1 ) // multi-restriction
+ then
+ modify ( f ){ value = 1 };
+ System.out.println( f.sequence + " == " + f.value );
+end</programlisting>
+ </example>
+
+ <para>At this point the Agenda looks as shown below. However,
+ the Bootstrap rule does not fire because the Recurse rule has a higher
+ salience.</para>
+
+ <figure>
+ <title>Fibonacci Example "Recurse" Agenda View 1</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/Chapter-Examples/FibonacciExample/fibonacci_agenda1.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>When a <code>Fibonacci</code> object with a sequence of 1 is
+ asserted the Bootstrap rule is matched again, causing two activations
+ for this rule. Note that the "Recurse" rule does not match and activate
+ because the <kw>not</kw> conditional element stops the rule's matching
+ as soon as a <code>Fibonacci</code> object with a sequence of 1
+ exists.</para>
+
+ <figure>
+ <title>Fibonacci Example "Recurse" Agenda View 2</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/Chapter-Examples/FibonacciExample/fibonacci_agenda2.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Once we have two <code>Fibonacci</code> objects with values
+ not equal to -1 the "calculate" rule is able to match. It was
+ the "Bootstrap" rule that set the objects with sequence 1 and 2 to
+ values of 1. At this point we have 50 Fibonacci objects in the Working
+ Memory. Now we need to select a suitable triple to calculate each
+ of their values in turn. Using three Fibonacci patterns in a rule without
+ field constraints to confine the possible cross products would result
+ in 50x49x48 possible combinations, leading to about 125,000 possible rule
+ firings, most of them incorrect. The "Calculate" rule uses field
+ constraints to correctly constraint the thee Fibonacci patterns in the
+ correct order; this
+ technique is called <emphasis>cross product matching</emphasis>. The
+ first pattern finds any Fibonacci with a value != -1 and binds both
+ the pattern and the field. The second Fibonacci does this, too, but
+ it adds an additional field constraint to ensure that its sequence is
+ greater by one than the Fibonacci bound to <code>f1</code>. When this
+ rule fires for the first time, we know that only sequences 1 and 2
+ have values of 1, and the two constraints ensure that <code>f1</code>
+ references sequence 1 and <code>f2</code> references sequence 2. The
+ final pattern finds the Fibonacci with a value equal to -1 and with a
+ sequence one greater than <code>f2</code>. At this point, we have
+ three <code>Fibonacci</code> objects correctly selected from the
+ available cross products, and we can calculate the value for the
+ third <code>Fibonacci</code> object that's bound to <code>f3</code>.</para>
+
+ <example>
+ <title>Fibonacci Example : Rule "Calculate"</title>
+
+ <programlisting>rule Calculate
+ when
+ // Bind f1 and s1
+ f1 : Fibonacci( s1 : sequence, value != -1 )
+ // Bind f2 and v2; refer to bound variable s1
+ f2 : Fibonacci( sequence == (s1 + 1), v2 : value != -1 )
+ // Bind f3 and s3; alternative reference of f2.sequence
+ f3 : Fibonacci( s3 : sequence == (f2.sequence + 1 ), value == -1 )
+ then
+ // Note the various referencing rechniques.
+ modify ( f3 ) { value = f1.value + v2 };
+ System.out.println( s3 + " == " + f3.value );
+end
+</programlisting>
+ </example>
+
+ <para>The <kw>modify</kw> statement updated the value of the
+ <code>Fibonacci</code> object bound to <code>f3</code>. This means
+ we now have another new Fibonacci object with a value not equal to -1,
+ which allows the "Calculate" rule to rematch and calculate the next
+ Fibonacci number. The Audit view below shows how the firing of the
+ last "Bootstrap" modifies the <code>Fibonacci</code> object,
+ enabling the "Calculate" rule to match, which then modifies
+ another Fibonacci object allowing the "Calculate" rule to match again.
+ This continues till the value is set for all <code>Fibonacci</code>
+ objects.</para>
+
+ <figure>
+ <title>Fibonacci Example "Bootstrap" Audit View 1</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/Chapter-Examples/FibonacciExample/fibonacci4.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-PricingExample.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-PricingExample.xml 2009-04-25 17:35:09 UTC (rev 26259)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-PricingExample.xml 2009-04-25 21:15:40 UTC (rev 26260)
@@ -1,96 +1,150 @@
-<?xml version="1.0" encoding="UTF-8"?>
- <section version="5.0" xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xmlns:svg="http://www.w3.org/2000/svg"
- xmlns:m="http://www.w3.org/1998/Math/MathML"
- xmlns:html="http://www.w3.org/1999/xhtml"
- xmlns:db="http://docbook.org/ns/docbook" xml:base="../../">
-
- <title>Pricing Rule Decision Table Example</title>
-
- <para>The Pricing Rule decision table demonstrates the use of a decision table in a spreadsheet (XLS format) in calculating the retail cost of an insurance policy. The purpose of the set of rules provided is to calculate a base price, and an additional discount for a car driver applying for a specific policy. The drivers age, history and the policy type all contribute to what the basic premium is, and an additional chunk of rules deals with refining this with a subtractive percentage discount.</para>
-
- <programlisting><emphasis role="bold">Name:</emphasis> Example Policy Pricing
-<emphasis role="bold">Main class:</emphasis> org.drools.examples.PricingRuleDTExample
-<emphasis role="bold">Type:</emphasis> java application
-<emphasis role="bold">Rules file:</emphasis> ExamplePolicyPricing.xls
-<emphasis role="bold">Objective:</emphasis> demonstrate spreadsheet based decision tables. </programlisting>
-
- <section>
- <title>Executing the example</title>
-
- <para>Open the PricingRuleDTExample.java and execute it as a Java application. It should produce the following console output:</para>
-
- <programlisting>Cheapest possible
-BASE PRICE IS: 120
-DISCOUNT IS: 20 </programlisting>
-
- <para>The code to the execute the example is very similar to the other examples. The rules are loaded, the facts inserted and a stateless session is used. What is different is how the rules are added:</para>
-
- <programlisting>DecisionTableConfiguration dtableconfiguration = KnowledgeBuilderFactory.newDecisionTableConfiguration();
+<?xml version="1.0" encoding="UTF-8"?>
+ <section version="5.0" xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns:m="http://www.w3.org/1998/Math/MathML"
+ xmlns:html="http://www.w3.org/1999/xhtml"
+ xmlns:db="http://docbook.org/ns/docbook" xml:base="../../">
+
+ <title>Pricing Rule Decision Table Example</title>
+
+ <para>The Pricing Rule decision table demonstrates the use of a
+ decision table in a spreadsheet, in Excel's XLS format, in calculating
+ the retail cost of an insurance policy. The purpose of the provide set
+ of rules is to calculate a base price and a discount for a
+ car driver applying for a specific policy. The driver's age, history and
+ the policy type all contribute to what the basic premium is, and an
+ additional chunk of rules deals with refining this with a discount
+ percentage.</para>
+
+ <programlisting><emphasis role="bold">Name:</emphasis> Example Policy Pricing
+<emphasis role="bold">Main class:</emphasis> org.drools.examples.PricingRuleDTExample
+<emphasis role="bold">Type:</emphasis> Java application
+<emphasis role="bold">Rules file:</emphasis> ExamplePolicyPricing.xls
+<emphasis role="bold">Objective:</emphasis> demonstrate spreadsheet-based decision tables.</programlisting>
+
+ <section>
+ <title>Executing the example</title>
+
+ <para>Open the file <filename>PricingRuleDTExample.java</filename> and
+ execute it as a Java application. It should produce the following
+ output in the Console window:</para>
+
+ <programlisting>Cheapest possible
+BASE PRICE IS: 120
+DISCOUNT IS: 20 </programlisting>
+
+ <para>The code to execute the example follows the usual pattern.
+ The rules are loaded, the facts inserted and a Stateless Session is
+ created. What is different is how the rules are added.</para>
+
+ <programlisting>DecisionTableConfiguration dtableconfiguration =
+ KnowledgeBuilderFactory.newDecisionTableConfiguration();
dtableconfiguration.setInputType( DecisionTableInputType.XLS );
KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
- kbuilder.add( ResourceFactory.newClassPathResource( "ExamplePolicyPricing.xls", getClass() ),
- ResourceType.DTABLE,
- dtableconfiguration );
-</programlisting>
-
- <para>Note the use of the DecisionTableConfiguration class. It is what takes the DecisionTableInputType.XLS as input type. If you use the BRMS, all this is of course taken care of for you.</para>
-
- <para>There are 2 facts used in this example, Driver, and Policy. Both are used with their default values. The Driver is 30 years old, has had no prior claims and currently has a risk profile of LOW. The Policy being applied for is COMPREHENSIVE, and the policy has not yet been approved.</para>
- </section>
-
- <section>
- <title>The decision table</title>
-
- <para>In this decision table, each row is a rule, and each column is a condition or an action.</para>
-
- <figure>
- <title>Decision table configuration</title>
-
- <mediaobject>
- <imageobject>
- <imagedata width="100%"
- fileref="images/Chapter-Examples/PricingExample/DT_Config.png" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Referring to the above, we have the RuleSet declaration, which provides the package name. There are also other optional items you can have here, such as Variables for global variables, and Imports for importing classes. In this case, the namespace of the rules is the same as the fact classes we are using, so we can omit it.</para>
-
- <para>Moving further down, we can see the RuleTable declaration. The name after this (Pricing bracket) is used as the prefix for all the generated rules. Below that, we have CONDITION or ACTION - this indicates the purpose of the column (ie does it form part of the condition, or an action of a rule that will be generated).</para>
-
- <para>You can see there is a Driver which is spanned across 3 cells, this means the template expressions below it apply to that fact. So we look at the drivers age range (which uses $1 and $2 with comma separated values), locationRiskProfile, and priorClaims in the respective columns. In the action columns, we are setting the policy base price, and then logging a message.</para>
-
- <figure>
- <title>Base price calculation</title>
-
- <mediaobject>
- <imageobject>
- <imagedata width="100%"
- fileref="images/Chapter-Examples/PricingExample/DT_Table1.png" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Referring to the above, we can see there are broad category brackets (indicated by the comment in the left most column). As we know the details of our driver and their policy, we can tell (with a bit of thought) that they should match row number 18, as they have no prior accidents, and are 30 years old. This gives us a base price of 120.</para>
-
- <figure>
- <title>Discount calculation</title>
-
- <mediaobject>
- <imageobject>
- <imagedata width="100%"
- fileref="images/Chapter-Examples/PricingExample/DT_Table2.png" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Referring to the above, we are seeing if there is any discount we can give our driver. Based on the Age bracket, number of priot claims, and the policy type, a discount is provided. In our case, the drive is 3, with no priors, and they are applying for COMPREHENSIVE, this means we can give a discount of 20%. Note that this is actually a separate table, but in the same worksheet. This different templates apply.</para>
-
- <para>It is important to note that decision tables generate rules, this means they aren't simply top down logic, but more a means to capture data that generate rules (this is a subtle difference that confuses some people). The evaluation of the rules is not "top down" necessarily, all the normal indexing and mechanics of the rule engine still apply.</para>
- </section>
- </section>
+ Resource xlsRes = ResourceFactory.newClassPathResource( "ExamplePolicyPricing.xls",
+ getClass() );
+ kbuilder.add( xlsRes,
+ ResourceType.DTABLE,
+ dtableconfiguration );
+</programlisting>
+
+ <para>Note the use of the <code>DecisionTableConfiguration</code> object.
+ Its input type is set to <code>DecisionTableInputType.XLS</code>.
+ If you use the BRMS, all this is of course taken care of for you.</para>
+
+ <para>There are two fact types used in this example, <code>Driver</code>
+ and <code>Policy</code>. Both are used with their default values. The
+ <code>Driver</code> is 30 years old, has had no prior claims and
+ currently has a risk profile of <code>LOW</code>. The <code>Policy</code>
+ being applied for is <code>COMPREHENSIVE</code>, and it has not yet been
+ approved.</para>
+ </section>
+
+ <section>
+ <title>The decision table</title>
+
+ <para>In this decision table, each row is a rule, and each column is
+ a condition or an action.</para>
+
+ <figure>
+ <title>Decision table configuration</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/PricingExample/DT_Config.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Referring to the spreadsheet show above, we have the
+ <code>RuleSet</code> declaration, which provides the package name.
+ There are also other optional items you can have here, such as
+ <code>Variables</code> for global variables, and <code>Imports</code>
+ for importing classes. In this case, the namespace of the rules is
+ the same as the fact classes we are using, so we can omit it.</para>
+
+ <para>Moving further down, we can see the <code>RuleTable</code>
+ declaration. The name after this (Pricing bracket) is used as the
+ prefix for all the generated rules. Below that, we have
+ "CONDITION or ACTION", indicating the purpose of the column, i.e.,
+ whether it forms part of the condition or the consequence of the rule
+ that will be generated.</para>
+
+ <para>You can see that there is a driver, his data spanned across three
+ cells, which means that the template expressions below it apply to that
+ fact. We observe the driver's age range (which uses <code>$1</code> and
+ <code>$2</code> with comma-separated values),
+ <code>locationRiskProfile</code>, and <code>priorClaims</code> in the
+ respective columns. In the action columns, we are set the policy
+ base price and log a message.</para>
+
+ <figure>
+ <title>Base price calculation</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/PricingExample/DT_Table1.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>In the preceding spreadsheet section, there are broad category
+ brackets, indicated by the comment in the leftmost column. As we know
+ the details of our drivers and their policies, we can tell (with a bit
+ of thought) that they should match row number 18, as they have no
+ prior accidents, and are 30 years old. This gives us a base price
+ of 120.</para>
+
+ <figure>
+ <title>Discount calculation</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/PricingExample/DT_Table2.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The above section contains the conditions for the discount we
+ might grant our driver. The discount results from the <code>Age</code>
+ bracket, the number of prior claims, and the policy type. In our case,
+ the driver is 30, with no prior claims, and is applying for a
+ <code>COMPREHENSIVE</code> policy, which means we can give a discount
+ of 20%. Note that this is actually a separate table, but in the same
+ worksheet, so that different templates apply.</para>
+
+ <para>It is important to note that decision tables generate rules.
+ This means they aren't simply top-down logic, but more a means to
+ capture data resulting in rules. This is a subtle difference that
+ confuses some people. The evaluation of the rules is not necessarily
+ in the given order, since all the normal mechanics of the rule engine
+ still apply.</para>
+ </section>
+ </section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-StateExample.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-StateExample.xml 2009-04-25 17:35:09 UTC (rev 26259)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-StateExample.xml 2009-04-25 21:15:40 UTC (rev 26260)
@@ -1,58 +1,71 @@
<?xml version="1.0" encoding="UTF-8"?>
- <section version="5.0" xmlns="http://docbook.org/ns/docbook"
+ <section version="5.0" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook" xml:base="../../">
- <title>State Example</title>
+ <title>State Example</title>
- <para>This example is actually implemented in three different versions to demonstrate different ways of implementing the same basic behavior: rules forward chaining, i.e., the ability the engine has to evaluate, activate and fire rules in sequence, based on changes on the facts in the working memory.</para>
-
- <section>
- <title>Understanding the State Example</title>
+ <para>This example is implemented in three different versions to
+ demonstrate different ways of implementing the same basic behavior:
+ forward chaining, i.e., the ability the engine has to evaluate,
+ activate and fire rules in sequence, based on changes on the facts
+ in the Working Memory.</para>
+
+ <section>
+ <title>Understanding the State Example</title>
- <screen><emphasis role="bold">Name:</emphasis> State Example
+ <screen><emphasis role="bold">Name:</emphasis> State Example
<emphasis role="bold">Main class:</emphasis> org.drools.examples.StateExampleUsingSalience
-<emphasis role="bold">Type:</emphasis> java application
+<emphasis role="bold">Type:</emphasis> Java application
<emphasis role="bold">Rules file:</emphasis> StateExampleUsingSalience.drl
-<emphasis role="bold">Objective:</emphasis> Demonstrates basic rule use and Conflict Resolution for rule firing priority.</screen>
+<emphasis role="bold">Objective:</emphasis> Demonstrates basic rule use
+ and Conflict Resolution for rule firing priority.</screen>
- <para>Each State class has fields for its name and its current state (see org.drools.examples.State class). The two possible states for each objects are:</para>
+ <para>Each <code>State</code> class has fields for its name and its
+ current state (see the class <code>org.drools.examples.State</code>).
+ The two possible states for each objects are:</para>
- <itemizedlist>
- <listitem>
- <para>NOTRUN</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para><code>NOTRUN</code></para>
+ </listitem>
- <listitem>
- <para>FINISHED</para>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para><code>FINISHED</code></para>
+ </listitem>
+ </itemizedlist>
- <example>
- <title>State Class</title>
+ <example>
+ <title>State Class</title>
- <programlisting>public class State {
- public static final int NOTRUN = 0;
- public static final int FINISHED = 1;
+ <programlisting>public class State {
+ public static final int NOTRUN = 0;
+ public static final int FINISHED = 1;
- private final PropertyChangeSupport changes = new PropertyChangeSupport( this );
+ private final PropertyChangeSupport changes =
+ new PropertyChangeSupport( this );
- private String name;
- private int state;
+ private String name;
+ private int state;
... setters and getters go here...
}</programlisting>
- </example>
+ </example>
- <para>Ignore the PropertyChangeSupport for now, that will be explained later. In the example we create four State objects with names: A, B, C and D. Initially all are set to state NOTRUN, which is default for the used constructor. Each instance is asserted in turn into the session and then fireAllRules() is called.</para>
+ <para>Ignoring the <code>PropertyChangeSupport</code>, which will
+ be explained later, we see the creation of four <code>State</code>
+ objects named A, B, C and D. Initially their states are set to
+ <code>NOTRUN</code>, which is default for the used constructor.
+ Each instance is asserted in turn into the Session and then
+ <code>fireAllRules()</code> is called.</para>
- <example>
- <title>Salience State Example Execution</title>
+ <example>
+ <title>Salience State: Execution</title>
- <programlisting>State a = new State( "A" );
+ <programlisting>State a = new State( "A" );
State b = new State( "B" );
State c = new State( "C" );
final State d = new State( "D" );
@@ -61,90 +74,105 @@
// PropertyChangeListeners so you don't have to call update().
boolean dynamic = true;
-session.insert( a,
- dynamic );
-session.insert( b,
- dynamic );
-session.insert( c,
- dynamic );
-session.insert( d,
- dynamic );
+session.insert( a, dynamic );
+session.insert( b, dynamic );
+session.insert( c, dynamic );
+session.insert( d, dynamic );
session.fireAllRules();
session.dispose(); // Stateful rule session must always be disposed when finished</programlisting>
- </example>
+ </example>
- <para>To execute the application:</para>
+ <para>To execute the application:</para>
- <orderedlist>
- <listitem>
- <para>Open the class org.drools.examples.StateExampleUsingSalience in your Eclipse IDE</para>
- </listitem>
+ <orderedlist>
+ <listitem>
+ <para>Open the class <code>org.drools.examples.StateExampleUsingSalience</code> in your Eclipse IDE.</para>
+ </listitem>
- <listitem>
- <para>Right-click the class an select "Run as..." -> "Java application"</para>
- </listitem>
- </orderedlist>
+ <listitem>
+ <para>Right-click the class and select "Run as..." and then
+ "Java application"</para>
+ </listitem>
+ </orderedlist>
- <para>And you will see the following output in the Eclipse console output:</para>
+ <para>You will see the following output in the Eclipse console
+ window:</para>
- <example>
- <title>Salience State Example Console Output</title>
+ <example>
+ <title>Salience State: Console Output</title>
- <programlisting>A finished
+ <programlisting>A finished
B finished
C finished
D finished
</programlisting>
- </example>
+ </example>
- <para>There are four rules in total, first a Bootstrap rule fires setting A to state FINISHED which then causes B to change to state FINISHED. C and D are both dependent on B - causing a conflict which is resolved by setting salience values. First lets look at how this was executed</para>
+ <para>There are four rules in total. First, the <code>Bootstrap</code>
+ rule fires, setting A to state <code>FINISHED</code>, which then
+ causes B to change its state to <code>FINISHED</code>. C and D are
+ both dependent on B, causing a conflict which is resolved by the
+ salience values. Let's look at the way this was executed.</para>
- <para>The best way to understand what is happening is to use the "Audit Log" feature to graphically see the results of each operation. The Audit log was generated when the example was previously run. To view the Audit log in Eclipse:</para>
+ <para>The best way to understand what is happening is to use the
+ Audit Logging feature to graphically see the results of each
+ operation. To view the Audit log generated by a run of this
+ example:</para>
- <orderedlist>
- <listitem>
- <para>If the "Audit View" is not visible, click on: "Window"->"Show View"->"Other..."->"Drools"->"Audit View"</para>
- </listitem>
+ <orderedlist>
+ <listitem>
+ <para>If the Audit View is not visible, click on "Window" and
+ then select "Show View", then "Other..." and "Drools" and
+ finally "Audit View".</para>
+ </listitem>
- <listitem>
- <para>In the "Audit View" click in the "Open Log" button and select the file "<drools-examples-drl-dir>/log/state.log"</para>
- </listitem>
- </orderedlist>
+ <listitem>
+ <para>In the "Audit View" click the "Open Log" button and select
+ the file "<drools-examples-drl-dir>/log/state.log".</para>
+ </listitem>
+ </orderedlist>
- <para>After that, the "Audit view" will look like the following screenshot.</para>
+ <para>After that, the "Audit view" will look like the following
+ screenshot:</para>
- <figure>
- <title>Salience State Example Audit View</title>
+ <figure>
+ <title>Salience State Example Audit View</title>
- <mediaobject>
- <imageobject>
- <imagedata width="100%"
- fileref="images/Chapter-Examples/StateExample/state_example_audit1.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/StateExample/state_example_audit1.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>Reading the log in the "Audit View", top to down, we see every action and the corresponding changes in the working memory. This way we see that the assertion of the State "A" object with the "NOTRUN" state activates the "Bootstrap" rule, while the assertions of the other state objects have no immediate effect.</para>
+ <para>Reading the log in the "Audit View", top to bottom, we see every
+ action and the corresponding changes in the Working Memory. This way
+ we observe that the assertion of the State object A in the state
+ <code>NOTRUN</code> activates the <code>Bootstrap</code> rule, while
+ the assertions of the other <code>State</code> objects have no
+ immediate effect.</para>
- <example>
- <title>Salience State Example: Rule "Bootstrap"</title>
+ <example>
+ <title>Salience State: Rule "Bootstrap"</title>
- <programlisting>rule Bootstrap
+ <programlisting>rule Bootstrap
when
a : State(name == "A", state == State.NOTRUN )
then
System.out.println(a.getName() + " finished" );
a.setState( State.FINISHED );
end</programlisting>
- </example>
+ </example>
- <para>The execution of "Bootstrap" rule changes the state of "A" to "FINISHED", that in turn activates the "A to B" rule.</para>
+ <para>The execution of rule Bootstrap changes the state of A to
+ <code>FINISHED</code>, which, in turn, activates rule "A to B".</para>
- <example>
- <title>Salience State Example: Rule "A to B"</title>
+ <example>
+ <title>Salience State: Rule "A to B"</title>
- <programlisting>rule "A to B"
+ <programlisting>rule "A to B"
when
State(name == "A", state == State.FINISHED )
b : State(name == "B", state == State.NOTRUN )
@@ -153,24 +181,38 @@
b.setState( State.FINISHED );
end
</programlisting>
- </example>
+ </example>
- <para>The execution of "A to B" rule changes the state of "B" to "FINISHED", which activates both rules "B to C" and "B to D", placing both Activations onto the Agenda. In this moment the two rules may fire and are said to be in conflict. The conflict resolution strategy allows the engine's Agenda to decide which rule to fire. As the "B to C" rule has a <emphasis role="bold">higher salience value</emphasis> (10 versus the default salience value of 0), it fires first, modifying the "C" object to state "FINISHED". The Audit view above shows the modification of the State object in the rule "A to B" which results in two highlighted activations being in conflict. The Agenda view can also be used to investigate the state of the Agenda, debug points can be placed in the rules themselves and the Agenda view opened; the screen shot below shows the break point in the rule "A to B" and the state of the Agenda with the two conflicting rules.</para>
+ <para>The execution of rule "A to B" changes the state of B to
+ <code>FINISHED</code>, which activates both, rules "B to C" and
+ "B to D", placing their Activations onto the Agenda. From this moment
+ on, both rules may fire and, therefore, they are said to be
+ "in conflict". The conflict resolution strategy allows the engine's
+ Agenda to decide which rule to fire. As rule "B to C" has the
+ <emphasis role="bold">higher salience value</emphasis> (10 versus
+ the default salience value of 0), it fires first, modifying object C
+ to state <code>FINISHED</code>. The Audit view shown above reflects
+ the modification of the <code>State</code> object in the rule "A to B",
+ which results in two activations being in conflict. The Agenda view
+ can also be used to investigate the state of the Agenda, with debug
+ points being placed in the rules themselves and the Agenda view opened.
+ The screen shot below shows the breakpoint in the rule "A to B" and
+ the state of the Agenda with the two conflicting rules.</para>
- <figure>
- <title>State Example Agenda View</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/Chapter-Examples/StateExample/state_example_agenda1.png" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <example>
- <title>Salience State Example: Rule "B to C"</title>
-
- <programlisting>rule "B to C"
+ <figure>
+ <title>State Example Agenda View</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/Chapter-Examples/StateExample/state_example_agenda1.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <example>
+ <title>Salience State: Rule "B to C"</title>
+
+ <programlisting>rule "B to C"
salience 10
when
State(name == "B", state == State.FINISHED )
@@ -180,14 +222,15 @@
c.setState( State.FINISHED );
end
</programlisting>
- </example>
+ </example>
- <para>The "B to D" rule fires last, modifying the "D" object to state "FINISHED".</para>
-
- <example>
- <title>Salience State Example: Rule "B to D"</title>
-
- <programlisting>rule "B to D"
+ <para>Rule "B to D" fires last, modifying object D to state
+ <code>FINISHED</code>.</para>
+
+ <example>
+ <title>Salience State: Rule "B to D"</title>
+
+ <programlisting>rule "B to D"
when
State(name == "B", state == State.FINISHED )
d : State(name == "D", state == State.NOTRUN )
@@ -195,46 +238,79 @@
System.out.println(d.getName() + " finished" );
d.setState( State.FINISHED );
end</programlisting>
- </example>
-
- <para>There are no more rules to execute and so the engine stops.</para>
-
- <para>Another notable concept in this example is the use of <emphasis role="bold">dynamic facts</emphasis>, which is the PropertyChangeListener part. As mentioned previously in the documentation, in order for the engine to see and react to fact's properties change, the application must tell the engine that changes occurred. This can be done explicitly in the rules, by calling the <emphasis role="bold">update()</emphasis> memory action, or implicitly by letting the engine know that the facts implement PropertyChangeSupport as defined by the <emphasis>Javabeans specification</emphasis>. This example demonstrates how to use PropertyChangeSupport to avoid the need for explicit update() calls in the rules. To make use of this feature, make sure your facts implement the PropertyChangeSupport as the org.drools.example.State class does and use the following code to insert the facts into the working memory:</para>
-
- <example>
- <title>Inserting a Dynamic Fact</title>
-
- <programlisting>// By setting dynamic to TRUE, Drools will use JavaBean
+ </example>
+
+ <para>There are no more rules to execute and so the engine stops.</para>
+
+ <para>Another notable concept in this example is the use of
+ <emphasis>dynamic facts</emphasis>, based on
+ <code>PropertyChangeListener</code> objects. As described in the
+ documentation, in order for the engine to see and react to changes of
+ fact properties, the application must tell the engine that changes
+ occurred. This can be done explicitly in the rules by using the
+ <kw>update</kw> statement, or implicitly by letting the engine know
+ that the facts implement <code>PropertyChangeSupport</code> as defined
+ by the <emphasis>JavaBeans specification</emphasis>. This example
+ demonstrates how to use <code>PropertyChangeSupport</code> to avoid
+ the need for explicit <kw>update</kw> statements in the rules. To
+ make use of this feature, ensure that your facts implement
+ <code>PropertyChangeSupport</code>, the same way the class
+ <code>org.drools.example.State</code> does, and use the following
+ code to insert the facts into the Working Memory:</para>
+
+ <example>
+ <title>Inserting a Dynamic Fact</title>
+
+ <programlisting>// By setting dynamic to TRUE, Drools will use JavaBean
// PropertyChangeListeners so you don't have to call update().
final boolean dynamic = true;
-session.insert( fact,
- dynamic );
+session.insert( fact, dynamic );
</programlisting>
- </example>
-
- <para>When using PropertyChangeListeners each setter must implement a little extra code to do the notification, here is the state setter for thte org.drools.examples.State class:</para>
-
- <example>
- <title>Setter Example with PropertyChangeSupport</title>
-
- <programlisting>public void setState(final int newState) {
+ </example>
+
+ <para>When using <code>PropertyChangeListener</code> objects, each
+ setter must implement a little extra code for the notification. Here
+ is the setter for <code>state</code> in the class
+ <code>org.drools.examples</code>:</para>:
+
+ <example>
+ <title>Setter Example with PropertyChangeSupport</title>
+
+ <programlisting>public void setState(final int newState) {
int oldState = this.state;
this.state = newState;
this.changes.firePropertyChange( "state",
oldState,
newState );
}</programlisting>
- </example>
+ </example>
- <para>There are two other State examples: StateExampleUsingAgendGroup and StateExampleWithDynamicRules. Both execute from A to B to C to D, as just shown, the StateExampleUsingAgendGroup uses agenda-groups to control the rule conflict and which one fires first and StateExampleWithDynamicRules shows how an additional rule can be added to an already running WorkingMemory with all the existing data applying to it at runtime.</para>
-
- <para>Agenda groups are a way to partition the agenda into groups and controlling which groups can execute. All rules by default are in the "MAIN" agenda group, by simply using the "agenda-group" attribute you specify a different agenda group for the rule. A working memory initially only has focus on the "MAIN" agenda group, only when other groups are given the focus can their rules fire; this can be achieved by either using the method setFocus() or the rule attribute "auto-focus". "auto-focus" means that the rule automatically sets the focus to it's agenda group when the rule is matched and activated. It is this "auto-focus" that enables "B to C" to fire before "B to D".</para>
-
- <example>
- <title>Agenda Group State Example: Rule "B to C"</title>
-
- <programlisting>rule "B to C"
+ <para>There are two other classes in this example:
+ <code>StateExampleUsingAgendGroup</code> and
+ <code>StateExampleWithDynamicRules</code>. Both execute from A to B
+ to C to D, as just shown. The <code>StateExampleUsingAgendGroup</code>
+ uses agenda-groups to control the rule conflict and which one fires
+ first. <code>StateExampleWithDynamicRules</code> shows how an
+ additional rule can be added to an already running Working Memory
+ with all the existing data applying to it at runtime.</para>
+
+ <para>Agenda groups are a way to partition the Agenda into groups
+ and to control which groups can execute. By default, all rules are
+ in the agenda group "MAIN". The "agenda-group" attribute lets
+ you specify a different agenda group for the rule. Initially,
+ a Working Memory has its focus on the Agenda group "MAIN". A group's
+ rules will only fire when the group receives the focus. This can be
+ achieved either ny using the method by <code>setFocus()</code> or the
+ rule attribute <kw>auto-focus</kw>. "auto-focus" means that the rule
+ automatically sets the focus to its agenda group when the rule is
+ matched and activated. It is this "auto-focus" that enables rule
+ "B to C" to fire before "B to D".</para>
+
+ <example>
+ <title>Agenda Group State Example: Rule "B to C"</title>
+
+ <programlisting>rule "B to C"
agenda-group "B to C"
auto-focus true
when
@@ -245,14 +321,16 @@
c.setState( State.FINISHED );
drools.setFocus( "B to D" );
end</programlisting>
- </example>
+ </example>
- <para>The rule "B to C" calls "drools.setFocus( "B to D" );" which gives the agenda group "B to D" focus allowing its active rules to fire; which allows the rule "B to D" to fire.</para>
+ <para>The rule "B to C" calls <code>drools.setFocus( "B to D" )</code>
+ which gives the agenda group "B to D" focus allowing its active rules
+ to fire, which allows the rule "B to D" to fire.</para>
- <example>
- <title>Agenda Group State Example: Rule "B to D"</title>
+ <example>
+ <title>Agenda Group State Example: Rule "B to D"</title>
- <programlisting>rule "B to D"
+ <programlisting>rule "B to D"
agenda-group "B to D"
when
State(name == "B", state == State.FINISHED )
@@ -261,14 +339,16 @@
System.out.println(d.getName() + " finished" );
d.setState( State.FINISHED );
end</programlisting>
- </example>
+ </example>
- <para>The example StateExampleWithDynamicRules adds another rule to the RuleBase after fireAllRules(), the rule it adds is just another State transition.</para>
+ <para>The example <code>StateExampleWithDynamicRules</code> adds
+ another rule to the Rule Base after <code>fireAllRules()</code>.
+ The added rule is just another state transition.</para>
- <example>
- <title>Dynamic State Example: Rule "D to E"</title>
+ <example>
+ <title>Dynamic State Example: Rule "D to E"</title>
- <programlisting>rule "D to E"
+ <programlisting>rule "D to E"
when
State(name == "D", state == State.FINISHED )
e : State(name == "E", state == State.NOTRUN )
@@ -276,21 +356,21 @@
System.out.println(e.getName() + " finished" );
e.setState( State.FINISHED );
end</programlisting>
- </example>
+ </example>
- <para>It gives the following expected output:</para>
+ <para>This produces the following expected output:</para>
- <example>
- <title>Dynamic Sate Example Output</title>
-
- <programlisting>A finished
+ <example>
+ <title>Dynamic Sate Example Output</title>
+
+ <programlisting>A finished
B finished
C finished
D finished
E finished
</programlisting>
- </example>
-
- </section>
-
- </section>
+ </example>
+
+ </section>
+
+ </section>
More information about the jboss-svn-commits
mailing list