[jboss-svn-commits] JBL Code SVN: r6155 - in labs/jbossrules/trunk/documentation/manual/en: . Chapter-Rule_Engine
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Mon Sep 11 15:59:11 EDT 2006
Author: sam.griffith at jboss.com
Date: 2006-09-11 15:59:08 -0400 (Mon, 11 Sep 2006)
New Revision: 6155
Modified:
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Leaps_Algorithm.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Rete_Algorithm.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Rules.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-What_is_a_Rule_Engine.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Why_use_a_Rule_Engine.xml
labs/jbossrules/trunk/documentation/manual/en/master.xml
Log:
Edited for grammar and puntuation. Clarified some of the texts. Put code samples into CDATA tags.
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Leaps_Algorithm.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Leaps_Algorithm.xml 2006-09-11 19:18:06 UTC (rev 6154)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Leaps_Algorithm.xml 2006-09-11 19:59:08 UTC (rev 6155)
@@ -2,7 +2,7 @@
<section>
<title>Leaps Algorithm</title>
- <para>Leaps algorithm for production systems uses a "lazy" approach to
+ <para>The Leaps algorithm for production systems uses a "lazy" approach to
condition evaluations. A modified version of this algorithm, implemented as part
of Drools v3, attempts to take the best features of both Leaps and Rete
approaches in processing facts in the working memory. Leaps is not being
@@ -13,62 +13,69 @@
the main stack according to the order facts were asserted in the working
memory (FIFO). It inspects facts one by one trying to find a match for each
relevant (based on type of the fact and data types required by CEs) rule by
- iterating over collections of facts that match datatype of each CE. As soon
- as such match is found system remembers iteration position to resume such
- iteration later and fires the rule consequence. After execution of
- consequence is completed, systems is trying to resume processing by
- inspecting a fact at the top of the main processing stack and either start
- processing from beginning or resumes the processing if it was stopped due to
- finding a match for a rule and consequence firing.</para>
+ iterating over collections of facts that match the datatype of each CE. As soon
+ as such match is found, the system remembers the current iteration position so
+ it can possibly resume iteration later and then fires the matching rules consequence.
+ After execution of consequence is completed, the system trys to resume processing by
+ inspecting a fact on the top of the main processing stack and either start
+ processing from beginning or resumes the processing that was suspended.</para>
<section>
- <title>Conflict resolution</title>
-
+ <title>Conflict Resolution</title>
+
+<!-- FIXME - This needs to be clarified. It is unclear at best as it stands now... -->
+
<para>Please note that Leaps allows for rule firing before ALL cross-fact
- matches were attempted as per RETE approach that explains reported
+ matches are attempted as per RETE approach, which explains the reported
significant performance gains for this algorithm. It's made possible by
- pushing conflict resolution upfront (sort order of facts on the stack and
- rules matching order), before matching begins while with RETE all matches
- should be attempted, activations sorted based on the conflict resolution
+ pushing conflict resolution upfront before matching begins (sort order
+ of facts on the stack and rules matching order), while with RETE all matches
+ should (must) be attempted, activations are sorted based on the conflict resolution
strategy and head element's consequence fired.</para>
<para>The current implementation allows for flexible conflict resolution
- strategy selection. Even that it's not exposed as a pluggable feature one
- can either use supplied conflict resolution strategies
- (org.drools.leaps.conflict) or develop new ones to modify default
- behavior. Up to date the general approach was to state conflict resolution
- stategy without specifying if order activation is based on fact or rules
- attributes. Current implementation allows for specifying separate ordering
- based on fact attribute and rule attribute conflict resolution strategy
- that makes it more apparent.</para>
+ strategy selection. Even though it's not exposed as a pluggable feature, you
+ can either use the supplied conflict resolution strategies
+ (org.drools.leaps.conflict) or develop new ones to customize the default
+ behavior. Update: The general approach for the conflict resolution stategy
+ does not specifying whether the order of activation was based on fact or
+ rule attributes. The current implementation does, however, allow for
+ specifying that the conflict resolution strategy be based on the fact and
+ rule attribute so it is more apparent.</para>
</section>
<section>
- <title>'not' and 'exists'</title>
+ <title>'Not' and 'Exists'</title>
- <para>The main deviation from the "classical" leaps in this implementation
- lays in the way it deals with "negative" and "exists" CE processing.
- "classical" approach makes use of "shadow" fact stack, full scan of
+ <para>The main deviation of the Drools 3 implmentation of Leaps from the
+ "classical" Leaps is in the way it deals with "negative" and "exists" CE processing.
+ The "classical" approach makes use of a "shadow" fact stack, a full scan of
relevant collections to determine presence of certain facts matching NOT
- or EXISTS conditions, and conversion of source rules to account for the
+ or EXISTS conditions and conversion of source rules to account for the
instances where retracted facts "release" rule activations that were
- previously blocked by it. Current implementation takes a different
- approach. Its functionality is similar to the way RETE negative node by
+ previously blocked by it. The current implementation takes a different
+ approach. Its functionality is similar to the way RETE negates nodes by
creating tuples with deferred activation in "lazy" manner.</para>
-
- <para>After finding match for all "positive" conditions, current
+<!-- FIXME - Last sentence of previous paragraph was confusing. Need to
+ verfiy I didn't change the meaning.
+ It was this:
+ Its functionality is similar to the way RETE negative node by
+ creating tuples with deferred activation in "lazy" manner.
+-->
+
+ <para>After finding matchs for all "positive" conditions, the current
implementation starts looking for facts that might satisfy "not" and
- "exists" conditions. As soon as such fact found the system stops looking
- for a given CE and stores found fact handle. When all "not" and "exists"
- CEs are checked the tuple is being evaluated if it eligible for activation
- - no matching "not" facts and all "exists" CEs have matching facts. Tuple
- is either activated or if it has blocking conditions ("not" facts or
- missing "exists") than it's being deferred for further inspection.</para>
+ "exists" conditions. As soon as such a fact is found the system stops looking
+ for a given CE and stores found fact handle. All the "not" and "exists"
+ CEs are checked, with the CE's tuple being evaluated to see if it is eligible
+ for activation - no matching "not" facts and all "exists" CEs have matching
+ facts. The tuple is either activated or if it has blocking conditions ("not" facts or
+ missing "exists"), then it's is deferred for further inspection.</para>
- <para>All fact assertions are being used to see if it can activate tuples
- with deferred activation from above. At the same time all fact that are
- being retracted inspected to see they remove blocking condition from the
- deferred tuples or deactivate activation triggered by matching given fact
- in "exists" condition.</para>
+ <para>All fact assertions are then checked again, to see if they can activate tuples
+ that were deferred from activation. At the same time, all facts that are
+ being retracted are inspected to see if they remove a blocking condition from the
+ deferred tuples or if they will deactivate an activation that was triggered by
+ matching a given fact in an "exists" condition.</para>
</section>
</section>
\ No newline at end of file
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Rete_Algorithm.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Rete_Algorithm.xml 2006-09-11 19:18:06 UTC (rev 6154)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Rete_Algorithm.xml 2006-09-11 19:59:08 UTC (rev 6155)
@@ -3,18 +3,18 @@
<title>Rete Algorithm</title>
<para>The RETE algorithm was invented by Dr. Charles Forgy and documented in
- his PHd thesis in 1978-79. A simplified version of the paper was published
+ his PhD thesis in 1978-79. A simplified version of the paper was published
in 1982 (<ulink
- url="http://citeseer.ist.psu.edu/context/505087/0">http://citeseer.ist.psu.edu/context/505087/0</ulink>).The
- word RETE is latin for "net" meaning network. RETE algorithm can be broken
+ url="http://citeseer.ist.psu.edu/context/505087/0">http://citeseer.ist.psu.edu/context/505087/0</ulink>).
+ The word RETE is latin for "net" meaning network. The RETE algorithm can be broken
into 2 parts: rule compilation and runtime execution.</para>
<para>The compilation algorithm describes how the Rules in the Production
Memory to generate an efficient descrimination network. In non-technical
terms, a descrimination network is used to filter data. The idea is to
- filter data as it propogates through the network. At the top, the nodes
- would have many matches. As we go down the network, there would be fewer
- matches. At the very bottom of the network are the terminal nodes. In Dr
+ filter data as it propogates through the network. At the top of the network
+ the nodes would have many matches and as we go down the network, there would be
+ fewer matches. At the very bottom of the network are the terminal nodes. In Dr.
Forgy's 1982 paper, he described 4 basic nodes: root, 1-input, 2-input and
terminal.</para>
@@ -42,11 +42,11 @@
create an ObjectTypeNode and have all 1-input and 2-input nodes descend from
it. This way, if an application asserts a new account, it won't propogate to
the nodes for the Order object. In Drools when an object is asserted it
- retrieves the List of valid ObjectTypesNodes via a lookup in a HashMap from
- the object's Class; if this list does'nt exist it scans all the ObjectTypde
- nodes finding valid matches which it caches in the List. This enables Drools
+ retrieves a list of valid ObjectTypesNodes via a lookup in a HashMap from
+ the object's Class; if this list doesn't exist it scans all the ObjectTypde
+ nodes finding valid matches which it caches in the list. This enables Drools
to match against any Class type that matches with an
- <literal>instanceof</literal> of check.</para>
+ <literal>instanceof</literal> check.</para>
<figure>
<title>ObjectTypeNodes</title>
@@ -96,21 +96,21 @@
checks.</para>
<para>There are two two-input nodes; JoinNode and NotNode - both are
- referred as BetaNodes. BetaNodes are use to compare 2 objects, and their
+ types of BetaNodes. BetaNodes are use to compare 2 objects, and their
fields, to each other. The objects may be the same or different types. By
convention we refer to the two inputs as left and right. The left input for
- a BetaNode is generally a list of objects, in Drools this is a Tuple. The
+ a BetaNode is generally a list of objects; in Drools this is a Tuple. The
right input is a single object. Two Nots can be used to implement 'exists'
checks. BetaNodes also have memory. The left input is called the Beta Memory
and remembers all incoming tuples. The right input is called the Alpha
Memory and remembers all incoming objects. Drools extends Rete by
- performaning indexing on the BetaNodes. For instance if we know that a
+ performaning indexing on the BetaNodes. For instance, if we know that a
BetaNode is peforming a check on a String field, as each object enters we
can do a hash lookup on that String value. This means when facts enter from
the opposite side, instead of iterating over all the facts to find valid
- joins we instead do a lookup returning potentially valid candidates. At any
- point a valid join is found the Tuple is joined with the Object, which is
- referred to as a partial match, and then propagated to the next node.</para>
+ joins, we do a lookup returning potentially valid candidates. At any
+ point a valid join is found the Tuple is joined with the Object; which is
+ referred to as a partial match; and then propagated to the next node.</para>
<figure>
<title>JoinNode</title>
@@ -141,24 +141,32 @@
don't have to be re-evaluated for every single instance. The following two
rules share the first same pattern, but not the last:</para>
- <programlisting>rule
+ <programlisting>
+ <![CDATA[
+ rule
when
Cheese( $chedddar : name == "cheddar" )
$person : Person( favouriteCheese == $cheddar )
then
System.out.println( $person.getName() + " likes cheddar" );
-end</programlisting>
+ end
+ ]]>
+ </programlisting>
- <programlisting>rule
+ <programlisting>
+ <![CDATA[
+ rule
when
Cheese( $chedddar : name == "cheddar" )
$person : Person( favouriteCheese != $cheddar )
then
System.out.println( $person.getName() + " does not like cheddar" );
-end</programlisting>
+ end
+ ]]>
+ </programlisting>
- <para>As you can see the compiled Rete network shows the alpha node is
- shared, but the beta nodes are not, each with their own TerminalNode. Had
+ <para>As you can see below, the compiled Rete network shows the alpha node is
+ shared, but the beta nodes are not. Each beta node has its own TerminalNode. Had
the second pattern been the same it would have also been shared.</para>
<figure>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Rules.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Rules.xml 2006-09-11 19:18:06 UTC (rev 6154)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Rules.xml 2006-09-11 19:59:08 UTC (rev 6155)
@@ -5,10 +5,13 @@
<section>
<title>Production Rules</title>
- <para>A <indexterm>
+ <para>A
+ <indexterm>
<primary>Production Rule</primary>
- </indexterm>Production Rule, or Rule, in Drools is a two part structure
- with a Left Hand Side (LHS) and a Right Hand Side (RHS) additionally a
+ </indexterm>
+ Production Rule (aka Rule) in Drools is a two part structure,
+ with a Left Hand Side (LHS) and a Right Hand Side (RHS) which are
+ alternately known as the "Head" and "Tail" respectively. Additionally a
Rule may have the following attributes:</para>
<itemizedlist>
@@ -37,23 +40,29 @@
</listitem>
</itemizedlist>
- <programlisting>rule “<name>”
- <attribute> <value>
- when
- <LHS>
- then
- <RHS>
-end
-</programlisting>
+ <programlisting>
+ <![CDATA[
+ rule "<name>" <attribute> <value>
+ when <LHS>
+ then <RHS>
+ end
+ ]]>
+ </programlisting>
- <para>The LHS of a Rule consists of <indexterm>
+ <para>The LHS of a Rule consists of
+ <indexterm>
<primary>Conditional Element</primary>
- </indexterm>Conditional Elements (CE) and Columns; to facilate the
- encoding of propositional and first order logic. The term <indexterm>
+ </indexterm>
+ Conditional Elements (CE) and Columns (aka - Patterns); to facilate the
+ encoding of propositional and first order logic. The term
+ <indexterm>
<primary>Column</primary>
- </indexterm>Column is used to indicate <indexterm>
+ </indexterm>
+ Column is used to indicate
+ <indexterm>
<primary>Field Constraint</primary>
- </indexterm>Field Constraints on a Fact.</para>
+ </indexterm>
+ Field Constraints on a Fact.</para>
<para>Drools currently supports the follows CEs:</para>
@@ -75,8 +84,8 @@
</listitem>
</itemizedlist>
- <para>'forall' and 'accumulate' will be added shortley. The following
- Field Constraints are allowed:</para>
+ <para>'forall' and 'accumulate' will be added shortley.
+ The following Field Constraints are allowed:</para>
<itemizedlist>
<listitem>
@@ -99,19 +108,24 @@
<para>The Language Guide chapter provides more indepth information for
each of these.</para>
- <para>As facts are asserted and modified in the Working Memory it matches
- the facts against the LHS conditions, when all the conditions are met and
- true the Rule plus those match facts are activated. When a Rule is
+ <para>As facts are asserted and modified in the Working Memory, the rules engine
+ matches the facts against the LHS conditions, when all the conditions of a rules
+ LHS are met and true that rule plus those match facts are activated. When a Rule is
activated it is placed onto the Agenda for potential execution, where the
- actions of RHS, called t he <indexterm>
+ actions of RHS, called the
+ <indexterm>
<primary>Consequence</primary>
- </indexterm>Consequence, are executed. The LHS and the RHS is analogous
- to:</para>
+ </indexterm>
+ Consequence, are executed. The LHS and the RHS is analogous to:</para>
+
+ <programlisting>
+ <![CDATA[
+ if (<LHS>) {
+ <RHS>
+ }
+ ]]>
+ </programlisting>
- <programlisting>if ( <LHS> ) {
- <RHS>
-}</programlisting>
-
<para>However 'if' is considered procedural in that it is one part of a
possible execution flow - if this.... else if.... else ..... Rules use
'when' to more semantically recognise that the rule will activate when,
@@ -121,10 +135,12 @@
<literal>package</literal> keyword; other Rule Engines may call this a
<indexterm>
<primary>Rule Set</primary>
- </indexterm>Rule Set. A Package declares imports, global variables,
- functions and rules.</para>
+ </indexterm>
+ Rule Set. A Package declares imports, global variables, functions and rules.</para>
- <programlisting>package com.sample
+ <programlisting>
+<![CDATA[
+package com.sample
import java.util.List
import com.sample.Cheese
@@ -141,33 +157,45 @@
then
exampleFunction( cheese );
cheeses.add( cheese );
-end</programlisting>
+end
+]]>
+ </programlisting>
<para>The following example shows a LHS with a single Column that has a
- single <indexterm>
- <primary>Literal Field Constraint</primary>
- </indexterm>Literal Field Constraint used with a Cheese Fact:</para>
+ single
+ <indexterm>
+ <primary>Literal Field Constraint</primary>
+ </indexterm>
+ Literal Field Constraint used with a Cheese Fact:</para>
- <programlisting>rule "Cheddar Cheese"
- when
- Cheese( type == "cheddar" )
- then
- System.out.println( "cheddar" );
-end</programlisting>
+ <programlisting>
+<![CDATA[
+rule "Cheddar Cheese"
+when
+ Cheese( type == "cheddar" )
+then
+ System.out.println( "cheddar" );
+end
+ ]]>
+ </programlisting>
<para>The example above is analogous to :</para>
- <programlisting>public void cheddarCheese(Cheese cheese) {
- if ( cheese.getType().equals("cheddar") {
- System.out.println( "cheddar" );
- }
-}</programlisting>
+ <programlisting>
+<![CDATA[
+public void cheddarCheese(Cheese cheese) {
+ if ( cheese.getType().equals("cheddar") {
+ System.out.println( "cheddar" );
+ }
+}
+]]>
+ </programlisting>
- <para>Rule are a complete de-coupling of data from the logic. Rules cannot
+ <para>Rules are a complete de-coupling of data from the logic. Rules cannot
be called directly as they are not methods or functions instead Rules fire
in response to changes in Working Memory's data. Rules are also fully
declarative in that they describe "what" not "how" like imperative
- languages such as java.</para>
+ languages such as Java.</para>
</section>
<section>
@@ -186,9 +214,9 @@
be a "closed statement". In programming terms this is an expression that
does not reference any variables:</para>
- <para>10 = = 2 * 5</para>
+ <para>10 == 2 * 5</para>
- <para>Expressions that evaluate against one or more variables, facts, are
+ <para>Expressions that evaluate against one or more variables, the facts, are
"open statements", in that we cannot determine whether the statement is
true until we have a variable instance to evaluate against:</para>
@@ -218,7 +246,7 @@
</mediaobject>
</figure>
- <para>So in java we can say that a simple proposition is of the form
+ <para>So in Java we can say that a simple proposition is of the form
'variable' 'operator' 'value' - where we often refer to 'value' as being a
literal value - a proposition can be thought as a field constraint.
Further to this propositions can be combined with conjuntive and
@@ -226,22 +254,34 @@
'&&' and '||'. The following shows two open propositional
statements connected together with a single disjunctive connective.</para>
- <programlisting>person.getEyeColor().equals("blue") || person.getEyeColor().equals("green") </programlisting>
+ <programlisting>
+ <![CDATA[
+ person.getEyeColor().equals("blue") || person.getEyeColor().equals("green")
+ ]]>
+ </programlisting>
<para>This can be expressed using a disjunctive Conditional Element
connective - which actually results in the generation of two rules, to
represent the two possible logic outcomes.</para>
- <programlisting>Person( eyeColour == "blue" ) || Person( eyeColor == "green" )</programlisting>
+ <programlisting>
+ <![CDATA[
+ Person( eyeColour == "blue" ) || Person( eyeColor == "green" )
+ ]]>
+ </programlisting>
<para>Disjunctive field constraints connectives could also be used -
although they are not currently supported in Drools 3.0 - and would not
result in multiple rule generation.</para>
- <programlisting>Person( eyeColour == "blue"||"green" )</programlisting>
+ <programlisting>
+ <![CDATA[
+ Person( eyeColour == "blue"||"green" )
+ ]]>
+ </programlisting>
- <para>However Propositional Logic is not Turing complete in that you are
- limited to the problems you can define because it cannot express criteria
+ <para>Propositional Logic is not Turing complete, limiting the problems
+ you can define, because it cannot express criteria
for the structure of data. First Order Logic (FOL), or Predicate Logic,
extends Propositional Logic with two new quantifier concepts to allow
expressions defining structure - specifically universal and existential
@@ -259,42 +299,56 @@
40" open proposition to check for the existence of a Module that is true
for the specified criteria.</para>
- <programlisting>public class Student {
+ <programlisting>
+ <![CDATA[
+ public class Student {
private String name;
private List modules;
...
-}</programlisting>
+ }
+ ]]>
+ </programlisting>
- <programlisting>public class Module {
+ <programlisting>
+ <![CDATA[
+ public class Module {
private String name;
private String studentName;
- private int score;</programlisting>
+ private int score;
+ ]]>
+ </programlisting>
<para>Java is Turing complete in that you can write code, among other
things, to iterate data structures to check for existence. The following
should return a List of students who have failed the semester.</para>
- <programlisting>List failedStudents = new ArrayList();
-
-for ( Iterator studentIter = students.iterator(); studentIter.hasNext() {
- Student student = ( Student ) studentIter.next();
- for ( Iterator it = student.getModules.iterator(); it.hasNext(); ) {
- Module module = ( Module ) it.next();
- if ( module.getScore() < 40 ) {
- failedStudents.add( student ) ;
- break;
+ <programlisting>
+ <![CDATA[
+ List failedStudents = new ArrayList();
+
+ for ( Iterator studentIter = students.iterator(); studentIter.hasNext() {
+ Student student = ( Student ) studentIter.next();
+ for ( Iterator it = student.getModules.iterator(); it.hasNext(); ) {
+ Module module = ( Module ) it.next();
+ if ( module.getScore() < 40 ) {
+ failedStudents.add( student ) ;
+ break;
+ }
}
}
-}</programlisting>
+ ]]>
+ </programlisting>
<para>Early SQL implementations were not Turing complete as they did not
- provide quantifiers to asses the structure of data. However modern SQL
- engines allow nesting of SQL which can be combined with keywords like
- 'exists' and 'in': The following query would return a set of Students who
+ provide quantifiers to access the structure of data. Modern SQL
+ engines do allow nesting of SQL, which can be combined with keywords like
+ 'exists' and 'in'. The following show SQL and a Rule to return a set of Students who
have failed the semester.</para>
- <programlisting>select
+ <programlisting>
+<![CDATA[
+ select
*
from
Students s
@@ -305,14 +359,20 @@
Modules m
where
m.student_name = s.name and
- m.score < 40
-)</programlisting>
+ m.score < 40
+)
+]]>
+ </programlisting>
<para></para>
- <programlisting>rule
+ <programlisting>
+<![CDATA[
+ rule "Failed_Students"
when
- exists( $student : Student() && Module( student == $student, score < 40 ) )</programlisting>
+ exists( $student : Student() && Module( student == $student, score < 40 ) )
+]]>
+ </programlisting>
<para></para>
</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml 2006-09-11 19:18:06 UTC (rev 6154)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml 2006-09-11 19:59:08 UTC (rev 6155)
@@ -5,16 +5,16 @@
<section>
<title>Overview</title>
- <para>Drools is split into two main parts Authoring and Runtime.</para>
+ <para>Drools is split into two main parts: Authoring and Runtime.</para>
- <para>The authoring process involves the creation of drl or xml files for
- rules which are fed into a parser, which is then passed using antlr 3
- grammer. The parser checks for correctly formed grammer and produces an
- intermediate structure for "descr"; where descr indicates the AST
+ <para>The authoring process involves the creation of DRL or XML files for
+ rules which are fed into a parser - defined by an Antlr 3 grammer. The
+ parser checks for correctly formed grammer and produces an
+ intermediate structure for the "descr"; where the "descr" indicates the AST that
"describes" the rules. The AST is then passed to the Package Builder which
produces Packages. Package Builder also undertakes any code generation and
compilation that is necessary for the creation of the Pacakge. A Packge
- object is a self contained and deployeable, in that it's serializable,
+ object is self contained and deployeable, in that it's a serialized
object consisting of one or more rules.</para>
<figure>
@@ -32,14 +32,13 @@
</figure>
<para>A RuleBase is a runtime component which consists of one or more
- Package's. Packages can be added and removed from the RuleBase at any
- time. A Rule Base can instantiate one or more WorkingMemories at any time;
- a weak reference is maintained, unless it's told otherwise. The Working
- Memory consists of a number of sub components inculding Working Memory
+ Packages. Packages can be added and removed from the RuleBase at any
+ time. A RuleBase can instantiate one or more WorkingMemories at any time;
+ a weak reference is maintained, unless configured otherwise. The Working
+ Memory consists of a number of sub components, inculding Working Memory
Event Support, Truth Maintenance System, Agenda and Agenda Event Support.
- Object assertion may result in the creation of one or more Activations,
- the agenda is resonpsible for scheduling the execution of these
- Activations.</para>
+ Object assertion may result in the creation of one or more Activations.
+ The Agenda is responsible for scheduling the execution of these Activations.</para>
<figure>
<title>Runtime Components</title>
@@ -73,29 +72,33 @@
</mediaobject>
</figure>
- <para>Three classes are used for authoring DrlParser, XmlParser and
- PackageBuilder. The two parser classes produce desc AST models from a
+ <para>Three classes are used for authoring: DrlParser, XmlParser and
+ PackageBuilder. The two parser classes produce "descr" AST models from a
provided Reader instance. PackageBuilder provides convienience APIs so
that you can mostly forget about those classes. The two convienience
methods are "addPackageFromDrl" and "addPackageFromXml" - both take an
instance of Reader as an argument. The example below shows how to build a
- package which includes rules from both an xml and drl source which are in
+ package that includes both XML and DRL rule files, which are in
the classpath. Note that all added package sources must be of the same
- package namespace for the current PackageBuilder instance.</para>
+ package namespace for the current PackageBuilder instance!</para>
<example>
- <title>Building a Package from multiple sources</title>
+ <title>Building a Package from Multiple Sources</title>
- <programlisting>PackageBuilder builder = new PackageBuilder();
+ <programlisting>
+ <![CDATA[
+PackageBuilder builder = new PackageBuilder();
builder.addPackageFromDrl( new InputStreamReader( getClass().getResourceAsStream( "package1.drl" ) ) );
builder.addPackageFromXml( new InputStreamReader( getClass().getResourceAsStream( "package2.drl" ) ) );
-Package pkg = builder.getPackage();</programlisting>
+Package pkg = builder.getPackage();
+ ]]>
+ </programlisting>
</example>
- <para>PackagBuilder is configurable, using PackageBuilderConfiguration. It
+ <para>PackagBuilder is configurable using PackageBuilderConfiguration. It
has default values that can be overriden programmatically via setters or
on first use via property settings. Currently it allows alternative
- compilers (Janino, Eclipse JDT) to be specified, different jdk source
+ compilers (Janino, Eclipse JDT) to be specified, different JDK source
levels ("1.4" and "1.5") and a parent class loader. The default compiler
is Eclipse JDT Core at source level "1.4" with the parent class loader set
to "Thread.currentThread().getContextClassLoader()".</para>
@@ -106,9 +109,13 @@
<example>
<title>Configuring the PackageBuilder to use JANINO</title>
- <programlisting>PackageBuilderConfiguration conf = new PackageBuilderConfiguration();
+ <programlisting>
+ <![CDATA[
+PackageBuilderConfiguration conf = new PackageBuilderConfiguration();
conf.setCompiler( PackageBuilderConfiguration.JANINO );
-PackageBuilder builder = new PackageBuilder( conf );</programlisting>
+PackageBuilder builder = new PackageBuilder( conf );
+ ]]>
+ </programlisting>
</example>
<para>This could also be done with a property file setting
@@ -118,9 +125,13 @@
<title>Configuring the PackageBuilder to build with JDk 1.5
compatability</title>
- <programlisting>PackageBuilderConfiguration conf = new PackageBuilderConfiguration();
+ <programlisting>
+ <![CDATA[
+PackageBuilderConfiguration conf = new PackageBuilderConfiguration();
conf.setJavaLanguageLevel( "1.5" );
-PackageBuilder builder = new PackageBuilder( conf );</programlisting>
+PackageBuilder builder = new PackageBuilder( conf );
+ ]]>
+ </programlisting>
</example>
<para>This could also be done with a property file setting
@@ -144,7 +155,7 @@
</section>
<section>
- <title>Rule Base</title>
+ <title>RuleBase</title>
<figure>
<title>RuleBase</title>
@@ -160,19 +171,23 @@
</mediaobject>
</figure>
- <para>A Rule Base contains one more more packages of rules, ready to be
- used (ie they have been validated/compiled etc). A Rule Base is
- serializable so it can be deployed to JNDI, or other such services.
+ <para>A RuleBase contains one more more packages of rules, ready to be
+ used, i.e., they have been validated/compiled etc. A Rule Base is
+ serializable so it can be deployed to JNDI or other such services.
Typically, a rulebase would be generated and cached on first use; to save
on the continually re-generation of the Rule Base; which is expensive. A
RuleBase is instantiated using the RuleBaseFactory, by default this
returns a ReteOO RuleBase. Arguments can be used to specify ReteOO or
- Leaps. pks are added, in turn, using the addPackage method. You may
+ Leaps. packages are added, in turn, using the addPackage method. You may
specify packages of any namespace and multiple packages of the same
namespace may be added.</para>
- <programlisting>RuleBase ruleBase = RuleBaseFactory.newRuleBase();
-ruleBase.addPackage( pkg );</programlisting>
+ <programlisting>
+ <![CDATA[
+RuleBase ruleBase = RuleBaseFactory.newRuleBase();
+ruleBase.addPackage( pkg );
+ ]]>
+ </programlisting>
<figure>
<title>RuleBaseFactory</title>
@@ -189,45 +204,57 @@
</figure>
<para>A Rule Base instance is threadsafe, in the sense that you can have
- the one instance shared accross threads in your application (which may be
- a web application, for instance). The most common operation on a rulebase
- is to create a newWorkingMemory.</para>
+ the one instance shared across threads in your application, which may be
+ a web application, for instance. The most common operation on a rulebase
+ is to create a new WorkingMemory.</para>
<para>The Rule Base also holds weak references to any working memories
- that it has spawned, so if rules are changing (or being added/removed etc)
- for long running working memories, they can be updated with the latest
+ that it has spawned, so that if rules are changing (or being added/removed etc.
+ for long running working memories), they can be updated with the latest
rules (without necessarily having to restart the working memory). You can
specify not to maintain a weak reference, but only do so if you know the
Rule Base will not be updated.</para>
- <programlisting>ruleBase.newWorkingMemory(); // maintains a weak reference.
-ruleBase.newWorkingMemory( false ); // do not maintain a weak reference</programlisting>
+ <programlisting>
+ <![CDATA[
+ruleBase.newWorkingMemory(); // maintains a weak reference.
+ruleBase.newWorkingMemory( false ); // do not maintain a weak reference
+ ]]>
+ </programlisting>
- <para>At any time Packages can be added and removed - all changes will be
- propated to the existing Working Memories, don't forget to call
+ <para>Packages can be added and removed at any time - all changes will be
+ propagated to the existing Working Memories; don't forget to call
fireAllRules() for resulting Activations to fire.</para>
- <programlisting>ruleBase.addPackage( pkg ); // Add a package instance
-ruleBase.removePackage( "org.com.sample" ); // remove a package, and all its parts, by it's namespace
-ruleBase.removeRule( "org.com.sample", "my rule" ); // remove a specific rule from a namespace</programlisting>
+ <programlisting>
+ <![CDATA[
+ruleBase.addPackage( pkg ); // Add a package instance
+ruleBase.removePackage( "org.com.sample" ); // remove a package, and all its parts, by it's namespace
+ruleBase.removeRule( "org.com.sample", "my rule" ); // remove a specific rule from a namespace
+ ]]>
+ </programlisting>
<para>While there is a method to remove an indivual rule, there is no
method to add an individual rule - to achieve this just add a new packge
with a single rule in it.</para>
<para>RuleBaseConfigurator can be used to specify additional behaviour of
- the RuleBase. RuleBaseConfiguration is set immutable after it has been
+ the RuleBase. RuleBaseConfiguration is set to immutable after it has been
added to a Rule Base.</para>
- <programlisting>RuleBaseConfiguration conf = new RuleBaseConfiguration();
+ <programlisting>
+ <![CDATA[
+RuleBaseConfiguration conf = new RuleBaseConfiguration();
conf.setProperty( RuleBaseConfiguration.PROPERTY_ASSERT_BEHAVIOR,
RuleBaseConfiguration..WM_BEHAVIOR_EQUALITY );
-RuleBase ruleBase = new ReteooRuleBase( conf );</programlisting>
+RuleBase ruleBase = new ReteooRuleBase( conf );
+ ]]>
+ </programlisting>
- <para>The two main propertiesto be aware of PROPERT_ASSERT_BEHAVIOR and
- PROPERTY_LOGICAL_OVERRIDE_BEHAVIOR, which are explain in later sections.
+ <para>The two main properties to be aware of are PROPERT_ASSERT_BEHAVIOR and
+ PROPERTY_LOGICAL_OVERRIDE_BEHAVIOR, which are explain more in later sections.
All properties and their values are public static field constants on
RuleBaseConfiguration.</para>
@@ -269,14 +296,14 @@
runtime. It holds references to all data that has been "asserted" into it
(until retracted) and it is the place where the interaction with your
application occurs. Working memories are stateful objects. They may be
- shortlived, or longlived. If you are interacting with an engine in a
+ shortlived or longlived. If you are interacting with an engine in a
stateless manner, that means you would use the RuleBase object to create a
newWorkingMemory for each session, and then discard the working memory
when finished (creating a working memory is a cheap operation). An
alternative pattern is a working memory that is kept around for a longer
time (such as a conversation) - and kept updated with new facts. When you
- wish to dispose of WorkingMemory it is best pactice to use the dispose()
- method, so that it removes the reference in the parent Rule Base - however
+ wish to dispose of WorkingMemory the best pactice is to use the dispose()
+ method, so that the reference to it is removed in the parent Rule Base. However,
this is a weak reference, so it should eventually be garbage collected
anyway. The term Working Memory Action is used to describe assertions,
retractions and modifications with the Working Memory.</para>
@@ -285,7 +312,7 @@
<title>Facts</title>
<para>Facts are objects (beans) from your application that you assert
- into the working memory. Facts are any java objects which the rules can
+ into the working memory. Facts are any Java objects which the rules can
access. The rule engine does not "clone" facts at all, it is all
references/pointers at the end of the day. Facts are your applications
data. Strings and other classes without getters and setters are not
@@ -301,17 +328,25 @@
facts. WorkingMemory.assertObject(yourObject) for example. When you
assert a fact, it is examined for matches against the rules etc. This
means ALL of the work is done during assertion; however, no rules are
- executed you call "fireAllRules()" after you have finished asserting
+ executed until you call "fireAllRules()". You don't call "fireAllRules()"
+ until after you have finished asserting
your facts. This is a common misunderstanding by people who think the
work happens when you call "fireAllRules()".</para>
-
+ <!-- FIXME - I think we might want to add this sentence to the previous paragraph.
+ However, when the rules are executed, they can assert new objects
+ thus causing new work to be needed.
+ -->
<para>When an Object is asserted it returns a FactHandle. This
FactHandle is the token used to represent your asserted Object inside
the WorkingMemory, it is also how you will interact with the Working
Memory when you wish to retract or modify an object.</para>
- <programlisting>Cheese stilton = new Cheese("stilton");
-FactHandle stiltonHandle = workingMemory.assertObject( stilton );</programlisting>
+ <programlisting>
+ <![CDATA[
+Cheese stilton = new Cheese("stilton");
+FactHandle stiltonHandle = workingMemory.assertObject( stilton );
+ ]]>
+ </programlisting>
<para>As mentioned in the Rule Base section a Working Memory may operate
in two assertions modes equality and identity - identity is
@@ -333,16 +368,20 @@
<para>"Retraction" is when you retract a fact from the Working Memory,
which means it will no longer track and match that fact, and any rules
- that are Activated and dependent on that fact will be cancelled. Note
+ that are activated and dependent on that fact will be cancelled. Note
that it is possible to have rules that depend on the "non existence" of
a fact, in which case retracting a fact may cause a rule to activate
(see the 'not' and 'exist' keywords). Retraction is done using the
FactHandle that was returned during the assert.</para>
- <programlisting>Cheese stilton = new Cheese("stilton");
+ <programlisting>
+ <![CDATA[
+Cheese stilton = new Cheese("stilton");
FactHandle stiltonHandle = workingMemory.assertObject( stilton );
....
-workingMemory.retractObject( stiltonHandle );</programlisting>
+workingMemory.retractObject( stiltonHandle );
+ ]]>
+ </programlisting>
</section>
<section>
@@ -357,17 +396,21 @@
parameter - this allows you to specify new instances for immutable
objects.</para>
- <programlisting>Cheese stilton = new Cheese("stilton");
+ <programlisting>
+ <![CDATA[
+Cheese stilton = new Cheese("stilton");
FactHandle stiltonHandle = workingMemory.assertObject( stilton );
....
stilton.setPrice( 100 );
-workingMemory.modifyObject( stiltonHandle, stilton );</programlisting>
+workingMemory.modifyObject( stiltonHandle, stilton );
+ ]]>
+ </programlisting>
</section>
<section>
<title>Property Change Listener</title>
- <para>If your fact objects are java beans, you can implement a property
+ <para>If your fact objects are Java Beans, you can implement a property
change listener for them, and then tell the rule engine about it. This
means that the engine will automatically know when a fact has changed,
and behave accordingly (you don't need to tell it that it is modified).
@@ -375,14 +418,20 @@
of drools will bundle some to make it easier). To use the Object in
dynamic mode specify true for the second assertObject parameter.</para>
- <programlisting>Cheese stilton = new Cheese("stilton");
-FactHandle stiltonHandle = workingMemory.assertObject( stilton, true ); //specifies that this is a dynamic fact</programlisting>
+ <programlisting>
+ <![CDATA[
+Cheese stilton = new Cheese("stilton");
+FactHandle stiltonHandle = workingMemory.assertObject( stilton, true ); //specifies that this is a dynamic fact
+ ]]>
+ </programlisting>
<para>To make a JavaBean dynamic add a PropertyChangeSupport field
memory along with two add/remove mothods and make sure that each setter
notifies the PropertyChangeSupport instance of the change.</para>
- <programlisting>private final PropertyChangeSupport changes = new PropertyChangeSupport( this );
+ <programlisting>
+ <![CDATA[
+private final PropertyChangeSupport changes = new PropertyChangeSupport( this );
...
public void addPropertyChangeListener(final PropertyChangeListener l) {
this.changes.addPropertyChangeListener( l );
@@ -399,7 +448,9 @@
this.changes.firePropertyChange( "state",
oldState,
newState );
-}</programlisting>
+}
+ ]]>
+ </programlisting>
</section>
<section>
@@ -410,8 +461,12 @@
static information, or services that are used in the RHS of a rule, or
perhaps a means to return objects from the rule engine.</para>
- <programlisting>new List list = new ArrayList;
-workingMemory.setGlobal("list", list);</programlisting>
+ <programlisting>
+ <![CDATA[
+new List list = new ArrayList;
+workingMemory.setGlobal("list", list);
+ ]]>
+ </programlisting>
<para>The global definition must be defined in the Rule Base and of the
same type, otherwise a runtime exception will be thrown. If a rule
@@ -446,21 +501,28 @@
adding the burden of tracking changes to facts and when they should
notify the rule engine.</para>
- <para>As of Drools 3.0, shadow facts hasn't been implemented, but it is
- planned for the future. However users can implement this facility
+ <para>As of Drools 3.0, Shadow Facts haven't been implemented, but it is
+ planned for the future. However, users can implement this facility
themselves if they really need it by building their own proxy
implementations.</para>
</section>
<section>
- <title>Initial Fact</title>
- <para>
- To support conditional elements like "not" (which will be covered later on), there is a need to "seed" the engine with something
- known as the "Initial Fact". This fact is a special fact that is not intended to be seen by the user.
-
- On the first working memory action (assert, fireAllRules) on a fresh working memory, the Initial Fact will be propagated through the RETE network. This allows rules that have no LHS, or perhaps do not use normal facts (such as rules that use "from"
- to pull data from an external source). For instance, if a new working memory is created, and no facts are asserted, calling the fireAllRules will cause the Initial Fact to propagate, possibly activating rules (otherwise, nothing would happen as there area no other facts to start with).
- </para>
+ <title>Initial Fact</title>
+ <para>
+ To support conditional elements like "not" (which will be covered later on), there
+ is a need to "seed" the engine with something known as the "Initial Fact". This fact
+ is a special fact that is not intended to be seen by the user.</para>
+
+ <para>
+ On the first working memory action (assert, fireAllRules) on a fresh working memory,
+ the Initial Fact will be propagated through the RETE network. This allows rules that
+ have no LHS, or perhaps do not use normal facts (such as rules that use "from"
+ to pull data from an external source). For instance, if a new working memory is created,
+ and no facts are asserted, calling the fireAllRules will cause the Initial Fact to
+ propagate, possibly activating rules (otherwise, nothing would happen as there area
+ no other facts to start with).
+ </para>
</section>
<section>
@@ -478,7 +540,7 @@
in a stateless session where rules actions cause other rules to fire, or
where there are large numbers of facts to match with rules.</para>
- <para>The JSR-94 api specifies statefull and stateless modes, but the
+ <para>The JSR-94 API specifies statefull and stateless modes, but the
equivalent in the native API is to simply create a new working memory
instance, and then discard it when the session is finished.</para>
</section>
@@ -503,7 +565,7 @@
<para>The Agenda is a RETE feature. During a Working Memory Action rules
may become fully matched and legible for execution; a single Working
- Memory Action can result in multiple legible rules. When a rule is fully
+ Memory Action can result in multiple eligible rules. When a rule is fully
matched an Activation is created, referencing the Rule and the matched
facts, and placed onto the Agenda. The Agenda controls the execution order
of these Activations using a Conflict Resolution strategy.</para>
@@ -514,15 +576,15 @@
<listitem>
<para>Working Memory Actions - this is where most of the work takes
place - in either the Consequence or the main java application
- process. Once the Consequence has finished or the main java
- application process calls fireAllRules() the engine switcesh to Agenda
+ process. Once the Consequence has finished or the main Java
+ application process calls fireAllRules() the engine switches to the Agenda
Evaluation phase.</para>
</listitem>
<listitem>
<para>Agenda Evaluation - attempts to select a rule to fire, if a rule
- is not found it exits otherwise it attempts to fire the rule switching
- the phase back to Working Memory Actions and the process begins again
+ is not found it exits, otherwise it attempts to fire the found rule, switching
+ the phase back to Working Memory Actions and the process repeats again
until the Agenda is empty.</para>
</listitem>
</orderedlist>
@@ -636,19 +698,25 @@
following example will filter out all rules ending with the text
"Test":</para>
- <programlisting>workingMemory.fireAllRules( new RuleNameEndsWithAgendaFilter( "Test" ) );</programlisting>
+ <programlisting>
+ <![CDATA[
+ workingMemory.fireAllRules( new RuleNameEndsWithAgendaFilter( "Test" ) );
+ ]]>
+ </programlisting>
</section>
</section>
<section>
- <title>Truth Maintenance with <indexterm>
+ <title>Truth Maintenance with
+ <indexterm>
<primary>Logical Object</primary>
- </indexterm>Logical Objects</title>
+ </indexterm>
+ Logical Objects</title>
<para>In a regular assertion, you need to explicitly retract a fact. With
logical assertions, the fact that was asserted will be automatically
retracted when the conditions that asserted it in the first place are no
- longer true (its actually cleverer then this, if there are no possible
+ longer true (it's actually more clever then that! If there are no possible
conditions that could support the logical assertion, only then will it be
retracted).</para>
@@ -657,7 +725,7 @@
we track how many times a particuar equality is STATED; this means we
count how many different instances are equal. When we logically assert an
object we are said to justify it and it is justified by the firing
- rule.For each logical assertion there can only be one equal object, each
+ rule. For each logical assertion there can only be one equal object, each
subsequent equal logical assertion increases the justification counter for
this logical assertion. As each justification is removed when we have no
more justifications the logical object is automatically retracted.</para>
@@ -671,9 +739,9 @@
this is the default behaviour - otherwise we overrde it to STATED but we
create an new FactHandle.</para>
- <para>This can sound confusing on a first read, so hopefully the flow
+ <para>This can be confusing on a first read, so hopefully the flow
charts below help. When it says that it returns a new FactHandle, this
- also indecates the Object was propagated through the network.</para>
+ also indicates the Object was propagated through the network.</para>
<figure>
<title>Stated Assertion</title>
@@ -708,7 +776,7 @@
</figure>
<section>
- <title>Example scenario</title>
+ <title>Example Scenario</title>
<para>An example may make things clearer. Imagine a credit card
processing application, processing transactions for a given account
@@ -719,10 +787,10 @@
suspicious" and when "everything is normal".</para>
<para>Of course there are many rules that operate no matter what
- (performing standard calculations etc). Now there are possibly many
+ (performing standard calculations, etc.). Now there are possibly many
reasons as to what could trigger a "reason to be suspicious": someone
notifying the bank, a sequence of large transactions, transactions for
- geographically disparate locations, or even reports of credit card
+ geographically disparate locations or even reports of credit card
theft. Rather then smattering all the little conditions in lots of
rules, imagine there is a fact class called
"SuspiciousAccount".</para>
@@ -739,7 +807,7 @@
kick in which flushes through any interrupted transactions).</para>
<para>If you have followed this far, you will note that truth
- maintenance like logical assertions allows rules to behave a little
+ maintenance, like logical assertions, allows rules to behave a little
like a human would, and can certainly make the rules more
managable.</para>
</section>
@@ -750,7 +818,7 @@
<title>Event Model</title>
<para>The event package provides means to be notified of rule engine
- events, including rules firing, objects being asserted etc. This allows
+ events, including rules firing, objects being asserted, etc. This allows
you to seperate out logging/auditing activities from the main part of your
application (and the rules) - as events are a cross cutting
concern.</para>
@@ -798,21 +866,28 @@
Working Memory - the example prints statements for only when rules are
fired:</para>
- <programlisting>workingMemory.addEventListener( new DefaultAgendaEventListener() {
+ <programlisting>
+ <![CDATA[
+workingMemory.addEventListener( new DefaultAgendaEventListener() {
public void afterActivationFired(AfterActivationFiredEvent event) {
super.afterActivationFired( event );
System.out.println( event );
}
-
-});</programlisting>
+});
+ ]]>
+ </programlisting>
<para>Drools also provides DebugWorkingMemoryEventListener and
DebugAgendaEventListener that implements each method with a debug print
statement:</para>
- <programlisting>workingMemory.addEventListener( new DebugWorkingMemoryEventListener() );</programlisting>
+ <programlisting>
+ <![CDATA[
+workingMemory.addEventListener( new DebugWorkingMemoryEventListener() );
+ ]]>
+ </programlisting>
- <para>The Eclipse based Rule IDE also provides an audit logger, and
+ <para>The Eclipse based Rule IDE also provides an audit logger and
graphical viewer, so that the rule engine can log events for later
viewing, and auditing.</para>
</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-What_is_a_Rule_Engine.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-What_is_a_Rule_Engine.xml 2006-09-11 19:18:06 UTC (rev 6154)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-What_is_a_Rule_Engine.xml 2006-09-11 19:59:08 UTC (rev 6155)
@@ -1,63 +1,64 @@
<?xml version="1.0" encoding="UTF-8"?>
<section>
- <title>What is a Rule Engine</title>
+ <title>What is a Rule Engine?</title>
<section>
<title>Introduction and Background</title>
<para>Artificial Intelligence (A.I.) is a very broad research area that
focuses on "Making computers think like people" and includes disciplines
- like Neural Networks, Genetic Algorithms, Decision Trees, Frame Systems
+ such as Neural Networks, Genetic Algorithms, Decision Trees, Frame Systems
and Expert Systems. Knowledge representation is the area of A.I. concerned
with how knowledge is represented and manipulated. Expert Systems use
Knowledge representation to facilitate the codification of knowledge into
a knowledge base which can be used for reasoning - i.e. we can process
data with this knowledge base to infer conclusions. Expert Systems are
- also known as Knowledge-based Systems and Knowledge-based Expert System
- and are considered 'applied artificial intelligence'; the process of
+ also known as Knowledge-based Systems and Knowledge-based Expert Systems
+ and are considered 'applied artificial intelligence'. The process of
developing with an Expert System is Knowledge Engineering. EMYCIN was one
of the first "shells" for an Expert System, which was created from the
- MYCIN medical diagnosis Expert System. Where early Expert Systems had
- their logic hard coded "shells" separated the logic from the system,
+ MYCIN medical diagnosis Expert System. Where-as early Expert Systems had
+ their logic hard coded, "shells" separated the logic from the system,
providing an easy to use environment for user input. Drools is a Rule
Engine that uses the Rule Based approached to implement an Expert System
and is more correctly classified as a Production Rule System.</para>
- <para>The term "Production Rule" originates from formal grammer - where it
+ <para>The term "Production Rule" originates from formal grammar - where it
is described as "an abstract structure that describes a formal language
precisely, i.e., a set of rules that mathematically delineates a (usually
infinite) set of finite-length strings over a (usually finite) alphabet"
(<ulink
url="http://en.wikipedia.org/wiki/Formal_grammar">wikipedia</ulink>).</para>
- <para>Business Rule Management Systems build value on top of an Rule
- Engine providing systems for rule management, deployment, collaboration,
- analysis and end user tools for business users. Further to this the
- "Business Rules Approach" is a fast evolving and popular methodology
- helping to formalise the role of Rule Engines in the enterprise.</para>
+ <para>Business Rule Management Systems build additional value on top of
+ a general purpose Rule Engines by providing, business user focused,
+ systems for rule creation, management, deployment, collaboration, analysis
+ and end user tools. Further adding to this value is the fast evolving and
+ popular methodology "Business Rules Approach", which is a helping
+ to formalize the role of Rule Engines in the enterprise.</para>
<para>The term Rule Engine is quite ambiguous in that it can be any system
that uses rules, in any form, that can be applied to data to produce
outcomes; which includes simple systems like form validation and dynamic
- expression engines: "How to Build a Business Rules Engine (2004)" by
+ expression engines. The book "How to Build a Business Rules Engine (2004)" by
Malcolm Chisholm exemplifies this ambiguity. The book is actually about
- how to build and alter a database schema to hold validation rules which it
+ how to build and alter a database schema to hold validation rules. The book
then shows how to generate VB code from those validation rules to validate
data entry - while a very valid and useful topic for some, it caused quite
a suprise to this author, unaware at the time in the subtleties of Rules
Engines differences, who was hoping to find some hidden secrets to help
- improve the Drools engine. jBPM uses expressions and delegates in its
- Decision nodes; which controls the transitions in a Workflow. At each node
- it evaluates a rule that dicates the transition to undertake - this is
+ improve the Drools engine. JBoss jBPM uses expressions and delegates in its
+ Decision nodes; which control the transitions in a Workflow. At each node
+ it evaluates has a rule set that dicates the transition to undertake - this is
also a Rule Engine. While a Production Rule System is a kind of Rule
- Engine and also Expert System, the validation and expression evaluation
+ Engine and also an Expert System, the validation and expression evaluation
Rule Engines mention previously are not Expert Systems.</para>
<para>A Production Rule System is turing complete with a focus on
knowledge representation to expression propositional and first order logic
in a concise, non ambigious and declarative manner. The brain of a
Production Rules System is an Inference Engine that is able to scale to a
- large number of rules and facts. The Inference Engine matches facts, the
+ large number of rules and facts. The Inference Engine matches facts and
data, against Production Rules, also called Productions or just Rules, to
infer conclusions which result in actions. A Production Rule is a two-part
structure using First Order Logic for knowledge representation.</para>
@@ -68,11 +69,15 @@
<actions></programlisting>
<para>The process of matching the new or existing facts against Production
- Rules is called <indexterm>
+ Rules is called
+ <indexterm>
<primary>Pattern Matching</primary>
- </indexterm> Pattern Matching, which is performed by the <indexterm>
+ </indexterm>
+ Pattern Matching, which is performed by the
+ <indexterm>
<primary>Inference Engine</primary>
- </indexterm>Inference Engine. There are a number of algorithms used for
+ </indexterm>
+ Inference Engine. There are a number of algorithms used for
Pattern Matching by Inference Engines including:</para>
<itemizedlist>
@@ -93,30 +98,40 @@
</listitem>
</itemizedlist>
- <para>Drools has implementations for both <indexterm>
- <primary>Rete</primary>
- </indexterm>Rete and <indexterm>
- <primary>Leaps</primary>
- </indexterm>Leaps; Leaps is considered experimental, as it is quite new.
- The Drools <indexterm>
- <primary>Rete</primary>
- </indexterm>Rete implementation is called ReteOO signifying that Drools
+ <para>Drools has implementations for both
+ <indexterm>
+ <primary>Rete</primary>
+ </indexterm>
+ Rete and
+ <indexterm>
+ <primary>Leaps</primary>
+ </indexterm>
+ Leaps; Leaps is considered experimental, as it is quite new.
+ The Drools
+ <indexterm>
+ <primary>Rete</primary>
+ </indexterm>
+ Rete implementation is called ReteOO, signifying that Drools
has an enhanced and optimised implementation of the Rete algorithm for
Object Oriented systems. Other Rete based engines also have marketing
terms for their proprietary enhancements to Rete, like RetePlus and Rete
III. It is important to understand that names like Rete III are purely
marketing where, unlike the original published Rete Algorithm, no details
- of implementation are published; thus asking a question like "Does Drools
- implement Rete III?" is nonsensical. The most common enhancements are
+ of the implementation are published. This makes questions such as "Does Drools
+ implement Rete III?" nonsensical. The most common enhancements are
covered in "Production Matching for Large Learning Systems (Rete/UL)"
(1995) by Robert B. Doorenbos.</para>
- <para>The Rules are stored in the the <indexterm>
+ <para>The Rules are stored in the
+ <indexterm>
<primary>Production Memory</primary>
- </indexterm>Production Memory and the facts that the Inference Engine
- matches against the <indexterm>
+ </indexterm>
+ Production Memory and the facts that the Inference Engine
+ matches against the
+ <indexterm>
<primary>WorkingMemory</primary>
- </indexterm>Working Memory. Facts are asserted into the Working Memory
+ </indexterm>
+ Working Memory. Facts are asserted into the Working Memory
where they may then be modiied or retracted. A system with a large number
of rules and facts may result in many rules being true for the same fact
assertion, these rules are said to be in conflict. The Agenda manages the
@@ -145,7 +160,8 @@
Maintenance, which always ensures that hope can only exist for a
decomcracy while we have honest politicians.</para>
- <programlisting>when
+ <programlisting>
+when
an honest Politician exists
then
logically assert Hope
@@ -188,13 +204,13 @@
</mediaobject>
</figure>
- <para>Backward chaining is 'goal-driven', we start with a conclusion which
- the engine tries to satisfy. If it can't it searches for conclusions, 'sub
- goals', that help satisfy an unknown part for the current goal - it
- continues this process untill either the initial conclusion is proven or
- there are no more sub goals. Prolog is an example of a Backward Chaining
- engine; Drools will adding support for Backward Chaining in its next major
- release.</para>
+ <para>Backward chaining is 'goal-driven', meaning that we start with a conclusion
+ which the engine tries to satisfy. If it can't it then searches for conclusions that
+ it can, known as 'sub goals', that will help satisfy some unknown part of the
+ current goal - it continues this process until either the initial conclusion
+ is proven or there are no more sub goals. Prolog is an example of a Backward
+ Chaining engine; Drools will adding support for Backward Chaining in its next
+ major release.</para>
<figure>
<title>Backward Chaining</title>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Why_use_a_Rule_Engine.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Why_use_a_Rule_Engine.xml 2006-09-11 19:18:06 UTC (rev 6154)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Why_use_a_Rule_Engine.xml 2006-09-11 19:59:08 UTC (rev 6155)
@@ -1,31 +1,33 @@
<?xml version="1.0" encoding="UTF-8"?>
<section>
- <title>Why use a Rule Engine</title>
+ <title>Why use a Rule Engine?</title>
- <para>Some questions often asked are</para>
+ <para>Some frequently asked questions:</para>
<orderedlist>
<listitem>
- <para>When should I use a rule engine ?</para>
+ <para>When should you use a rule engine?</para>
</listitem>
<listitem>
- <para>What advantage does this have over hand coded "if ..... then"
+ <para>What advantage does a rules engine have over hand coded "if...then"
approaches?</para>
</listitem>
<listitem>
- <para>Why should I use a Rule Engine instead of a scripting framework,
- like <indexterm>
+ <para>Why should you use a rule engine instead of a scripting framework,
+ like
+ <indexterm>
<primary>BeanShell</primary>
- </indexterm> Beanshell?</para>
+ </indexterm>
+ BeanShell?</para>
</listitem>
</orderedlist>
- <para>We will attempt to adderess these below.</para>
+ <para>We will attempt to adderess these questions below.</para>
<section>
- <title>Summary of advantages of a rule engine</title>
+ <title>Advantages of a Rule Engine</title>
<itemizedlist>
<listitem>
@@ -34,26 +36,32 @@
<para>Rule engines allow you to say "What to do" not "How to do
it".</para>
- <para>They key advantage of this point is that it can make it easy to
- express solutions to hard problems, and consequently have those
- solutions verified (rules are much easier to read then code).</para>
+ <para>The key advantage of this point is that using rules can make
+ it easy to express solutions to difficult problems and consequently
+ have those solutions verified (rules are much easier to read then code).
+ </para>
- <para>Rule systems are capable of solving very very hard problems, yet
- providing a solution that is able to explain why a "decision" was made
- (not so easy with other types of AI systems like neural networks, or
- say, my brain - I have no idea why I scratched the side of the
- car).</para>
+ <para>Rule systems are capable of solving very, very hard problems,
+ providing an explination of how the solution was arrived at and
+ why each "decision" along the way was made (not so easy with other
+ of AI systems like neural networks or the human brain - I have no
+ idea why I scratched the side of the car).
+ </para>
</listitem>
<listitem>
<para>Logic and Data Separation</para>
<para>Your data is in your domain objects, the logic is in the rules.
- This is fundamentally breaking the OO coupling of data and logic (this
- can be an advantage as well as a disadvantage depending on your point
- of view). The upshot is that the logic can be much easier to maintain
+ This is fundamentally breaking the OO coupling of data and logic, which
+ can be an advantage or a disadvantage depending on your point
+ of view. The upshot is that the logic can be much easier to maintain
as there are changes in the future, as the logic is all layed out in
- rules.</para>
+ rules. This can be espically true if the logic is cross-domain
+ or multi-domain logic. Instead of the logic being spread across many
+ domain objects or controllers, it can all be organized in one
+ or more very distinct rules files.
+ </para>
</listitem>
<listitem>
@@ -68,123 +76,131 @@
</listitem>
<listitem>
- <para>Centralisation of Knowledge</para>
+ <para>Centralization of Knowledge</para>
- <para>By using rules, you are creating a repository of knowlegde (a
- knowledebase) which is executable. This means its a single point of
+ <para>By using rules, you create a repository of knowlegde (a
+ knowledgebase) which is executable. This means it's a single point of
truth, for business policy (for instance) - ideally rules are so
- readable, they also serve as the documentation.</para>
+ readable that they can also serve as documentation.</para>
</listitem>
<listitem>
<para>Tool Integration</para>
- <para>Tools such as eclipse (and in future, Web based UIs) provide
+ <para>Tools such as Eclipse (and in future, Web based UIs) provide
ways to edit and manage rules and get immediate feedback, validation
and content assistance. Auditing and debugging tools are also
available.</para>
</listitem>
<listitem>
- <para>Explanation facility</para>
+ <para>Explanation Facility</para>
<para>Rule systems effectively provide an "explanation facility" by
- being able to log the "decisions" made by the rule engine (and why the
- decisions were made).</para>
+ being able to log the decisions made by the rule engine along with
+ why the decisions were made.</para>
</listitem>
<listitem>
- <para>Understandable rules (readable by domain experts)</para>
+ <para>Understandable Rules</para>
- <para>By creating object models (and optionally Domain Specific
- Languages) that model your problem domain, rules can look very close
- to natural language. They lend themselves to logic that is
- understandable to domain experts who may be non technical (as all the
- program plumbing is in the usual code, hidden away).</para>
+ <para>
+ By creating object models and optionally Domain Specific
+ Languages that model your problem domain you can set yourself up to
+ write rules that look very close to natural language. They lend themselves
+ to logic that is understandable to, possibly nontechnical, domain experts
+ as they are expressed in their language. (as all the program plumbing,
+ the "How", is in the usual code, hidden away).
+ </para>
</listitem>
</itemizedlist>
</section>
<section>
- <title>When should you use a rule engine</title>
+ <title>When should you use a Rule Engine?</title>
<para>The shortest answer to this is "when there is no satisfactory
traditional programming approach to solve the problem.". Given that short
answer, some more explanation is required. The reason why there is no
- "traditional" approach is possibly one of the following: <itemizedlist>
+ "traditional" approach is possibly one of the following:
+ <itemizedlist>
<listitem>
<para>The problem is just too fiddly for traditional code.</para>
-
- <para>The problem may not be complex, but you can't see a non
- fragile way of building it.</para>
+
+ <para>The problem may not be complex, but you can't see a
+ non-fragile way of building it.
+ </para>
</listitem>
-
+
<listitem>
<para>The problem is beyond any obvious algorithm based
- solution.</para>
-
+ solution.
+ </para>
+
<para>It is a complex problem to solve, there are no obvious
traditional solutions or basically the problem isn't fully
- understood.</para>
+ understood.
+ </para>
</listitem>
-
+
<listitem>
<para>The logic changes often</para>
-
+
<para>The logic itself may be simple (but doesn't have to be) but
- the rules change just too often. In many organisations, software
- releases are few and far between, and rules can help provide the
- "agility" that is needed, and expected these days (in a reasonably
- safe way).</para>
+ the rules change quite often. In many organizations software
+ releases are few and far between and rules can help provide the
+ "agility" that is needed and expected in a reasonably
+ safe way.</para>
</listitem>
-
+
<listitem>
<para>Domain experts (or business analysts) are readily available,
- but are non technical.</para>
-
- <para>Non technical domain experts are often a wealth of knowledge
- about business rules. They typically are non technical, but can be
- very logical. Rules can allow them to express the logic in their own
- terms. Of course, they still have to think critically and be capable
- of logical thinking (many people in "soft" non technical positions
- are not, so be careful, as by codifying business knowledge in rules,
- you will often be exposing flaws in the way the business rules are
- at present).</para>
+ but are nontechnical.</para>
+
+ <para>Domain experts are often a wealth of knowledge
+ about business rules and processes. They typically are nontechnical,
+ but can be very logical. Rules can allow them to express the logic in
+ their own terms. Of course, they still have to think critically and be
+ capable of logical thinking (many people in "soft" nontechnical positions
+ do not have training in formal logic, so be careful and work with them,
+ as by codifying business knowledge in rules, you will often expose holes
+ in the way the business rules and processes are currently understood).</para>
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
- <para>Of course if rules are a new technology in your project teams
- experience, the overhead in getting going must be factored in. Its not a
- trivial technology, but we try to make it easier.</para>
+ <para>If rules are a new technology for your project teams,
+ the overhead in getting going must be factored in. Its not a trivial
+ technology, but this document tries to make it easier to understand.</para>
<para>Typically in a modern OO application you would use a rule engine to
contain key parts of your business logic (what that means of course
- depends on the application) - ESPECIALLY the REALLY MESSY parts !. This is
+ depends on the application) - ESPECIALLY the REALLY MESSY parts!. This is
an inversion of the OO concept of encapsulating all the logic inside your
objects. This is not to say that you throw out OO practices, on the
contrary in any real world application, business logic is just one part of
- the application. If you ever notice lots of "if" "else" "switch" and other
- messy logic in your code that just doesn't feel right (and you keep coming
- back to fix it - either because you got it wrong, or the logic/your
- understanding changes) - think about using rules. If you are faced with
- tough problems of which there are no algorithms or patterns for, consider
- rules.</para>
+ the application. If you ever notice lots of "if", "else", "switch", an
+ over abundance of strategy patterns and/or other messy logic in your code that
+ just doesn't feel right (and you keep coming back to fix it - either because
+ you got it wrong, or the logic/your understanding changes) - think about
+ using rules. If you are faced with tough problems of which there are no
+ algorithms or patterns for, consider using rules.
+ </para>
- <para>Rules could be used embedded in your application, or perhaps as a
+ <para>Rules could be used embedded in your application or perhaps as a
service. Often rules work best as "stateful" component - hence they are
often an integral part of an application. However, there have been
- successful cases of creating reusable rul eservices which are
- stateless.</para>
+ successful cases of creating reusable rule services which are stateless.</para>
- <para>In your organisation, it is important to think about the process you
- may want to/have to use for updating rules in systems that are in
- production (the options are many, but different organisations have
- different requirements - often they are out of the control of the
- application vendors/project teams).</para>
+ <para>In your organization it is important to think about the process you
+ will use for updating rules in systems that are in production (the options
+ are many, but different organizations have different requirements - often
+ they are out of the control of the application vendors/project teams).
+ </para>
</section>
<section>
- <title>When not to use a rule engine</title>
+ <title>When not to use a Rule Engine</title>
<para>To quote a Drools mailing list regular (Dave Hamu): "It seems to me
that in the excitement of working with rules engines, that people forget
@@ -196,18 +212,18 @@
it's designed for."</para>
<para>As rule engines are dynamic (dynamic in the sense that the rules can
- be stored and managed and updates as data), they are often looked at as a
+ be stored and managed and updated as data), they are often looked at as a
solution to the problem of deploying software (most IT departments seem to
exist for the purpose of preventing software being rolled out). If this is
the reason you wish to use a rule engine, be aware that rule engines work
best when you are able to write declarative rules. As an alternative, you
can consider data-driven designs (lookup tables), or script/process
- engines where the scripts are managed in a database, and able to be
+ engines where the scripts are managed in a database and are able to be
updated on the fly.</para>
</section>
<section>
- <title>Scripting or process engines</title>
+ <title>Scripting or Process Engines</title>
<para>Hopefully the preceeding sections have explained when you may want
to use a rule engine.</para>
@@ -215,9 +231,9 @@
<para>Alternatives are script-based engines that provide the dynamicness
for "changes on the fly" (there are many solutions here). </para>
- <para>Alternatively Process engines (also capable of workflow) such as jBPM allow you to
- graphically (or programmatically) describe steps in a process - those
- steps can also involve decision point which are in themselves a simple
+ <para>Alternatively Process Engines (also capable of workflow) such as jBPM
+ allow you to graphically (or programmatically) describe steps in a process
+ - those steps can also involve decision point which are in themselves a simple
rule. Process engines and rules often can work nicely together, so its not
an either-or proposition.</para>
@@ -228,34 +244,36 @@
difficulty in future maintenance, as they tend to grow in complexity over
time. The upside of scripting engines is they can be easier to implement
at first, and you can get quick results (and conceptually simpler for
- imperative programmers !).</para>
+ imperative programmers!).</para>
<para>Many people have also implemented data-driven systems successfully
in the past (where there are control tables that store meta-data that
changes your applications behaviour) - these can work well when the
control can remain very limited. However, they can quickly grow out of
control if extended to much (such that only the original creators can
- change the applications behaviour), or, they cause the application to
+ change the applications behaviour) or they cause the application to
stagnate as they are too inflexible.</para>
</section>
<section>
- <title>Strong and Loose coupling</title>
+ <title>Strong and Loose Coupling</title>
<para>No doubt you have heard terms like "tight coupling" and "loose
- coupling" in systems design. Generally people assert that loose or "weak"
- coupling is preferable in design terms, due to the added flexibility.
- Similarly with rules, you can have "strongly coupled" and "weakly coupled"
+ coupling" in systems design. Generally people assert that "loose" or "weak"
+ coupling is preferable in design terms, due to the added flexibility it affords.
+ Similarly, you can have "strongly coupled" and "weakly coupled"
rules. Strongly coupled in this sense means that one rule "firing" will
- clearly result in another rule firing etc. in other words there is a clear
+ clearly result in another rule firing etc.; in other words there is a clear
(probably obvious) chain of logic. If your rules are all strongly coupled,
the chances are that the rules will have future inflexibility, and more
significantly, that perhaps a rule engine is overkill (as the logic is a
- clear chain of rules - and can be hard coded). This is not to say that
- strong or weak coupling is inherently bad, but its a point to keep in mind
- when considering a rule engine, and also in how you capture the rules.
- "Loosely" coupled rules should result in a system that allows rules to be
- changed, removed, added without requiring changes to other rules that are
- unrelated.</para>
+ clear chain of rules - and can be hard coded. [A Decision Tree may be in order]).
+ This is not to say that strong or weak coupling is inherently bad, but it is a
+ point to keep in mind when considering a rule engine and in how you
+ capture the rules. "Loosely" coupled rules should result in a system that
+ allows rules to be changed, removed and added without requiring changes to other
+ rules that are unrelated.
+ </para>
+
</section>
</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/master.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/master.xml 2006-09-11 19:18:06 UTC (rev 6154)
+++ labs/jbossrules/trunk/documentation/manual/en/master.xml 2006-09-11 19:59:08 UTC (rev 6155)
@@ -30,6 +30,12 @@
<surname>Frandsen</surname>
</author>
+
+ <author>
+ <firstname>Sam</firstname>
+
+ <surname>Griffith Jr.</surname>
+ </author>
</bookinfo>
<toc />
More information about the jboss-svn-commits
mailing list