[jboss-svn-commits] JBL Code SVN: r26317 - labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Thu Apr 30 04:11:03 EDT 2009
Author: laune
Date: 2009-04-30 04:11:03 -0400 (Thu, 30 Apr 2009)
New Revision: 26317
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-ConwaysGameOfLifeExample.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-FibonacciExample.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-MannersExample.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-NumberGuessExample.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-PetStoreExample.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-StateExample.xml
Log:
improvements
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-ConwaysGameOfLifeExample.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-ConwaysGameOfLifeExample.xml 2009-04-30 06:08:07 UTC (rev 26316)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-ConwaysGameOfLifeExample.xml 2009-04-30 08:11:03 UTC (rev 26317)
@@ -6,45 +6,47 @@
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook" xml:base="../../">
- <title>Conways Game Of Life Example</title>
+ <title>Conway's Game Of Life</title>
- <programlisting><emphasis role="bold">Name:</emphasis> Conways Game Of Life
-<emphasis role="bold">Main class:</emphasis> org.drools.examples.conway.ConwayAgendaGroupRun org.drools.examples.conway.ConwayRuleFlowGroupRun
-<emphasis role="bold">Type:</emphasis> java application
+ <programlisting><emphasis role="bold">Name:</emphasis> Conway's Game Of Life
+<emphasis role="bold">Main class:</emphasis> org.drools.examples.conway.ConwayAgendaGroupRun
+ org.drools.examples.conway.ConwayRuleFlowGroupRun
+<emphasis role="bold">Type:</emphasis> Java application
<emphasis role="bold">Rules file:</emphasis> conway-ruleflow.drl conway-agendagroup.drl
<emphasis role="bold">Objective:</emphasis> Demonstrates 'accumulate', 'collect' and 'from'</programlisting>
- <para>Conway's Game Of Life, <ulink
- url="http://en.wikipedia.org/wiki/Conway's_Game_of_Life">http://en.wikipedia.org/wiki/Conway's_Game_of_Life</ulink>
+ <para>Conway's Game Of Life, described in <ulink
+ url="http://en.wikipedia.org/wiki/Conway's_Game_of_Life">http://en.wikipedia.org/wiki/Conway's_Game_of_Life</ulink> and in
<ulink
url="http://www.math.com/students/wonders/life/life.html">http://www.math.com/students/wonders/life/life.html</ulink>,
- is a famous cellular automaton conceived in the early 1970's by
+ is a famous cellular automaton conceived in the early 1970's by the
mathematician John Conway. While the system is well known as "Conway's
Game Of Life", it really isn't a game at all. Conway's system is more like
- a life simulation. Don't be intimidated. The system is terribly simple and
- terribly interesting. Math and Computer Science students alike have
- marvelled over Conway's system for more than 30 years now. The application
- represented here is a Swing based implementation of Conway's Game of Life.
+ a simulation of a form of life. Don't be intimidated. The system
+ is terribly simple and terribly interesting. Math and Computer Science
+ students alike have marvelled over Conway's system for more than 30 years
+ now. The application
+ presented here is a Swing-based implementation of Conway's Game of Life.
The rules that govern the system are implemented as business rules using
Drools. This document will explain the rules that drive the simulation and
- discuss the Drools specific parts of the implementation.</para>
+ discuss the Drools parts of the implementation.</para>
- <para>We'll first introduce the grid view, shown below, to help
- visualisation of the problem; this is where the life simuation takes
- place. Initially the grid is empty, meaning that there are no live cells
- in the system; ech cell can be considered "LIVE" or "DEAD", live cells
- have a green ball in them. Pre-selected patterns of live cells can be
- selected from the "Pattern" drop down or cells can be doubled-clicked to
- toggle them between LIVE and DEAD. It's important to understand that each
- cell is related to it's neighbour cells, which is a core part of the
- game's rules and will be explained in a moment. Neighbors include not only
+ <para>We'll first introduce the grid view, shown below, designed for the
+ visualisation of the game, showing the "arena" where the life simuation
+ takes place. Initially the grid is empty, meaning that there are no live
+ cells in the system. Each cell is either alive or dead, with live cells
+ showing a green ball. Preselected patterns of live cells can be
+ chosen from the "Pattern" drop-down list. Alternatively, individual
+ cells can be doubled-clicked to toggle them between live and dead. It's
+ important to understand that each cell is related to its neighboring cells,
+ which is fundamental for the game's rules. Neighbors include not only
cells to the left, right, top and bottom but also cells that are connected
- diagonally. Each cell has a total of 8 neighbors except the 4 corner cells
- and all of the other cells along the 4 edges. Corner cells have 3
- neighbors and other edge cells have 5 neighbors.</para>
+ diagonally, so that each cell has a total of 8 neighbors. Exceptions
+ are the four corner cells which have only three neighbors, and the cells
+ along the four border, with five neighbors each.</para>
<figure>
- <title>Conways Example : Starting a new game</title>
+ <title>Conway's Game of Life: Starting a new game</title>
<mediaobject>
<imageobject>
@@ -54,48 +56,49 @@
</mediaobject>
</figure>
- <para>So what are the basic rules that govern this game? Each generation,
- i.e. completion iteration and evalution of all cells, the system evolves
- and cells may be born or killed, there are a very simple set of rules that
- govern what the next generation will look like.</para>
+ <para>So what are the basic rules that govern this game? Its goal is to
+ show the development of a population, generation by generation. Each
+ generation results from the preceding one, based on the simultaneous
+ evaluation of all cells. This is the simple set of rules that
+ govern what the next generation will look like:</para>
<itemizedlist>
<listitem>
<para>If a live cell has fewer than 2 live neighbors, it dies of
- loneliness</para>
+ loneliness.</para>
</listitem>
<listitem>
<para>If a live cell has more than 3 live neighbors, it dies from
- overcrowding</para>
+ overcrowding.</para>
</listitem>
<listitem>
<para>If a dead cell has exactly 3 live neighbors, it comes to
- life</para>
+ life.</para>
</listitem>
</itemizedlist>
<para>That is all there is to it. Any cell that doesn't meet any of those
criteria is left as is for the next generation. With those simple rules in
mind, go back and play with the system a little bit more and step through
- some generations one at a time and notice these rules taking their
+ some generations, one at a time, and notice these rules taking their
effect.</para>
- <para>The screnshot below shows an example generation, with a number of
+ <para>The screenshot below shows an example generation, with a number of
live cells. Don't worry about matching the exact patterns represented in
the screen shot. Just get some groups of cells added to the grid. Once you
have groups of live cells in the grid, or select a pre-designed pattern,
click the "Next Generation" button and notice what happens. Some of the
live cells are killed (the green ball disappears) and some dead cells come
- to life (a green ball appears). Cycle through several generations and see
+ to life (a green ball appears). Step through several generations and see
if you notice any patterns. If you click on the "Start" button, the system
will evolve itself so you don't need to click the "Next Generation" button
over and over. Play with the system a little and then come back here for
more details of how the application works.</para>
<figure>
- <title>Conways Example : A running game</title>
+ <title>Conway's Game of Life: A running game</title>
<mediaobject>
<imageobject>
@@ -105,34 +108,35 @@
</mediaobject>
</figure>
- <para>Now lets delve into the code, as this is an advanced example we'll
- assume that by now you know your way around the Drools framework and able
- to connect many of the dots, so we'll just focus at a hgh level
- overview.The example has two ways to execute, one way uses AgendaGroups to
- manage execution flow the other uses RuleFlowGroups to manage execution
- flow - so it's a great way to see the differences. - that's
- ConwayAgendaGroupRun and ConwayRuleFlowGroupRun respectively. For this
- example I'll cover the ruleflow version, as its what most people will
+ <para>Now lets delve into the code. As this is an advanced example we'll
+ assume that by now you know your way around the Drools framework and are
+ able to connect the presented highlight, so that we'll just focus at a
+ high level overview. The example has two ways to execute, one way
+ uses Agenda Groups to manage execution flow, and the other one uses
+ Rule Flow Groups to manage execution flow. These two versions are
+ implemented in <code>ConwayAgendaGroupRun</code> and
+ <code>ConwayRuleFlowGroupRun</code>, respectively. Here,
+ we'll discuss the Rule Flow version, as it's what most people will
use.</para>
- <para>All the Cells are inserted into the session and the rules in the
- ruleflow-group "register neighbor" are allowed to execute by the ruleflow
- process. What this group of rules does is for each cell it registers the
- north east, north, north west and west cells using a Neighbor relation
- class, notice this relation is bi-drectional which is why we don't have to
- do any rules for southern facing cells. Note that the constraints make
- sure we stay one column back from the end and 1 row back from the top. By
- the time all activations have fired for these rules all cells are related
+ <para>All the <code>Cell</code> objects are inserted into the Session
+ and the rules in the <kw>ruleflow-group</kw> "register neighbor" are
+ allowed to execute by the Rule Flow process. This group of four rules
+ creates <code>Neighbor</code> relations between some cell and its
+ northeastern, northern, northwestern and western neighbors. This
+ relation is bidirectional, which takes care of the other four directions.
+ Border cells don't need any special treatment - they simply won't be
+ paired with neighboring cells where there isn't any. By
+ the time all activations have fired for these rules, all cells are related
to all their neighboring cells.</para>
<example>
- <title>Conways Example : Register all Cell Neighbour relations</title>
+ <title>Conway's Game of Life: Register Cell Neighbour relations</title>
<programlisting>rule "register north east"
ruleflow-group "register neighbor"
when
- CellGrid( $numberOfColumns : numberOfColumns )
- $cell: Cell( $row : row > 0, $col : col < ( $numberOfColumns - 1 ) )
+ $cell: Cell( $row : row, $col : col )
$northEast : Cell( row == ($row - 1), col == ( $col + 1 ) )
then
insert( new Neighbor( $cell, $northEast ) );
@@ -142,7 +146,7 @@
rule "register north"
ruleflow-group "register neighbor"
when
- $cell: Cell( $row : row > 0, $col : col )
+ $cell: Cell( $row : row, $col : col )
$north : Cell( row == ($row - 1), col == $col )
then
insert( new Neighbor( $cell, $north ) );
@@ -152,7 +156,7 @@
rule "register north west"
ruleflow-group "register neighbor"
when
- $cell: Cell( $row : row > 0, $col : col > 0 )
+ $cell: Cell( $row : row, $col : col )
$northWest : Cell( row == ($row - 1), col == ( $col - 1 ) )
then
insert( new Neighbor( $cell, $northWest ) );
@@ -162,7 +166,7 @@
rule "register west"
ruleflow-group "register neighbor"
when
- $cell: Cell( $row : row >= 0, $col : col > 0 )
+ $cell: Cell( $row : row, $col : col )
$west : Cell( row == $row, col == ( $col - 1 ) )
then
insert( new Neighbor( $cell, $west ) );
@@ -170,14 +174,14 @@
end</programlisting>
</example>
- <para>Once all the cells are inserted some java code applies the pattern
- to the grid setting certain cells to Live. Then when the user clicks
- "start" or "next generation" it executes the "Generation" ruleflow. This
+ <para>Once all the cells are inserted, some Java code applies the pattern
+ to the grid, setting certain cells to Live. Then, when the user clicks
+ "Start" or "Next Generation", it executes the "Generation" ruleflow. This
ruleflow is responsible for the management of all changes of cells in each
generation cycle.</para>
<figure>
- <title>Conways Example : ruleflow "Generation"</title>
+ <title>Conway's Game of Life: rule flow "Generation"</title>
<mediaobject>
<imageobject>
@@ -186,31 +190,34 @@
</mediaobject>
</figure>
- <para>The ruleflow process first enters the "evaluate" group, this means
- any active rule in that group can fire. The rules in this group apply the
- main game of life rules discussed in the beginning of the example, where
- it determines what cells will be killed and which ones given life. We use
- the "phase" attribute to drives the reasoning of the Cell by specific
- groups of rules; typical the phase is tied to a RuleFlowGroup. in the
- ruleflow process definition. Notice that it doesn't actually change the
- state of any Cells at this point; this is because it's evaluating the Grid
- in turn and it must complete the full evaluation until those changes can
- be applied. To achieve this it sets the cell to a "phase" which is either
- Phase.KILL or Phase.BIRTH, which is used later to control actions applied
- to the Cell and when.</para>
+ <para>The rule flow process first enters the "evaluate" group, which means
+ that any active rule in the group can fire. The rules in this group apply
+ the Game-of-Life rules discussed in the beginning of the example,
+ determining the cells to be killed and the ones to be given life. We use
+ the "phase" attribute to drive the reasoning of the Cell by specific
+ groups of rules; typically the phase is tied to a Rule Flow Group in the
+ Rule Flow process definition. Notice that it doesn't actually change the
+ state of any <code>Cell</code> objectss at this point; this is because
+ it's evaluating the grid in turn and it must complete the full evaluation
+ until those changes can be applied. To achieve this, it sets the cell to
+ a "phase" which is either <code>Phase.KILL</code> or
+ <code>Phase.BIRTH</code>, used later to control actions applied
+ to the <code>Cell</code> object.</para>
<example>
- <title>Conways Example : Evaluate Cells with state changes</title>
+ <title>Conway's Game of Life: Evaluate Cells with state changes</title>
<programlisting>rule "Kill The Lonely"
ruleflow-group "evaluate"
no-loop
when
# A live cell has fewer than 2 live neighbors
- theCell: Cell(liveNeighbors < 2, cellState == CellState.LIVE, phase == Phase.EVALUATE)
+ theCell: Cell( liveNeighbors < 2, cellState == CellState.LIVE,
+ phase == Phase.EVALUATE )
then
- theCell.setPhase(Phase.KILL);
- update( theCell );
+ modify( theCell ){
+ setPhase( Phase.KILL );
+ }
end
rule "Kill The Overcrowded"
@@ -218,10 +225,12 @@
no-loop
when
# A live cell has more than 3 live neighbors
- theCell: Cell(liveNeighbors > 3, cellState == CellState.LIVE, phase == Phase.EVALUATE)
+ theCell: Cell( liveNeighbors > 3, cellState == CellState.LIVE,
+ phase == Phase.EVALUATE )
then
- theCell.setPhase(Phase.KILL);
- update( theCell );
+ modify( theCell ){
+ setPhase( Phase.KILL );
+ }
end
rule "Give Birth"
@@ -229,23 +238,26 @@
no-loop
when
# A dead cell has 3 live neighbors
- theCell: Cell(liveNeighbors == 3, cellState == CellState.DEAD, phase == Phase.EVALUATE)
+ theCell: Cell( liveNeighbors == 3, cellState == CellState.DEAD,
+ phase == Phase.EVALUATE )
then
- theCell.setPhase(Phase.BIRTH);
- update( theCell );
+ modify( theCell ){
+ theCell.setPhase( Phase.BIRTH );
+ }
end
</programlisting>
</example>
- <para>Once all Cells in the grid have been evaluated we first clear any
- calculation activations, that occured from any previous data changes, via
- the "reset calculate" rule, which clears any activations in the
- "calculate" group. We then enter a split which allows any activations in
- the "kill" groups and "birth" groups to fire, these rules are responsible
- for applying the state change.</para>
+ <para>Once all <code>Cell</code> objects in the grid have been evaluated,
+ we first clear any calculation activations that occured from any previous
+ data changes. This is done via the "reset calculate" rule, which clears
+ any activations in the "calculate" group. We then enter a split in the
+ rule flow which allows any activations in both the "kill" and the "birth"
+ group to fire. These rules are responsible for applying the state
+ change.</para>
<example>
- <title>Conways Example : Apply the state changes</title>
+ <title>Conway's Game of Life: Apply the state changes</title>
<programlisting>rule "reset calculate"
ruleflow-group "reset calculate"
@@ -259,65 +271,71 @@
ruleflow-group "kill"
no-loop
when
- theCell: Cell(phase == Phase.KILL)
+ theCell: Cell( phase == Phase.KILL )
then
- theCell.setCellState(CellState.DEAD);
- theCell.setPhase(Phase.DONE);
- update( theCell );
+ modify( theCell ){
+ setCellState( CellState.DEAD ),
+ setPhase( Phase.DONE );
+ }
end
rule "birth"
ruleflow-group "birth"
no-loop
when
- theCell: Cell(phase == Phase.BIRTH)
+ theCell: Cell( phase == Phase.BIRTH )
then
- theCell.setCellState(CellState.LIVE);
- theCell.setPhase(Phase.DONE);
- update( theCell );
+ modify( theCell ){
+ setCellState( CellState.LIVE ),
+ setPhase( Phase.DONE );
+ }
end </programlisting>
</example>
- <para>At this stage a number of Cells have been modified with the state
- changed to either LIVE or DEAD, this is where we get to see the power of
- the Neighbour cell and relational programming. When a cell becomes LIVE or
- DEAD we use the Neigbor relation drive the iteration over all surrounding
- Cells increasing or decreasing the LIVE neighbour count, any cell who has
- their count changed is also set to to the EVALUATE phase, to make sure
- they are reasoned over duing the evaluate stage of the ruleflow process.
- Notice that we don't have to do any iteration ourselves, by simpy applying
- the relations in the rules we can get the rule engine to do all the hard
- work for us in a minimal amount of code - very nice :) Once the live count
- for all Cells has been determiend and set the ruleflow process comes to
- and end; the user can either tell it to evaluate another generation, of if
- "start" was clicked the engine will start the ruleflow process
- again.</para>
+ <para>At this stage, a number of <code>Cell</code> objects have been
+ modified with the state changed to either <code>LIVE</code> or
+ <code>DEAD</code>. Now we get to see the power of the
+ <code>Neighbor</code> facts defining the cell relations. When a cell
+ becomes live or dead, we use the <code>Neighbor</code> relation to
+ iterate over all surrounding cells, increasing or decreasing the
+ <code>liveNeighbor</code> count. Any cell that has its count changed
+ is also set to to the <code>EVALUATE</code> phase, to make sure
+ it is included in the reasoning during the evaluation stage of the
+ Rule Flow Process. Notice that we don't have to do any iteration
+ ourselves; simply by applying the relations in the rules we make
+ the rule engine do all the hard work for us, with a minimal amount of
+ code. Once the live count has been determined and set for all cells,
+ the Rule Flow Process comes to and end. If the user has initially
+ clicked the "Start" button, the engine will restart the rule flow;
+ otherwise the user may request another generation.</para>
<example>
- <title>Conways Example : Evaluate Cells with state changes</title>
+ <title>Conway's Game of Life: Evaluate cells with state changes</title>
<programlisting>rule "Calculate Live"
ruleflow-group "calculate"
lock-on-active
when
- theCell: Cell(cellState == CellState.LIVE)
- Neighbor(cell == theCell, $neighbor : neighbor)
+ theCell: Cell( cellState == CellState.LIVE )
+ Neighbor( cell == theCell, $neighbor : neighbor )
then
- $neighbor.setLiveNeighbors( $neighbor.getLiveNeighbors() + 1 );
- $neighbor.setPhase( Phase.EVALUATE );
- update( $neighbor );
+ modify( $neighbor ){
+ setLiveNeighbors( $neighbor.getLiveNeighbors() + 1 ),
+ setPhase( Phase.EVALUATE );
+ }
end
rule "Calculate Dead"
ruleflow-group "calculate"
lock-on-active
when
- theCell: Cell(cellState == CellState.DEAD)
- Neighbor(cell == theCell, $neighbor : neighbor )
+ theCell: Cell( cellState == CellState.DEAD )
+ Neighbor( cell == theCell, $neighbor : neighbor )
then
- $neighbor.setLiveNeighbors( $neighbor.getLiveNeighbors() - 1 );
- $neighbor.setPhase( Phase.EVALUATE );
- update( $neighbor );
+ modify( $neighbor ){
+ setLiveNeighbors( $neighbor.getLiveNeighbors() - 1 ),
+ setPhase( Phase.EVALUATE );
+ }
end </programlisting>
</example>
</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-FibonacciExample.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-FibonacciExample.xml 2009-04-30 06:08:07 UTC (rev 26316)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-FibonacciExample.xml 2009-04-30 08:11:03 UTC (rev 26317)
@@ -63,7 +63,7 @@
"...snip..." indicating lines that were removed to save space):</para>
<example>
- <title>Fibonacci Example Console Output</title>
+ <title>Fibonacci Example: Console Output</title>
<programlisting>recurse for 50
recurse for 49
@@ -90,13 +90,14 @@
<para>To kick this off from Java we only insert a single Fibonacci
object, with a sequence field of 50. A recursive rule is then used
- to insert the other 49 Fibonacci objects. This example doesn't use
+ to insert the other 49 <code>Fibonacci</code> objects. This example
+ doesn't use
<code>PropertyChangeSupport</code>. It uses the MVEL dialect, which
means we can use the <kw>modify</kw> keyword, which allows a block
setter action which also notifies the engine of changes.</para>
<example>
- <title>Fibonacci Example Execution</title>
+ <title>Fibonacci Example: Execution</title>
<programlisting>ksession.insert( new Fibonacci( 50 ) );
ksession.fireAllRules();</programlisting>
@@ -110,11 +111,11 @@
does not exist, the rule re-matches and fires again. The
<kw>not</kw> conditional element is used to stop the rule's matching
once we have all 50 Fibonacci objects in memory. The rule also has a
- salience value, because we need to have all 50 Fibonacci objects
- asserted before we execute the Bootstrap rule.</para>
+ salience value, because we need to have all 50 <code>Fibonacci</code>
+ objects asserted before we execute the Bootstrap rule.</para>
<example>
- <title>Fibonacci Example : Rule "Recurse"</title>
+ <title>Fibonacci Example: Rule "Recurse"</title>
<programlisting>rule Recurse
salience 10
@@ -131,10 +132,10 @@
<code>Fibonacci</code> object with a sequence field of 50, done from
Java code. From there on, the Audit view shows the continual
recursion of the rule, where each asserted <code>Fibonacci</code>
- object causes the Recurse rule to become activate and fire again.</para>
+ object causes the Recurse rule to become activated and to fire again.</para>
<figure>
- <title>Fibonacci Example "Recurse" Audit View 1</title>
+ <title>Fibonacci Example: "Recurse" Audit View 1</title>
<mediaobject>
<imageobject>
@@ -150,7 +151,7 @@
<code>sequence</code>, testing for equality with 1 or 2.</para>
<example>
- <title>Fibonacci Example : Rule "Bootstrap"</title>
+ <title>Fibonacci Example: Rule "Bootstrap"</title>
<programlisting>rule Bootstrap
when
@@ -162,11 +163,11 @@
</example>
<para>At this point the Agenda looks as shown below. However,
- the Bootstrap rule does not fire because the Recurse rule has a higher
+ the "Bootstrap" rule does not fire because the "Recurse" rule has a higher
salience.</para>
<figure>
- <title>Fibonacci Example "Recurse" Agenda View 1</title>
+ <title>Fibonacci Example: "Recurse" Agenda View 1</title>
<mediaobject>
<imageobject>
@@ -183,7 +184,7 @@
exists.</para>
<figure>
- <title>Fibonacci Example "Recurse" Agenda View 2</title>
+ <title>Fibonacci Example: "Recurse" Agenda View 2</title>
<mediaobject>
<imageobject>
@@ -193,7 +194,7 @@
</figure>
<para>Once we have two <code>Fibonacci</code> objects with values
- not equal to -1 the "calculate" rule is able to match. It was
+ not equal to -1 the "Calculate" rule is able to match. It was
the "Bootstrap" rule that set the objects with sequence 1 and 2 to
values of 1. At this point we have 50 Fibonacci objects in the Working
Memory. Now we need to select a suitable triple to calculate each
@@ -218,7 +219,7 @@
third <code>Fibonacci</code> object that's bound to <code>f3</code>.</para>
<example>
- <title>Fibonacci Example : Rule "Calculate"</title>
+ <title>Fibonacci Example: Rule "Calculate"</title>
<programlisting>rule Calculate
when
@@ -248,7 +249,7 @@
objects.</para>
<figure>
- <title>Fibonacci Example "Bootstrap" Audit View 1</title>
+ <title>Fibonacci Example: "Bootstrap" Audit View</title>
<mediaobject>
<imageobject>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-MannersExample.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-MannersExample.xml 2009-04-30 06:08:07 UTC (rev 26316)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-MannersExample.xml 2009-04-30 08:11:03 UTC (rev 26317)
@@ -1,311 +1,293 @@
-<?xml version="1.0" encoding="UTF-8"?>
- <section version="5.0" xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xmlns:svg="http://www.w3.org/2000/svg"
- xmlns:m="http://www.w3.org/1998/Math/MathML"
- xmlns:html="http://www.w3.org/1999/xhtml"
- xmlns:db="http://docbook.org/ns/docbook" xml:base="../../">
- <title>Miss Manners and Benchmarking</title>
-
- <programlisting><emphasis role="bold">Name:</emphasis> Miss Manners
-<emphasis role="bold">Main class:</emphasis> org.drools.benchmark.manners.MannersBenchmark
-<emphasis role="bold">Type:</emphasis> java application
-<emphasis role="bold">Rules file:</emphasis> manners.drl
-<emphasis role="bold">Objective:</emphasis> Advanced walkthrough on the Manners benchmark, covers Depth conflict resolution in depth.</programlisting>
-
- <section>
- <title>Introduction</title>
-
- <para>Miss Manners is throwing a party and being the good host she wants
- to arrange good seating. Her initial design arranges everyone in male
- female pairs, but then she worries about people have things to talk
- about; what is a good host to do? So she decides to note the hobby of
- each guest so she can then arrange guests in not only male and female
- pairs but also ensure that a guest has someone to talk about a common
- hobby, from either their left or right side.</para>
-
- <figure>
- <title>Miss Manners' Guests</title>
-
- <mediaobject>
-
- <imageobject>
+<?xml version="1.0" encoding="UTF-8"?>
+ <section version="5.0" xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns:m="http://www.w3.org/1998/Math/MathML"
+ xmlns:html="http://www.w3.org/1999/xhtml"
+ xmlns:db="http://docbook.org/ns/docbook" xml:base="../../">
+ <title>Miss Manners and Benchmarking</title>
+
+ <programlisting><emphasis role="bold">Name:</emphasis> Miss Manners
+<emphasis role="bold">Main class:</emphasis> org.drools.benchmark.manners.MannersBenchmark
+<emphasis role="bold">Type:</emphasis> Java application
+<emphasis role="bold">Rules file:</emphasis> manners.drl
+<emphasis role="bold">Objective:</emphasis> Advanced walkthrough on the Manners benchmark, covers Depth conflict resolution in depth.</programlisting>
+
+ <section>
+ <title>Introduction</title>
+
+ <para>Miss Manners is throwing a party and, being a good host, she wants
+ to arrange good seating. Her initial design arranges everyone in
+ male-female pairs, but then she worries about people have things to talk
+ about. What is a good host to do? She decides to note the hobby of
+ each guest so she can then arrange guests not only pairing them according
+ to alternating sex but also ensuring that a guest has someone with a
+ common hobby, at least on one side.</para>
+
+ <figure>
+ <title>Miss Manners' Guests</title>
+
+ <mediaobject>
+
+ <imageobject>
<imagedata width="100%"
- align="center" fileref="images/Chapter-Examples/MannersExample/guests_at_table.png"
- format="PNG"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <section>
- <title>BenchMarking</title>
-
- <para>5 benchmarks were established in the 1991 paper "Effects of
- Database Size on Rule System Performance: Five Case Studies" by Brant,
- Timothy Grose, Bernie Lofaso, & Daniel P. Miranker.</para>
-
- <itemizedlist>
- <listitem>
- <para>Manners</para>
-
- <itemizedlist>
- <listitem>
- <para>Uses a depth-first search approach to determine the
- seating arrangements of boy/girl and one common hobby for
- dinner guests</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>Waltz</para>
-
- <itemizedlist>
- <listitem>
- <para>line labeling for simple scenes by constraint
- propagation</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>WaltzDB</para>
-
- <itemizedlist>
- <listitem>
- <para>More general version of Walts to be able to adapt to a
- database of facts</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>ARP</para>
-
- <itemizedlist>
- <listitem>
- <para>Route planner for a robotic air vehicle using the A*
- search algorithm</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>Weavera</para>
-
- <itemizedlist>
- <listitem>
- <para>VLSI router for channels and boxes using a black-board
- technique</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </itemizedlist>
-
- <para>Manners has become the de facto rule engine benchmark; however
- it's behavior is now well known and many engines optimize for this
- thus negating its usefulness as a benchmark which is why Waltz is
- becoming more favorable. These 5 benchmarks are also published at the
- University of Texas <ulink
- url="http://www.cs.utexas.edu/ftp/pub/ops5-benchmark-suite/">http://www.cs.utexas.edu/ftp/pub/ops5-benchmark-suite/</ulink>.</para>
- </section>
-
- <section>
- <title>Miss Manners Execution Flow</title>
-
- <para>After the first Seating arrangement has been assigned a
- depth-first recursion occurs which repeatedly assigns correct Seating
- arrangements until the last seat is assigned. Manners uses a Context
- instance to control execution flow; the activity diagram is
- partitioned to show the relation of the rule execution to the current
- Context state.</para>
-
- <figure>
- <title>Manners Activity Diagram</title>
-
- <mediaobject>
-
- <imageobject>
- <imagedata width="100%"
- align="center" fileref="images/Chapter-Examples/MannersExample/manners_activity_diagram.png"
- format="PNG" />
- </imageobject>
- </mediaobject>
- </figure>
- </section>
-
- <section>
- <title>The Data and Results</title>
-
- <para>Before going deeper into the rules lets first take a look at the
- asserted data and the resulting Seating arrangement. The data is a
- simple set of 5 guests who should be arranged in male/female pairs
- with common hobbies.</para>
-
- <para><emphasis role="bold">The Data</emphasis></para>
-
- <para>Each line of the results list is printed per execution of the
- "Assign Seat" rule. They key bit to notice is that each line has pid
- one greater than the last, the significance of this will be explained
- in t he "Assign Seating" rule description. The 'l' and the 'r' refer
- to the left and right, 's' is sean and 'n' is the guest name. In my
- actual implementation I used longer notation, 'leftGuestName', but
- this is not practice in a printed article. I found the notation of
- left and right preferable to the original OPS5 '1' and '2</para>
-
- <literallayout>(guest (name n1) (sex m) (hobby h1) )
-(guest (name n2) (sex f) (hobby h1) )
-(guest (name n2) (sex f) (hobby h3) )
-(guest (name n3) (sex m) (hobby h3) )
-(guest (name n4) (sex m) (hobby h1) )
-(guest (name n4) (sex f) (hobby h2) )
-(guest (name n4) (sex f) (hobby h3) )
-(guest (name n5) (sex f) (hobby h2) )
-(guest (name n5) (sex f) (hobby h1) )
-(last_seat (seat 5) )</literallayout>
-
- <para><emphasis role="bold">The Results</emphasis></para>
-
- <literallayout>[Seating id=1, pid=0, done=true, ls=1, ln=n5, rs=1, rn=n5]
-[Seating id=2, pid=1, done=false, ls=1, ln=n5, rs=2, rn=n4]
-[Seating id=3, pid=2, done=false, ls=2, ln=n4, rs=3, rn=n3]
-[Seating id=4, pid=3, done=false, ls=3, rn=n3, rs=4, rn=n2]
-[Seating id=5, pid=4, done=false, ls=4, ln=n2, rs=5, rn=n1]</literallayout>
- </section>
- </section>
-
- <section>
- <title>Indepth look</title>
-
- <section>
- <title>Cheating</title>
-
- <para>Manners has been around a long time and is a contrived benchmark
- meant to exercise the cross product joins and agenda, many people not
- understanding this tweak the example to achieve better performance,
- making their use of the Manners benchmark pointless. Known cheats to
- Miss Manners are:</para>
-
- <itemizedlist>
- <listitem>
- <para>Using arrays for a guests hobbies, instead of asserting each
- one as a single fact. This massively reduces the cross
- products.</para>
- </listitem>
-
- <listitem>
- <para>The altering of the sequence of data can also reducing the
- amount of matching increase execution speed</para>
- </listitem>
-
- <listitem>
- <para>Changing NOT CE (conditional element) such that the test
- algorithm only uses the "first-best-match". Basically, changing
- the test algorithm to backward chaining. the results are only
- comparable to other backward chaining rule engines or ports of
- Manners.</para>
- </listitem>
-
- <listitem>
- <para>Removing the context so the rule engine matches the guests
- and seats pre-maturely. A proper port will prevent facts from
- matching using the context start.</para>
- </listitem>
-
- <listitem>
- <para>Any change which prevents the rule engine from performing
- combinatorial pattern matching</para>
- </listitem>
-
- <listitem>
- <para>If no facts are retracted in the reasoning cycle, as a
- result of NOT CE, the port is incorrect.</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Conflict Resolution</title>
-
- <para>Manners benchmark was written for OPS5 which has two conflict
- resolution strategies, LEX and MEA; LEX is a chain of several
- strategies including Salience, Recency, Complexity. The Recency part
- of the strategy drives the depth first (LIFO) firing order. The Clips
- manual documents the recency strategy as:</para>
-
- <blockquote>
- <attribution>Clips Reference Manual</attribution>
-
- <para>Every fact and instance is marked internally with a "time tag"
- to indicate its relative recency with respect to every other fact
- and instance in the system. The pattern entities associated with
- each rule activation are sorted in descending order for determining
- placement. An activation with a more recent pattern entities is
- placed before activations with less recent pattern entities. To
- determine the placement order of two activations, compare the sorted
- time tags of the two activations one by one starting with the
- largest time tags. The comparison should continue until one
- activation’s time tag is greater than the other activation’s
- corresponding time tag. The activation with the greater time tag is
- placed before the other activation on the agenda. If one activation
- has more pattern entities than the other activation and the compared
- time tags are all identical, then the activation with more time tags
- is placed before the other activation on the agenda.</para>
- </blockquote>
-
- <para>However Jess and Clips both use the Depth strategy, which is
- simpler and lighter, which Drools also adopted. The Clips manual
- documents the Depth strategy as:</para>
-
- <blockquote>
- <attribution>Clips Reference Manual</attribution>
-
- <para>Newly activated rules are placed above all rules of the same
- salience. For example, given that fact-a activates rule-1 and rule-2
- and fact-b activates rule-3 and rule-4, then if fact-a is asserted
- before fact-b, rule-3 and rule-4 will be above rule-1 and rule-2 on
- the agenda. However, the position of rule-1 relative to rule-2 and
- rule-3 relative to rule-4 will be arbitrary.</para>
- </blockquote>
-
- <para>The initial Drools implementation for the Depth strategy would
- not work for manners without the use of salience on the "make_path"
- rule, the Clips support team had this to say:</para>
-
- <blockquote>
- <attribution>Clips Support Forum</attribution>
-
- <para>The default conflict resolution strategy for CLIPS, depth, is
- different than the default conflict resolution strategy used by
- OPS5. Therefore if you directly translate an OPS5 program to CLIPS,
- but use the default depth conflict resolution strategy, you're only
- likely to get the correct behavior by coincidence. The lex and mea
- conflict resolution strategies are provided in CLIPS to allow you to
- quickly convert and correctly run an OPS5 program in CLIPS</para>
- </blockquote>
-
- <para>Investigation into the Clips code reveals there is undocumented
- functionality in the Depth strategy. There is an accumulated time tag
- used in this strategy; it's not an extensively fact by fact comparison
- as in the recency strategy, it simply adds the total of all the time
- tags for each activation and compares.</para>
- </section>
-
- <section>
- <title>Assign First Seat</title>
-
- <para>Once the context is changed to START_UP Activations are created
- for all asserted Guests; because all Activations are created as the
- result of a single Working Memory action, they all have the same
- Activation time tag. The last asserted Guest would have a higher fact
- time tag and its Activation would fire, becuase it has the highest
- accumulated fact time tag. The execution order in this rule has little
- importance, but has a big impact in the rule "Assign Seat". The
- Activation fires and asserts the first Seating arrangement, a Path and
- then sets the Context's state to create Activation for "Assign
- Seat".</para>
-
+ align="center" fileref="images/Chapter-Examples/MannersExample/guests_at_table.png"
+ format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <section>
+ <title>BenchMarking</title>
+
+ <para>Five benchmarks were established in the 1991 paper "Effects of
+ Database Size on Rule System Performance: Five Case Studies" by
+ David Brant, Timothy Grose, Bernie Lofaso and Daniel P. Miranker:</para>
+
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">Manners</emphasis> uses a
+ depth-first search approach to determine the
+ seating arrangements alternating women and men and ensuring
+ one common hobby for neighbors.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Waltz</emphasis> establishes
+ a three-dimensional interpretation of a line drawing by
+ line labeling by constraint propagation.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">WaltzDB</emphasis> is a more
+ general version of Waltz, supporting junctions of more
+ than three lines and using a database.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">ARP</emphasis> is a
+ route planner for a robotic air vehicle using the A*
+ search algorithm to achieve minimal cost.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Weaver</emphasis>
+ VLSI router for channels and boxes using a black-board
+ technique.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Manners has become the de facto rule engine benchmark.
+ Its behavior, however, is now well known and many engines
+ optimize for this, thus negating its usefulness as a benchmark
+ which is why Waltz is becoming more favorable. These five
+ benchmarks are also published at the University of Texas <ulink
+ url="http://www.cs.utexas.edu/ftp/pub/ops5-benchmark-suite/">http://www.cs.utexas.edu/ftp/pub/ops5-benchmark-suite/</ulink>.</para>
+ </section>
+
+ <section>
+ <title>Miss Manners Execution Flow</title>
+
+ <para>After the first seating arrangement has been assigned, a
+ depth-first recursion occurs which repeatedly assigns correct
+ seating arrangements until the last seat is assigned. Manners
+ uses a <code>Context</code> instance to control execution flow.
+ The activity diagram is partitioned to show the relation of the
+ rule execution to the current <code>Context</code> state.</para>
+
+ <figure>
+ <title>Manners Activity Diagram</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata width="100%"
+ align="center" fileref="images/Chapter-Examples/MannersExample/manners_activity_diagram.png"
+ format="PNG" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+ <section>
+ <title>The Data and Results</title>
+
+ <para>Before going deeper into the rules, let's first take a look
+ at the asserted data and the resulting seating arrangement. The
+ data is a simple set of five guests who should be arranged so
+ that sexes alternate and neighbors have a common hobby.</para>
+
+ <para><emphasis role="bold">The Data</emphasis></para>
+
+ <para>The data is given in OPS5 syntax, with a parenthesized
+ list of name and value pairs for each attribute. Each
+ person has only one hobby.</para>
+
+ <literallayout>(guest (name n1) (sex m) (hobby h1) )
+(guest (name n2) (sex f) (hobby h1) )
+(guest (name n2) (sex f) (hobby h3) )
+(guest (name n3) (sex m) (hobby h3) )
+(guest (name n4) (sex m) (hobby h1) )
+(guest (name n4) (sex f) (hobby h2) )
+(guest (name n4) (sex f) (hobby h3) )
+(guest (name n5) (sex f) (hobby h2) )
+(guest (name n5) (sex f) (hobby h1) )
+(last_seat (seat 5) )</literallayout>
+
+ <para><emphasis role="bold">The Results</emphasis></para>
+
+ <para>Each line of the results list is printed per execution of the
+ "Assign Seat" rule. They key bit to notice is that each line has
+ a "pid" value one greater than the last. (The significance of this
+ will be explained in the discussion of the rule "Assign Seating".)
+ The "ls", "rs", "ln" and "rn" refer to the left and right
+ seat and neighbor's name, respectively. The actual implementation
+ uses longer attribute names (e.g., <code>leftGuestName</code>,
+ but here we'll stick to the notation from the original
+ implementation.</para>
+
+ <literallayout>[Seating id=1, pid=0, done=true, ls=1, ln=n5, rs=1, rn=n5]
+[Seating id=2, pid=1, done=false, ls=1, ln=n5, rs=2, rn=n4]
+[Seating id=3, pid=2, done=false, ls=2, ln=n4, rs=3, rn=n3]
+[Seating id=4, pid=3, done=false, ls=3, rn=n3, rs=4, rn=n2]
+[Seating id=5, pid=4, done=false, ls=4, ln=n2, rs=5, rn=n1]</literallayout>
+ </section>
+ </section>
+
+ <section>
+ <title>Indepth Discussion</title>
+
+ <section>
+ <title>Cheating</title>
+
+ <para>Manners has been designed to exercise cross product
+ joins and Agenda activities. Many people not understanding this
+ tweak the example to achieve better performance, making their
+ port of the Manners benchmark pointless. Known cheats or
+ porting errors for Miss Manners are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Using arrays for a guests hobbies, instead of asserting each
+ one as a single fact massively reduces the cross products.</para>
+ </listitem>
+
+ <listitem>
+ <para>Altering the sequence of data can also reduce the
+ amount of matching, increasing execution speed.</para>
+ </listitem>
+
+ <listitem>
+ <para>It's possible to change the <kw>not</kw> Conditional
+ Element so that the test algorithm only uses the
+ "first-best-match", which is, basically, transforming
+ the test algorithm to backward chaining. The results are only
+ comparable to other backward chaining rule engines or ports of
+ Manners.</para>
+ </listitem>
+
+ <listitem>
+ <para>Removing the context so the rule engine matches the guests
+ and seats prematurely. A proper port will prevent facts from
+ matching using the context start.</para>
+ </listitem>
+
+ <listitem>
+ <para>It's possible to prevent the rule engine from performing
+ combinatorial pattern matching.</para>
+ </listitem>
+
+ <listitem>
+ <para>If no facts are retracted in the reasoning cycle, as a
+ result of the <kw>not</kw> CE, the port is incorrect.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Conflict Resolution</title>
+
+ <para>The Manners benchmark was written for OPS5 which has two conflict
+ resolution strategies, LEX and MEA. LEX is a chain of several
+ strategies including salience, recency and complexity. The recency
+ part of the strategy drives the depth first (LIFO) firing order.
+ The CLIPS manual documents the Recency strategy as follows:</para>
+
+ <blockquote>
+ <attribution>CLIPS Reference Manual</attribution>
+
+ <para>Every fact and instance is marked internally with a "time tag"
+ to indicate its relative recency with respect to every other fact
+ and instance in the system. The pattern entities associated with
+ each rule activation are sorted in descending order for determining
+ placement. An activation with a more recent pattern entity is
+ placed before activations with less recent pattern entities. To
+ determine the placement order of two activations, compare the sorted
+ time tags of the two activations one by one starting with the
+ largest time tags. The comparison should continue until one
+ activation’s time tag is greater than the other activation’s
+ corresponding time tag. The activation with the greater time tag is
+ placed before the other activation on the agenda. If one activation
+ has more pattern entities than the other activation and the compared
+ time tags are all identical, then the activation with more time tags
+ is placed before the other activation on the agenda.</para>
+ </blockquote>
+
+ <para>However Jess and CLIPS both use the Depth strategy, which is
+ simpler and lighter, which Drools also adopted. The CLIPS manual
+ documents the Depth strategy as:</para>
+
+ <blockquote>
+ <attribution>CLIPS Reference Manual</attribution>
+
+ <para>Newly activated rules are placed above all rules of the same
+ salience. For example, given that fact-a activates rule-1 and rule-2
+ and fact-b activates rule-3 and rule-4, then if fact-a is asserted
+ before fact-b, rule-3 and rule-4 will be above rule-1 and rule-2 on
+ the agenda. However, the position of rule-1 relative to rule-2 and
+ rule-3 relative to rule-4 will be arbitrary.</para>
+ </blockquote>
+
+ <para>The initial Drools implementation for the Depth strategy would
+ not work for Manners without the use of salience on the "make_path"
+ rule. The CLIPS support team had this to say:</para>
+
+ <blockquote>
+ <attribution>Clips Support Forum</attribution>
+
+ <para>The default conflict resolution strategy for CLIPS, Depth, is
+ different than the default conflict resolution strategy used by
+ OPS5. Therefore if you directly translate an OPS5 program to CLIPS,
+ but use the default depth conflict resolution strategy, you're only
+ likely to get the correct behavior by coincidence. The LEX and MEA
+ conflict resolution strategies are provided in CLIPS to allow you to
+ quickly convert and correctly run an OPS5 program in CLIPS.</para>
+ </blockquote>
+
+ <para>Investigation into the CLIPS code reveals there is undocumented
+ functionality in the Depth strategy. There is an accumulated time tag
+ used in this strategy; it's not an extensively fact by fact comparison
+ as in the recency strategy, it simply adds the total of all the time
+ tags for each activation and compares.</para>
+ </section>
+
+ <section>
+ <title>Rule "assignFirstSeat"</title>
+
+ <para>Once the context is changed to <code>START_UP</code>,
+ activations are created for all asserted guest. Because all
+ activations are created as the result of a single Working Memory
+ action, they all have the same Activation time tag. The last
+ asserted <code>Guest</code> object would have a higher fact
+ time tag, and its Activation would fire because it has the highest
+ accumulated fact time tag. The execution order in this rule has little
+ importance, but has a big impact in the rule "Assign Seat". The
+ activation fires and asserts the first <code>Seating</code>
+ arrangement and a <code>Path</code>, and then sets the
+ <code>Context</code> attribute <code>state</code> to create
+ an activation for rule <code>findSeating</code>.</para>
+
<programlisting>rule assignFirstSeat
when
context : Context( state == Context.START_UP )
@@ -314,7 +296,8 @@
then
String guestName = guest.getName();
- Seating seating = new Seating( count.getValue(), 1, true, 1, guestName, 1, guestName);
+ Seating seating =
+ new Seating( count.getValue(), 1, true, 1, guestName, 1, guestName);
insert( seating );
Path path = new Path( count.getValue(), 1, guestName );
@@ -322,22 +305,23 @@
modify( count ) { setValue ( count.getValue() + 1 ) }
- System.out.println( "assign first seat : " + seating + " : " + path );
+ System.out.println( "assign first seat : " + seating + " : " + path );
modify( context ) {
setState( Context.ASSIGN_SEATS )
}
-end</programlisting>
- </section>
-
- <section>
- <title>Assign Seat</title>
-
- <para>This rule determines each of the Seating arrangements. The Rule
- creates cross product solutions for ALL asserted Seating arrangements
- against ALL the asserted guests; accept against itself or any already
- assigned Chosen solutions.</para>
-
+end</programlisting>
+ </section>
+
+ <section>
+ <title>Rule "findSeating"</title>
+
+ <para>This rule determines each of the <code>Seating</code>
+ arrangements. The rule creates cross product solutions for
+ <emphasis>all</emphasis> asserted <code>Seating</code> arrangements
+ against <emphasis>all</emphasis> the asserted guests except
+ against itself or any already assigned chosen solutions.</para>
+
<programlisting>rule findSeating
when
context : Context( state == Context.ASSIGN_SEATS )
@@ -354,8 +338,10 @@
int seatId = $s.getId();
int countValue = count.getValue();
- Seating seating = new Seating( countValue, seatId, false, rightSeat, $s.getRightGuestName(), rightSeat + 1, $g2.getName() );
- insert( seating );
+ Seating seating =
+ new Seating( countValue, seatId, false, rightSeat,
+ $s.getRightGuestName(), rightSeat + 1, $g2.getName() );
+ insert( seating );
Path path = new Path( countValue, rightSeat + 1, $g2.getName() );
insert( path );
@@ -363,66 +349,73 @@
Chosen chosen = new Chosen( seatId, $g2.getName(), $g1.getHobby() );
insert( chosen );
- System.err.println( "find seating : " + seating + " : " + path + " : " + chosen);
+ System.err.println( "find seating : " + seating + " : " + path +
+ " : " + chosen);
- modify( count ) {setValue( countValue + 1 )}
- modify( context ) {setState( Context.MAKE_PATH )}
-end</programlisting>
-
- <para>However, as can be seen from the printed results shown earlier,
- it is essential that only the Seating with the highest pid cross
- product be chosen – yet how can this be possible if we have
- Activations, of the same time tag, for nearly all existing Seating and
- Guests. For example on the third iteration of "Assing Seat" these are
- the produced Activations, remember this is from a very small data set
- and with larger data sets there would be many more possible Activated
- Seating solutions, with multiple solutions per pid:</para>
-
- <literallayout>=>[ActivationCreated(35): rule=findSeating
-[fid:19:33]:[Seating id=3, pid=2, done=true, ls=2, ln=n4, rs=3, rn=n3]
-[fid:4:4]:[Guest name=n3, sex=m, hobbies=h3]
-[fid:3:3]:[Guest name=n2, sex=f, hobbies=h3]
-
-=>[ActivationCreated(35): rule=findSeating
-[fid:15:23]:[Seating id=2, pid=1, done=true, ls=1, ln=n5, rs=2, rn=n4]
-[fid:5:5]:[Guest name=n4, sex=m, hobbies=h1]
-[fid:2:2]:[Guest name=n2, sex=f, hobbies=h1]
-
-=>[ActivationCreated(35): rule=findSeating
-[fid:13:13]:[Seating id=1, pid=0, done=true, ls=1, ln=n5, rs=1, rn=n5]
-[fid:9:9]:[Guest name=n5, sex=f, hobbies=h1]
-[fid:1:1]:[Guest name=n1, sex=m, hobbies=h1]</literallayout>
-
- <para>The creation of all these redundant Activations might seem
- pointless, but it must be remembered that Manners is not about good
- rule design; it's purposefully designed as a bad ruleset to fully
- stress test the cross product matching process and the agenda, which
- this clearly does. Notice that each Activation has the same time tag
- of 35, as they were all activated by the change in Context to
- ASSIGN_SEATS. With OPS5 and LEX it would correctly fire the Activation
- with the last asserted Seating. With Depth the accumulated fact time
- tag ensures the Activation with the last asserted Seating
- fires.</para>
- </section>
-
- <section>
- <title>Make Path and Path Done</title>
-
- <para>"Make Path" must always fires before "Path Done". A Path is
- asserted for each Seating arrangement up to the last asserted Seating.
- Notice that "Path Done" is a subset of "Make Path", so how do we
- ensure that "Make Path" fires first?</para>
-
- <programlisting>rule makePath
- when
- Context( state == Context.MAKE_PATH )
- Seating( seatingId:id, seatingPid:pid, pathDone == false )
- Path( id == seatingPid, pathGuestName:guestName, pathSeat:seat )
- not Path( id == seatingId, guestName == pathGuestName )
- then
- insert( new Path( seatingId, pathSeat, pathGuestName ) );
-end</programlisting>
-
+ modify( count ) {setValue( countValue + 1 )}
+ modify( context ) {setState( Context.MAKE_PATH )}
+end</programlisting>
+
+ <para>However, as can be seen from the printed results shown earlier,
+ it is essential that only the <code>Seating</code> with the highest
+ <code>pid</code> cross product be chosen. How can this be possible
+ if we have activations, of the same time tag, for nearly all
+ existing <code>Seating</code> and <code>Guest</code> objects? For
+ example, on the third iteration of <code>findDeating</code> the
+ produced activations will be as shown below. Remember, this is from
+ a very small data set, and with larger data sets there would be many
+ more possible activated <code>Seating</code> solutions, with multiple
+ solutions per <code>pid</code>:</para>
+
+ <literallayout>=>[ActivationCreated(35): rule=findSeating
+[fid:19:33]:[Seating id=3, pid=2, done=true, ls=2, ln=n4, rs=3, rn=n3]
+[fid:4:4]:[Guest name=n3, sex=m, hobbies=h3]
+[fid:3:3]:[Guest name=n2, sex=f, hobbies=h3]
+
+=>[ActivationCreated(35): rule=findSeating
+[fid:15:23]:[Seating id=2, pid=1, done=true, ls=1, ln=n5, rs=2, rn=n4]
+[fid:5:5]:[Guest name=n4, sex=m, hobbies=h1]
+[fid:2:2]:[Guest name=n2, sex=f, hobbies=h1]
+
+=>[ActivationCreated(35): rule=findSeating
+[fid:13:13]:[Seating id=1, pid=0, done=true, ls=1, ln=n5, rs=1, rn=n5]
+[fid:9:9]:[Guest name=n5, sex=f, hobbies=h1]
+[fid:1:1]:[Guest name=n1, sex=m, hobbies=h1]</literallayout>
+
+ <para>The creation of all these redundant activations might seem
+ pointless, but it must be remembered that Manners is not about good
+ rule design; it's purposefully designed as a bad ruleset to fully
+ stress-test the cross product matching process and the Agenda, which
+ this clearly does. Notice that each activation has the same time tag
+ of 35, as they were all activated by the change in the
+ <code>Context</code> object to <code>ASSIGN_SEATS</code>. With OPS5
+ and LEX it would correctly fire the activation with the
+ <code>Seating</code> asserted last. With Depth, the accumulated fact
+ time tag ensures that the activation with the last asserted
+ <code>Seating</code> fires.</para>
+ </section>
+
+ <section>
+ <title>Rules "makePath" and "pathDone"</title>
+
+ <para>Rule <code>makePath</code> must always fire before
+ <code>pathDone</code>. A <code>Path</code> object is asserted for
+ each <code>Seating</code> arrangement, up to the last asserted
+ <code>Seating</code>. Notice that the conditions in
+ <code>pathDone</code> are a subset of those in
+ <code>makePath</code> - so how do we ensure that <code>makePath</code>
+ fires first?</para>
+
+ <programlisting>rule makePath
+ when
+ Context( state == Context.MAKE_PATH )
+ Seating( seatingId:id, seatingPid:pid, pathDone == false )
+ Path( id == seatingPid, pathGuestName:guestName, pathSeat:seat )
+ not Path( id == seatingId, guestName == pathGuestName )
+ then
+ insert( new Path( seatingId, pathSeat, pathGuestName ) );
+end</programlisting>
+
<programlisting>rule pathDone
when
context : Context( state == Context.MAKE_PATH )
@@ -430,34 +423,35 @@
then
modify( seating ) {setPathDone( true )}
- modify( context ) {setState( Context.CHECK_DONE)}
-end</programlisting>
-
- <figure>
- <title>Rete Diagram</title>
-
- <mediaobject>
-
- <imageobject>
- <imagedata align="center" fileref="images/Chapter-Examples/MannersExample/make_path.png" format="PNG"
- scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>Both rules end up on the Agenda in conflict and with identical
- activation time tags, however the accumulate fact time tag is greater
- for "Make Path" so it gets priority.</para>
- </section>
-
- <section>
- <title>Continue and Are We Done</title>
-
- <para>"Are We Done" only activates when the last seat is assigned, at
- which point both rules will be activated. For the same reason that
- "Make Path" always wins over "Path Done" "Are We Done" will take
- priority over "Continue".</para>
-
+ modify( context ) {setState( Context.CHECK_DONE)}
+end</programlisting>
+
+ <figure>
+ <title>Rete Diagram</title>
+
+ <mediaobject>
+
+ <imageobject>
+ <imagedata align="center" fileref="images/Chapter-Examples/MannersExample/make_path.png" format="PNG"
+ scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Both rules end up on the Agenda in conflict and with identical
+ activation time tags. However, the accumulate fact time tag is greater
+ for "Make Path" so it gets priority.</para>
+ </section>
+
+ <section>
+ <title>Rules "continue" and "areWeDone"</title>
+
+ <para>Rule <code>areWeDone</code> only activates when the last seat
+ is assigned, at which point both rules will be activated. For the
+ same reason that <code>makePath</code> always wins over
+ <code>path Done</code>, <code>areWeDone</code> will take
+ priority over rule <code>continue</code>.</para>
+
<programlisting>rule areWeDone
when
context : Context( state == Context.CHECK_DONE )
@@ -465,159 +459,159 @@
Seating( rightSeat == lastSeat )
then
modify( context ) {setState(Context.PRINT_RESULTS )}
-end
-</programlisting>
-
+end
+</programlisting>
+
<programlisting>rule continue
when
context : Context( state == Context.CHECK_DONE )
then
modify( context ) {setState( Context.ASSIGN_SEATS )}
-end
-</programlisting>
- </section>
- </section>
-
- <section>
- <title>Output Summary</title>
-
- <literallayout><emphasis role="bold">Assign First seat</emphasis>
-=>[fid:13:13]:[Seating id=1, pid=0, done=true, ls=1, ln=n5, rs=1, rn=n5]
-=>[fid:14:14]:[Path id=1, seat=1, guest=n5]
-
-==>[ActivationCreated(16): rule=findSeating
-[fid:13:13]:[Seating id=1, pid=0, done=true, ls=1, ln=n5, rs=1, rn=n5]
-[fid:9:9]:[Guest name=n5, sex=f, hobbies=h1]
-[fid:1:1]:[Guest name=n1, sex=m, hobbies=h1]
-
-==>[ActivationCreated(16): rule=findSeating
-[fid:13:13]:[Seating id=1 , pid=0, done=true, ls=1, ln=n5, rs=1, rn=n5]
-[fid:9:9]:[Guest name=n5, sex=f, hobbies=h1]
-[fid:5:5]:[Guest name=n4, sex=m, hobbies=h1]*
-
-<emphasis role="bold">Assign Seating</emphasis>
-=>[fid:15:17] :[Seating id=2 , pid=1 , done=false, ls=1, lg=n5, rs=2, rn=n4]
-=>[fid:16:18]:[Path id=2, seat=2, guest=n4]
-=>[fid:17:19]:[Chosen id=1, name=n4, hobbies=h1]
-
-=>[ActivationCreated(21): rule=makePath
-[fid:15:17] : [Seating id=2, pid=1, done=false, ls=1, ln=n5, rs=2, rn=n4]
-[fid:14:14] : [Path id=1, seat=1, guest=n5]*
-
-==>[ActivationCreated(21): rule=pathDone
-[Seating id=2, pid=1, done=false, ls=1, ln=n5, rs=2, rn=n4]*
-
-<emphasis role="bold">Make Path</emphasis>
-=>[fid:18:22:[Path id=2, seat=1, guest=n5]]
-
-<emphasis role="bold">Path Done</emphasis>
-
-<emphasis role="bold">Continue Process</emphasis>
-=>[ActivationCreated(25): rule=findSeating
-[fid:15:23]:[Seating id=2, pid=1, done=true, ls=1, ln=n5, rs=2, rn=n4]
-[fid:7:7]:[Guest name=n4, sex=f, hobbies=h3]
-[fid:4:4] : [Guest name=n3, sex=m, hobbies=h3]*
-
-=>[ActivationCreated(25): rule=findSeating
-[fid:15:23]:[Seating id=2, pid=1, done=true, ls=1, ln=n5, rs=2, rn=n4]
-[fid:5:5]:[Guest name=n4, sex=m, hobbies=h1]
-[fid:2:2]:[Guest name=n2, sex=f, hobbies=h1], [fid:12:20] : [Count value=3]
-
-=>[ActivationCreated(25): rule=findSeating
-[fid:13:13]:[Seating id=1, pid=0, done=true, ls=1, ln=n5, rs=1, rn=n5]
-[fid:9:9]:[Guest name=n5, sex=f, hobbies=h1]
-[fid:1:1]:[Guest name=n1, sex=m, hobbies=h1]
-
-<emphasis role="bold">Assign Seating</emphasis>
-=>[fid:19:26]:[Seating id=3, pid=2, done=false, ls=2, lnn4, rs=3, rn=n3]]
-=>[fid:20:27]:[Path id=3, seat=3, guest=n3]]
-=>[fid:21:28]:[Chosen id=2, name=n3, hobbies=h3}]
-
-=>[ActivationCreated(30): rule=makePath
-[fid:19:26]:[Seating id=3, pid=2, done=false, ls=2, ln=n4, rs=3, rn=n3]
-[fid:18:22]:[Path id=2, seat=1, guest=n5]*
-
-=>[ActivationCreated(30): rule=makePath
-[fid:19:26]:[Seating id=3, pid=2, done=false, ls=2, ln=n4, rs=3, rn=n3]
-[fid:16:18]:[Path id=2, seat=2, guest=n4]*
-
-=>[ActivationCreated(30): rule=done
-[fid:19:26]:[Seating id=3, pid=2, done=false, ls=2, ln=n4, rs=3, rn=n3]*
-
-<emphasis role="bold">Make Path</emphasis>
-=>[fid:22:31]:[Path id=3, seat=1, guest=n5]
-
-<emphasis role="bold">Make Path </emphasis>
-=>[fid:23:32] [Path id=3, seat=2, guest=n4]
-
-<emphasis role="bold">Path Done</emphasis>
-
-<emphasis role="bold">Continue Processing</emphasis>
-=>[ActivationCreated(35): rule=findSeating
-[fid:19:33]:[Seating id=3, pid=2, done=true, ls=2, ln=n4, rs=3, rn=n3]
-[fid:4:4]:[Guest name=n3, sex=m, hobbies=h3]
-[fid:3:3]:[Guest name=n2, sex=f, hobbies=h3], [fid:12:29]*
-
-=>[ActivationCreated(35): rule=findSeating
-[fid:15:23]:[Seating id=2, pid=1, done=true, ls=1, ln=n5, rs=2, rn=n4]
-[fid:5:5]:[Guest name=n4, sex=m, hobbies=h1]
-[fid:2:2]:[Guest name=n2, sex=f, hobbies=h1]
-
-=>[ActivationCreated(35): rule=findSeating
-[fid:13:13]:[Seating id=1, pid=0, done=true, ls=1, ln=n5, rs=1, rn=n5]
-[fid:9:9]:[Guest name=n5, sex=f, hobbies=h1], [fid:1:1] : [Guest name=n1, sex=m, hobbies=h1]
-
-<emphasis role="bold">Assign Seating</emphasis>
-=>[fid:24:36]:[Seating id=4, pid=3, done=false, ls=3, ln=n3, rs=4, rn=n2]]
-=>[fid:25:37]:[Path id=4, seat=4, guest=n2]]
-=>[fid:26:38]:[Chosen id=3, name=n2, hobbies=h3]
-
-==>[ActivationCreated(40): rule=makePath
-[fid:24:36]:[Seating id=4, pid=3, done=false, ls=3, ln=n3, rs=4, rn=n2]
-[fid:23:32]:[Path id=3, seat=2, guest=n4]*
-
-==>[ActivationCreated(40): rule=makePath
-[fid:24:36]:[Seating id=4, pid=3, done=false, ls=3, ln=n3, rs=4, rn=n2]
-[fid:20:27]:[Path id=3, seat=3, guest=n3]*
-
-=>[ActivationCreated(40): rule=makePath
-[fid:24:36]:[Seating id=4, pid=3, done=false, ls=3, ln=n3, rs=4, rn=n2]
-[fid:22:31]:[Path id=3, seat=1, guest=n5]*
-
-=>[ActivationCreated(40): rule=done
-[fid:24:36]:[Seating id=4, pid=3, done=false, ls=3, ln=n3, rs=4, rn=n2]*
-
-<emphasis role="bold">Make Path </emphasis>
-=>fid:27:41:[Path id=4, seat=2, guest=n4]
-
-<emphasis role="bold">Make Path</emphasis>
-=>fid:28:42]:[Path id=4, seat=1, guest=n5]]
-
-<emphasis role="bold">Make Path</emphasis>
-=>fid:29:43]:[Path id=4, seat=3, guest=n3]]
-
-<emphasis role="bold">Path Done</emphasis>
-
-<emphasis role="bold">Continue Processing</emphasis>
-=>[ActivationCreated(46): rule=findSeating
-[fid:15:23]:[Seating id=2, pid=1, done=true, ls=1, ln=n5, rs=2, rn=n4]
-[fid:5:5]:[Guest name=n4, sex=m, hobbies=h1], [fid:2:2]
-[Guest name=n2, sex=f, hobbies=h1]
-
-=>[ActivationCreated(46): rule=findSeating
-[fid:24:44]:[Seating id=4, pid=3, done=true, ls=3, ln=n3, rs=4, rn=n2]
-[fid:2:2]:[Guest name=n2, sex=f, hobbies=h1]
-[fid:1:1]:[Guest name=n1, sex=m, hobbies=h1]*
-
-=>[ActivationCreated(46): rule=findSeating
-[fid:13:13]:[Seating id=1, pid=0, done=true, ls=1, ln=n5, rs=1, rn=n5]
-[fid:9:9]:[Guest name=n5, sex=f, hobbies=h1]
-[fid:1:1]:[Guest name=n1, sex=m, hobbies=h1]
-
-<emphasis role="bold">Assign Seating</emphasis>
-=>[fid:30:47]:[Seating id=5, pid=4, done=false, ls=4, ln=n2, rs=5, rn=n1]
-=>[fid:31:48]:[Path id=5, seat=5, guest=n1]
-=>[fid:32:49]:[Chosen id=4, name=n1, hobbies=h1]
-</literallayout>
- </section>
+end
+</programlisting>
+ </section>
+ </section>
+
+ <section>
+ <title>Output Summary</title>
+
+ <literallayout><emphasis role="bold">Assign First seat</emphasis>
+=>[fid:13:13]:[Seating id=1, pid=0, done=true, ls=1, ln=n5, rs=1, rn=n5]
+=>[fid:14:14]:[Path id=1, seat=1, guest=n5]
+
+==>[ActivationCreated(16): rule=findSeating
+[fid:13:13]:[Seating id=1, pid=0, done=true, ls=1, ln=n5, rs=1, rn=n5]
+[fid:9:9]:[Guest name=n5, sex=f, hobbies=h1]
+[fid:1:1]:[Guest name=n1, sex=m, hobbies=h1]
+
+==>[ActivationCreated(16): rule=findSeating
+[fid:13:13]:[Seating id=1 , pid=0, done=true, ls=1, ln=n5, rs=1, rn=n5]
+[fid:9:9]:[Guest name=n5, sex=f, hobbies=h1]
+[fid:5:5]:[Guest name=n4, sex=m, hobbies=h1]*
+
+<emphasis role="bold">Assign Seating</emphasis>
+=>[fid:15:17] :[Seating id=2 , pid=1 , done=false, ls=1, lg=n5, rs=2, rn=n4]
+=>[fid:16:18]:[Path id=2, seat=2, guest=n4]
+=>[fid:17:19]:[Chosen id=1, name=n4, hobbies=h1]
+
+=>[ActivationCreated(21): rule=makePath
+[fid:15:17] : [Seating id=2, pid=1, done=false, ls=1, ln=n5, rs=2, rn=n4]
+[fid:14:14] : [Path id=1, seat=1, guest=n5]*
+
+==>[ActivationCreated(21): rule=pathDone
+[Seating id=2, pid=1, done=false, ls=1, ln=n5, rs=2, rn=n4]*
+
+<emphasis role="bold">Make Path</emphasis>
+=>[fid:18:22:[Path id=2, seat=1, guest=n5]]
+
+<emphasis role="bold">Path Done</emphasis>
+
+<emphasis role="bold">Continue Process</emphasis>
+=>[ActivationCreated(25): rule=findSeating
+[fid:15:23]:[Seating id=2, pid=1, done=true, ls=1, ln=n5, rs=2, rn=n4]
+[fid:7:7]:[Guest name=n4, sex=f, hobbies=h3]
+[fid:4:4] : [Guest name=n3, sex=m, hobbies=h3]*
+
+=>[ActivationCreated(25): rule=findSeating
+[fid:15:23]:[Seating id=2, pid=1, done=true, ls=1, ln=n5, rs=2, rn=n4]
+[fid:5:5]:[Guest name=n4, sex=m, hobbies=h1]
+[fid:2:2]:[Guest name=n2, sex=f, hobbies=h1], [fid:12:20] : [Count value=3]
+
+=>[ActivationCreated(25): rule=findSeating
+[fid:13:13]:[Seating id=1, pid=0, done=true, ls=1, ln=n5, rs=1, rn=n5]
+[fid:9:9]:[Guest name=n5, sex=f, hobbies=h1]
+[fid:1:1]:[Guest name=n1, sex=m, hobbies=h1]
+
+<emphasis role="bold">Assign Seating</emphasis>
+=>[fid:19:26]:[Seating id=3, pid=2, done=false, ls=2, lnn4, rs=3, rn=n3]]
+=>[fid:20:27]:[Path id=3, seat=3, guest=n3]]
+=>[fid:21:28]:[Chosen id=2, name=n3, hobbies=h3}]
+
+=>[ActivationCreated(30): rule=makePath
+[fid:19:26]:[Seating id=3, pid=2, done=false, ls=2, ln=n4, rs=3, rn=n3]
+[fid:18:22]:[Path id=2, seat=1, guest=n5]*
+
+=>[ActivationCreated(30): rule=makePath
+[fid:19:26]:[Seating id=3, pid=2, done=false, ls=2, ln=n4, rs=3, rn=n3]
+[fid:16:18]:[Path id=2, seat=2, guest=n4]*
+
+=>[ActivationCreated(30): rule=done
+[fid:19:26]:[Seating id=3, pid=2, done=false, ls=2, ln=n4, rs=3, rn=n3]*
+
+<emphasis role="bold">Make Path</emphasis>
+=>[fid:22:31]:[Path id=3, seat=1, guest=n5]
+
+<emphasis role="bold">Make Path </emphasis>
+=>[fid:23:32] [Path id=3, seat=2, guest=n4]
+
+<emphasis role="bold">Path Done</emphasis>
+
+<emphasis role="bold">Continue Processing</emphasis>
+=>[ActivationCreated(35): rule=findSeating
+[fid:19:33]:[Seating id=3, pid=2, done=true, ls=2, ln=n4, rs=3, rn=n3]
+[fid:4:4]:[Guest name=n3, sex=m, hobbies=h3]
+[fid:3:3]:[Guest name=n2, sex=f, hobbies=h3], [fid:12:29]*
+
+=>[ActivationCreated(35): rule=findSeating
+[fid:15:23]:[Seating id=2, pid=1, done=true, ls=1, ln=n5, rs=2, rn=n4]
+[fid:5:5]:[Guest name=n4, sex=m, hobbies=h1]
+[fid:2:2]:[Guest name=n2, sex=f, hobbies=h1]
+
+=>[ActivationCreated(35): rule=findSeating
+[fid:13:13]:[Seating id=1, pid=0, done=true, ls=1, ln=n5, rs=1, rn=n5]
+[fid:9:9]:[Guest name=n5, sex=f, hobbies=h1], [fid:1:1] : [Guest name=n1, sex=m, hobbies=h1]
+
+<emphasis role="bold">Assign Seating</emphasis>
+=>[fid:24:36]:[Seating id=4, pid=3, done=false, ls=3, ln=n3, rs=4, rn=n2]]
+=>[fid:25:37]:[Path id=4, seat=4, guest=n2]]
+=>[fid:26:38]:[Chosen id=3, name=n2, hobbies=h3]
+
+==>[ActivationCreated(40): rule=makePath
+[fid:24:36]:[Seating id=4, pid=3, done=false, ls=3, ln=n3, rs=4, rn=n2]
+[fid:23:32]:[Path id=3, seat=2, guest=n4]*
+
+==>[ActivationCreated(40): rule=makePath
+[fid:24:36]:[Seating id=4, pid=3, done=false, ls=3, ln=n3, rs=4, rn=n2]
+[fid:20:27]:[Path id=3, seat=3, guest=n3]*
+
+=>[ActivationCreated(40): rule=makePath
+[fid:24:36]:[Seating id=4, pid=3, done=false, ls=3, ln=n3, rs=4, rn=n2]
+[fid:22:31]:[Path id=3, seat=1, guest=n5]*
+
+=>[ActivationCreated(40): rule=done
+[fid:24:36]:[Seating id=4, pid=3, done=false, ls=3, ln=n3, rs=4, rn=n2]*
+
+<emphasis role="bold">Make Path </emphasis>
+=>fid:27:41:[Path id=4, seat=2, guest=n4]
+
+<emphasis role="bold">Make Path</emphasis>
+=>fid:28:42]:[Path id=4, seat=1, guest=n5]]
+
+<emphasis role="bold">Make Path</emphasis>
+=>fid:29:43]:[Path id=4, seat=3, guest=n3]]
+
+<emphasis role="bold">Path Done</emphasis>
+
+<emphasis role="bold">Continue Processing</emphasis>
+=>[ActivationCreated(46): rule=findSeating
+[fid:15:23]:[Seating id=2, pid=1, done=true, ls=1, ln=n5, rs=2, rn=n4]
+[fid:5:5]:[Guest name=n4, sex=m, hobbies=h1], [fid:2:2]
+[Guest name=n2, sex=f, hobbies=h1]
+
+=>[ActivationCreated(46): rule=findSeating
+[fid:24:44]:[Seating id=4, pid=3, done=true, ls=3, ln=n3, rs=4, rn=n2]
+[fid:2:2]:[Guest name=n2, sex=f, hobbies=h1]
+[fid:1:1]:[Guest name=n1, sex=m, hobbies=h1]*
+
+=>[ActivationCreated(46): rule=findSeating
+[fid:13:13]:[Seating id=1, pid=0, done=true, ls=1, ln=n5, rs=1, rn=n5]
+[fid:9:9]:[Guest name=n5, sex=f, hobbies=h1]
+[fid:1:1]:[Guest name=n1, sex=m, hobbies=h1]
+
+<emphasis role="bold">Assign Seating</emphasis>
+=>[fid:30:47]:[Seating id=5, pid=4, done=false, ls=4, ln=n2, rs=5, rn=n1]
+=>[fid:31:48]:[Path id=5, seat=5, guest=n1]
+=>[fid:32:49]:[Chosen id=4, name=n1, hobbies=h1]
+</literallayout>
+ </section>
</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-NumberGuessExample.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-NumberGuessExample.xml 2009-04-30 06:08:07 UTC (rev 26316)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-NumberGuessExample.xml 2009-04-30 08:11:03 UTC (rev 26317)
@@ -80,7 +80,7 @@
below.</para>
<para>Before we finish the discussion of our Java code, we note that in
- some real life application we would examine the final state of the objects.
+ some real-life application we would examine the final state of the objects.
(Here, we could retrieve the number of guesses, to add it to a high score
table.) For this example we are content to ensure that the Working Memory
session is cleared by calling the <code>dispose()</code> method.</para>
@@ -125,13 +125,13 @@
</figure>
<para>Keep an eye on the Properties View as we progress through the
- example's rule flow, as it gives valuable information. In this case, it
+ example's rule flow, as it presents valuable information. In this case, it
provides us with the identification of the Rule Flow Process that
we used in our earlier code snippet, when we called
<code>session.startProcess()</code>.</para>
- <para>In the Number Guess rule flow, we encounter several node
- types, sometimes identified by an icon.</para>
+ <para>In the "Number Guess" Rule Flow we encounter several node
+ types, many of them identified by an icon.</para>
<para>
<itemizedlist>
@@ -177,22 +177,22 @@
NumberGuess.drl</title>
<programlisting>rule "Get user Guess"
- ruleflow-group "Guess"
- no-loop
- when
- $r : RandomNumber()
- rules : GameRules( allowed : allowedGuesses )
- game : Game( guessCount < allowed )
- not ( Guess() )
- then
- System.out.println( "You have " + ( rules.allowedGuesses - game.guessCount )
- + " out of " + rules.allowedGuesses
- + " guesses left.\nPlease enter your guess from 0 to "
- + rules.maxRange );
- br = new BufferedReader( new InputStreamReader( System.in ) );
- i = br.readLine();
- modify ( game ) { guessCount = game.guessCount + 1 }
- insert( new Guess( i ) );
+ ruleflow-group "Guess"
+ no-loop
+ when
+ $r : RandomNumber()
+ rules : GameRules( allowed : allowedGuesses )
+ game : Game( guessCount < allowed )
+ not ( Guess() )
+ then
+ System.out.println( "You have " + ( rules.allowedGuesses - game.guessCount )
+ + " out of " + rules.allowedGuesses
+ + " guesses left.\nPlease enter your guess from 0 to "
+ + rules.maxRange );
+ br = new BufferedReader( new InputStreamReader( System.in ) );
+ i = br.readLine();
+ modify ( game ) { guessCount = game.guessCount + 1 }
+ insert( new Guess( i ) );
end</programlisting>
</example>
@@ -207,10 +207,10 @@
message to the user and then awaits user input from
<code>System.in</code>. After obtaining this input (the
<code>readLine()</code> method call blocks until the return key is
- pressed) it calls modifies the guess count and inserts the new
+ pressed) it modifies the guess count and inserts the new
guess, making both available to the Working Memory.</para>
- <para>The rest of the rules file is fairly standard; the package
+ <para>The rest of the rules file is fairly standard: the package
declares the dialect as MVEL, and various Java classes are imported.
In total, there are five rules in this file:</para>
@@ -239,18 +239,19 @@
</orderedlist>
<para>One point of integration between the standard Rules and
- the RuleFlow is via the 'ruleflow-group' attribute on the rules (as
- dicussed above). A <emphasis role="bold">second point of integration
- between the Rules File (drl) and the Rules Flow .rf files </emphasis>is
- that the Split Nodes (the blue ovals) can use values in working memory
- (as updated by the Rules) to decide which flow of action to take. To see
- how this works click on the "Guess Correct Node" ; then within the
- properties view, open the constraints editor (the button at the right
- that appears once you click on the 'Constraints' property line). You
- should see something similar to the Diagram below.</para>
+ the RuleFlow is via the <kw>ruleflow-group</kw> attribute on the
+ rules, as dicussed above. A
+ <emphasis>second point of integration between the rules (.drl) file
+ and the Rules Flow .rf files</emphasis> is
+ that the Split Nodes (the blue ovals) can use values in the Working Memory
+ (as updated by the rules) to decide which flow of action to take. To see
+ how this works, click on the "Guess Correct Node"; then within the
+ Properties View, open the Constraints Editor by clicking the button at
+ the right that appears once you click on the "Constraints" property line.
+ You should see something similar to the diagram below.</para>
<figure>
- <title>Edit Constraints for the GuessCorrect Node</title>
+ <title>Edit Constraints for the "Guess Correct" Node</title>
<mediaobject>
<imageobject>
@@ -259,15 +260,15 @@
</mediaobject>
</figure>
- <para>Click on 'Edit' beside 'To node Too High' and you see a dialog
- like the one below. The values in the 'Textual Editor' follow the
- standard Rule Format (LHS) and can refer to objects in working memory.
+ <para>Click on the "Edit" button beside "To node Too High" and you'll
+ see a dialog like the one below. The values in the "Textual Editor"
+ window follow the standard rule format for the LHS and can refer to
+ objects in Working Memory.
The consequence (RHS) is that the flow of control follows this node
- (i.e. To node Too high') if the LHS expression evaluates to true.</para>
+ (i.e., "To node Too High") if the LHS expression evaluates to true.</para>
<figure>
- <title>Constraints Editor for the GuessCorrect Node / value too
- high</title>
+ <title>Constraint Editor for the "Guess Correct" Node: value too high</title>
<mediaobject>
<imageobject>
@@ -276,10 +277,11 @@
</mediaobject>
</figure>
- <para>Since the NumberGuess.java example contains a main() method, it
- can be run as a standard Java application (either from the command line
- or via the IDE). A typical game might result in the interaction below
- (the numbers in bold are typed in by the user).</para>
+ <para>Since the file <filename>NumberGuess.java</filename> contains a
+ <code>main()</code> method, it
+ can be run as a standard Java application, either from the command line
+ or via the IDE. A typical game might result in the interaction below.
+ The numbers in bold are typed in by the user.</para>
<example>
<title>Example Console output where the Number Guess Example beat the
@@ -316,65 +318,68 @@
<orderedlist>
<listitem>
- <para>Main() method of NumberGuessExample.java loads RuleBase,
- gets a StatefulSession and inserts Game, GameRules and
- RandomNumber (containing the target number) objects into it. This
- method sets the process flow we are going to use, and fires all
- rules. Control passes to the RuleFlow.</para>
+ <para>The <code>main()</code> method of
+ <filename>NumberGuessExample.java</filename> loads a Rule Base,
+ creates a Stateful Session and inserts <code>Game</code>,
+ <code>GameRules</code> and <code>RandomNumber</code>
+ (containing the target number) objects into it. The
+ method also sets the process flow we are going to use, and fires all
+ rules. Control passes to the Rule Flow.</para>
</listitem>
<listitem>
- <para>The NumberGuess.rf RuleFlow begins at the Start node.</para>
+ <para>File <filename>NumberGuess.rf</filename>, the Rule Flow,
+ begins at the "Start" node.</para>
</listitem>
<listitem>
- <para>Control passes (via the "more guesses" join node) to the
- Guess Node..</para>
+ <para>Control passes (via the "More guesses" join node) to the
+ Guess node.</para>
</listitem>
<listitem>
- <para>At the Guess node, the appropriate RuleFlowGroup ("Get user
- Guess") is enabled. In this case the Rule "Guess" (in the
- NumberGuess.drl file) is triggered. This rule displays a message
- to the user, takes the response, and puts it into memory. Flow
- passes to the next Rule Flow Node.</para>
+ <para>At the Guess node, the appropriate Rule Flow Group
+ ("Get user Guess") is enabled. In this case the Rule "Guess" (in the
+ <filename>NumberGuess.drl</filename> file) is triggered. This rule
+ displays a message to the user, takes the response, and puts it into
+ Working Memory. Flow passes to the next Rule Flow Node.</para>
</listitem>
<listitem>
- <para>At the next node , "Guess Correct", constraints inspect the
- current session and decide which path we take next.</para>
+ <para>At the next node, "Guess Correct", constraints inspect the
+ current session and decide which path to take.</para>
- <para>If the guess in step 4 was too high / too low flow procees
- along a path which has (i) An action node with normal Java code
- prints a too high / too low statement and (ii) a RuleFlowGroup
- causes a highest guess / lowest guess Rule to be triggered in the
- Rules file. Flow passes from these nodes to step 6.</para>
+ <para>If the guess in step 4 was too high or too low, flow proceeds
+ along a path which has an action node with normal Java code
+ printing a suitable message and a Rule Flow Group causing a
+ highest guess or lowest guess rule to be triggered. Flow passes
+ from these nodes to step 6.</para>
- <para>If the guess in step 4 just right we proceed along the path
+ <para>If the guess in step 4 was right, we proceed along the path
towards the end of the Rule Flow. Before we get there, an action
node with normal Java code prints a statement "you guessed
correctly". There is a join node here (just before the Rule Flow
- End) so that our no-more-guesses path (step 7) can also terminate
- the RuleFlow.</para>
+ end) so that our no-more-guesses path (step 7) can also terminate
+ the Rule Flow.</para>
</listitem>
<listitem>
- <para>Control passes as per the RuleFlow via a join node, a guess
- incorrect RuleFlowGroup (triggers a rule to retract a guess from
- working memory) onto the "more guesses" decision node.</para>
+ <para>Control passes as per the Rule Flow via a join node, a guess
+ incorrect Rule Flow Group (triggering a rule to retract a guess from
+ Working Memory) onto the "More guesses" decision node.</para>
</listitem>
<listitem>
- <para>The "more guesses" decision node (right hand side of
- ruleflow) uses constraints (again looking at values that the Rules
- have put into the working memory) to decide if we have more
- guesses and if so, goto step 3. If not we proceed to the end of
- the workflow, via a RuleFlowGroup that triggers a rule stating
+ <para>The "More guesses" decision node (on the right hand side of the
+ rule flow) uses constraints, again looking at values that the rules
+ have put into the working memory, to decide if we have more
+ guesses and if so, goto step 3. If not, we proceed to the end of
+ the rule flow, via a Rule Flow Group that triggers a rule stating
"you have no more guesses".</para>
</listitem>
<listitem>
- <para>The Loop 3-7 continues until the number is guessed
+ <para>The loop over steps 3 to 7 continues until the number is guessed
correctly, or we run out of guesses.</para>
</listitem>
</orderedlist>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-PetStoreExample.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-PetStoreExample.xml 2009-04-30 06:08:07 UTC (rev 26316)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-PetStoreExample.xml 2009-04-30 08:11:03 UTC (rev 26317)
@@ -69,11 +69,12 @@
</itemizedlist>
<para>Much of the Java code is either plain JavaBeans or Swing-based.
- We will touch on some Swing-related points in the this tutorial, but
- a good place to get more information on Swing components is
+ Only a few Swing-related points will be discussed in this section,
+ but a good tutorial about Swing components can be found at Sun's
+ Swing website, in
<ulink url="???">
<uri>http://java.sun.com/docs/books/tutorial/uiswing/</uri>
- </ulink> at Sun's Swing website.</para>
+ </ulink>.</para>
<para>The pieces of Java code in <filename>Petstore.java</filename>
that relate to rules and facts are shown below.</para>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-StateExample.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-StateExample.xml 2009-04-30 06:08:07 UTC (rev 26316)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-StateExample.xml 2009-04-30 08:11:03 UTC (rev 26317)
@@ -71,7 +71,7 @@
final State d = new State( "D" );
// By setting dynamic to TRUE, Drools will use JavaBean
-// PropertyChangeListeners so you don't have to call update().
+// PropertyChangeListeners so you don't have to call modify or update().
boolean dynamic = true;
session.insert( a, dynamic );
@@ -248,11 +248,11 @@
documentation, in order for the engine to see and react to changes of
fact properties, the application must tell the engine that changes
occurred. This can be done explicitly in the rules by using the
- <kw>update</kw> statement, or implicitly by letting the engine know
+ <kw>modify</kw> statement, or implicitly by letting the engine know
that the facts implement <code>PropertyChangeSupport</code> as defined
by the <emphasis>JavaBeans specification</emphasis>. This example
demonstrates how to use <code>PropertyChangeSupport</code> to avoid
- the need for explicit <kw>update</kw> statements in the rules. To
+ the need for explicit <kw>modify</kw> statements in the rules. To
make use of this feature, ensure that your facts implement
<code>PropertyChangeSupport</code>, the same way the class
<code>org.drools.example.State</code> does, and use the following
@@ -262,7 +262,7 @@
<title>Inserting a Dynamic Fact</title>
<programlisting>// By setting dynamic to TRUE, Drools will use JavaBean
-// PropertyChangeListeners so you don't have to call update().
+// PropertyChangeListeners so you don't have to call modify or update().
final boolean dynamic = true;
session.insert( fact, dynamic );
More information about the jboss-svn-commits
mailing list