[jboss-svn-commits] JBL Code SVN: r25876 - in labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US: Chapter-Rule_Engine and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Sun Mar 29 20:43:15 EDT 2009
Author: mark.proctor at jboss.com
Date: 2009-03-29 20:43:14 -0400 (Sun, 29 Mar 2009)
New Revision: 25876
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Chapter-Quick_Start.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-Rete_Algorithm.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-Rules.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-What_is_a_Rule_Engine.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-Why_use_a_Rule_Engine.xml
Log:
JBRULES-2019 Documentation patches for Drools Expert Chapter "Rule Engine"
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Chapter-Quick_Start.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Chapter-Quick_Start.xml 2009-03-29 20:59:36 UTC (rev 25875)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Chapter-Quick_Start.xml 2009-03-30 00:43:14 UTC (rev 25876)
@@ -261,7 +261,7 @@
<para>Unlike a stateless session the dispose() method must be called
afterwards to ensure there are no memory leaks, as the KnowledgeBase
- contained references to StatefulKnowledgeSessions when they are created.
+ contains references to StatefulKnowledgeSessions when they are created.
StatefulKnowledgeSession also supports the BatchExecutor interface like
StatelessKnowledgeSession, the only difference is that when used with
stateful the FireAllRules command is not automatically called at the
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-Rete_Algorithm.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-Rete_Algorithm.xml 2009-03-29 20:59:36 UTC (rev 25875)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-Rete_Algorithm.xml 2009-03-30 00:43:14 UTC (rev 25876)
@@ -8,18 +8,18 @@
xmlns:db="http://docbook.org/ns/docbook" xml:base="../../">
<title>Rete Algorithm</title>
- <para>The RETE algorithm was invented by Dr. Charles Forgy and documented in
+ <para>The <emphasis>Rete</emphasis> algorithm was invented by Dr. Charles Forgy and documented in
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. The RETE algorithm can be broken
- into 2 parts: rule compilation and runtime execution.</para>
+ The latin word "rete" means "net" or "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 discrimination network. In non-technical
- terms, a discrimination network is used to filter data. The idea is to
- filter data as it propagates 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
+ Memory are processed to generate an efficient discrimination network. In
+ non-technical terms, a discrimination network is used to filter data as
+ it propagates through the network. The nodes at the top of the network
+ 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,7 +42,7 @@
cycles. To make things efficient, the engine should only pass the object to
the nodes that match the object type. The easiest way to do this is to
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 propagate to
+ it. This way, if an application asserts a new Account, it won't propagate to
the nodes for the Order object. In Drools when an object is asserted it
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 ObjectTypeNodes finding valid matches which it caches in the list. This enables Drools
@@ -65,9 +65,9 @@
support other operations. For example, <code>Account.name == "Mr Trout"</code> is a
literal condition. When a rule has multiple literal conditions for a single
object type, they are linked together. This means that if an application
- asserts an account object, it must first satisfy the first literal condition
+ asserts an Account object, it must first satisfy the first literal condition
before it can proceed to the next AlphaNode. In Dr. Forgy's paper, he refers
- to these as IntraElement conditions. The following shows the AlphaNode
+ to these as IntraElement conditions. The following diagram shows the AlphaNode
combinations for Cheese( name == "cheddar", strength == "strong" ):</para>
<figure>
@@ -86,10 +86,10 @@
ObjectTypeNode it adds the literal value as a key to the HashMap with the
AlphaNode as the value. When a new instance enters the ObjectType node,
rather than propagating to each AlphaNode, it can instead retrieve the
- correct AlphaNode from the HashMap - avoiding unnecessary literal
+ correct AlphaNode from the HashMap,thereby avoiding unnecessary literal
checks.</para>
- <para>There are two two-input nodes; JoinNode and NotNode - both are
+ <para>There are two two-input nodes, JoinNode and NotNode, and both are
types of BetaNodes. BetaNodes are used 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
@@ -120,16 +120,16 @@
network we use a LeftInputNodeAdapter - this takes an Object as an input and
propagates a single Object Tuple.</para>
- <para>Terminal nodes are used to indicate a single rule has matched all its
- conditions - at this point we say the rule has a full match. A rule with an
+ <para>Terminal nodes are used to indicate a single rule having matched all its
+ conditions; at this point we say the rule has a full match. A rule with an
'or' conditional disjunctive connective results in subrule generation for
each possible logically branch; thus one rule can have multiple terminal
nodes.</para>
<para>Drools also performs node sharing. Many rules repeat the same
- patterns, node sharing allows us to collapse those patterns so that they
+ patterns, and node sharing allows us to collapse those patterns so that they
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>
+ rules share the first pattern, but not the last:</para>
<programlisting>
<![CDATA[
@@ -155,7 +155,7 @@
]]>
</programlisting>
- <para>As you can see below, the compiled Rete network shows the alpha node is
+ <para>As you can see below, the compiled Rete network shows that 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>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-Rules.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-Rules.xml 2009-03-29 20:59:36 UTC (rev 25875)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-Rules.xml 2009-03-30 00:43:14 UTC (rev 25876)
@@ -207,16 +207,16 @@
<section>
<title>First Order Logic</title>
- <para>Rules are written using First Order Logic, or predicate logic, which
+ <para>Rules are written using First Order Logic, or Predicate Logic, which
extends Propositional Logic. <ulink
url="http://en.wikipedia.org/wiki/Emil_Leon_Post">Emil Leon Post</ulink>
was the first to develop an inference based system using symbols to
- express logic - as a consequence of this he was able to prove that any
+ express logic. As a consequence of this he was able to prove that any
logical system (including mathematics) could be expressed with such a
system.</para>
<para>A proposition is a statement that can be classified as true or
- false. If the truth can be determined from statement alone it is said to
+ false. If the truth can be determined from the statement alone it is said to
be a "closed statement". In programming terms this is an expression that
does not reference any variables:</para>
@@ -228,14 +228,14 @@
<programlisting>Person.sex == "male"</programlisting>
- <para>With SQL if we look at the conclusion's action as simply returning
+ <para>With SQL, the conclusion's action is to return
the matched fact to the user:</para>
<programlisting>select * from Person where Person.sex == "male"</programlisting>
<para>For any rows, which represent our facts, that are returned we have
inferred that those facts are male people. The following diagram shows how
- the above SQL statement and People table can be represented in terms of an
+ the above SQL statement and Person table can be represented in terms of an
Inference Engine.</para>
<figure>
@@ -248,58 +248,57 @@
</mediaobject>
</figure>
- <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 proposition can be combined with conjunctive and
- disjunctive connectives, which is the logic theorists way of saying
- '&&' and '||'. The following shows two open propositional
- statements connected together with a single disjunctive connective.</para>
+ <para>In Java we can write simple proposition as a boolean expression
+ 'variable' 'operator' 'value', where 'value' frequently is a
+ literal value, and such a proposition can be thought of as a field constraint.
+ Furthermore, such a proposition can be combined with conjunctive and
+ disjunctive connectives, which is the logic theorists' denomination for
+ '&&' and '||'. The following expression shows two open propositional
+ statements connected with a single disjunctive connective.</para>
<programlisting role="JAVA">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
+ connective which actually results in the generation of two rules, to
represent the two possible logic outcomes.</para>
<programlisting role="JAVA">Person( eyeColour == "blue" ) || Person( eyeColor == "green" )</programlisting>
<para>Disjunctive field constraints connectives could also be used and
- would not result in multiple rule generation.</para>
+ would not result in multiple rules.</para>
<programlisting role="JAVA">Person( eyeColour == "blue"||"green" )</programlisting>
<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 quantifiers. Universal
- quantifiers allow you to check that something is true for everything;
+ Logic with two quantifier concepts to allow expressions defining
+ structure, i.e., the universal and existential quantifiers. Universal
+ quantifiers allow you to check that something is true for everything,
normally supported by the <code>forall</code> conditional element. Existential
quantifiers check for the existence of something, in that it occurs at
- least once - this is supported with <code>not</code> and <code>exists</code> conditional
+ least once, this being supported with <code>not</code> and <code>exists</code> conditional
elements.</para>
- <para>Imagine we have two classes - Student and Module. Module represents
+ <para>Imagine we have two classes: Student and Module. Module represents
each of the courses the Student attended for that semester, referenced by
the List collection. At the end of the semester each Module has a score.
If the Student has a Module score below 40 then they will fail that
- semester - the existential quantifier can be used used with the "less than
+ semester. The existential quantifier can be used used with the "less than
40" open proposition to check for the existence of a Module that is true
for the specified criteria.</para>
<programlisting role="JAVA"><![CDATA[public class Student {
- private String name;
- private List modules;
-
+ private String name;
+ private List<Module> modules;
...
}]]></programlisting>
<programlisting role="JAVA">
public class Module {
- private String name;
- private String studentName;
- private int score;
+ private String name;
+ private Student student;
+ private int score;
...
}
</programlisting>
@@ -311,10 +310,8 @@
<programlisting role="JAVA">
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();
+ for ( Student student: students ) {
+ for ( Module module: student.getModules ) {
if ( module.getScore() < 40 ) {
failedStudents.add( student ) ;
break;
@@ -326,8 +323,8 @@
<para>Early SQL implementations were not Turing complete as they did not
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>
+ and 'in'. The following snippets show SQL to return a set of students
+ who have failed the semester, and a rule firing for such students.</para>
<programlisting role="SQL">
select
@@ -349,7 +346,11 @@
<programlisting role="JAVA">
rule "Failed_Students"
when
- exists( $student : Student() && Module( student == $student, score < 40 ) )
+ $s : Student()
+ exists Module( student == $s, score < 40 )
+ then
+ # record $student as flunked
+ end
</programlisting>
</section>
</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml 2009-03-29 20:59:36 UTC (rev 25875)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml 2009-03-30 00:43:14 UTC (rev 25876)
@@ -16,11 +16,12 @@
<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 grammar. The
parser checks for correctly formed grammar and produces an intermediate
- structure for the "descr"; where the "descr" indicates the AST that
+ structure for the "descr"; where the "descr" indicates the
+ abstract syntax tree (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 Package. A Package
- object is self contained and deployable, in that it's a serialized object
+ object is self-contained and deployable, in that it is a serialized object
consisting of one or more rules.</para>
<figure>
@@ -70,8 +71,8 @@
<para>Four classes are used for authoring: <code>DrlParser</code>, <code>XmlParser</code>,
<code>ProcessBuilder</code> and <code>PackageBuilder</code>. The two parser classes produce "descr"
(description) AST models from a provided Reader instance. ProcessBuilder
- reads in an xstream serialization representation of the Rule Flow.
- PackageBuilder provides convienience APIs so that you can mostly forget
+ reads in an xstream serialization, i.e., a representation of the Rule Flow.
+ PackageBuilder provides convenience APIs so that you can mostly forget
about those classes. The three convenience methods are
<code>addPackageFromDrl</code>, <code>addPackageFromXml</code> and <code>addRuleFlow</code> - all take an
instance of Reader as an argument. The example below shows how to build a
@@ -104,7 +105,7 @@
PackageBuilderErrors errors = builder.getErrors();</programlisting>
</example>
- <para>PackageBuilder is configurable using PackageBuilderConfiguration
+ <para>PackageBuilder is configurable by using the PackageBuilderConfiguration
class.</para>
<figure>
@@ -117,26 +118,26 @@
</mediaobject>
</figure>
- <para>It has default values that can be overridden programmatically via
- setters or on first use via property settings. At the heart of the
+ <para>The configuration has default values that can be overridden programmatically via
+ setters, or on first use via property settings. At the heart of the
settings is the <code>ChainedProperties</code> class which searches a number of
locations looking for <code>drools.packagebuilder.conf</code> files; as it finds them
- it adds the properties to the master propperties list; this provides a
+ it adds the properties to the master properties list; this provides a
level precedence. In order of precedence those locations are: System
Properties, user defined file in System Properties, user home directory,
working directory, various <code>META-INF</code> locations. Further to this the
- <code>droosl-compiler</code> jar has the default settings in its <code>META-INF</code>
+ <code>drools-compiler</code> jar has the default settings in its <code>META-INF</code>
directory.</para>
<para>Currently the <code>PackageBuilderConfiguration</code> handles the registry of
- Accumulate functions, registry of Dialects and the main
+ Accumulate functions, the registry of Dialects and the main
ClassLoader.</para>
<para>Drools has a pluggable Dialect system, which allows other languages
- to compile and execution expressions and blocks, the two currently
+ to compile and execute expressions and blocks. The two currently
supported dialects are Java and MVEL. Each has its own
<code>DialectConfiguration</code> Implementation; the javadocs provide details for each
- setter/getter and the property names used to configure them.</para>
+ setter and getter, and the property names used to configure them.</para>
<figure>
<title><code>JavaDialectConfiguration</code></title>
@@ -168,7 +169,7 @@
override the compiler setting before you instantiate this <code>PackageBuilder</code>,
you can either do that with a <code>packagebuilder</code> properties file the
<code>ChainedProperties</code> class will find, or you can do it programmatically as
- shown below; note this time I use properties to inject the value for
+ shown below. Note that this time I use properties to inject the value for
startup.</para>
<example>
@@ -189,7 +190,7 @@
"1.4" with the parent class loader set to
<code>Thread.currentThread().getContextClassLoader()</code>.</para>
- <para>The following show how to specify the JANINO compiler
+ <para>The following lines show how to specify the JANINO compiler
programmatically:</para>
<example>
@@ -202,7 +203,7 @@
</example>
<para>The <code>MVELDialectConfiguration</code> is much simpler and only allows strict
- mode to be turned on and off, by default strict is true; this means all
+ mode to be turned on and off. By default strict is true, which means that all
method calls must be type safe either by inference or by explicit
typing.</para>
@@ -233,7 +234,7 @@
<para>A <code>RuleBase</code> is instantiated using the <code>RuleBaseFactory</code>, by default
this returns a ReteOO <code>RuleBase</code>. Packages are added, in turn, using the
- <code>addPackage</code> method. You may specify packages of any namespace and multiple
+ <code>addPackage</code> method. You may specify packages of any namespace, and multiple
packages of the same namespace may be added.</para>
<example>
@@ -254,10 +255,10 @@
</figure>
<para>A <code>RuleBase</code> contains one or more more packages of rules, ready to be
- used, i.e., they have been validated/compiled etc. A <code>RuleBase</code> is
+ used, i.e., they have been validated and compiled, etc. A <code>RuleBase</code> 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 <code>RuleBase</code>; which is
+ Typically, a rulebase would be generated and cached on first use, to
+ avoid the repeated regeneration of the <code>RuleBase</code>, which is
expensive.</para>
<para>A <code>RuleBase</code> instance is thread safe, in the sense that you can have
@@ -266,25 +267,25 @@
to create a new rule session; either stateful or stateless.</para>
<para>The <code>RuleBase</code> also holds references to any stateful session that it
- has spawned, so that if rules are changing (or being added/removed etc.
- for long running sessions), they can be updated with the latest rules
- (without necessarily having to restart the session). You can specify not
+ has spawned, so that if rules are changing (or being added and removed)
+ in a long running session, they can be updated with the latest rules
+ without having to restart the session. You can specify not
to maintain a reference, but only do so if you know the <code>RuleBase</code> will not
be updated. References are not stored for stateless sessions.</para>
<programlisting>ruleBase.newStatefulSession(); // maintains a reference.
ruleBase.newStatefulSession( false ); // do not maintain a reference </programlisting>
- <para>Packages can be added and removed at any time - all changes will be
- propagated to the existing stateful sessions; don't forget to call
+ <para>Packages can be added and removed at any time, and all changes will be
+ propagated to the existing stateful sessions, but don't forget to call
<code>fireAllRules()</code> 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.removePackage( "org.com.sample" ); // remove a package, and all its parts, by its 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 package
+ method to add an individual rule. To achieve this, just add a new package
with a single rule in it.</para>
<para><code>RuleBaseConfigurator</code> can be used to specify additional behavior of
@@ -292,7 +293,7 @@
added to a <code>RuleBase</code>. Nearly all the engine optimizations can be turned on
and off from here, and also the execution behavior can be set. Users will
generally be concerned with insertion behavior (identity or equality) and
- cross product behavior(remove or keep identity equals cross
+ cross product behavior (remove or keep identity equals across
products).</para>
<programlisting>RuleBaseConfiguration conf = new RuleBaseConfiguration();
@@ -313,7 +314,7 @@
</section>
<section>
- <title>WorkingMemory and Stateful/Stateless Sessions</title>
+ <title>WorkingMemory, Stateful and Stateless Sessions</title>
<figure>
<title>WorkingMemory</title>
@@ -325,10 +326,10 @@
</mediaobject>
</figure>
- <para>It holds references to all data that has been "inserted" into it
- (until retracted) and it is the place where the interaction with your
+ <para>The Working Memory holds references to all data that has been "inserted" into it and not yet retracted,
+ and it is the place where the interaction with your
application occurs. Working memories are stateful objects. They may be
- shortlived or longlived.</para>
+ short-lived or long-lived.</para>
<section>
<title>Facts</title>
@@ -336,8 +337,8 @@
<para>Facts are objects (beans) from your application that you insert
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
+ references (or pointers) at the end of the day. Facts are the data of your application.
+ Strings and other classes without getters and setters are not
valid Facts and can't be used with Field Constraints which rely on the
JavaBean standard of getters and setters to interact with the
object.</para>
@@ -346,16 +347,17 @@
<section>
<title>Insertion</title>
- <para>"Insert" is the act of telling the <code>WorkingMemory</code> about the facts.
- <code>WorkingMemory.insert(yourObject)</code> for example. When you insert a fact, it
- is examined for matches against the rules etc. This means <emphasis>ALL</emphasis> of the
- work is done during insertion; however, no rules are executed until you
- call <code>fireAllRules()</code>. You don't call <code>fireAllRules()</code> until after you
- have finished inserting your facts. This is a common misunderstanding by
- people who think the work happens when you call <code>fireAllRules()</code>. Expert
+ <para>"Insert" is the act of telling the <code>WorkingMemory</code> about a fact, which you do
+ by <code>wm.insert(yourObject)</code>, for example. When you insert a fact, it
+ is examined for matches against the rules. This means <emphasis>all</emphasis> of the
+ work for deciding about firing or not firing a rule is done during
+ insertion; no rule, however, is executed until you
+ call <code>fireAllRules()</code>, which you call <code>fireAllRules()</code> after you
+ have finished inserting your facts. It is a common misunderstanding for
+ people to think the condition evaluation happens when you call <code>fireAllRules()</code>. Expert
systems typically use the term <code>assert</code> or <code>assertion</code> to refer to facts
- made available to the system, however due to the <code>assert</code> become a keyword
- in most languages we have moved to use the <code>Insert</code> keyword; so expect
+ made available to the system. However due to the <code>assert</code> being a keyword
+ in most languages we have moved to use the <code>insert</code> keyword; so expect
to hear the two used interchangeably.</para>
<!-- FIXME - I think we might want to add this sentence to the previous paragraph.
@@ -364,35 +366,35 @@
-->
<para>When an Object is inserted it returns a <code>FactHandle</code>. This <code>FactHandle</code>
- is the token used to represent your insert Object inside the
- <code>WorkingMemory</code>, it will be used when interacting with the <code>WorkingMemory</code>
+ is the token used to represent your inserted object within the
+ <code>WorkingMemory</code>. It is also used for interactions with the <code>WorkingMemory</code>
when you wish to retract or modify an object.</para>
<programlisting>Cheese stilton = new Cheese("stilton");
FactHandle stiltonHandle = session.insert( stilton ); </programlisting>
<para>As mentioned in the Rule Base section a Working Memory may operate
- in two assertions modes equality and identity - identity is
+ in two assertion modes, i.e., equality or identity, with identity being
default.</para>
- <para>Identity means the Working Memory uses an <code>IdentityHashMap</code> to store
- all asserted Objects. New instance assertions always result in the
- return of a new <code>FactHandle</code>, if an instance is asserted twice then it
- returns the previous fact handle – i.e. it ignores the second insertion
+ <para><emphasis>Identity</emphasis> means that the Working Memory uses an <code>IdentityHashMap</code> to store
+ all asserted objects. New instance assertions always result in the
+ return of a new <code>FactHandle</code>, but if an instance is asserted again then it
+ returns the original fact handle, i.e., it ignores repeated insertions
for the same fact.</para>
- <para>Equality means the Working Memory uses a <code>HashMap</code> to store all
+ <para><emphasis>Equality</emphasis> means that the Working Memory uses a <code>HashMap</code> to store all
asserted Objects. New instance assertions will only return a new
- <code>FactHandle</code> if a not equal classes have been asserted.</para>
+ <code>FactHandle</code> if no equal objects have been asserted.</para>
</section>
<section>
<title>Retraction</title>
- <para>"Retraction" is when you retract a fact from the Working Memory,
+ <para>"Retraction" is the removal of 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 it is possible to have rules that depend on the "non existence" of
+ that it is possible to have rules that depend on the nonexistence of
a fact, in which case retracting a fact may cause a rule to activate
(see the <code>not</code> and <code>exist</code> keywords). Retraction is done using the
<code>FactHandle</code> that was returned during the assert.</para>
@@ -406,17 +408,18 @@
<section>
<title>Update</title>
- <para>The Rule Engine must be notified of modified Facts, so that it can
- be re-processed. Modification internally is actually a retract and then an
- insert; so it clears the <code>WorkingMemory</code> and then starts again. Use the
- <code>modifyObject</code> method to notify the Working Memory of changed objects, for
- objects that are not able to notify the Working Memory themselves.
- Notice <code>modifyObject</code> always takes the modified object as a second
- parameter - this allows you to specify new instances for immutable
- objects. The <code>update()</code> method can only be used with objects that have
+ <para>The Rule Engine must be notified of modified Facts, so that they can
+ be reprocessed. Internally, modification is actually a retract and then an
+ insert; so it removes the fact from the <code>WorkingMemory</code> and then
+ inserts it again. You must use the <code>update</code> method to notify the
+ <code>WorkingMemory</code> of changed objects for those objects that are
+ not able to notify the <code>WorkingMemory</code> themselves.
+ Notice that <code>update</code> always takes the modified object as a second
+ parameter, which allows you to specify new instances for immutable
+ objects. The <code>update</code> method can only be used with objects that have
shadow proxies turned on. If you do not use shadow proxies then you must
- call <code>session.modifyRetract()</code> before making your changes and
- <code>session.modifyInsert()</code> after the changes.</para>
+ call <code>wm.modifyRetract()</code> before making your changes and
+ <code>wm.modifyInsert()</code> after the changes.</para>
<programlisting>Cheese stilton = new Cheese("stilton");
FactHandle stiltonHandle = workingMemory.insert( stilton );
@@ -429,18 +432,18 @@
<title>Globals</title>
<para>Globals are named objects that can be passed in to the rule
- engine; without needing to insert them. Most often these are used for
- static information, or services that are used in the RHS of a rule, or
- perhaps a means to return objects from the rule engine. If you use a
+ engine, without needing to insert them. Most often these are used for
+ static information, or for services that are used in the RHS of a rule, or
+ perhaps as a means to return objects from the rule engine. If you use a
global on the LHS of a rule, make sure it is immutable. A global must
- first be declared in the drl before it can be set on the session.</para>
+ first be declared in a rules file before it can be set on the session.</para>
<programlisting>global java.util.List list</programlisting>
- <para>With the Rule Base now aware of the global identifier and its type
- any sessions are now able to call <code>session.setGlobal</code>; failure to declare
+ <para>With the Rule Base now aware of the global identifier and its type,
+ it is now possible to call <code>session.setGlobal</code> for any session. Failure to declare
the global type and identifier first will result in an exception being
- thrown. To set the global on the session use <code>session.setGlobal(identifier, value)</code>;</para>
+ thrown. To set the global on the session use <code>session.setGlobal(identifier, value)</code>:</para>
<programlisting>List list = new ArrayList();
session.setGlobal("list", list); </programlisting>
@@ -453,13 +456,13 @@
<title>Shadow Facts</title>
<para>A shadow fact is a shallow copy of an asserted object. Shadow
- facts are cached copies of object asserted to the working memory. The
- term shadow facts is commonly known as a feature of JESS (Java Expert
+ facts are cached copies of objects asserted to the working memory. The
+ term "shadow fact" is commonly known as a feature of JESS (Java Expert
System Shell).</para>
- <para>The origins of shadow facts traces back to the concept of truth
+ <para>The origin of shadow facts traces back to the concept of truth
maintenance. The basic idea is that an expert system should guarantee
- the derived conclusions are accurate. A running system may alter a fact
+ that the derived conclusions are accurate. A running system may alter a fact
during evaluation. When this occurs, the rule engine must know a
modification occurred and handle the change appropriately. There's
generally two ways to guarantee truthfulness. The first is to lock all
@@ -469,9 +472,9 @@
Shadow facts are particularly important in multi-threaded environments,
where an engine is shared by multiple sessions. Without truth
maintenance, a system has a difficult time proving the results are
- accurate. The primary benefit of shadow facts is it makes development
+ accurate. The primary benefit of shadow facts is that they make development
easier. When developers are forced to keep track of fact modifications,
- it can lead to errors, which are difficult to debug. Building a
+ it can lead to errors which are difficult to debug. Building a
moderately complex system using a rule engine is hard enough without
adding the burden of tracking changes to facts and when they should
notify the rule engine.</para>
@@ -482,14 +485,14 @@
<important><para>Since Drools
implements Shadow Facts as Proxies, the fact classes must <emphasis>either be immutable</emphasis> or <emphasis>should not be final</emphasis>, nor have final methods. If a
- fact class is final or have final methods and is still a mutable class,
- the engine is not able to create a proper shadow fact for it and results
+ fact class is final or has final methods and is still a mutable class,
+ the engine is not able to create a proper shadow fact for it which results
in unpredictable behavior.</para></important>
- <para>Although shadow facts are a great way of ensuring the engine
- integrity, they add some overhead to the the reasoning process. As so,
- Drools 4.0 supports fine grained control over them with the ability to
- enable/disable them for each individual class. </para>
+ <para>Although shadow facts are a great way of ensuring the engine's
+ integrity, they add some overhead to the the reasoning process. Therefore,
+ Drools 4.0 supports fine-grained control over them with the ability to
+ enable or disable them for each individual class. </para>
<section>
<title>When is it possible to disable Shadow Facts?</title>
@@ -499,19 +502,19 @@
<orderedlist>
- <listitem><para><emphasis role="bold">Immutable classes are safe:</emphasis>
- if a class is immutable it does not require shadow facts. Just to
+ <listitem><para><emphasis role="bold">Immutable classes are safe.</emphasis>
+ If a class is immutable it does not require shadow facts. Just to
clarify, a class is immutable from the engine perspective if once an
instance is asserted into the working memory, no attribute will change
until it is retracted.</para></listitem>
<listitem><para><emphasis role="bold">Inside your rules, attributes are only
- changed using modify() blocks:</emphasis> both Drools dialects (MVEL
+ changed using modify() blocks.</emphasis> Both Drools dialects (MVEL
and Java) have the modify block construct. If all attribute value
changes for a given class happen inside modify() blocks, you can
disable shadow facts for that class.
<example>
- <title>Example: modify() block using Java dialect</title>
+ <title>modify() block using Java dialect</title>
<programlisting>rule "Eat Cheese"
when
@@ -527,7 +530,7 @@
</example>
<example>
- <title>Example: modify() block using MVEL dialect</title>
+ <title>modify() block using MVEL dialect</title>
<programlisting>rule "Eat Cheese"
dialect "mvel"
@@ -544,10 +547,10 @@
</example></para></listitem>
<listitem><para><emphasis role="bold">In your application, attributes are
only changed between calls to modifyRetract() and
- modifyInsert():</emphasis> this way, the engine becomes aware that
+ modifyInsert().</emphasis> This way, the engine becomes aware that
attributes will be changed and can prepare itself for them.
<example>
- <title>Example: safely modifying attributes in the application
+ <title>Safely modifying attributes in the application
code</title>
<programlisting> // create session
StatefulSession session = ruleBase.newStatefulSession();
@@ -573,14 +576,14 @@
</section>
<section>
- <title>How to disable Shadow Facts?</title>
+ <title>How to disable Shadow Facts</title>
- <para>To disable shadow fact for all classes set the following
+ <para>To disable shadow facts for all classes set the following
property in a configuration file of system property:</para>
<programlisting>drools.shadowProxy = false</programlisting>
- <para>Alternatively, it is possible to disable through an API
+ <para>Alternatively, it is possible to disable shadow facts through an API
call:</para>
<programlisting>RuleBaseConfiguration conf = new RuleBaseConfiguration();
@@ -605,17 +608,18 @@
<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).
- There are proxy libraries that can help automate this (a future version
- of Drools will bundle some to make it easier). To use the Object in
+ and behave accordingly, without you having to tell it that the fact is modified.
+ There are proxy libraries that can help automate this. (A future version
+ of Drools will bundle some to make it easier.) To use an object in
dynamic mode specify true for the second assertObject parameter.</para>
<programlisting>Cheese stilton = new Cheese("stilton");
FactHandle stiltonHandle = workingMemory.insert( stilton, true ); //specifies that this is a dynamic fact </programlisting>
<para>To make a JavaBean dynamic add a <code>PropertyChangeSupport</code> field
- memory along with two add/remove mothods and make sure that each setter
- notifies the <code>PropertyChangeSupport</code> instance of the change.</para>
+ along with an add and a remove method, and make sure that each setter
+ calls the <code>PropertyChangeSupport</code> instance with
+ <code>firePropertyChange</code>.</para>
<programlisting>private final PropertyChangeSupport changes = new PropertyChangeSupport( this );
...
@@ -647,12 +651,12 @@
<para>On the first working memory action (<code>assert</code>, <code>fireAllRules</code>) 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 <code>from</code> to pull data from an
- external source). For instance, if a new working memory is created, and
+ RETE network. This lets you write rules that have an empty LHS, or do not use
+ normal facts, such as rules that use <code>from</code> to pull data from an
+ external source. For instance, if a new working memory is created, and
no facts are asserted, calling the <code>fireAllRules</code> will cause the Initial
- Fact to propagate, possibly activating rules (otherwise, nothing would
- happen as there is no other fact to start with).</para>
+ Fact to propagate, possibly activating rules. If there were not even an
+ initial fact, nothing at all would happen.</para>
</section>
</section>
@@ -670,10 +674,10 @@
</figure>
<para>The <code>StatefulSession</code> extends the <code>WorkingMemory</code> class. It simply adds
- async methods and a <code>dispose()</code> method. The <code>ruleBase</code> retains a reference to
+ async methods and a <code>dispose()</code> method. The <code>RuleBase</code> retains a reference to
each <code>StatefulSession</code> it creates, so that it can update them when new rules
- are added, <code>dispose()</code> is needed to release the <code>StatefulSession</code> reference
- from the <code>RuleBase</code>, without it you can get memory leaks.</para>
+ are added. Thus, <code>dispose()</code> is needed to release the <code>StatefulSession</code> reference
+ from the <code>RuleBase</code>, because without it you can get memory leaks.</para>
<example>
<title>Createing a <code>StatefulSession</code></title>
@@ -695,38 +699,41 @@
</figure>
<para>The <code>StatelessSession</code> wraps the <code>WorkingMemory</code>, instead of extending
- it, its main focus is on decision service type scenarios.</para>
+ it. Its main focus is on decision service type scenarios.</para>
<example>
- <title>Createing a <code>StatelessSession</code></title>
+ <title>Creating a <code>StatelessSession</code></title>
<programlisting>StatelessSession session = ruleBase.newStatelessSession();
session.execute( new Cheese( "cheddar" ) );</programlisting>
</example>
- <para>The API is reduced for the problem domain and is thus much simpler;
- which in turn can make maintenance of those services easier. The <code>RuleBase</code>
+ <para>The API is reduced to the problem domain and is thus much simpler.
+ This, in turn, can make maintenance of those services easier. The <code>RuleBase</code>
never retains a reference to the <code>StatelessSession</code>, thus <code>dispose()</code> is not
- needed, and they only have an <code>execute()</code> method that takes an object, an
- array of objects or a collection of objects - there is no <code>insert</code> or
- <code>fireAllRules</code>. The execute method iterates the objects inserting each and
- calling <code>fireAllRules()</code> at the end; session finished. Should the session
- need access to any results information they can use the <code>executeWithResults</code>
+ needed. The class only has an overloaded set of <code>execute()</code>
+ methods, accepting either a single object, an array of objects or a
+ collection of objects, but there are no <code>insert</code> and
+ <code>fireAllRules</code> methods. The <code>execute()</code> method
+ iterates over the objects, inserting each into the
+ <code>WorkingMemory</code>, and calls <code>fireAllRules()</code> at the
+ end, after which the session is finished. Should the session
+ need access to any result information you can use the <code>executeWithResults</code>
method, which returns a <code>StatelessSessionResult</code>. The reason for this is in
- remoting situations you do not always want the return payload, so this way
- it's optional.</para>
+ remote situations where you do not always want the return payload, so this way
+ it is optional.</para>
<para><code>setAgendaFilter</code>, <code>setGlobal</code> and <code>setGlobalResolver</code> share their state
across sessions; so each call to <code>execute()</code> will use the set <code>AgendaFilter</code>,
- or see any previous set globals etc.</para>
+ see any previously set globals, etc.</para>
<para><code>StatelessSession</code>s do not currently support
<code>PropertyChangeListener</code>s.</para>
- <para>Async versions of the <code>Execute</code> method are supported, remember to
+ <para>Async versions of the <code>execute</code> method are supported. Remember to
override the <code>ExecutorService</code> implementation when in special managed thread
environments such as JEE.</para>
- <para><code>StatelessSession</code>s also support sequential mode, which is a special
+ <para><code>StatelessSession</code>s also supports sequential mode, which is a special
optimized mode that uses less memory and executes faster; please see the
<link xlink:href="#sequential">Sequential</link> section for more details.</para>
@@ -742,22 +749,24 @@
</mediaobject>
</figure>
- <para><code>StatelessSession.executeWithResults(....)</code> returns a minimal API to
- examine the session's data. The inserted Objects can be iterated over,
- queries can be executed and globals retrieved. Once the
+ <para><code>StatelessSession.executeWithResults()</code> returns an
+ object from a class providing a minimal API to
+ examine the session's data. You may iterate over inserted objects,
+ execute queries and retrieve globals. Once the
<code>StatelessSessionResult</code> is serialized it loses the reference to the
underlying <code>WorkingMemory</code> and <code>RuleBase</code>, so queries can no longer be
- executed, however globals can still be retrieved and objects iterated. To
+ executed; it is, however, still possible to retrieve globals and ti
+ iterate over objects. To
retrieve globals they must be exported from the <code>StatelessSession</code>; the
<code>GlobalExporter</code> strategy is set with <code>StatelessSession.setGlobalExporter(
GlobalExporter globalExporter )</code>. Two implementations of <code>GlobalExporter</code> are
- available and users may implement their own strategies.
+ available, and users may implement their own strategies.
<code>CopyIdentifiersGlobalExporter</code> copies named identifiers into a new
- <code>GlobalResovler</code> that is passed to the <code>StatelessSessionResult</code>; the
- constructor takes a <code>String[]</code> array of identifiers, if no identifiers are
+ <code>GlobalResolver</code> that is passed to the <code>StatelessSessionResult</code>; its
+ constructor takes a <code>String</code> array of identifiers, but if no identifiers are
specified it copies all identifiers declared in the <code>RuleBase</code>.
<code>ReferenceOriginalGlobalExporter</code> just passes a reference to the original
- <code>GlobalResolver</code>; the latter should be used with care as identifier
+ <code>GlobalResolver</code>. The latter should be used with care as identifier
instances can be changed at any time by the <code>StatelessSession</code> and the
<code>GlobalResolver</code> may not be serializable-friendly.</para>
@@ -775,7 +784,7 @@
<title>Agenda</title>
<figure>
- <title>Two Phase Execution</title>
+ <title>Agenda</title>
<mediaobject>
<imageobject>
@@ -784,29 +793,29 @@
</mediaobject>
</figure>
- <para>The Agenda is a RETE feature. During a Working Memory Action rules
+ <para>The Agenda is a RETE feature. During actions on the <code>WorkingMemory</code>,
+ rules
may become fully matched and eligible for execution; a single Working
Memory Action can result in multiple eligible rules. When a rule is fully
- matched an Activation is created, referencing the Rule and the matched
+ 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>
- <para>The engine operates in a "2 phase" mode which is recursive:</para>
+ <para>The engine cycles repeatedly through two phases:</para>
<orderedlist>
<listitem>
- <para>Working Memory Actions - this is where most of the work takes
- place - in either the <code>Consequence</code> or the main Java application
- process. Once the <code>Consequence</code> has finished or the main Java
+ <para>Working Memory Actions. This is where most of the work takes
+ place, either in the <code>Consequence</code> (the RHS itself) or the main Java
+ application process. Once the <code>Consequence</code> has finished or the main Java
application process calls <code>fireAllRules()</code> 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 found rule,
- switching the phase back to Working Memory Actions and the process
- repeats again until the Agenda is empty.</para>
+ <para>Agenda Evaluation. This attempts to select a rule to fire. If no rule
+ is found it exits, otherwise it fires the found rule,
+ switching the phase back to Working Memory Actions.</para>
</listitem>
</orderedlist>
@@ -820,7 +829,7 @@
</mediaobject>
</figure>
- <para>The process recurses until the agenda is clear, in which case
+ <para>The process repeats until the agenda is clear, in which case
control returns to the calling application. When Working Memory Actions
are taking place, no rules are being fired.</para>
@@ -838,19 +847,19 @@
<para>The most visible one is "salience" or priority, in which case a
user can specify that a certain rule has a higher priority (by giving it
- a higher number) than other rules. In that case, the higher salience
- rule will always be preferred. LIFO priorities are based on the assigned
- Working Memory Action counter value, multiple rules created from the
- same action have the same value - execution of these are considered
- arbitrary.</para>
+ a higher number) than other rules. In that case, the rule with higher salience
+ will be preferred. LIFO priorities are based on the assigned
+ Working Memory Action counter value, with all rules created during the
+ same action receiving the same value. The execution order of a set
+ of firings with the same priority value is arbitrary.</para>
<para>As a general rule, it is a good idea not to count on the rules
- firing in any particular order, and try and author the rules without
+ firing in any particular order, and to author the rules without
worrying about a "flow".</para>
<para>Custom conflict resolution strategies can be specified by setting
the Class in the <code>RuleBaseConfiguration</code> method <code>setConflictResolver</code>, or
- using the property <code>drools.conflictResolver</code>.</para>
+ by using the property <code>drools.conflictResolver</code>.</para>
</section>
<section>
@@ -858,23 +867,24 @@
<para>Agenda groups are a way to partition rules (activations, actually)
on the agenda. At any one time, only one group has "focus" which means
- that the activations for rules in that group will only take effect - you
- can also have rules "auto focus" which means the focus for its agenda
- group is taken when that rules conditions are true.</para>
+ that activations for rules in that group only will take effect. You
+ can also have rules with "auto focus" which means that the focus is
+ taken for its agenda group when that rule's conditions are true.</para>
- <para>They are sometimes known as "modules" in CLIPS terminology. Agenda
- groups are a handy way to create a "flow" between grouped rules. You can
+ <para>Agenda groups are known as "modules" in CLIPS terminology. They
+ provide a handy way to create a "flow" between grouped rules. You can
switch the group which has focus either from within the rule engine, or
- from the API. If your rules have a clear need for multiple "phases" or
+ via the API. If your rules have a clear need for multiple "phases" or
"sequences" of processing, consider using agenda-groups for this
purpose.</para>
- <para>Each time <code>setFocus(...)</code> is called it pushes that Agenda Group onto
- a stack, when the focus group is empty it is popped off and the next one
- on the stack evaluates. An Agenda Group can appear in multiple locations
- on the stack. The default Agenda Group is "MAIN", all rules which do not
- specify an Agenda Group are placed there, it is also always the first
- group on the Stack and given focus as default.</para>
+ <para>Each time <code>setFocus()</code> is called it pushes that Agenda Group onto
+ a stack. When the focus group is empty it is popped from the stack and the
+ focus group that is now on top evaluates. An Agenda Group can
+ appear in multiple locations
+ on the stack. The default Agenda Group is "MAIN", with all rules which do not
+ specify an Agenda Group being in this group. It is also always the first
+ group on the stack, given focus initially, by default.</para>
</section>
<section>
@@ -890,9 +900,11 @@
</figure>
<para>Filters are optional implementations of the filter interface
- which are used to allow/or deny an activation from firing (what you
- filter on, is entirely up to the implementation). Drools provides the
- following convenience default implementations</para>
+ which are used to allow or deny the firing of an activation. What you
+ filter on is entirely up to the implementation. Drools provides the
+ following convenience default implementations, all of which may be
+ used for allowing and denying. By default, they accept rules where
+ the name, or part of it, matches the first constructor parameter.</para>
<itemizedlist>
<listitem>
@@ -913,7 +925,8 @@
</itemizedlist>
<para>To use a filter specify it while calling <code>FireAllRules</code>. The
- following example will only allow activation of rules ending with the test <emphasis>Test</emphasis>. All others will be filtered out:
+ following example permits only rules ending in the string <emphasis>Test</emphasis>.
+ All others will be filtered out.
<programlisting>workingMemory.fireAllRules( new RuleNameEndsWithAgendaFilter( "Test" ) );</programlisting></para>
</section>
</section>
@@ -923,31 +936,39 @@
<primary>Logical Object</primary>
</indexterm> Logical Objects</title>
- <para>In a regular insert, you need to explicitly retract a fact. With
- logical assertions, the fact that was asserted will be automatically
+ <para>After regular inserts you have to retract facts explicitly. With
+ <emphasis>logical</emphasis> assertions, the fact that was asserted will
+ be automatically
retracted when the conditions that asserted it in the first place are no
- longer true. (It's actually more clever than that! If there are no possible
- conditions that could support the logical assertion, only then it will be
- retracted).</para>
+ longer true. Actually, it's even cleverer then that, because it will be
+ retracted only if there isn't any single condition that supports the
+ logical assertion.</para>
- <para>Normal insertions are said to be “STATED” (i.e. The Fact has been
- stated - just like the intuitive concept). Using a <code>HashMap</code> and a counter
- we track how many times a particular equality is STATED; this means we
- count how many different instances are equal. When we logically insert an
- object we are said to justify it and it is justified by the firing rule.
- For each logical insertion there can only be one equal object, each
+ <para>Normal insertions are said to be <emphasis>stated</emphasis>, i.e.,
+ just like the intuitive meaning of "stating a fact" implies. Using a
+ <code>HashMap</code> and a counter, we track how many times a particular
+ equality is <emphasis>stated</emphasis>; this means we count how many
+ different instances are equal.</para>
+
+ <para>When we <emphasis>logically</emphasis> insert an object during a
+ RHS execution we are said to <emphasis>justify</emphasis> it, and it is
+ considered to be justified by the firing rule. For each logical insertion
+ there can only be one equal object, and each
subsequent equal logical insertion 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>
+ this logical assertion. A justification is removed by the LHS of the
+ creating rule becoming untrue, and the counter is decreased accordingly.
+ As soon as we have no more justifications the logical object is
+ automatically retracted.</para>
- <para>If we logically insert an object when there is an equal STATED
- object it will fail and return null. If we STATE an object that has an
- existing equal object that is JUSTIFIED we override the Fact - how this
- override works depends on the configuration setting
+ <para>If we try to <emphasis>logically</emphasis> insert an object when
+ there is an equal <emphasis>stated</emphasis> object, this will fail and
+ return null. If we <emphasis>state</emphasis> an object that has an
+ existing equal object that is <emphasis>justified</emphasis> we override
+ the Fact; how this override works depends on the configuration setting
<code>WM_BEHAVIOR_PRESERVE</code>. When the property is set to discard we use the
- existing handle and replace the existing instance with the new Object -
- this is the default behavior - otherwise we override it to STATED but we
- create an new <code>FactHandle</code>.</para>
+ existing handle and replace the existing instance with the new Object,
+ which is the default behavior; otherwise we override it to
+ <emphasis>stated</emphasis> but we create an new <code>FactHandle</code>.</para>
<para>This can be confusing on a first read, so hopefully the flow charts
below help. When it says that it returns a new <code>FactHandle</code>, this also
@@ -977,31 +998,33 @@
<title>Example Scenario</title>
<para>An example may make things clearer. Imagine a credit card
- processing application, processing transactions for a given account (and
- we have a working memory accumulating knowledge about a single accounts
- transaction). The rule engine is doing its best to decide if
- transactions are possibly fraudulent or not. Imagine this rule base
+ processing application, processing transactions for a given account and
+ we have a working memory accumulating knowledge about a single account
+ transaction. The rule engine is doing its best to decide whether
+ transactions are possibly fraudulent or not. Imagine that this rule base
basically has rules that kick in when there is "reason to be 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
+ <para>Of course there are many rules that operate no matter what,
+ 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 theft.
+ 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>
<para>Then there can be a series of rules whose job is to look for
- things that may raise suspicion, and if they fire, they simply insert a
+ things that may raise suspicion, and if they fire, they
+ <emphasis>logically</emphasis> insert a
new SuspiciousAccount() instance. All the other rules just have
conditions like "not SuspiciousAccount()" or "SuspiciousAccount()"
depending on their needs. Note that this has the advantage of allowing
there to be many rules around raising suspicion, without touching the
- other rules. When the facts causing the SuspiciousAccount() insertion
- are removed, the rule engine reverts back to the normal "mode" of
- operation (and for instance, a rule with "not SuspiciousAccount()" may
- kick in which flushes through any interrupted transactions).</para>
+ other rules. After all the facts causing the SuspiciousAccount()
+ insertion are removed, the account handling reverts to a normal
+ mode of operation where, for instance, a rule with
+ "not SuspiciousAccount()" may kick in, which flushes through any
+ blocked transactions.</para>
<para>If you have followed this far, you will note that truth
maintenance, like logical assertions, allows rules to behave a little
@@ -1013,16 +1036,17 @@
<title>Important note: Equality for Java objects</title>
<para>It is important to note that for Truth Maintenance (and logical
- assertions) to work at all, your Fact objects (which may be Javabeans)
- override equals and hashCode methods (from java.lang.Object) correctly.
- As the truth maintenance system needs to know when 2 different physical
- objects are equal in value, BOTH equals and hashCode must be overridden
+ assertions) to work at all, your Fact objects (which may be JavaBeans)
+ must override equals and hashCode methods (from java.lang.Object) correctly.
+ As the truth maintenance system needs to know when two different physical
+ objects are equal in value,
+ <emphasis>both</emphasis> equals and hashCode must be overridden
correctly, as per the Java standard.</para>
<para>Two objects are equal if and only if their equals methods return
true for each other and if their hashCode methods return the same
- values. See the Java API for more details (but do keep in mind you MUST
- override both equals and hashCode).</para>
+ values. See the Java API for more details (but do keep in mind you
+ <emphasis>MUST</emphasis> override both equals and hashCode).</para>
</section>
</section>
@@ -1031,13 +1055,12 @@
<para>The event package provides means to be notified of rule engine
events, including rules firing, objects being asserted, etc. This allows
- you to separate out logging/auditing activities from the main part of your
- application (and the rules) - as events are a cross cutting
- concern.</para>
+ you, for instance, to separate logging and auditing activities from the
+ main part of your application (and the rules).</para>
- <para>There are three types of event listeners -
- WorkingMemoryEventListener, AgendaEventListener
- RuleFlowEventListener.</para>
+ <para><code>WorkingMemoryEventListener</code>,
+ <code>AgendaEventListener</code> and <code>RuleFlowEventListener</code>
+ represent the three types of event listeners:</para>
<figure>
<title>WorkingMemoryEventListener</title>
@@ -1062,7 +1085,7 @@
</figure>
<figure>
- <title>RuEventListener</title>
+ <title>RuleFlowEventListener</title>
<mediaobject>
<imageobject>
@@ -1086,12 +1109,14 @@
</figure>
<para>All EventListeners have default implementations that implement each
- method, but do nothing, these are convienience classes that you can
- inherit from to save having to implement each method -
- DefaultAgendaEventListener, DefaultWorkingMemoryEventListener,
- DefaultRuleFlowEventListener. The following shows how to extend
- DefaultAgendaEventListener and add it to the session - the example prints
- statements for only when rules are fired:</para>
+ method, but do nothing; these are convienience classes that you can
+ inherit from to avoid having to implement each method. The default classes
+ are <code>DefaultAgendaEventListener</code>,
+ <code>DefaultWorkingMemoryEventListener</code> and
+ <code>DefaultRuleFlowEventListener</code>. The following code snippet
+ shows how to extend <code>DefaultAgendaEventListener</code> and add an
+ instance to the session. It prints events resulting from rules being
+ fired.</para>
<programlisting>session.addEventListener( new DefaultAgendaEventListener() {
public void afterActivationFired(AfterActivationFiredEvent event) {
@@ -1100,9 +1125,11 @@
}
}); </programlisting>
- <para>Drools also provides DebugWorkingMemoryEventListener,
- DebugAgendaEventListener and DebugRuleFlowEventListener that implements
- each method with a debug print statement:</para>
+ <para>Drools also provides <code>DebugWorkingMemoryEventListener</code>,
+ <code>DebugAgendaEventListener</code> and
+ <code>DebugRuleFlowEventListener</code> which implement
+ each method with a debug print statement. To print all Working
+ Memory events, you add a listener like this:</para>
<programlisting>session.addEventListener( new DebugWorkingMemoryEventListener() ); </programlisting>
@@ -1115,16 +1142,17 @@
<title><link linkend="sequential">Sequential Mode</link></title>
<para>With Rete you have a stateful session where objects can be asserted
- and modified over time, rules can also be added and removed. Now what
+ and modified over time, and where rules can also be added and removed.
+ Now what
happens if we assume a stateless session, where after the initial data set
- no more data can be asserted or modified (no rule re-evaluations) and
- rules cannot be added or removed? This means we can start to make
- assumptions to minimize what work the engine has to do.</para>
+ no more data can be asserted or modified and rules cannot be added or
+ removed? Certainly it won't be necessary to re-evaluate rules,
+ and the engine will be able to operate in a simplified way.</para>
<orderedlist>
<listitem>
- <para>Order the Rules by salience and position in the ruleset (just
- sets a sequence attribute on the rule terminal node). 4</para>
+ <para>Order the Rules by salience and position in the ruleset (by
+ setting a sequence attribute on the rule terminal node).</para>
</listitem>
<listitem>
@@ -1138,14 +1166,14 @@
</listitem>
<listitem>
- <para>Disconnect the LeftInputAdapterNode propagation, and have the
- Object plus the Node referenced in a Command object, which is added to
+ <para>Disconnect the LeftInputAdapterNode propagation, and let the
+ Object plus the Node be referenced in a Command object, which is added to
a list on the WorkingMemory for later execution.</para>
</listitem>
<listitem>
- <para>Assert all objects, when all assertions are finished and thus
- right-input node memories are populated check the Command list and
+ <para>Assert all objects, and, when all assertions are finished and thus
+ right-input node memories are populated, check the Command list and
execute each in turn.</para>
</listitem>
@@ -1175,9 +1203,9 @@
a right-input propagation will never need to attempt a join with the
left-inputs (removing the need for left-input memory). All nodes have
their memory turned off, including the left-input Tuple memory but
- excluding the right-input Object memory – i.e. The only node that
- remembers an insertion propagation is the right-input Object memory. Once
- all the assertions are finished, and all right-input memories populated,
+ excluding the right-input Object memory, which means that the only node
+ remembering an insertion propagation is the right-input Object memory. Once
+ all the assertions are finished and all right-input memories populated,
we can then iterate the list of LeftInputAdatperNode Command objects
calling each in turn; they will propagate down the network attempting to
join with the right-input objects; not being remembered in the left input,
@@ -1190,12 +1218,13 @@
array to place the Activation. Once all Command Objects have finished we
can iterate our array checking each element in turn and firing the
Activations if they exist. To improve performance in the array we remember
- record the first and last populated cells. The network is constructed
+ the first and last populated cells. The network is constructed
where each RuleTerminalNode is given a sequence number, based on a
salience number and its order of being added to the network.</para>
<para>Typically the right-input node memories are HashMaps, for fast
- Object retraction, as we know there will be no Object retractions, we can
+ Object retraction; here, as we know there will be no Object retractions,
+ we can
use a list when the values of the Object are not indexed. For larger
numbers of Objects indexed HashMaps provide a performance increase; if we
know an Object type has a low number of instances then indexing is
@@ -1204,8 +1233,8 @@
<para>Sequential mode can only be used with a StatelessSession and is off
by default. To turn on either set the RuleBaseConfiguration.setSequential
to true or set the rulebase.conf property drools.sequential to true.
- Sequential mode can fallback to a dynamic agenda with setSequentialAgenda
- to either SequentialAgenda.SEQUENTIAL or SequentialAgenda.DYNAMIC setter
- or the "drools.sequential.agenda" property</para>
+ Sequential mode can fall back to a dynamic agenda with setSequentialAgenda
+ to either SequentialAgenda.SEQUENTIAL or SequentialAgenda.DYNAMIC
+ set by a call or via the "drools.sequential.agenda" property.</para>
</section>
</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-What_is_a_Rule_Engine.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-What_is_a_Rule_Engine.xml 2009-03-29 20:59:36 UTC (rev 25875)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-What_is_a_Rule_Engine.xml 2009-03-30 00:43:14 UTC (rev 25876)
@@ -17,26 +17,26 @@
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
+ 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 Systems
- and are considered 'applied artificial intelligence'. The process of
+ and are considered to be "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-as early Expert Systems had
- their logic hard coded, "shells" separated the logic from the system,
+ MYCIN medical diagnosis Expert System. Whereas 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 approach to implement an Expert System
+ Engine that uses the rule-based approach to implement an Expert System
and is more correctly classified as a Production Rule System.</para>
- <para>The term "Production Rule" originates from formal grammar - where it
+ <para>The term "Production Rule" originates from formal grammars 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"><citetitle>wikipedia</citetitle></ulink>).</para>
<para>Business Rule Management Systems build additional value on top of a
- general purpose Rule Engines by providing business user focused systems
+ general purpose Rule Engine 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
@@ -44,30 +44,30 @@
<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
+ outcomes. This includes simple systems like form validation and dynamic
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. 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
+ validate data entry. This, while a very valid and useful topic for some,
caused quite a surprise to this author, unaware at the time in the
- subtleties of Rules Engines differences, who was hoping to find some
+ subtleties of Rules Engines' differences, who was hoping to find some
hidden secrets to help 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
- dictates the transition to undertake - this is also a Rule Engine. While a
+ expressions and delegates in its Decision nodes which control the
+ transitions in a Workflow. At each node it evaluates ther is a rule set that
+ dictates the transition to undertake, and so this is also a Rule Engine. While a
Production Rule System is a kind of Rule Engine and also an Expert System,
the validation and expression evaluation Rule Engines mentioned previously
are not Expert Systems.</para>
- <para>A Production Rule System is Turing complete with a focus on
+ <para>A Production Rule System is Turing complete, with a focus on
knowledge representation to express propositional and first order logic in
a concise, non-ambiguous 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 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>
+ structure using First Order Logic for reasoning over knowledge representation.</para>
<programlisting role="JAVA"><![CDATA[when
<conditions>
@@ -102,16 +102,16 @@
<para>Drools implements and extends the <indexterm>
<primary>Rete</primary>
- </indexterm> Rete algorithm, <indexterm>
+ </indexterm> Rete algorithm;<indexterm>
<primary>Leaps</primary>
</indexterm> Leaps used to be provided but was retired as it became unmaintained. The Drools <indexterm>
<primary>Rete</primary>
</indexterm> Rete implementation is called ReteOO, signifying that
Drools has an enhanced and optimized implementation of the Rete algorithm
- for Object Oriented systems. Other Rete based engines also have marketing
+ 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
+ marketing oriented where, unlike the original published Rete Algorithm, no details
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)"
@@ -120,12 +120,12 @@
<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>
+ matches against are kept in the <indexterm>
<primary>WorkingMemory</primary>
</indexterm> Working Memory. Facts are asserted into the Working Memory
where they may then be modified 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
+ assertion; these rules are said to be in conflict. The Agenda manages the
execution order of these conflicting rules using a Conflict Resolution
strategy.</para>
@@ -139,9 +139,9 @@
</figure>
<para>A Production Rule System's Inference Engine is stateful and able to
- enforce truthfulness - called Truth Maintenance. A logical relationship can
+ enforce truthfulness, which is called Truth Maintenance. A logical relationship can
be declared by actions which means the action's state depends on the
- inference remaining true; when it is no longer true the logical dependent
+ inference remaining true; when it is no longer true the logically dependent
action is undone. The "Honest Politician" is an example of Truth
Maintenance, which always ensures that hope can only exist for a
democracy while we have honest politicians.</para>
@@ -163,14 +163,14 @@
print "Democracy is Doomed"
</programlisting>
- <para>There are two methods of execution for a Production Rule Systems -
+ <para>There are two methods of execution for a Production Rule Systems:
Forward Chaining and Backward Chaining; systems that implement both are
called Hybrid Production Rule Systems. Understanding these two modes of
- operation are key to understanding why a Production Rule System is
- different and how to get the best from them. Forward chaining is
- 'data-driven' and thus reactionary - facts are asserted into the working
- memory which results in one or more rules being concurrently true and
- scheduled for execution by the Agenda - we start with a fact, it
+ operation is the key to understanding why a Production Rule System is
+ different and how to get the best from it. Forward chaining is
+ "data-driven" and thus reactionary, with facts being asserted into working
+ memory, which results in one or more rules being concurrently true and
+ scheduled for execution by the Agenda. In short, we start with a fact, it
propagates and we end in a conclusion. Drools is a forward chaining
engine.</para>
@@ -185,12 +185,12 @@
</mediaobject>
</figure>
- <para>Backward chaining is 'goal-driven', meaning that we start with a
+ <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 be adding
+ for conclusions that it can satisfy; these are known as subgoals, 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 subgoals.
+ Prolog is an example of a Backward Chaining engine; Drools will provide
support for Backward Chaining in its next major release.</para>
<figure>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-Why_use_a_Rule_Engine.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-Why_use_a_Rule_Engine.xml 2009-03-29 20:59:36 UTC (rev 25875)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-Why_use_a_Rule_Engine.xml 2009-03-30 00:43:14 UTC (rev 25876)
@@ -16,7 +16,7 @@
</listitem>
<listitem>
- <para>What advantage does a rules engine have over hand coded
+ <para>What advantage does a rule engine have over hand coded
"if...then" approaches?</para>
</listitem>
@@ -37,13 +37,13 @@
<listitem>
<para>Declarative Programming</para>
- <para>Rule engines allow you to say "What to do" not "How to do
+ <para>Rule engines allow you to say "What to do", not "How to do
it".</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>
+ those solutions verified. Rules are much easier to read than
+ code.</para>
<para>Rule systems are capable of solving very, very hard problems,
providing an explanation of how the solution was arrived at and why
@@ -69,11 +69,11 @@
<listitem>
<para>Speed and Scalability</para>
- <para>The Rete algorithm, Leaps algorithm, and its descendants such as
- Drools' ReteOO (and Leaps), provide very efficient ways of matching
+ <para>The Rete algorithm,the Leaps algorithm, and their descendants such as
+ Drools' ReteOO, provide very efficient ways of matching
rule patterns to your domain object data. These are especially
- efficient when you have datasets that do not change entirely (as the
- rule engine can remember past matches). These algorithms are battle
+ efficient when you have datasets that change in small portions as the
+ rule engine can remember past matches. These algorithms are battle
proven.</para>
</listitem>
@@ -81,15 +81,16 @@
<para>Centralization of Knowledge</para>
<para>By using rules, you create a repository of knowledge (a
- knowledgebase) which is executable. This means it's a single point of
- truth, for business policy (for instance) - ideally rules are so
+ knowledge base) which is executable. This means it's a single point of
+ truth, for business policy, for instance. Ideally rules are so
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 user interfaces)
+ provide
ways to edit and manage rules and get immediate feedback, validation
and content assistance. Auditing and debugging tools are also
available.</para>
@@ -110,9 +111,9 @@
Languages that model your problem domain you can set yourself up to
write rules that are 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>
+ domain experts as they are expressed in their language, with all the
+ program plumbing, the technical know-how being hidden
+ away in the usual code.</para>
</listitem>
</itemizedlist>
</section>
@@ -128,24 +129,24 @@
<para>The problem is just too fiddle for traditional code.</para>
<para>The problem may not be complex, but you can't see a
- non-fragile way of building it.</para>
+ non-fragile way of building a solution for it.</para>
</listitem>
<listitem>
- <para>The problem is beyond any obvious algorithm based
+ <para>The problem is beyond any obvious algorithmic
solution.</para>
<para>It is a complex problem to solve, there are no obvious
- traditional solutions or basically the problem isn't fully
+ traditional solutions, or basically the problem isn't fully
understood.</para>
</listitem>
<listitem>
<para>The logic changes often</para>
- <para>The logic itself may be simple (but doesn't have to be) but
+ <para>The logic itself may even be simple but
the rules change quite often. In many organizations software
- releases are few and far between and rules can help provide the
+ releases are few and far between and pluggable rules can help provide the
"agility" that is needed and expected in a reasonably safe
way.</para>
</listitem>
@@ -154,15 +155,15 @@
<para>Domain experts (or business analysts) are readily available,
but are nontechnical.</para>
- <para>Domain experts are often a wealth of knowledge about business
+ <para>Domain experts often possess 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
+ of logical thinking. Many people in 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>
+ understood.</para>
</listitem>
</itemizedlist></para>
@@ -171,29 +172,31 @@
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
+ contain key parts of your business logic,
+ <emphasis>especially the really messy parts</emphasis>. 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", 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>
+ the application. If you ever notice lots of conditional statements
+ such as "if" and "switch", an
+ overabundance of strategy patterns and other messy logic in your code
+ that just doesn't feel right: that would be a place for rules.
+ If there is some such logic and you keep coming back to fix it, either
+ because you got it wrong, or the logic or your understanding changes: think
+ about using rules. If you are faced with tough problems for which there are
+ no algorithms or patterns: consider using rules.</para>
<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
+ service. Often a rule engine works best as "stateful" component, being
+ an integral part of an application. However, there have been
successful cases of creating reusable rule services which are
stateless.</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>
+ <para>For your organization it is important to decide 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.
+ Frequently, rules maintenance is out of the control of the application
+ vendors or project developers.</para>
</section>
<section>
@@ -212,11 +215,11 @@
<para>As rule engines are dynamic (dynamic in the sense that the rules can
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
+ 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
+ can consider data-driven designs (lookup tables), or script processing
engines where the scripts are managed in a database and are able to be
updated on the fly.</para>
</section>
@@ -227,23 +230,23 @@
<para>Hopefully the preceding sections have explained when you may want to
use a rule engine.</para>
- <para>Alternatives are script-based engines that provide the dynamicness
- for "changes on the fly" (there are many solutions here).</para>
+ <para>Alternatives are script-based engines that provide the drive
+ for "changes on the fly", and there are many such solutions.</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
+ process. Those steps can also involve decision points which are in
themselves a simple rule. Process engines and rules often can work nicely
- together, so it is not an either-or proposition.</para>
+ together, so they are not mutually exclusive.</para>
- <para>One key point to note with rule engines, is that some rule-engines
+ <para>One key point to note with rule engines is that some rule engines
are really scripting engines. The downside of scripting engines is that
- you are tightly coupling your application to the scripts (if they are
- rules, you are effectively calling rules directly) and this may cause more
+ you are tightly coupling your application to the scripts. If they are
+ rules, you are effectively calling rules directly and this may cause more
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>
+ time. The upside of scripting engines is that they can be easier to
+ implement initially, producing results quickly, and are conceptually
+ simpler for 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
@@ -262,16 +265,17 @@
"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
+ "firing" will clearly result in another rule firing, and so on; 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.
- [A Decision Tree may be in order]). This is not to say that strong or weak
+ strongly coupled, the chances are that the will turn out to be inflexible,
+ and, more significantly, that a rule engine is an overkill. A clear chain
+ can be hard coded, or implemented using a Decision Tree. This is not to
+ say that strong
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"
+ considering a rule engine and the way 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>
+ removed and added without requiring changes to other, unrelated
+ rules.</para>
</section>
</section>
More information about the jboss-svn-commits
mailing list