[jboss-svn-commits] JBL Code SVN: r26227 - in labs/jbossrules/trunk/drools-docs: drools-docs-expert/src/main/docbook/en-US/Chapter-Authoring and 5 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Thu Apr 23 14:49:23 EDT 2009
Author: laune
Date: 2009-04-23 14:49:22 -0400 (Thu, 23 Apr 2009)
New Revision: 26227
Modified:
labs/jbossrules/trunk/drools-docs/docbook-xsl-drools/src/main/resources/org/jboss/common.xsl
labs/jbossrules/trunk/drools-docs/docbook-xsl-drools/src/main/resources/org/jboss/xhtml-common.xsl
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Authoring/Section-Decision_Tables.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Chapter-Examples.xml
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-HelloWorldExample.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-HonestPoliticianExample.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-PricingExample.xml
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-IDE/Chapter-QuickStart.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-ErrorMessages.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Function.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Keywords.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Overview.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Package.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Rule.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-TypeDeclaration.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Section-A_Little_More_Theory.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Section-More_On_Building_And_Deploying.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Section-The_Basics.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-User_Guide/Section-Building.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-User_Guide/Section-Deploying.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-User_Guide/Section-Running.xml
Log:
improvements
Modified: labs/jbossrules/trunk/drools-docs/docbook-xsl-drools/src/main/resources/org/jboss/common.xsl
===================================================================
--- labs/jbossrules/trunk/drools-docs/docbook-xsl-drools/src/main/resources/org/jboss/common.xsl 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/docbook-xsl-drools/src/main/resources/org/jboss/common.xsl 2009-04-23 18:49:22 UTC (rev 26227)
@@ -7,8 +7,11 @@
Author: Mark Newton (mark.newton at jboss.org)
-->
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
+ xmlns:d="http://docbook.org/ns/docbook"
+ exclude-result-prefixes="d">
+
<!-- We need to add this as it's needed later for a check -->
<xsl:param name="confidential" select="0"/>
@@ -203,4 +206,11 @@
<xsl:call-template name="inline.monoseq"/>
</xsl:template>
+<!--
+WL: add <kw> for keywords: bold, monospaced
+-->
+<xsl:template match="d:kw">
+ <xsl:call-template name="inline.boldmonoseq"/>
+</xsl:template>
+
</xsl:stylesheet>
Modified: labs/jbossrules/trunk/drools-docs/docbook-xsl-drools/src/main/resources/org/jboss/xhtml-common.xsl
===================================================================
--- labs/jbossrules/trunk/drools-docs/docbook-xsl-drools/src/main/resources/org/jboss/xhtml-common.xsl 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/docbook-xsl-drools/src/main/resources/org/jboss/xhtml-common.xsl 2009-04-23 18:49:22 UTC (rev 26227)
@@ -17,9 +17,16 @@
<xsl:import href="common.xsl" />
- <!-- Ignore image scaling in html version -->
- <xsl:param name="ignore.image.scaling" select="1"/>
-
+ <!-- Do not ignore image scaling in html version -->
+ <xsl:param name="ignore.image.scaling" select="0"/>
+ <xsl:param name="graphicsize.extension" select="0"></xsl:param>
+
+ <!-- WL: failed experiments - postponed
+ <xsl:param name="use.extensions" select="1"></xsl:param>
+ <xsl:param name="graphicsize.use.img.src.path" select="1"></xsl:param>
+ <xsl:param name="keep.relative.image.uris" select="1"></xsl:param>
+ -->
+
<xsl:param name="generate.legalnotice.link" select="1"/>
<xsl:param name="generate.revhistory.link" select="0"/>
@@ -39,7 +46,6 @@
<xsl:param name="siteLinkText" select="'JBoss.org'"/>
<xsl:param name="docLinkText" select="'Community Documentation'"/>
- <xsl:param name="graphicsize.extension">0</xsl:param>
<!-- Placement of titles -->
<xsl:param name="formal.title.placement">
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Authoring/Section-Decision_Tables.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Authoring/Section-Decision_Tables.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Authoring/Section-Decision_Tables.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -58,7 +58,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Decision_Tables/excel.png"
+ <imagedata width="100%"
+ fileref="images/Chapter-Decision_Tables/excel.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -79,7 +80,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Decision_Tables/open_office.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Decision_Tables/open_office.png" />
</imageobject>
</mediaobject>
</screenshot>
@@ -118,7 +120,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Decision_Tables/multi_table.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Decision_Tables/multi_table.png" />
</imageobject>
</mediaobject>
</screenshot>
@@ -136,7 +139,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Decision_Tables/row_col.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Decision_Tables/row_col.png" />
</imageobject>
</mediaobject>
</screenshot>
@@ -158,7 +162,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Decision_Tables/expanded.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Decision_Tables/expanded.png" />
</imageobject>
</mediaobject>
</screenshot>
@@ -535,7 +540,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Decision_Tables/Key.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Decision_Tables/Key.png" />
</imageobject>
</mediaobject>
</screenshot>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Chapter-Examples.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Chapter-Examples.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Chapter-Examples.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -6,16 +6,17 @@
<title>Examples</title>
<section>
- <title>Getting the examples</title>
+ <title>Getting the Examples</title>
<para>Make sure the Drools Eclipse plugin is installed, which
- needs GEF dependency installed first. Then download and extract the
+ needs the Graphical Editing Framework (GEF) dependency installed
+ first. Then download and extract the
drools-examples zip file, which includes an already created Eclipse
project. Import that project into a new Eclipse workspace. The rules
all have example classes that execute the rules. If you want to try
the examples in another project (or another IDE) then you will need
- to setup the dependencies by hand of course. Many, but not all of the
- examples are documented below, enjoy :)</para>
+ to set up the dependencies by hand, of course. Many, but not all of the
+ examples are documented below, enjoy!</para>
</section>
<xi:include href="Section-HelloWorldExample.xml" />
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-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-ConwaysGameOfLifeExample.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -48,7 +48,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Examples/ConwaysGameOfLifeExample/conway1.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/ConwaysGameOfLifeExample/conway1.png" />
</imageobject>
</mediaobject>
</figure>
@@ -98,7 +99,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Examples/ConwaysGameOfLifeExample/conway2.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/ConwaysGameOfLifeExample/conway2.png" />
</imageobject>
</mediaobject>
</figure>
@@ -318,4 +320,4 @@
update( $neighbor );
end </programlisting>
</example>
- </section>
\ No newline at end of file
+ </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-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-FibonacciExample.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -101,7 +101,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Examples/FibonacciExample/fibonacci1.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/FibonacciExample/fibonacci1.png" />
</imageobject>
</mediaobject>
</figure>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-HelloWorldExample.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-HelloWorldExample.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-HelloWorldExample.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -10,18 +10,18 @@
<screen><emphasis role="bold">Name:</emphasis> Hello World
<emphasis role="bold">Main class:</emphasis> org.drools.examples.HelloWorldExample
-<emphasis role="bold">Type:</emphasis> java application
+<emphasis role="bold">Type:</emphasis> Java application
<emphasis role="bold">Rules file:</emphasis> HelloWorld.drl
<emphasis role="bold">Objective:</emphasis> demonstrate basic rules in use</screen>
<para>The "Hello World" example shows a simple example of rules usage, and
both the MVEL and Java dialects.</para>
- <para>In this example it will be shown how to build knowledgebases and sessions
- and how to add audit logging and debug outputs, this information is ommitted
+ <para>This example demonstrates how to build knowledgebases and sessions.
+ Also, audit logging and debug outputs are shown, which is ommitted
from other examples as it's all very similar. KnowledgeBuilder is used to turn
- a drl source file into Package objects which the KnowledgeBase can consume,
- add takes a Resource interface and ResourceType as parameters. Resource can be
+ a DRL source file into Package objects which the KnowledgeBase can consume.
+ The add method takes a Resource interface and ResourceType as parameters. Resource can be
used to retrieve a source drl file from various locations, in this case the
drl file is being retrieved from the classpath using ResourceFactory; but it could come from
the disk or a url. In this case we only add a single drl source file, but
@@ -147,7 +147,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Examples/HelloWorldExample/helloworld_agenda1.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/HelloWorldExample/helloworld_agenda1.png" />
</imageobject>
</mediaobject>
</figure>
@@ -201,7 +202,7 @@
the changes at the end of the block.</para>
<example>
- <title>HelloWorld example: rule "Hello World"</title>
+ <title>HelloWorld: rule "Hello World"</title>
<programlisting>rule "Hello World"
dialect "mvel"
@@ -235,7 +236,7 @@
dialect is activated and placed on the agenda.</para>
<figure>
- <title>Hello World : rule "Hello World" Agenda View</title>
+ <title>Hello World: rule "Hello World" Agenda View</title>
<mediaobject>
<imageobject>
@@ -273,11 +274,12 @@
Activation executed event.</para>
<figure>
- <title>Hello World : Audit View</title>
+ <title>Hello World: Audit View</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Examples/HelloWorldExample/helloworld_auditview1.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/HelloWorldExample/helloworld_auditview1.png" />
</imageobject>
</mediaobject>
</figure>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-HonestPoliticianExample.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-HonestPoliticianExample.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-HonestPoliticianExample.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -130,7 +130,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Examples/HonestPoliticianExample/honest_politician_audit.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/HonestPoliticianExample/honest_politician_audit.png" />
</imageobject>
</mediaobject>
</figure>
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-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-MannersExample.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -31,8 +31,9 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-Examples/MannersExample/guests_at_table.png"
- format="PNG" scalefit="1" />
+ <imagedata width="100%"
+ align="center" fileref="images/Chapter-Examples/MannersExample/guests_at_table.png"
+ format="PNG"/>
</imageobject>
</mediaobject>
</figure>
@@ -126,8 +127,9 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-Examples/MannersExample/manners_activity_diagram.png"
- format="PNG" scalefit="1" />
+ <imagedata width="100%"
+ align="center" fileref="images/Chapter-Examples/MannersExample/manners_activity_diagram.png"
+ format="PNG" />
</imageobject>
</mediaobject>
</figure>
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-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-NumberGuessExample.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -94,7 +94,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Examples/NumberGuessExample/numberguess-ruleflow.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/NumberGuessExample/numberguess-ruleflow.png" />
</imageobject>
</mediaobject>
</figure>
@@ -120,7 +121,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Examples/NumberGuessExample/numberguess-ruleflow-properties.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/NumberGuessExample/numberguess-ruleflow-properties.png" />
</imageobject>
</mediaobject>
</figure>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-PricingExample.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-PricingExample.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-PricingExample.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -53,7 +53,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Examples/PricingExample/DT_Config.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/PricingExample/DT_Config.png" />
</imageobject>
</mediaobject>
</figure>
@@ -69,7 +70,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Examples/PricingExample/DT_Table1.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/PricingExample/DT_Table1.png" />
</imageobject>
</mediaobject>
</figure>
@@ -81,7 +83,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Examples/PricingExample/DT_Table2.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/PricingExample/DT_Table2.png" />
</imageobject>
</mediaobject>
</figure>
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-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Examples/Section-StateExample.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -119,7 +119,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Examples/StateExample/state_example_audit1.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Examples/StateExample/state_example_audit1.png" />
</imageobject>
</mediaobject>
</figure>
@@ -292,4 +293,4 @@
</section>
- </section>
\ No newline at end of file
+ </section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-IDE/Chapter-QuickStart.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-IDE/Chapter-QuickStart.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-IDE/Chapter-QuickStart.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -34,8 +34,8 @@
<mediaobject xml:base="../">
<imageobject>
- <imagedata align="center" contentwidth="10in"
- fileref="images/Chapter-IDE/all.jpg" format="JPG" scalefit="1" />
+ <imagedata width="100%"
+ fileref="images/Chapter-IDE/all.jpg" format="JPG" />
</imageobject>
</mediaobject>
</figure>
@@ -426,7 +426,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-IDE/audit.jpg" scalefit="1" width="100%" />
+ <imagedata width="100%"
+ fileref="images/Chapter-IDE/audit.jpg" />
</imageobject>
</mediaobject>
@@ -550,7 +551,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-IDE/dsl_editor.jpg" format="JPG" />
+ <imagedata width="100%"
+ align="center" fileref="images/Chapter-IDE/dsl_editor.jpg" format="JPG" />
</imageobject>
</mediaobject>
</figure>
@@ -675,7 +677,8 @@
<title>Debugging</title>
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-IDE/debug-overview.png" format="PNG"/>
+ <imagedata width="100%"
+ align="center" fileref="images/Chapter-IDE/debug-overview.png" format="PNG"/>
</imageobject>
</mediaobject>
</figure>
@@ -721,7 +724,8 @@
<title>Debug as Drools Application</title>
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-IDE/debugAsDrools.png" format="PNG" role="" />
+ <imagedata width="100%"
+ align="center" fileref="images/Chapter-IDE/debugAsDrools.png" format="PNG" role="" />
</imageobject>
</mediaobject>
</figure>
@@ -768,7 +772,8 @@
<title>Debug as Drools Application Configuration</title>
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-IDE/debug_rules_configuration.png" format="PNG" role="" />
+ <imagedata width="100%"
+ align="center" fileref="images/Chapter-IDE/debug_rules_configuration.png" format="PNG" role="" />
</imageobject>
</mediaobject>
</figure>
@@ -788,7 +793,8 @@
<title>Debugging</title>
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-IDE/debug.png" format="PNG"/>
+ <imagedata width="100%"
+ align="center" fileref="images/Chapter-IDE/debug.png" format="PNG"/>
</imageobject>
</mediaobject>
</figure>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-ErrorMessages.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-ErrorMessages.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-ErrorMessages.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -204,7 +204,7 @@
</itemizedlist>
<para>Note that the second problem is related to the first. To fix it,
- just replace the commas (",") by AND operator ("&&").</para>
+ just replace the commas (',') by AND operator ('&&').</para>
<tip>
<para>In some situations you can get more than one error message. Try to
@@ -249,7 +249,7 @@
</itemizedlist>
<para>The <emphasis role="bold">fdsfdsfds</emphasis> text is invalid and
- the parser couldn’t identify it as the soft keyword "rule".</para>
+ the parser couldn’t identify it as the soft keyword <kw>rule</kw>.</para>
<tip>
<para>This error is very similar to 102: Mismatched input, but usually
@@ -260,7 +260,7 @@
<section>
<title>104: Trailing semi-colon not allowed</title>
- <para>This error is associated with the "eval" clause, where its
+ <para>This error is associated with the <kw>eval</kw> clause, where its
expression may not be terminated with a semicolon. Check this
example:</para>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Function.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Function.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Function.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -24,7 +24,7 @@
for you behind the scenes.) The main advantage of using functions in a rule
is that you can keep the logic all in one place, and you can change the
functions as needed (which can be a good or a bad thing). Functions are most
- useful for invoking actions on the consequence ("then") part of a rule,
+ useful for invoking actions on the consequence (<kw>then</kw>) part of a rule,
especially if that particular action is used over and over again, perhaps
with only differing parameters for each rule.</para>
@@ -35,7 +35,7 @@
}
</programlisting>
- <para>Note that the "function" keyword is used, even though its not really
+ <para>Note that the <kw>function</kw> keyword is used, even though its not really
part of Java. Parameters to the function are defined as for a method, and
you don't have to have parameters if they are not needed. The return type
is defined just like in a regular method.</para>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Keywords.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Keywords.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Keywords.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -26,39 +26,39 @@
<itemizedlist>
<listitem>
- <para>true</para>
+ <para><kw>true</kw></para>
</listitem>
<listitem>
- <para>false</para>
+ <para><kw>false</kw></para>
</listitem>
<listitem>
- <para>accumulate</para>
+ <para><kw>accumulate</kw></para>
</listitem>
<listitem>
- <para>collect</para>
+ <para><kw>collect</kw></para>
</listitem>
<listitem>
- <para>from</para>
+ <para><kw>from</kw></para>
</listitem>
<listitem>
- <para>null</para>
+ <para><kw>null</kw></para>
</listitem>
<listitem>
- <para>over</para>
+ <para><kw>over</kw></para>
</listitem>
<listitem>
- <para>then</para>
+ <para><kw>then</kw></para>
</listitem>
<listitem>
- <para>when</para>
+ <para><kw>when</kw></para>
</listitem>
</itemizedlist>
@@ -68,143 +68,143 @@
<itemizedlist>
<listitem>
- <para>lock-on-active</para>
+ <para><kw>lock-on-active</kw></para>
</listitem>
<listitem>
- <para>date-effective</para>
+ <para><kw>date-effective</kw></para>
</listitem>
<listitem>
- <para>date-expires</para>
+ <para><kw>date-expires</kw></para>
</listitem>
<listitem>
- <para>no-loop</para>
+ <para><kw>no-loop</kw></para>
</listitem>
<listitem>
- <para>auto-focus</para>
+ <para><kw>auto-focus</kw></para>
</listitem>
<listitem>
- <para>activation-group</para>
+ <para><kw>activation-group</kw></para>
</listitem>
<listitem>
- <para>agenda-group</para>
+ <para><kw>agenda-group</kw></para>
</listitem>
<listitem>
- <para>ruleflow-group</para>
+ <para><kw>ruleflow-group</kw></para>
</listitem>
<listitem>
- <para>entry-point</para>
+ <para><kw>entry-point</kw></para>
</listitem>
<listitem>
- <para>duration</para>
+ <para><kw>duration</kw></para>
</listitem>
<listitem>
- <para>package</para>
+ <para><kw>package</kw></para>
</listitem>
<listitem>
- <para>import</para>
+ <para><kw>import</kw></para>
</listitem>
<listitem>
- <para>dialect</para>
+ <para><kw>dialect</kw></para>
</listitem>
<listitem>
- <para>salience</para>
+ <para><kw>salience</kw></para>
</listitem>
<listitem>
- <para>enabled</para>
+ <para><kw>enabled</kw></para>
</listitem>
<listitem>
- <para>attributes</para>
+ <para><kw>attributes</kw></para>
</listitem>
<listitem>
- <para>rule</para>
+ <para><kw>rule</kw></para>
</listitem>
<listitem>
- <para>extend</para>
+ <para><kw>extend</kw></para>
</listitem>
<listitem>
- <para>template</para>
+ <para><kw>template</kw></para>
</listitem>
<listitem>
- <para>query</para>
+ <para><kw>query</kw></para>
</listitem>
<listitem>
- <para>declare</para>
+ <para><kw>declare</kw></para>
</listitem>
<listitem>
- <para>function</para>
+ <para><kw>function</kw></para>
</listitem>
<listitem>
- <para>global</para>
+ <para><kw>global</kw></para>
</listitem>
<listitem>
- <para>eval</para>
+ <para><kw>eval</kw></para>
</listitem>
<listitem>
- <para>not</para>
+ <para><kw>not</kw></para>
</listitem>
<listitem>
- <para>in</para>
+ <para><kw>in</kw></para>
</listitem>
<listitem>
- <para>or</para>
+ <para><kw>or</kw></para>
</listitem>
<listitem>
- <para>and</para>
+ <para><kw>and</kw></para>
</listitem>
<listitem>
- <para>exists</para>
+ <para><kw>exists</kw></para>
</listitem>
<listitem>
- <para>forall</para>
+ <para><kw>forall</kw></para>
</listitem>
<listitem>
- <para>action</para>
+ <para><kw>action</kw></para>
</listitem>
<listitem>
- <para>reverse</para>
+ <para><kw>reverse</kw></para>
</listitem>
<listitem>
- <para>result</para>
+ <para><kw>result</kw></para>
</listitem>
<listitem>
- <para>end</para>
+ <para><kw>end</kw></para>
</listitem>
<listitem>
- <para>init</para>
+ <para><kw>init</kw></para>
</listitem>
</itemizedlist>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Overview.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Overview.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Overview.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -15,7 +15,8 @@
with this native rule format. The diagrams used to present the syntax are
known as "railroad" diagrams, and they are basically flow charts for the
language terms. The
- technically very keen may also refer to "DRL.g" which is the Antlr3
+ technically very keen may also refer to <filename>DRL.g</filename> which is
+ the Antlr3
grammar for the rule language. If you use the Rule Workbench, a lot of the
rule structure is done for you with content assistance, for example, type
"ru" and press ctrl+space, and it will build the rule structure for
@@ -24,7 +25,7 @@
<section>
<title>A rule file</title>
- <para>A rule file is typically a file with a .drl extension. In a drl file
+ <para>A rule file is typically a file with a .drl extension. In a DRL file
you can have multiple rules, queries and functions, as well as some
resource declarations like imports, globals and attributes that are
assigned and used by your rules and queries. However, you are also able to
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Package.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Package.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Package.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -27,8 +27,8 @@
up a package. Note that a package <emphasis>must</emphasis> have a namespace and be declared
using standard Java conventions for package names; i.e., no spaces, unlike
rule names which allow spaces. In terms of the order of elements, they can
- appear in any order in the rule file, with the exception of the "package"
- and "expander" statements being at the top of the file, before any rules
+ appear in any order in the rule file, with the exception of the <kw>package</kw>
+ and <kw>expander</kw> statements being at the top of the file, before any rules
appear. In all cases, the semicolons are optional.</para>
<figure>
@@ -101,7 +101,7 @@
</mediaobject>
</figure>
- <para>With global you define global variables. They are used to make
+ <para>With <kw>global</kw> you define global variables. They are used to make
application objects available to the rules. Typically, they are used
to provide data or services that the rules use, especially application
services used in rule consequences, and to return data from the rules,
@@ -151,8 +151,8 @@
<para>Note that these are just named instances of objects that you pass in
from your application to the working memory. This means you can pass in
any object you want: you could pass in a service locator, or perhaps a
- service itself. With the new 'from' element it is now common to pass a
- Hibernate session as a global, to allow 'from' to pull data from a named
+ service itself. With the new <kw>from</kw> element it is now common to pass a
+ Hibernate session as a global, to allow <kw>from</kw> to pull data from a named
Hibernate query.</para>
<para>One example may be an instance of a Email service. In your
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Rule.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Rule.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Rule.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -40,9 +40,9 @@
<para>Attributes - described below - are optional. They are best written
one per line.</para>
- <para>The LHS of the rule follows the "when" keyword (ideally on a new
- line), similarly the RHS follows the "then" keyword (again, ideally on
- a newline). The rule is terminated by the keyword "end". Rules cannot
+ <para>The LHS of the rule follows the <kw>when</kw> keyword (ideally on a new
+ line), similarly the RHS follows the <kw>then</kw> keyword (again, ideally on
+ a newline). The rule is terminated by the keyword <kw>end</kw>. Rules cannot
be nested.</para>
<example>
@@ -94,7 +94,7 @@
<variablelist>
<varlistentry>
- <term>no-loop</term>
+ <term><kw>no-loop</kw></term>
<listitem>
<para>default value: false</para>
@@ -110,7 +110,7 @@
</varlistentry>
<varlistentry>
- <term>ruleflow-group</term>
+ <term><kw>ruleflow-group</kw></term>
<listitem>
<para>default value: N/A</para>
@@ -125,7 +125,7 @@
</varlistentry>
<varlistentry>
- <term>lock-on-active</term>
+ <term><kw>lock-on-active</kw></term>
<listitem>
<para>default value: false</para>
@@ -149,7 +149,7 @@
</varlistentry>
<varlistentry>
- <term>salience</term>
+ <term><kw>salience</kw></term>
<listitem>
<para>default value : 0</para>
@@ -166,7 +166,7 @@
<varlistentry>
- <term>agenda-group</term>
+ <term><kw>agenda-group</kw></term>
<listitem>
<para>default value: MAIN</para>
@@ -180,7 +180,7 @@
</varlistentry>
<varlistentry>
- <term>auto-focus</term>
+ <term><kw>auto-focus</kw></term>
<listitem>
<para>default value: false</para>
@@ -195,7 +195,7 @@
</varlistentry>
<varlistentry>
- <term>activation-group</term>
+ <term><kw>activation-group</kw></term>
<listitem>
<para>default value: N/A</para>
@@ -214,7 +214,7 @@
</varlistentry>
<varlistentry>
- <term>dialect</term>
+ <term><kw>dialect</kw></term>
<listitem>
<para>default value: as specified by the package</para>
@@ -233,7 +233,7 @@
<varlistentry>
- <term>date-effective</term>
+ <term><kw>date-effective</kw></term>
<listitem>
<para>default value: N/A</para>
@@ -245,8 +245,8 @@
</listitem>
</varlistentry>
- <varlistentry>
- <term>date-expires</term>
+ <varlistentry>
+ <term><kw>date-expires</kw></term>
<listitem>
<para>default value: N/A</para>
@@ -259,7 +259,7 @@
</varlistentry>
<varlistentry>
- <term>duration</term>
+ <term><kw>duration</kw></term>
<listitem>
<para>default value: no default value</para>
@@ -322,11 +322,11 @@
</example>
<para>Conditional elements work on one or more <emphasis>patterns</emphasis> (which are
- described below). The most common one is "and", which is implicit when you
+ described below). The most common one is <kw>and</kw>, which is implicit when you
have multiple patterns in the LHS of a rule that are not connected in
- any way. Note that an "and" cannot have a leading declaration binding like
- "or". This is obvious, since a declaration can only
- reference a single fact, and when the "and" is satisfied it matches more
+ any way. Note that an <kw>and</kw> cannot have a leading declaration binding like
+ <kw>or</kw>. This is obvious, since a declaration can only
+ reference a single fact, and when the <kw>and</kw> is satisfied it matches more
than one fact - so which fact would the declaration bind to?</para>
<section>
@@ -381,7 +381,8 @@
</example>
<para>For referring to the matched object, use a pattern binding
- variable such as '$c'. The prefixed '$' symbol is optional; it can
+ variable such as <code>$c</code>. The prefixed dollar symbol ('$')
+ is optional; it can
be useful in complex rules where it helps to more easily
differentiate between variables and fields.</para>
@@ -430,8 +431,8 @@
</mediaobject>
</figure>
- <para>The ',' (comma) character is used to separate constraint groups.
- It has implicit "and" connective semantics.<example>
+ <para>The comma character (',') is used to separate constraint groups.
+ It has implicit and connective semantics.<example>
<title>Constraint Group connective ','</title>
<programlisting># Cheese type is stilton and price < 10 and age is mature.
@@ -563,13 +564,13 @@
<code>Cheese(type == "brie")</code> applies the getType() method
to a Cheese instance. If a field name cannot be found, the
compiler will resort to using the name as a method without
- arguments. Thus, the method "toString()" is called due to a
+ arguments. Thus, the method <code>toString()</code> is called due to a
constraint <code>Cheese(toString == "cheddar")</code>. In this
case, you use the full name of the method with correct
capitalization, but still without parentheses. Do
please make sure that you are accessing methods that take no
- parameters, and that are in fact "accessors" which don't change
- the state of the object in a way that may effect the rules.
+ parameters, and that are in fact <emphasis>accessors</emphasis>
+ which don't change the state of the object in a way that may effect the rules.
Remember that the rule engine effectively caches the results of its
matching in between invocations to make it faster.</para>
</section>
@@ -626,7 +627,7 @@
</figure>
<para>You can do checks against fields that are or may be null, using
- '==' and '!=' as you would expect, and the literal "null" keyword, as
+ '==' and '!=' as you would expect, and the literal <kw>null</kw> keyword, as
in <code>Cheese(type != null)</code>, where the evaluator will not
throw an exception and return true if the value is null.
Type coercion is always attempted if the field and the value are
@@ -673,14 +674,14 @@
<para>The operators '==' and '!=' are valid for all types. Other
relational operatory may be used whenever the type values are
- ordered; for date fields, "<" means "before". The pair "matches" and
- "not matches" is only applicable to string fields, "contains" and
- "not contains" require the field to be of some Collection type.
+ ordered; for date fields, '<' means "before". The pair <kw>matches</kw> and
+ <kw>not matches</kw> is only applicable to string fields, <kw>contains</kw> and
+ <kw>not contains</kw> require the field to be of some Collection type.
Coercion to the correct value for the evaluator and the field will be
attempted, as mentioned in the "Values" section.</para>
<simplesect>
- <title>Matches Operator</title>
+ <title>The Operator <kw>matches</kw></title>
<para>Matches a field against any valid Java <indexterm>
<primary>regular expression</primary>
@@ -698,10 +699,10 @@
</simplesect>
<simplesect>
- <title>Not Matches Operator</title>
+ <title>The Operator <kw>not matches</kw></title>
<para>The operator returns true if the string does not match the
- regular expression. The same rules apply as for the "matches" operator.
+ regular expression. The same rules apply as for the <kw>matches</kw> operator.
Example:</para>
<example>
@@ -712,9 +713,9 @@
</simplesect>
<simplesect>
- <title>Contains Operator</title>
+ <title>The Operator <kw>contains</kw></title>
- <para>The operator <code>contains</code> is used to check whether a
+ <para>The operator <kw>contains</kw> is used to check whether a
field that is a <indexterm>
<primary>Collection</primary>
</indexterm>Collection or array contains the specified
@@ -729,9 +730,9 @@
</simplesect>
<simplesect>
- <title>not contains</title>
+ <title>The Operator <kw>not contains</kw></title>
- <para>The operator <code>not contains</code> is used to check whether a
+ <para>The operator <kw>not contains</kw> is used to check whether a
field that is a <indexterm>
<primary>Collection</primary>
</indexterm>Collection or array does <emphasis>not</emphasis> contain the
@@ -745,17 +746,15 @@
</example>
<blockquote>
- <para><emphasis role="bold">Note: </emphasis>for backward
- compatibility, the <emphasis role="bold">excludes</emphasis>
- operator is supported as a synonym for <emphasis role="bold">not
- contains</emphasis>.</para>
+ <note><para>For backward compatibility, the <kw>excludes</kw>
+ operator is supported as a synonym for <kw>not contains</kw>.</para></note>
</blockquote>
</simplesect>
<simplesect>
- <title>memberOf</title>
+ <title>The Operator <kw>memberOf</kw></title>
- <para>The operator <code>memberOf</code> is used to check whether a field is a
+ <para>The operator <kw>memberOf</kw> is used to check whether a field is a
member of a collection or array; that collection must be a variable.</para>
<example>
@@ -766,9 +765,9 @@
</simplesect>
<simplesect>
- <title>not memberOf</title>
+ <title>The Operator <kw>not memberOf</kw></title>
- <para>The operator <code>not memberOf</code> is used to check whether a
+ <para>The operator <kw>not memberOf</kw> is used to check whether a
field is not a
member of a collection or array; that collection must be a variable.</para>
@@ -780,9 +779,9 @@
</simplesect>
<simplesect>
- <title>soundslike</title>
+ <title>The Operator <kw>soundslike</kw></title>
- <para>This operator is similar to <code>matches</code>, but it checks
+ <para>This operator is similar to <kw>matches</kw>, but it checks
whether a word has almost the same sound (using English pronounciation)
as the given value. This is based on the Soundex algorithm
(see <code>http://en.wikipedia.org/wiki/Soundex</code>).</para>
@@ -834,7 +833,7 @@
<para>The date format "dd-mmm-yyyy" is supported by default. You
can customize this by providing an alternative date format mask
- as the System property named "drools.dateformat". If more control
+ as the System property named <code>drools.dateformat</code>. If more control
is required, use the inline-eval constraint.</para>
<example>
@@ -970,8 +969,8 @@
<title>Compound Value Restriction</title>
<para>The compound value restriction is used where there is more
- than one possible value to match. Currently only the "in" and "not in"
- evaluators support this. The second operand of this operator must be
+ than one possible value to match. Currently only the <kw>in</kw> and
+ <kw>not in</kw> evaluators support this. The second operand of this operator must be
a comma-separated list of values, enclosed in parentheses. Values may
be given as variables, literals, return values or qualified identifiers.
Both evaluators are actually "syntactic sugar", internally rewritten as
@@ -1098,7 +1097,7 @@
you wish to modify a nested value you should remove the parent objects
first and re-assert afterwards. If you only have a single parent at
the root of the graph, when in the MVEL dialect, you can use the
- "modify" construct and its block setters to write the nested accessor
+ <kw>modify</kw> construct and its block setters to write the nested accessor
assignments while retracting and inserting the the root parent object
as required. Nested accessors can be used on either side of the operator
symbol.</para>
@@ -1123,12 +1122,12 @@
</section>
<section>
- <title>Conditional Element "and"</title>
+ <title>Conditional Element <kw>and</kw></title>
- <para>The Conditional Element "and" is used to group other Conditional
+ <para>The Conditional Element <kw>and</kw> is used to group other Conditional
Elements into a logical conjunction. The root element of the LHS is an
- implicit prefix "and" and doesn't need to be specified. Drools supports
- both prefix "and" and infix "and", but prefix is the preferred option
+ implicit prefix <kw>and</kw> and doesn't need to be specified. Drools supports
+ both prefix <kw>and</kw> and infix <kw>and</kw>, but prefix is the preferred option
as its implicit grouping avoids confusion.</para>
<figure>
@@ -1160,9 +1159,9 @@
Person( favouriteCheese == cheeseType )</programlisting>
</example>
- <para>Infix "and" is supported along with explicit grouping with
+ <para>Infix <kw>and</kw> is supported along with explicit grouping with
parentheses, should it be needed. The symbol '&&', as an
- alternative to "and", is deprecated although it is still supported in
+ alternative to <kw>and</kw>, is deprecated although it is still supported in
the syntax for legacy support reasons.</para>
<figure>
@@ -1189,17 +1188,17 @@
</section>
<section>
- <title>Conditional Element "or"</title>
+ <title>Conditional Element <kw>or</kw></title>
- <para>The Conditional Element "or" is used to group other Conditional
- Elements into a logical disjunction. Drools supports both prefix "or" and
- infix "or", but prefix is the preferred option as its implicit grouping
- avoids confusion. The behavior of the Conditional Element "or" is different
+ <para>The Conditional Element <kw>or</kw> is used to group other Conditional
+ Elements into a logical disjunction. Drools supports both prefix <kw>or</kw> and
+ infix <kw>or</kw>, but prefix is the preferred option as its implicit grouping
+ avoids confusion. The behavior of the Conditional Element <kw>or</kw> is different
from the connective '||' for constraints and restrictions in field
constraints. The engine actually has no understanding of the Conditional
- Element "or"; instead, via a number of different logic transformations,
- a rule with "or" is rewritten as a number of subrules. This process ultimately
- results in a rule that has a single "or" as the root node and one subrule
+ Element <kw>or</kw>; instead, via a number of different logic transformations,
+ a rule with <kw>or</kw> is rewritten as a number of subrules. This process ultimately
+ results in a rule that has a single <kw>or</kw> as the root node and one subrule
for each of its CEs. Each subrule can activate and fire like any normal rule;
there is no special behavior or interaction between these subrules. - This can
be most confusing to new rule authors.</para>
@@ -1223,9 +1222,9 @@
</programlisting>
</example>
- <para>Infix "or" is supported along with explicit grouping with
+ <para>Infix <kw>or</kw> is supported along with explicit grouping with
parentheses, should it be needed. The symbol '||', as an alternative to
- "or", is deprecated although it is still supported in the syntax for
+ <kw>or</kw>, is deprecated although it is still supported in the syntax for
legacy support reasons.</para>
<figure>
@@ -1250,7 +1249,7 @@
Person( favouriteCheese == cheeseType ) )</programlisting>
</example>
- <para>The Conditional Element "or" also allows for optional pattern
+ <para>The Conditional Element <kw>or</kw> also allows for optional pattern
binding. This means that each resulting subrule will bind its pattern to
the pattern binding. Each pattern must be bound separately,
using eponymous variables:</para>
@@ -1262,13 +1261,13 @@
pensioner : Person( sex == "m", age > 65 ) )</programlisting>
</example>
- <para>Since the conditional element "or" results in multiple subrule
+ <para>Since the conditional element <kw>or</kw> results in multiple subrule
generation, one for each possible logically outcome, the example above
would result in the internal generation of two rules. These two rules
work independently within the Working Memory, which means both can
match, activate and fire - there is no shortcutting.</para>
- <para>The best way to think of the conditional element "or" is as a
+ <para>The best way to think of the conditional element <kw>or</kw> is as a
shortcut for generating two or more similar rules. When you think
of it that
way, it's clear that for a single rule there could be multiple
@@ -1276,7 +1275,7 @@
</section>
<section>
- <title>Conditional Element "eval"</title>
+ <title>Conditional Element <kw>eval</kw></title>
<figure>
<title>eval</title>
@@ -1288,11 +1287,11 @@
</mediaobject>
</figure>
- <para>The CE "eval" is essentially a catch-all which allows any semantic code
+ <para>The CE <kw>eval</kw> is essentially a catch-all which allows any semantic code
(that returns a primitive boolean) to be executed. This code can refer to
variables that were bound in the LHS of the rule, and functions in the
rule package. Overuse of eval reduces the declarativeness of your rules
- and can result in a poorly performing engine. While "eval" can be used
+ and can result in a poorly performing engine. While <kw>eval</kw> can be used
anywhere in the patterns, the best practice is to add it as the last
conditional element in the LHS of a rule.</para>
@@ -1317,7 +1316,7 @@
</section>
<section>
- <title>Conditional Element "not"</title>
+ <title>Conditional Element <kw>not</kw></title>
<figure>
<title>not</title>
@@ -1330,11 +1329,11 @@
</mediaobject>
</figure>
- <para>The CS "not" is first order logic's non-existential quantifier and checks
+ <para>The CE <kw>not</kw> is first order logic's non-existential quantifier and checks
for the non-existence of something in the Working Memory. Think of "not"
as meaning "there must be none of...".</para>
- <para>The keyword "not" be followed by parentheses around the CEs
+ <para>The keyword <kw>not</kw> be followed by parentheses around the CEs
that it applies to. In the simplest case of a single pattern (like
below) you may optionally omit the parentheses.</para>
@@ -1351,7 +1350,7 @@
not Bus(color == "red")
// Brackets are optional:
not ( Bus(color == "red", number == 42) )
-// "not" with nested infix "and" - two patterns,
+// "not" with nested infix <kw>and</kw> - two patterns,
// brackets are requires:
not ( Bus(color == "red") and
Bus(color == "blue") )</programlisting>
@@ -1359,7 +1358,7 @@
</section>
<section>
- <title>Conditional Element "exists"</title>
+ <title>Conditional Element <kw>exists</kw></title>
<figure>
<title>exists</title>
@@ -1372,16 +1371,16 @@
</mediaobject>
</figure>
- <para>The CE "exists" is first order logic's existential quantifier and checks
+ <para>The CE <kw>exists</kw> is first order logic's existential quantifier and checks
for the existence of something in the Working Memory. Think of "exists" as
meaning "there is at least one..". It is different from just having the pattern
on its own, which is more like saying "for each one of...". If you use
- "exists" with a pattern, the rule will only activate at most once, regardless
+ <kw>exists</kw> with a pattern, the rule will only activate at most once, regardless
of how much data there is in working memory that matches the
- condition inside of the "exists". Since only the existence matters, no bindings
- will be established.</para>
+ condition inside of the <kw>exists</kw> pattern. Since only the existence matters,
+ no bindings will be established.</para>
- <para>The keyword "exists" must be followed by parentheses around the
+ <para>The keyword <kw>exists</kw> must be followed by parentheses around the
CEs that it applies to. In the simplest case of a single pattern (like
below) you may optionally omit the parentheses.</para>
@@ -1397,7 +1396,7 @@
<programlisting>exists Bus(color == "red")
// brackets are optional:
exists ( Bus(color == "red", number == 42) )
-// "exists" with nested infix "and",
+// "exists" with nested infix <kw>and</kw>,
// brackets are required:
exists ( Bus(color == "red") and
Bus(color == "blue") )</programlisting>
@@ -1405,7 +1404,7 @@
</section>
<section>
- <title>Conditional Element "forall"</title>
+ <title>Conditional Element <kw>forall</kw></title>
<figure>
<title>forall</title>
@@ -1418,8 +1417,8 @@
</mediaobject>
</figure>
- <para>The Conditional Element "forall" completes the First Order Logic
- support in Drools. The Conditional Element "forall" evaluates to true
+ <para>The Conditional Element <kw>forall</kw> completes the First Order Logic
+ support in Drools. The Conditional Element <kw>forall</kw> evaluates to true
when all facts that match the first pattern match all the remaining
patterns. Example:</para>
@@ -1438,7 +1437,7 @@
true.</para>
<para>To state that all facts of a given type in the working memory must
- match a set of constraints, "forall" can be written with a single pattern
+ match a set of constraints, <kw>forall</kw> can be written with a single pattern
for simplicity. Example:</para>
<para><example>
@@ -1453,7 +1452,7 @@
</programlisting>
</example></para>
- <para>Another example shows multiple patterns inside the "forall":<example>
+ <para>Another example shows multiple patterns inside the <kw>forall</kw>:<example>
<title>Multi-Pattern Forall</title>
<programlisting>rule "all employees have health and dental care programs"
@@ -1469,7 +1468,7 @@
</example></para>
<para>Forall can be nested inside other CEs for complete expressiveness.
- For instance, "forall" can be used inside a "not" CE. Note that only single
+ For instance, <kw>forall</kw> can be used inside a <kw>not</kw> CE. Note that only single
patterns have optional parentheses, so that with a nested forall parentheses
must be used :<example>
<title>Combining Forall with Not CE</title>
@@ -1491,14 +1490,14 @@
<programlisting>not(p1 and not(and p2 p3...))</programlisting>
- <para>Also, it is important to note that "forall" is a <emphasis>scope
+ <para>Also, it is important to note that <kw>forall</kw> is a <emphasis>scope
delimiter</emphasis>. Therefore, it can use any previously bound
variable, but no variable bound inside it will be available for use
outside of it.</para>
</section>
<section>
- <title>Conditional Element "from"</title>
+ <title>Conditional Element <kw>from</kw></title>
<figure>
<title>from</title>
@@ -1510,7 +1509,7 @@
</mediaobject>
</figure>
- <para>The Conditional Element "from" enables users to specify an arbitrary
+ <para>The Conditional Element <kw>from</kw> enables users to specify an arbitrary
source for data to be matched by LHS patterns. This
allows the engine to reason over data not in the Working Memory. The data
source could be a sub-field on a bound variable or the results of a method
@@ -1550,8 +1549,8 @@
</programlisting></para>
<para>Previous examples were evaluations using a single pattern. The
- CE "from" also support object sources that return a collection of objects.
- In that case, "from" will iterate over all objects in the
+ CE <kw>from</kw> also support object sources that return a collection of objects.
+ In that case, <kw>from</kw> will iterate over all objects in the
collection and try to match each of them individually. For instance, if
we want a rule that applies 10% discount to each item in an order, we
could do:</para>
@@ -1568,9 +1567,9 @@
<para>The above example will cause the rule to fire once for each item
whose value is greater than 100 for each given order.</para>
- <para>You must take caution, however, when using "from",
+ <para>You must take caution, however, when using <kw>from</kw>,
especially in conjunction with the
- <emphasis role="bold">lock-on-active</emphasis> rule attribute
+ <kw>lock-on-active</kw> rule attribute
as it may produce unexpected results. Consider the example provided earlier, but
now slightly modified as follows:</para>
@@ -1601,28 +1600,27 @@
will find that only the second rule fires.</para>
<para>If you were to turn on the audit log, you would also see that when the second rule fires,
- it deactivates the first rule. Since the rule attribute <emphasis role="bold">lock-on-active</emphasis>
+ it deactivates the first rule. Since the rule attribute <kw>lock-on-active</kw>
prevents a rule from creating new activations when a set of facts change, the first rule fails to
reactivate. Though the set of facts have not changed, the use of
- "from" returns a new fact for all intents and purposes each time
+ <kw>from</kw> returns a new fact for all intents and purposes each time
it is evaluated.
</para>
<para>First, it's important to review why you would use the above pattern. You may have
many rules across different rule-flow groups. When rules modify working memory and other rules
- downstream of your RuleFlow (in different rule-flow groups) need to be reevaluated, the use of <emphasis role="bold">modify</emphasis>
- is critical. You don't, however, want other rules in the same rule-flow group to place
- activations on one another recursively. In this case, the <emphasis role="bold">no-loop</emphasis>
- attribute is ineffective, as it would only prevent a rule from activating itself recursively. Hence,
- you resort to <emphasis role="bold">lock-on-active</emphasis>.
- </para>
+ downstream of your RuleFlow (in different rule-flow groups) need to be reevaluated,
+ the use of <kw>modify</kw> is critical. You don't, however, want other rules in the
+ same rule-flow group to place activations on one another recursively. In this case,
+ the <kw>no-loop</kw> attribute is ineffective, as it would only prevent a rule from
+ activating itself recursively. Hence, you resort to <kw>lock-on-active</kw>.</para>
<para>
There are several ways to address this issue:</para>
<itemizedlist>
<listitem>
- <para>Avoid the use of "from" when you can assert all facts into working memory
+ <para>Avoid the use of <kw>from</kw> when you can assert all facts into working memory
or use nested object references in your constraint expressions (shown below).</para>
</listitem>
<listitem>
@@ -1630,13 +1628,13 @@
in your condition (LHS).</para>
</listitem>
<listitem>
- <para>Avoid the use of <emphasis role="bold">lock-on-active</emphasis> when you
+ <para>Avoid the use of <kw>lock-on-active</kw> when you
can explicitly manage how rules within the same rule-flow group place
activations on one another (explained below).</para>
</listitem>
</itemizedlist>
- <para>The preferred solution is to minimize use of "from" when you can assert
+ <para>The preferred solution is to minimize use of <kw>from</kw> when you can assert
all your facts into working memory directly. In the example above, both the
Person and Address instance can be asserted into working memory. In this case,
because the graph is fairly simple, an even easier solution is to modify your
@@ -1666,12 +1664,12 @@
holds one or more Addresses and you wish to use an existential quantifier to
match people with at least one address that meets certain conditions.
In this case, you would have to resort to
- the use of "from" to reason over the collection.</para>
+ the use of <kw>from</kw> to reason over the collection.</para>
<para>
- There are several ways to use "from" to achieve this and not all of them
- exhibit an issue with the use of <emphasis role="bold">lock-on-active</emphasis>.
- For example, the following use of "from" causes both rules to fire as
+ There are several ways to use <kw>from</kw> to achieve this and not all of them
+ exhibit an issue with the use of <kw>lock-on-active</kw>.
+ For example, the following use of <kw>from</kw> causes both rules to fire as
expected:</para>
<para><programlisting>rule "Assign people in North Carolina (NC) to sales region 1"
@@ -1722,29 +1720,28 @@
end</programlisting></para>
<para>In the above example, the $addresses variable is returned from the
- use of <emphasis role="bold">from</emphasis>. The example also introduces
+ use of <kw>from</kw>. The example also introduces
a new object, assessment, to highlight one possible solution in this case.
If the $assessment variable assigned in the condition (LHS) is moved to the last condition
in each rule, both rules fire as expected.
</para>
<para>
- Though the above examples demonstrate how to combine the use of "from"
- with <emphasis role="bold">lock-on-active</emphasis> where no loss of
- rule activations occurs, they carry the drawback of placing a dependency
+ Though the above examples demonstrate how to combine the use of <kw>from</kw>
+ with <kw>lock-on-active</kw> where no loss of rule activations occurs, they
+ carry the drawback of placing a dependency
on the order of conditions on the LHS. In addition, the solutions present
greater complexity for the rule author in terms of keeping track of
which conditions may create issues.</para>
<para>A better alternative is to
assert more facts into working memory. In this case, a person's addresses
- may be asserted into working memory and the use of "from"
+ may be asserted into working memory and the use of <kw>from</kw>
would not be necessary.</para>
<para>There are cases, however, where asserting all data into working memory is not
practical and we need to find other solutions. Another option is to reevaluate the
- need for <emphasis role="bold">lock-on-active</emphasis>.
- An alternative to <emphasis role="bold">lock-on-active</emphasis> is to
+ need for <kw>lock-on-active</kw>. An alternative to <kw>lock-on-active</kw> is to
directly manage how rules within the same rule-flow group activate one another
by including conditions in each rule that prevent rules from activating
each other recursively when working memory is modified. For example, in the
@@ -1755,7 +1752,7 @@
</section>
<section>
- <title>Conditional Element "collect"</title>
+ <title>Conditional Element <kw>collect</kw></title>
<figure>
<title>collect</title>
@@ -1768,7 +1765,7 @@
</mediaobject>
</figure>
- <para>The Conditional Element "collect" allows rules to reason over a collection
+ <para>The Conditional Element <kw>collect</kw> allows rules to reason over a collection
of objects obtained from the given source or from the working memory. In First
Oder Logic terms this is the cardinality quantifier. A simple example:</para>
@@ -1791,7 +1788,7 @@
If 3 or more alarms are found for a given system, the rule will
fire.</para>
- <para>The result pattern of "collect" can
+ <para>The result pattern of <kw>collect</kw> can
be any concrete class that implements the <code>java.util.Collection</code>
interface
and provides a default no-arg public constructor. This means that you can use
@@ -1802,13 +1799,13 @@
<para>Both source and result patterns can be constrained as any other
pattern.</para>
- <para>Variables bound before the "collect" CE are in the scope of both source and
+ <para>Variables bound before the <kw>collect</kw> CE are in the scope of both source and
result patterns and therefore you can use them to constrain both your
- source and result patterns. But note that "collect" is a scope delimiter for
+ source and result patterns. But note that <kw>collect</kw> is a scope delimiter for
bindings, so that any binding made inside of it is not available for use
outside of it.</para>
- <para>Collect accepts nested "from" CEs. The following example is a valid
+ <para>Collect accepts nested <kw>from</kw> CEs. The following example is a valid
use of "collect":</para>
<programlisting>import java.util.LinkedList;
@@ -1827,7 +1824,7 @@
</section>
<section>
- <title>Conditional Element "accumulate"</title>
+ <title>Conditional Element <kw>accumulate</kw></title>
<figure>
<title>accumulate</title>
@@ -1839,70 +1836,69 @@
</mediaobject>
</figure>
- <para>The Conditional Element "accumulate" is a more flexible and powerful
- form of "collect", the sense that it can be used to do what "collect" does
- and also achieve things that the CE "collect" is not capable of doing.
+ <para>The Conditional Element <kw>accumulate</kw> is a more flexible and powerful
+ form of <kw>collect</kw>, the sense that it can be used to do what <kw>collect</kw> does
+ and also achieve things that the CE <kw>collect</kw> is not capable of doing.
Basically, what it does is that it allows a rule to iterate
over a collection of objects, executing custom actions for each of the
elements, and at the end it returns a result object.</para>
- <para>The general syntax of the <emphasis
- role="bold">accumulate</emphasis> CE is:</para>
+ <para>The general syntax of the <kw>accumulate</kw> CE is:</para>
- <programlisting><replaceable><result pattern></replaceable> from accumulate( <replaceable><source pattern></replaceable>,
- init( <replaceable><init code></replaceable> ),
- action( <replaceable><action code></replaceable> ),
- reverse( <replaceable><reverse code></replaceable> ),
- result( <replaceable><result expression></replaceable> ) )
+ <programlisting><replaceable><result pattern></replaceable> <kw>from accumulate(</kw> <replaceable><source pattern></replaceable><kw>,</kw>
+ <kw>init(</kw> <replaceable><init code></replaceable> <kw>),</kw>
+ <kw>action(</kw> <replaceable><action code></replaceable> <kw>),</kw>
+ <kw>reverse(</kw> <replaceable><reverse code></replaceable> <kw>),</kw>
+ <kw>result(</kw> <replaceable><result expression></replaceable> <kw>) )</kw>
</programlisting>
<para>The meaning of each of the elements is the following:</para>
<itemizedlist>
<listitem>
- <para><emphasis role="bold"><source pattern></emphasis>: the
+ <para><emphasis><source pattern></emphasis>: the
source pattern is a regular pattern that the engine will try to
match against each of the source objects.</para>
</listitem>
<listitem>
- <para><emphasis role="bold"><init code></emphasis>: this is a
+ <para><emphasis><init code></emphasis>: this is a
semantic block of code in the selected dialect that will be executed
once for each tuple, before iterating over the source
objects.</para>
</listitem>
<listitem>
- <para><emphasis role="bold"><action code></emphasis>: this is
+ <para><emphasis><action code></emphasis>: this is
a semantic block of code in the selected dialect that will be
executed for each of the source objects.</para>
</listitem>
<listitem>
- <para><emphasis role="bold"><reverse code></emphasis>: this is
+ <para><emphasis><reverse code></emphasis>: this is
an optional semantic block of code in the selected dialect that if
present will be executed for each source object that no longer
matches the source pattern. The objective of this code block is to
- "undo" any calculation done in the <action code> block, so
+ undo any calculation done in the <emphasis><action code></emphasis> block, so
that the engine can do decremental calculation when a source object
is modified or retracted, hugely improving performance of these
operations.</para>
</listitem>
<listitem>
- <para><emphasis role="bold"><result expression></emphasis>:
+ <para><emphasis><result expression></emphasis>:
this is a semantic expression in the selected dialect that is
executed after all source objects are iterated.</para>
</listitem>
<listitem>
- <para><emphasis role="bold"><result pattern></emphasis>: this
+ <para><emphasis><result pattern></emphasis>: this
is a regular pattern that the engine tries to match against the
- object returned from the <result expression>. If it matches,
- the "accumulate" conditional element
+ object returned from the <emphasis><result expression></emphasis>.
+ If it matches, the <kw>accumulate</kw> conditional element
evaluates to <emphasis>true</emphasis> and the engine
proceeds with the evaluation of the next CE in the rule. If it does
- not matches, the "accumulate" CE
+ not matches, the <kw>accumulate</kw> CE
evaluates to <emphasis>false</emphasis> and the engine
stops evaluating CEs for that rule.</para>
</listitem>
@@ -1924,30 +1920,30 @@
end
</programlisting>
- <para>In the above example, for each Order() in the working memory, the
- engine will execute the <emphasis role="bold">init code</emphasis>
+ <para>In the above example, for each <code>Order</code> in the
+ Working Memory, the engine will execute the <emphasis>init code</emphasis>
initializing the total variable to zero. Then it will iterate over all
- OrderItem() objects for that order, executing the <emphasis
- role="bold">action</emphasis> for each one (in the example, it will sum
+ <code>OrderItem</code> objects for that order, executing the
+ <emphasis>action</emphasis> for each one (in the example, it will sum
the value of all items into the total variable). After iterating over
- all OrderItem, it will return the value corresponding to the <emphasis
- role="bold">result expression</emphasis> (in the above example, the
- value of the total variable). Finally, the engine will try to match the
- result with the Number() pattern and if the double value is greater than
- 100, the rule will fire.</para>
+ all <code>OrderItem</code> objects, it will return the value corresponding
+ to the <emphasis>result expression</emphasis> (in the above example, the
+ value of variable <code>total</code>). Finally, the engine will try to match the
+ result with the <code>Number</code> pattern, and if the double value is greater
+ than 100, the rule will fire.</para>
<para>The example used Java as the semantic dialect, and as such, note
- that the usage of ';' is mandatory in the init, action and reverse code
- blocks. The result is an expression and as such, it does not admit ';'.
- If the user uses any other dialect, he must comply to that dialect
+ that the usage of the semicolon as statement delimiter is mandatory in the
+ init, action and reverse code
+ blocks. The result is an expression and, as such, it does not admit ';'.
+ If the user uses any other dialect, he must comply to that dialect's
specific syntax.</para>
- <para>As mentioned before, the <emphasis role="bold">reverse
- code</emphasis> is optional, but it is strongly recommended that the
- user writes it in order to benefit from the <emphasis>improved
- performance on update and retracts</emphasis>.</para>
+ <para>As mentioned before, the <emphasis>reverse code</emphasis> is optional,
+ but it is strongly recommended that the user writes it in order to benefit
+ from the <emphasis>improved performance on update and retract</emphasis>.</para>
- <para>The "accumulate" CE can be used to
+ <para>The <kw>accumulate</kw> CE can be used to
execute any action on source objects. The following example instantiates
and populates a custom object:</para>
@@ -2041,7 +2037,7 @@
line to the configuration file or set a system property to let the
engine know about the new function. As an example of an Accumulate
Function implementation, the following is the implementation of the
- "average" function:</para>
+ <kw>average</kw> function:</para>
<programlisting>/*
* Copyright 2007 JBoss Inc
@@ -2170,51 +2166,51 @@
memory; without having to first reference a working memory
instance.</para>
- <para>"update(object, handle);" will tell the engine that an object has
+ <para><kw>update(</kw><emphasis>object, handle</emphasis><kw>);</kw>
+ will tell the engine that an object has
changed (one that has been bound to something on the LHS) and rules may
need to be reconsidered.</para>
- <para>"update(object);" can also be used, here the KnowledgeHelper will
- lookup the facthandle for you, via an identity check, for the passed object.</para>
+ <para><kw>update(</kw><emphasis>object</emphasis><kw>);</kw> can
+ also be used; here the Knowledge Helper will look up the facthandle for you,
+ via an identity check, for the passed object.</para>
- <para>"insert(new Something());" will place a new object of your creation
- in working memory.</para>
+ <para><kw>insert(new</kw> <emphasis>Something</emphasis><kw>());</kw>
+ will place a new object of your creation into the Working Memory.</para>
- <para>"insertLogical(new Something());" is similar to insert, but the
- object will be automatically retracted when there are no more facts to
- support the truth of the currently firing rule.</para>
+ <para><kw>insertLogical(new</kw> <emphasis>Something</emphasis><kw>());</kw>
+ is similar to insert, but the object will be automatically retracted when there are
+ no more facts to support the truth of the currently firing rule.</para>
- <para>"retract(handle);" removes an object from working memory.</para>
+ <para><kw>retract(</kw><emphasis>handle</emphasis><kw>);</kw>
+ removes an object from Working Memory.</para>
<para>These convenience methods are basically macros that provide short
cuts to the KnowledgeHelper instance (refer to the KnowledgeHelper
interface for more advanced operations). The KnowledgeHelper interface is
- made available to the RHS code block as a variable called "drools". If you
- provide "Property Change Listeners" to your Java beans that you are
- inserting into the engine, you can avoid the need to call "update" when
+ made available to the RHS code block as the variable <code>drools</code>.
+ If you provide Property Change Listeners to your Java beans that you are
+ inserting into the engine, you can avoid the need to call <code>update()</code> when
the object changes.</para>
</section>
<section>
- <title>The modify Statement</title>
+ <title>The <kw>modify</kw> Statement</title>
<para>This language extension provides a structured approach to
fact updates. It combines the update operation with a number of
- setter calls to change the object's fields.</para>
+ setter calls to change the object's fields. This is the syntax
+ schema for the <kw>modify</kw> statement:</para>
- <example>
- <title>The modify statement</title>
+ <programlisting><kw>modify ( </kw><replaceable><fact-expression></replaceable><kw> ) {</kw>
+ <replaceable><expression></replaceable> [ <kw>,</kw> <replaceable><expression></replaceable> ]*
+<kw>}</kw></programlisting>
- <programlisting><emphasis role="bold">modify ( </emphasis><emphasis>fact-expression</emphasis><emphasis role="bold"> {</emphasis>
- <emphasis>expression</emphasis> [ <emphasis role="bold">,</emphasis> <emphasis>expression</emphasis> ]
-<emphasis role="bold">}</emphasis></programlisting>
- </example>
+ <para>The parenthesized <emphasis><fact-expression></emphasis> must yield
+ a fact object reference. The expression list in the block should consist of
+ setter calls for the given object, to be written without the usual object reference,
+ which is automatically prepended by the compiler.</para>
- <para>The parenthesized fact-expression must yield a fact object reference.
- The expression list in the block should consist of setter calls for the given
- object, to be written without the usual object reference, which is
- automatically prepended by the compiler.</para>
-
<para>The example illustrates a simple fact modification.</para>
<example>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-TypeDeclaration.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-TypeDeclaration.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-TypeDeclaration.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -61,8 +61,8 @@
<title>Declaring New Types</title>
<para>To declare a new type, all you need to do is use the keyword
- <emphasis role="bold">declare</emphasis>, followed by the list of fields,
- and the keyword <emphasis role="bold">end</emphasis>.</para>
+ <kw>declare</kw>, followed by the list of fields, and the keyword
+ <kw>end</kw>.</para>
<example>
<title>Declaring a new fact type: Address</title>
@@ -76,14 +76,14 @@
</example>
<para>The previous example declares a new fact type called
- <emphasis>Address</emphasis>. This fact type will have 3 attributes:
- <emphasis>number</emphasis>, <emphasis>streetName</emphasis> and
- <emphasis>city</emphasis>. Each attribute has a type that can be any valid
+ <code>Address</code>. This fact type will have three attributes:
+ <code>number</code>, <code>streetName</code> and <code>city</code>.
+ Each attribute has a type that can be any valid
Java type, including any other class created by the user or even other
fact types previously declared.</para>
<para>For instance, we may want to declare another fact type
- <emphasis>Person</emphasis>:</para>
+ <code>Person</code>:</para>
<para><example>
<title>declaring a new fact type: Person</title>
@@ -95,13 +95,13 @@
<emphasis role="bold">end</emphasis>
</programlisting>
</example>As we can see on the previous example,
- <emphasis>dateOfBirth</emphasis> is of type <code>java.util.Date</code>,
- from the Java API, while <emphasis>address</emphasis> is of the previously
+ <code>dateOfBirth</code> is of type <code>java.util.Date</code>,
+ from the Java API, while <code>address</code> is of the previously
defined fact type Address.</para>
<para>You may avoid having to write the fully qualified name of a class
- every time you write it by using the <emphasis
- role="bold">import</emphasis> clause, as previously discussed.</para>
+ every time you write it by using the <kw>import</kw> clause, as previously
+ discussed.</para>
<para><example>
<title>Avoiding the need to use fully qualified class names by using
@@ -162,14 +162,13 @@
<para>Metadata may be assigned to several different constructions in
Drools: fact types, fact attributes and rules. Drools uses the
- <emphasis role="bold">@</emphasis> symbol to introduce metadata, and it
- always uses the form:</para>
+ at sign ('@') to introduce metadata, and it always uses the form:</para>
<para><programlisting>@<emphasis>metadata_key</emphasis>( <emphasis>metadata_value</emphasis> )</programlisting>The
parenthesized <emphasis>metadata_value</emphasis> is optional.</para>
<para>For instance, if you want to declare a metadata attribute like
- <emphasis>author</emphasis>, whose value is <emphasis>Bob</emphasis>, you
+ <code>author</code>, whose value is <emphasis>Bob</emphasis>, you
could simply write:</para>
<example>
@@ -203,11 +202,10 @@
</example>
<para>In the previous example, there are two metadata items declared for the
- fact type (<emphasis>@author</emphasis> and
- <emphasis>@dateOfCreation</emphasis>) and two more defined for the name
- attribute (<emphasis>@key</emphasis> and <emphasis>@maxLength</emphasis>).
- Please note that the <emphasis>@key</emphasis> metadata has no value, and
- so the parentheses and the value were omitted.</para>
+ fact type (<code>@author</code> and <code>@dateOfCreation</code>) and two
+ more defined for the name attribute (<code>@key</code> and
+ <code>@maxLength</code>). Please note that the <code>@key</code> metadata
+ has no value, and so the parentheses and the value were omitted.</para>
</section>
<section>
@@ -266,10 +264,10 @@
<para>The first important thing to realize is that a declared fact will
belong to the package where it was declared. So, for instance, in the
- example below, <emphasis>Person</emphasis> will belong to the
- <emphasis>org.drools.examples</emphasis> package, and so the
+ example below, <code>Person</code> will belong to the
+ <code>org.drools.examples</code> package, and so the
fully qualified name of the generated class will be
- <emphasis>org.drools.examples.Person</emphasis>.</para>
+ <code>org.drools.examples.Person</code>.</para>
<example>
<title>Declaring a type in the org.drools.examples package</title>
@@ -292,7 +290,7 @@
<para>Drools then provides an interface through which users can handle
declared types from the application code:
- org.drools.definition.type.FactType. Through this interface, the user can
+ <code>org.drools.definition.type.FactType</code>. Through this interface, the user can
instantiate, read and write fields in the declared fact types.</para>
<example>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Section-A_Little_More_Theory.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Section-A_Little_More_Theory.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Section-A_Little_More_Theory.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -83,8 +83,8 @@
" sprinkler:" + $sprinkler.getRoom().getName() );
end</programlisting>
- <para>In SQL terms this would be like doing "select * from Room,
- Sprinkler" and every row in the Room table would be joined with every
+ <para>In SQL terms this would be like doing <code>select * from Room,
+ Sprinkler</code> and every row in the Room table would be joined with every
row in the Sprinkler table resulting in the following output:</para>
<programlisting>room:office sprinker:office
@@ -121,7 +121,7 @@
<para>This results in just four rows of data, with the correct Sprinkler
for each Room. In SQL (actually HQL) the corresponding query would be
- "select * from Room, Sprinkler where Room == Sprinkler.room"</para>
+ <code>select * from Room, Sprinkler where Room == Sprinkler.room</code>.</para>
<programlisting>room:office sprinkler:office
room:kitchen sprinkler:kitchen
@@ -139,7 +139,7 @@
of what is actually going on under the hood. Three classes will be used,
as shown below.</para>
- <programlisting>public class Cashflow {
+ <programlisting>public class CashFlow {
private Date date;
private double amount;
private int type;
@@ -159,26 +159,28 @@
// getter and setter methods here
}</programlisting>
- <para>By now you already know how to create KnowledgeBases and how to
- instantiate facts to populate the StatefulKnowledgeSession, so tables
+ <para>By now you already know how to create Knowledge Bases and how to
+ instantiate facts to populate the <code>StatefulKnowledgeSession</code>, so tables
will be used to show the state of the inserted data, as it makes things
clearer for illustration purposes. The tables below show that a single fact
- was inserted for the Account. Also inserted are a series of debits and credits
- as Cashflows for that Account, extending over two quarters.</para>
+ was inserted for the <code>Account</code>. Also inserted are a series of debits
+ and credits as <code>CashFlow</code> objects for that account, extending over two
+ quarters.</para>
<figure>
<title>CashFlows and Account</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-Quick_Start/tables1.png" />
+ <imagedata width="100%"
+ fileref="images/Chapter-Quick_Start/tables1.png" />
</imageobject>
</mediaobject>
</figure>
<para>Two rules can be used to determine the debit and credit for that
quarter and update the Account balance. The two rules below constrain
- the Cashflows for an Account for a given time period. Notice the
+ the cashflows for an account for a given time period. Notice the
"&&" which use short cut syntax to avoid repeating the field
name twice.</para>
@@ -216,12 +218,12 @@
</tbody>
</informaltable>
- <para>If the AccountPeriod is set to the first quarter we constrain the
- "increase balance for credits" to fire on two rows of data and
+ <para>If the <code>AccountPeriod</code> is set to the first quarter we constrain the
+ rule "increase balance for credits" to fire on two rows of data and
"decrease balance for debits" to act on one row of data.</para>
<figure>
- <title>CashFlows and Account</title>
+ <title>AccountingPeriod, CashFlows and Account</title>
<mediaobject>
<imageobject>
@@ -230,10 +232,11 @@
</mediaobject>
</figure>
- <para>The two Cashflow tables above represent the matched data for the
+ <para>The two cashflow tables above represent the matched data for the
two rules. The data is matched during the insertion stage and, as you
discovered in the previous chapter, does not fire straight away, but only
- after fireAllRules() is called. Meanwhile, rule plus its matched data is
+ after <code>fireAllRules()</code> is called. Meanwhile, the rule plus its
+ matched data is
placed on the Agenda and referred to as an Activation. The Agenda is a
table of Activations that are able to fire and have their consequences
executed, as soon as fireAllRules() is called. Activations on the
@@ -250,7 +253,7 @@
</mediaobject>
</figure>
- <para>After all of the above activations are fired, the Account has a
+ <para>After all of the above activations are fired, the account has a
balance of -25.</para>
<figure>
@@ -263,7 +266,7 @@
</mediaobject>
</figure>
- <para>If the AccountPeriod is updated to the second quarter, we have just
+ <para>If the <code>AccountPeriod</code> is updated to the second quarter, we have just
a single matched row of data, and thus just a single Activation on the
Agenda.</para>
@@ -295,7 +298,7 @@
is used to determine the order of execution. At the simplest level the
default strategy uses salience to determine rule priority. Each rule has
a default value of 0, the higher the value the higher the priority. To
- illustrate this we add a rule to print the Account balance, where we
+ illustrate this we add a rule to print the account balance, where we
want this rule to be executed after all the debits and credits have
been applied for all accounts. We achieve this by assigning a negative
salience to this rule so that it fires after all rules with the default
@@ -318,7 +321,7 @@
</tbody>
</table>
- <para>The table below depicts the resulting Agenda. The 3 debit and credit
+ <para>The table below depicts the resulting Agenda. The three debit and credit
rules are shown to be in arbitrary order, while the print rule is ranked
last, to execute afterwards.</para>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Section-More_On_Building_And_Deploying.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Section-More_On_Building_And_Deploying.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Section-More_On_Building_And_Deploying.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -24,11 +24,10 @@
XML, but we hope to add one soon. A few examples will be
shown to give you the gist of things. A resource approach is employed
that uses a prefix to indicate the protocol. All the protocols provided
- by java.net.URL, such as "file" and "http" are supported, as well as an
+ by java.net.URL, such as "file" and "http", are supported, as well as an
additional "classpath". Currently the type attribute must always be
specified for a resource, as it is not inferred from the file name extension.
- Here is a
- simple example that points to a http location for some rules.</para>
+ Here is a simple example that points to a http location for some rules.</para>
<programlisting> <change-set xmlns='http://drools.org/drools-5.0/change-set'
xmlns:xs='http://www.w3.org/2001/XMLSchema-instance'
@@ -40,7 +39,7 @@
</programlisting>
<para>To use the above XML the code is almost identical as before,
- except we change the ResourceType to CHANGE_SET.</para>
+ except we change the resource type to <code>CHANGE_SET</code>.</para>
<programlisting>KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
kbuilder.add( ResourceFactory.newClasspathResource( "myChangeSet.xml", getClass() ),
@@ -84,9 +83,9 @@
<section>
<title>Knowledge Agent</title>
- <para>The KnowlegeAgent provides automatic loading, caching and
+ <para>The Knowlege Agent provides automatic loading, caching and
re-loading of resources and is configured from a properties files. The
- KnowledgeAgent can update or rebuild this KnowlegeBase as the resources
+ Knowledge Agent can update or rebuild this Knowlege Base as the resources
it uses are changed. The strategy for this is determined by the
configuration given to the factory, but it is typically pull based using
regular polling. We hope to add push based updates and rebuilds in
@@ -96,12 +95,12 @@
kagent.applyChangeSet( ResourceFactory.newUrlResource( url ) );
KnowledgeBase kbase = kagent.getKnowledgeBase();</programlisting>
- <para>The KnowledgeAgent will continously scan all the added resources,
+ <para>A <code>KnowledgeAgent</code> object will continously scan all the added resources,
using a default polling interval of 60s, and if their last modified date is
- updated it will rebuild the cached KnowledgeBase using the new
- resources. Note that the previous KnowledgeBase reference will still exist
+ updated it will rebuild the cached Knowledge Base using the new
+ resources. Note that the previous <code>KnowledgeBase</code> reference will still exist
and you'll have to call getKnowledgeBase() to access the newly built
- KnowledgeBase. If a directory is specified as part of the change set,
+ KnowledgeB ase. If a directory is specified as part of the change set,
the entire contents of that directory will be scanned for
changes.</para>
</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Section-The_Basics.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Section-The_Basics.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Section-The_Basics.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -85,16 +85,17 @@
end</programlisting>
<para>To make the engine aware of data, so it can be processed against
- the rules, we have to "insert" the data, much like with a database. When
+ the rules, we have to <emphasis>insert</emphasis> the data, much like
+ with a database. When
the Applicant instance is inserted into the engine it is evaluated
against the constraints of the rules, in this case just two constraints
for one rule. We say <emphasis>two</emphasis> because the type Applicant
is the first object
- type constraint, and "age < 18" is the second field constraint.
+ type constraint, and <code>age < 18</code> is the second field constraint.
An object type constraint plus its zero or more field constraints is
referred to as a pattern. When an inserted instance satisfies both the
object type constraint and all the field constraints, it is said to be
- matched. The "$a" is a binding variable which permits us to reference
+ matched. The <code>$a</code> is a binding variable which permits us to reference
the matched object in the consequence. There its properties can be
updated. The dollar character ('$') is optional, but it helps to
differentiate variable names from field names. The process of
@@ -103,20 +104,21 @@
<para>Let's assume that the rules are in the same folder as the classes,
so we can use the classpath resource loader to build our first
- KnowledgeBase. A KnowledgeBase is what we call our collection of
- compiled rules, which are compiled using the KnowledgeBuilder.</para>
+ <code>KnowledgeBase</code>. A Knowledge Base is what we call our collection of
+ compiled rules, which are compiled using the <code>KnowledgeBuilder</code>.</para>
<programlisting>KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
-kbuilder.add( ResourceFactory.newClasspathResource( "licenseApplication.drl", getClass() ),
+kbuilder.add( ResourceFactory.newClassPathResource( "licenseApplication.drl", getClass() ),
ResourceType.DRL );
if ( kbuilder.hasErrors() ) {
System.err.println( builder.getErrors().toString() );
} </programlisting>
- <para>The above code snippet looks on the classpath for the "licenseApplication.drl"
- file, using the method newClasspathResource(). The ResourceType
+ <para>The above code snippet looks on the classpath for the
+ <filename>licenseApplication.drl</filename>
+ file, using the method <code>newClassPathResource()</code>. The resource type
is DRL, short for "Drools Rule Language". Once the DRL file has been added
- we can check the KnowledgeBuilder for any errors. If there are no
+ we can check the Knowledge Builder object for any errors. If there are no
errors, we are now ready to build our session and execute against some
data:</para>
@@ -132,9 +134,9 @@
<para>So far we've only used a single instance, but what if we want to use
more than one? We can execute against any object implementing Iterable, such as
- a collection. Let's add another class called Application, which has the
+ a collection. Let's add another class called <code>Application</code>, which has the
date of the application, and we'll also move the boolean valid field to the
- Application class.</para>
+ <code>Application</code> class.</para>
<programlisting>public class Applicant {
private String name;
@@ -148,7 +150,7 @@
// getter and setter methods here
}</programlisting>
- <para>We can also add another rule to validate that the Application
+ <para>We can also add another rule to validate that the application
was made within a period of time.</para>
<programlisting>package com.company.license
@@ -169,9 +171,11 @@
end
</programlisting>
- <para>Unfortunately in Java an array does not implement the Iterable
- interface, so we have to use the JDK converter asList(...). The code
- shown below executes against an Iterable, where all collection
+ <para>Unfortunately a Java array does not implement the
+ <code>Iterable</code>
+ interface, so we have to use the JDK converter method
+ <code>Arrays.asList(...)</code>. The code
+ shown below executes against an iterable list, where all collection
elements are inserted before any matched rules are fired.</para>
<programlisting>StatelessKnowledgeSession ksession = kbase.newStatelessKnowledgeSession();
@@ -182,18 +186,18 @@
assertFalse( application() );
</programlisting>
- <para>The two execute methods execute(Object object) and
- execute(Iterable objects) are actually convenience methods for the
- interface BatchExecutor's method execute(Command command).</para>
+ <para>The two execute methods <code>execute(Object object)</code> and
+ <code>execute(Iterable objects)</code> are actually convenience methods for the
+ interface <code>BatchExecutor</code>'s method <code>execute(Command command)</code>.</para>
- <para>The CommandFactory is used to create commands, so that the following is
- equivalent to execute( Iterable it ):</para>
+ <para>A <code>CommandFactory</code> is used to create commands, so that the following is
+ equivalent to <code>execute(Iterable it)</code>:</para>
<programlisting>ksession.execute( CommandFactory.newInsertIterable( new Object[] { application, applicant } ) );
</programlisting>
- <para>BatchExecutor and CommandFactory are particularly useful when working
- with multiple Commands and output identifiers for results.</para>
+ <para>Batch Executor and Command Factory are particularly useful when working
+ with multiple Commands and with output identifiers for obtaining results.</para>
<programlisting>List<Command> cmds = new ArrayList<Command>();
cmds.add( CommandFactory.newInsert( new Person( "Mr John Smith" ), "mrSmith" );
@@ -202,15 +206,16 @@
assertEquals( new Person( "Mr John Smith" ), results.getValue( "mrSmith" ) );
</programlisting>
- <para>CommandFactory supports many other Commands that can be used in
- the BatchExecutor like StartProcess, Query, and SetGlobal.</para>
+ <para><code>CommandFactory</code> supports many other Commands that can be used in
+ the <code>BatchExecutor</code> like <code>StartProcess</code>, <code>Query</code>, and
+ <code>SetGlobal</code>.</para>
</section>
<section>
<title>Stateful Knowledge Session</title>
- <para>Stateful sessions are longer lived and allow iterative changes
- over time. Some common use cases for stateful sessions are, but not
+ <para>Stateful Sessions are longer lived and allow iterative changes
+ over time. Some common use cases for Stateful Sessions are, but not
limited to:</para>
<itemizedlist>
@@ -256,18 +261,19 @@
</listitem>
</itemizedlist>
- <para>Unlike a stateless session the dispose() method must be called
- afterwards to ensure there are no memory leaks, as the KnowledgeBase
- contains references to StatefulKnowledgeSessions when they are created.
- StatefulKnowledgeSession also supports the BatchExecutor interface, like
- StatelessKnowledgeSession, the only difference being that
- the FireAllRules command is not automatically called at the
- end for a stateful session.</para>
+ <para>In contrast to a Stateless Session, the <code>dispose()</code>
+ method must be called
+ afterwards to ensure there are no memory leaks, as the Knowledge Base
+ contains references to Stateful Knowledge Sessions when they are created.
+ <code>StatefulKnowledgeSession</code> also supports the <code>BatchExecutor</code>
+ interface, like <code>StatelessKnowledgeSession</code>, the only difference
+ being that the <code>FireAllRules</code> command is not automatically called at the
+ end for a Stateful Session.</para>
<para>We illustrate the monitoring use case with an example for raising a
- fire alarm. Using just 4 classes, we represent rooms in a house, each of which
+ fire alarm. Using just four classes, we represent rooms in a house, each of which
has one sprinkler. If a fire starts in a room, we
- represent that with a single Fire instance.</para>
+ represent that with a single <code>Fire</code> instance.</para>
<programlisting>public class Room {
private String name
@@ -286,7 +292,7 @@
}
</programlisting>
- <para>In the previous section on stateless sessions the concepts of
+ <para>In the previous section on Stateless Sessions the concepts of
inserting and matching against data was introduced. That example assumed
that only a single instance of each object type was ever inserted and thus
only used literal constraints. However, a house has many rooms, so rules
@@ -295,11 +301,12 @@
in a pattern. This "join" process results in what is called cross products, which are
covered in the next section.</para>
- <para>When a fire occurs an instance of the Fire class is created, for
- that room, and inserted into the session. The rule uses a binding on the "room"
- field of the Fire object to constrain matching to the Sprinkler for that room,
+ <para>When a fire occurs an instance of the <code>Fire</code> class is created, for
+ that room, and inserted into the session. The rule uses a binding on the
+ <code>room</code>
+ field of the <code>Fire</code> object to constrain matching to the sprinkler for that room,
which is currently off. When this rule fires and the consequence is executed
- the sprinkler is turned on</para>
+ the sprinkler is turned on.</para>
<programlisting>rule "When there is a fire turn on the sprinkler"
when
@@ -310,26 +317,28 @@
System.out.println( "Turn on the sprinkler for room " + $room.getName() );
end</programlisting>
- <para>Whereas the stateless session used standard Java syntax to modify
- a field, in the above rule we use the "modify" statement, which acts as a
+ <para>Whereas the Stateless Session uses standard Java syntax to modify
+ a field, in the above rule we use the <kw>modify</kw> statement, which acts as a
sort of "with" statement. It may contain a series of comma separated Java
- expressions, calls to setters of the object selected by the "modify" control
+ expressions, i.e., calls to setters of the object selected by the <kw>modify</kw>
+ statement's control
expression. This modifies the data, and makes the engine aware of those changes
so it can reason over them once more. This process is called inference, and
- it's essential for the working of a stateful session. Stateless sessions
+ it's essential for the working of a Stateful Session. Stateless Sessions
typically do not use inference, so the engine does not need to be aware of
changes to data. Inference can also be turned off explicitly by using the
- "sequential mode".</para>
+ <emphasis>sequential mode</emphasis>.</para>
<para>So far we have rules that tell us when matching data exists, but
what about when it does <emphasis>not</emphasis> exist? How do we determine
- that a Fire has been extinguished, i.e., there isn't a Fire object any more.
- Previously the constraints have been sentences according to Propositional Logic,
+ that a fire has been extinguished, i.e., that there isn't a <code>Fire</code>
+ object any more? Previously the constraints have been sentences according
+ to Propositional Logic,
where the engine is constraining against individual intances. Drools also has
support for First Order Logic that allows you to look at sets of data.
- The 'not' keyword matches when something does not exist. The rule given
- below turns the Sprinkler off as soon as the Fire in that room has
- disappeared.</para>
+ A pattern under the keyword <kw>not</kw> matches when something does not exist.
+ The rule given below turns the sprinkler off as soon as the fire in that
+ room has disappeared.</para>
<programlisting>rule "When the fire is gone turn off the sprinkler"
when
@@ -341,12 +350,12 @@
System.out.println( "Turn off the sprinkler for room " + $room.getName() );
end</programlisting>
- <para>While there is a Sprinkler per room, there is just a single Alarm
- for the building. An Alarm is created when a Fire occurs, but only
- one Alarm is needed for the entire building, no matter how many Fires
- occur. Previously 'not' was introduced to match the absence of a fact;
- now we use its complement 'exists' which matches for one or more of
- something.</para>
+ <para>While there is one sprinkler per room, there is just a single alarm
+ for the building. An <code>Alarm</code> object is created when a fire occurs,
+ but only one <code>Alarm</code> is needed for the entire building, no matter
+ how many fires occur. Previously <kw>not</kw> was introduced to match the absence of
+ a fact; now we use its complement <kw>exists</kw> which matches for one or more
+ instances of some category.</para>
<programlisting>rule "Raise the alarm when we have one or more fires"
when
@@ -356,8 +365,8 @@
System.out.println( "Raise the alarm" );
end</programlisting>
- <para>Likewise, when there are no Fires we want to remove the alarm, so
- the 'not' keyword can be used again.</para>
+ <para>Likewise, when there are no fires we want to remove the alarm, so
+ the <kw>not</kw> keyword can be used again.</para>
<programlisting>rule "Cancel the alarm when all the fires have gone"
when
@@ -370,9 +379,9 @@
</programlisting>
- <para>Finally there is a general health status message, that is printed
- when the application first starts and after the Alarm is removed and all
- Sprinklers have been turned off.</para>
+ <para>Finally there is a general health status message that is printed
+ when the application first starts and after the alarm is removed and all
+ sprinklers have been turned off.</para>
<programlisting>rule "Status output when things are ok"
when
@@ -382,15 +391,17 @@
System.out.println( "Everything is ok" );
end</programlisting>
- <para>The above rules should be placed in a single drl file and saved to
- the classpath using the file name "fireAlarm.drl", as in the stateless
- session example. We can then build a KnowledgeBase, as before, just using
- the new name "fireAlarm.drl". The difference is that this time we create a
- stateful session from the kbase, whereas before we created a stateless
- session.</para>
+ <para>The above rules should be placed in a single DRL file and saved to
+ some directory on the classpath and using the file name
+ <filename>fireAlarm.drl</filename>,
+ as in the Stateless Session example. We can then build a Knowledge Base,
+ as before, just using the new name <filename>fireAlarm.drl</filename>.
+ The difference is that
+ this time we create a Stateful Session from the Knowledge Base, whereas
+ before we created a Stateless Session.</para>
<programlisting>KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
-kbuilder.add( ResourceFactory.newClasspathResource( "fireAlarm.drl", getClass() ),
+kbuilder.add( ResourceFactory.newClassPathResource( "fireAlarm.drl", getClass() ),
ResourceType.DRL );
if ( kbuilder.hasErrors() ) {
System.err.println( builder.getErrors().toString() );
@@ -398,10 +409,11 @@
StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();</programlisting>
<para>With the session created it is now possible to iteratvely work
- with it over time. Four Rooms are created and inserted, a Sprinkler for
- each room is also inserted. At this point the engine has done all of its
- matching, but no rules have fired yet. Calling "fireAllRules" on the
- ksession allows the matched rules to fire, but without a fire that will
+ with it over time. Four <code>Room</code> objects are created and
+ inserted, as well as one <code>Sprinkler</code> object for
+ each room. At this point the engine has done all of its
+ matching, but no rules have fired yet. Calling <code>ksession.fireAllRules()</code>
+ allows the matched rules to fire, but without a fire that will
just produce the health message.</para>
<programlisting>String[] names = new String[]{"kitchen", "bedroom", "office", "livingroom"};
@@ -419,12 +431,12 @@
<programlisting>> Everything is ok</programlisting>
- <para>We now create two fires and insert them, this time a reference is
- kept for the returned FactHandle. The FactHandle is an internal engine
- reference to the inserted instance and allows instances to be
- retracted or modified at a later point in time. With the Fires now in
- the engine, once "fireAllRules" is called, the Alarm is raised and the
- respective Sprinklers are turned on.</para>
+ <para>We now create two fires and insert them; this time a reference is
+ kept for the returned <code>FactHandle</code>. A Fact Handle is an
+ internal engine reference to the inserted instance and allows instances to be
+ retracted or modified at a later point in time. With the fires now in
+ the engine, once <code>fireAllRules()</code> is called, the alarm is raised and the
+ respective sprinklers are turned on.</para>
<programlisting>Fire kitchenFire = new Fire( name2room.get( "kitchen" ) );
Fire officeFire = new Fire( name2room.get( "office" ) );
@@ -438,8 +450,8 @@
> Turn on the sprinkler for room kitchen
> Turn on the sprinkler for room office</programlisting>
- <para>After a while the fires will be put out and the Fire intances are
- retracted. This results in the Sprinklers being turned off, the Alarm
+ <para>After a while the fires will be put out and the <code>Fire</code>
+ instances are retracted. This results in the sprinklers being turned off, the alarm
being cancelled, and eventually the health message is printed again.</para>
<programlisting>ksession.retract( kitchenFireHandle );
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-User_Guide/Section-Building.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-User_Guide/Section-Building.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-User_Guide/Section-Building.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -22,22 +22,23 @@
<title>Building using Code</title>
<para>The KnowledgeBuilder is responsible for taking source files, such as
- a .drl file or an .xls file, and turning them into a KnowledgePackage of
- rule and process definitions which a KnowledgeBase can consume. An object
- of the class ResourceType indicates the type of resource it is being
+ a DRL file or an Excel file, and turning them into a Knowledge Package of
+ rule and process definitions which a Knowledge Base can consume. An object
+ of the class <code>ResourceType</code> indicates the type of resource it is being
asked to build.</para>
- <para>The ResourceFactory provides capabilities to load Resources from a
+ <para>The <code>ResourceFactory</code> provides capabilities to load resources from a
number of sources, such as Reader, ClassPath, URL, File, or ByteArray.
- Binaries, such as .xls decision tables, should not use a Reader based
- Resource handler, which is only suitable for text based resources.</para>
+ Binaries, such as decision tables (Excel .xls files), should not use a Reader based
+ resource handler, which is only suitable for text based resources.</para>
<figure>
<title>KnowledgeBuilder</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-User_Guide/KnowledgeBuilder.png"></imagedata>
+ <imagedata width="100%"
+ fileref="images/Chapter-User_Guide/KnowledgeBuilder.png"></imagedata>
</imageobject>
</mediaobject>
</figure>
@@ -50,7 +51,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-User_Guide/KnowledgeBuilderFactory.png"></imagedata>
+ <imagedata width="100%"
+ fileref="images/Chapter-User_Guide/KnowledgeBuilderFactory.png"></imagedata>
</imageobject>
</mediaobject>
</figure>
@@ -64,11 +66,11 @@
<programlisting>KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();</programlisting>
</example>
- <para>A configuration can be created using the KnowledgeBuilderFactory.
- This allows the behavior of the KnowledgeBuilder to modified. The most
- common usage is to provide a custom ClassLoader so that the kbuilder can
- resolve classes that are not in the default classpath. The first parameter
- is for Properties and is optional, i.e., it may be left null, in which case the
+ <para>A configuration can be created using the <code>KnowledgeBuilderFactory</code>.
+ This allows the behavior of the Knowledge Builder to be modified. The most
+ common usage is to provide a custom class loader so that the <code>KnowledgeBuilder</code>
+ object can resolve classes that are not in the default classpath. The first parameter
+ is for properties and is optional, i.e., it may be left null, in which case the
default options will be used. The options parameter can be used for things
like changing the dialect or registering new accumulator functions.</para>
@@ -80,8 +82,8 @@
</programlisting>
</example>
- <para>Resources of any type can be added iteratively. Below, a DRL is
- added. Unlike Drools 4.0 PackageBuilder the KnowledgeBuilder can now
+ <para>Resources of any type can be added iteratively. Below, a DRL file is
+ added. Unlike Drools 4.0 Package Builder, the Knowledge Builder can now
handle multiple namespaces, so you can just keep adding resources
regardless of namespace.</para>
@@ -93,9 +95,9 @@
</programlisting>
</example>
- <para>It is best practice to always check the hasErrors() method after an
- addition. You should not add more resources or retrieve the KnowledgePackages
- if there are errors. getKnowledgePackages() returns an empty list if
+ <para>It is best practice to always check the <code>hasErrors()</code> method after an
+ addition. You should not add more resources or retrieve the Knowledge Packages
+ if there are errors. <code>getKnowledgePackages()</code> returns an empty list if
there are errors.</para>
<example>
@@ -109,9 +111,9 @@
</example>
<para>When all the resources have been added and there are no errors the
- collection of KnowledgePackages can be retrieved. It is a Collection because
- there is one KnowledgePackage per package namespace. These
- KnowledgePackages are serializable and often used as a unit of
+ collection of Knowledge Packages can be retrieved. It is a Collection because
+ there is one Knowledge Package per package namespace. These
+ Knowledge Packages are serializable and often used as a unit of
deployment.</para>
<example>
@@ -242,22 +244,22 @@
</programlisting>
</example>
- <para>Notice the "file:" prefix, this signifies the protocol for the
- resource. The ChangeSet supports all the protocols provided by
+ <para>Notice the <code>file:</code> prefix, which signifies the protocol for the
+ resource. The Change Set supports all the protocols provided by
java.net.URL, such as "file" and "http", as well as an additional
"classpath". Currently the type attribute must always be specified for a
resource, as it is not inferred from the file name extension. Using the
- ClassPath resource loader in Java allows you to specify the ClassLoader to
+ ClassPath resource loader in Java allows you to specify the Class Loader to
be used to locate the resource but this is not possible from XML. Instead,
- the ClassLoader will default to the one used by the KnowledgeBuilder
+ the Class Loader will default to the one used by the Knowledge Builder
unless the ChangeSet XML is itself loaded by the ClassPath resource, in
- which case it will use the ClassLoader specified for that resource.</para>
+ which case it will use the Class Loader specified for that resource.</para>
<para>Currently you still need to use the API to load that ChangeSet, but
we will add support for containers such as Spring in the future, so that the
- process of creating a KnowledgeBase can be done completely by XML configuration.
+ process of creating a Knowledge Base can be done completely by XML configuration.
Loading resources using an XML file couldn't be simpler, as it's just another
- ResourceType.</para>
+ resource type.</para>
<example>
<title>Loading the ChangeSet XML</title>
@@ -266,7 +268,7 @@
</programlisting>
</example>
- <para>Changesets can include any number of resources, and they even support
+ <para>ChangeSets can include any number of resources, and they even support
additional configuration information, which currently is only needed for
decision tables. Below, the example is expanded to load rules from a
http URL location, and an Excel decision table from the classpath.</para>
@@ -287,16 +289,16 @@
</programlisting>
</example>
- <para>The ChangeSet is especially useful when working with KnowledgeAgent,
+ <para>The ChangeSet is especially useful when working with a Knowledge Agent,
as it allows for change notification and automatic rebuilding of the
- KnowledgeBase, which is covered in more detail in the section on the
- KnowledgeAgent, under Deploying.</para>
+ Knowledge Base, which is covered in more detail in the section on the
+ Knowledge Agent, under Deploying.</para>
<para>Directories can also be specified, to add all resources
in that folder. Currently it is expected that all resources in
- that folder are of the same type. If you use the KnowledgeAgent it will
+ that folder are of the same type. If you use the Knowledge Agent it will
provide a continous scanning for added, modified or removed resources and
- rebuild the cached KnowledgeBase. The KnowledgeAgent provides more
+ rebuild the cached Knowledge Base. The KnowledgeAgent provides more
information on this.</para>
<example>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-User_Guide/Section-Deploying.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-User_Guide/Section-Deploying.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-User_Guide/Section-Deploying.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -11,9 +11,9 @@
<section>
<title>KnowledgePackage and Knowledge Definitions</title>
- <para>A KnowledgePackage is a collection of Knowledge Definitions, such
- as rules and processes. It is created by the KnowledgeBuilder, as
- described in chapter "Building". KnowledgePackages are self-contained and
+ <para>A Knowledge Package is a collection of Knowledge Definitions, such
+ as rules and processes. It is created by the Knowledge Builder, as
+ described in the chapter "Building". Knowledge Packages are self-contained and
serializable, and they currently form the basic deployment unit.</para>
<figure>
@@ -26,9 +26,9 @@
</mediaobject>
</figure>
- <para>KnowledgePackages are added to the KnowledgeBase. However, a
- KnowledgePackage instance cannot be reused once it's added to the
- KnowledgeBase. If you need to add it to another KnowledgeBase, try
+ <para>Knowledge Packages are added to the Knowledge Base. However, a
+ Knowledge Package instance cannot be reused once it's added to the
+ Knowledge Base. If you need to add it to another Knowledge Base, try
serializing it first and using the "cloned" result. We hope to fix this
limitation in future versions of Drools.</para>
</section>
@@ -36,14 +36,14 @@
<section>
<title>KnowledgeBase</title>
- <para>The KnowlegeBase is a repository of all the application's knowledge
+ <para>The Knowlege Base is a repository of all the application's knowledge
definitions. It may contain rules, processes, functions, and type models.
- The KnowledgeBase itself does not contain instance data, known as facts;
- instead, sessions are created from the KnowledgeBase into which data can be
+ The Knowledge Base itself does not contain instance data, known as facts;
+ instead, sessions are created from the Knowledge Base into which data can be
inserted and where process instances may be started. Creating the
- KnowlegeBase can be
+ Knowlege Base can be
heavy, whereas session creation is very light, so it is recommended that
- KnowleBases be cached where possible to allow for repeated session
+ Knowledge Bases be cached where possible to allow for repeated session
creation.</para>
<figure>
@@ -51,14 +51,15 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-User_Guide/KnowledgeBase.png"></imagedata>
+ <imagedata width="100%"
+ fileref="images/Chapter-User_Guide/KnowledgeBase.png"></imagedata>
</imageobject>
</mediaobject>
</figure>
- <para>The KnowledgeBase is also serializable and some people may prefer to
- build and then store the KnowledgeBase, treating it also as a unit of
- deployment, instead of the KnowledgePackages.</para>
+ <para>A <code>KnowledgeBase</code> object is also serializable, and some people
+ may prefer to build and then store a <code>KnowledgeBase</code>, treating it also
+ as a unit of deployment, instead of the Knowledge Packages.</para>
<para>The KnowlegeBase is created using the KnowledgeBaseFactory.</para>
@@ -67,7 +68,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-User_Guide/KnowledgeBaseFactory.png"></imagedata>
+ <imagedata width="100%"
+ fileref="images/Chapter-User_Guide/KnowledgeBaseFactory.png"></imagedata>
</imageobject>
</mediaobject>
</figure>
@@ -81,10 +83,10 @@
<programlisting>KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();</programlisting>
</example>
- <para>If a custom ClassLoader was used with the KnowledgeBuilder to
- resolve types not in the default ClassLoader, then that must also be set
- on the KnowledgeBuilder. The technique for this is the same as with the
- KnowledgeBuilder.</para>
+ <para>If a custom class loader was used with the <code>KnowledgeBuilder</code> to
+ resolve types not in the default class loader, then that must also be set
+ on the <code>KnowledgeBase</code>. The technique for this is the same as with the
+ <code>KnowledgeBuilder</code>.</para>
<example>
<title>Creating a new KnowledgeBase with a custom ClassLoader</title>
@@ -99,7 +101,7 @@
<title>In-Process Building and Deployment</title>
<para>This is the simplest form of deployment. It compiles the
- knowledge definitions and adds them to the KnowledgeBase in the same JVM.
+ knowledge definitions and adds them to the Knowledge Base in the same JVM.
This approach requires drools-core.jar and drools-compiler.jar to be on
the classpath.</para>
@@ -112,17 +114,19 @@
kbase.addKnowledgePackages( kpkgs );</programlisting>
</example>
- <para>Note that the addKnowledgePackages(kpkgs) method can be called
+ <para>Note that the <code>addKnowledgePackages(kpkgs)</code> method can be called
iteratively to add additional knowledge.</para>
</section>
<section>
<title>Building and Deployment in Separate Processes</title>
- <para>Both the KnowledgeBase and the KnowledgePackage are units of
+ <para>Both the <code>KnowledgeBase</code> and the <code>KnowledgePackage</code>
+ are units of
deployment and serializable. This means you can have one machine do any
- necessary building, requiring drools-compiler.jar, and have another
- machine deploy and execute everything, needing only drools-core.jar.</para>
+ necessary building, requiring <filename>drools-compiler.jar</filename>, and
+ have another machine deploy and execute everything, needing only
+ <filename>drools-core.jar</filename>.</para>
<para>Although serialization is standard Java, we present an example of
how one machine might write out the deployment unit and how another
@@ -151,23 +155,24 @@
</programlisting>
</example>
- <para>The KnowledgeBase is also serializable and some people may prefer
- to build and then store the KnowledgeBase itself, instead of the
- KnowledgePackages.</para>
+ <para>The <code>KnowledgeBase</code> is also serializable and some people may prefer
+ to build and then store the <code>KnowledgeBase</code> itself, instead of the
+ Knowledge Packages.</para>
<para>Drools Guvnor, our server side management system, uses this
deployment approach. After Guvnor has compiled and published serialized
- KnowledgePackages on a URL, Drools can use the URL resource type
+ Knowledge Packages on a URL, Drools can use the URL resource type
to load them.</para>
</section>
<section>
<title>StatefulknowledgeSessions and KnowledgeBase Modifications</title>
- <para>StatefulKnowledgeSessions will be discussed in more detail in
- section "Running". The KnowledgeBase creates and returns
- StatefulKnowledgeSessions and it may optionally keep references to those.
- When KnowledgeBase modifications occur those modifications are applied
+ <para>Stateful Knowledge Sessions will be discussed in more detail in
+ section "Running". The <code>KnowledgeBase</code> creates and returns
+ <code>StatefulKnowledgeSession</code> objects, and it may optionally
+ keep references to those.
+ When <code>KnowledgeBase</code> modifications occur those modifications are applied
against the data in the sessions. This reference is a weak reference and it
is also optional, which is controlled by a boolean flag.</para>
</section>
@@ -175,28 +180,30 @@
<section>
<title>KnowledgeAgent</title>
- <para>The KnowlegeAgent provides automatic loading, caching and
+ <para>The <code>KnowlegeAgent</code> provides automatic loading, caching and
re-loading of resources and is configured from a properties files. The
- KnowledgeAgent can update or rebuild this KnowlegeBase as the resources it
- uses are changed. The strategy for this is determined by the configuration
+ Knowledge Agent can update or rebuild this Knowlege Base as the
+ resources it uses are changed. The strategy for this is determined by the configuration
given to the factory, but it is typically pull-based using regular
polling. We hope to add push-based updates and rebuilds in future
- versions. The KnowledgeAgent will continuously scan all the added
+ versions. The Knowledge Agent will continuously scan all the added
resources, using a default polling interval of 60 seconds. If their
date of the last modification is updated it will rebuild the cached
- KnowledgeBase using the new resources.</para>
+ Knowledge Base using the new resources.</para>
<figure>
<title>KnowledgeAgent</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-User_Guide/KnowledgeAgent.png"></imagedata>
+ <imagedata width="100%"
+ fileref="images/Chapter-User_Guide/KnowledgeAgent.png"></imagedata>
</imageobject>
</mediaobject>
</figure>
- <para>The KnowlegeBuilder is created using the KnowledgeBuilderFactory.
+ <para>The <code>KnowlegeBuilder</code> is created using a
+ <code>KnowledgeBuilderFactory</code> object.
The agent must specify a name, which is used in the log files to associate
a log entry with the corresponding agent.</para>
@@ -212,7 +219,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-User_Guide/KnowledgeAgentFactory.png"></imagedata>
+ <imagedata width="100%"
+ fileref="images/Chapter-User_Guide/KnowledgeAgentFactory.png"></imagedata>
</imageobject>
</mediaobject>
</figure>
@@ -224,9 +232,9 @@
modify elements of the ChangeSet XML are not implemented, but future
versions will provide this as well, giving you more control over those
incremental changes.
- The KLnowledgeAgent polls the resources added from the ChangeSet
+ The Knowledge Agent polls the resources added from the ChangeSet
every 60 seconds, the default interval, to see if they are updated.
- Whenever changes are found it will construct a new KnowledgeBase.
+ Whenever changes are found it will construct a new Knowledge Base.
If the change set specifies a resource that
is a directory its contents will be scanned for changes, too.</para>
@@ -252,9 +260,9 @@
</example>
<para>The default resource scanning period may be changed via the
- ResourceChangeScannerService. A suitably updated
- ResourceChangeScannerConfiguration object is passed to the service's
- configure() method, which allows for the service to be reconfigured on
+ <code>ResourceChangeScannerService</code>. A suitably updated
+ <code>ResourceChangeScannerConfiguration</code> object is passed to the service's
+ <code>configure()</code> method, which allows for the service to be reconfigured on
demand.</para>
<example>
@@ -268,20 +276,20 @@
</programlisting>
</example>
- <para>KnowledgeAgents can take an empty KnowledgeBase or a populated one.
- If a populated KnowledgeBase is provided, the KnowledgeAgent will
- run an iterator from KnowledgeBase and subscribe to the resources that
+ <para>Knowledge Agents can take an empty Knowledge Base or a populated one.
+ If a populated Knowledge Base is provided, the Knowledge Agent will
+ run an iterator from Knowledge Base and subscribe to the resources that
it finds. While it is
- possible for the KnowledgeBuilder to build all resources found in a
- directory, that information is lost by the KnowledgeBuilder so that those
+ possible for the Knowledge Builder to build all resources found in a
+ directory, that information is lost by the Knowledge Builder so that those
directories will not be continuously scanned. Only directories specified
- as part of the applyChangeSet(Resource) method are monitored.</para>
+ as part of the <code>applyChangeSet(Resource)</code> method are monitored.</para>
- <para>One of the advantages of providing KnowledgeBase as the starting
- point is that you can provide it with a KnowledgeBaseConfiguration. When
- resource changes are detected and a new KnowledgeBase is instantiated, it
- will use the KnowledgeBaseConfiguration of the previous
- KnowledgeBase.</para>
+ <para>One of the advantages of providing <code>KnowledgeBase</code> as the starting
+ point is that you can provide it with a <code>KnowledgeBaseConfiguration</code>. When
+ resource changes are detected and a new <code>KnowledgeBase</code> object is
+ instantiated, it will use the <code>KnowledgeBaseConfiguration</code> of the previous
+ <code>KnowledgeBase</code> object.</para>
<example>
<title>Using an existing KnowledgeBase</title>
@@ -297,19 +305,19 @@
</programlisting>
</example>
- <para>In the above example getKnowledgeBase will return the same
+ <para>In the above example <code>getKnowledgeBase()</code> will return the same
provided kbase instance until resource changes are detected and a new
- KnowledgeBase is built. When the new KnowledgeBase is built, it will be
- done with the KnowledgeBaseConfiguration that was provided to the previous
- KnowledgeBase.</para>
+ Knowledge Base is built. When the new Knowledge Base is built, it will be
+ done with the <code>KnowledgeBaseConfiguration</code> that was provided to
+ the previous <code>KnowledgeBase</code>.</para>
<para>As mentioned previously, a ChangeSet XML can specify a directory and
all of its contents will be added. If this ChangeSet XML is used with the
- applyChangeSet method it will also add any directories to the scanning
+ <code>applyChangeSet()</code> method it will also add any directories to the scanning
process. When the directory scan detects an additional file, it will be
- added to the KnowledgeBase; any removed file is removed from the
- KnowledgeBase, and modified files will, as usual, force the build of a
- new KnowledgeBase using the latest version.</para>
+ added to the Knowledge Base; any removed file is removed from the
+ Knowledge Base, and modified files will, as usual, force the build of a
+ new Knowledge Base using the latest version.</para>
<example>
<title>ChangeSet XML which adds a directories contents</title>
@@ -325,11 +333,11 @@
</example>
<para>Note that for the resource type PKG the drools-compiler dependency is
- not needed as the KnowledgeAgent is able to handle those with just
+ not needed as the Knowledge Agent is able to handle those with just
drools-core.</para>
- <para>The KnowledgeAgentConfiguration can be used to modify a
- KnowledgeAgent's default behavior. You could use this to load
+ <para>The <code>KnowledgeAgentConfiguration</code> can be used to modify a
+ Knowledge Agent's default behavior. You could use this to load
the resources from a directory, while inhibiting the continuous scan
for changes of that directory.</para>
@@ -348,8 +356,8 @@
</example>
<para>Previously we mentioned Drools Guvnor and how it can build and
- publish serialized KnowledgePackages on a URL, and that the
+ publish serialized Knowledge Packages on a URL, and that the
ChangeSet XML can handle URLs and Packages. Taken together, this forms
- an importanty deployment scenario for the KnowledgeAgent.</para>
+ an importanty deployment scenario for the Knowledge Agent.</para>
</section>
</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-User_Guide/Section-Running.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-User_Guide/Section-Running.xml 2009-04-23 18:40:47 UTC (rev 26226)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-User_Guide/Section-Running.xml 2009-04-23 18:49:22 UTC (rev 26227)
@@ -13,14 +13,13 @@
<section>
<title>KnowledgeBase</title>
- <para>The KnowlegeBase is a repository of all the application's knowledge
+ <para>The <code>KnowlegeBase</code> is a repository of all the application's knowledge
definitions. It will contain rules, processes, functions, and type models.
- The
- KnowledgeBase itself does not contain data; instead, sessions are created
- from the KnowledgeBase into which data can be inserted and from which
- process instances may be started. Creating the KnowlegeBase can be heavy,
+ The Knowledge Base itself does not contain data; instead, sessions are created
+ from the <code>KnowledgeBase</code> into which data can be inserted and from which
+ process instances may be started. Creating the <code>KnowlegeBase</code> can be heavy,
whereas session creation
- is very light, so it is recommended that KnowleBases be cached where
+ is very light, so it is recommended that Knowle Bases be cached where
possible to allow for repeated session creation.</para>
<example>
@@ -33,15 +32,16 @@
<section>
<title>StatefulKnowledgeSession</title>
- <para>The StatefulKnowledgeSession stores and executes on the runtime data.
- It is created from the KnowledgeBase.</para>
+ <para>The <code>StatefulKnowledgeSession</code> stores and executes on the runtime data.
+ It is created from the <code>KnowledgeBase</code>.</para>
<figure>
<title>StatefulKnowledgeSession</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-User_Guide/StatefulKnowledgeSession.png"
+ <imagedata width="100%"
+ fileref="images/Chapter-User_Guide/StatefulKnowledgeSession.png"
format=""></imagedata>
</imageobject>
</mediaobject>
@@ -61,25 +61,25 @@
<section>
<title>WorkingMemoryEntryPoint</title>
- <para>The WorkingMemoryEntryPoint provides the methods around inserting,
+ <para>The <code>WorkingMemoryEntryPoint</code> provides the methods around inserting,
updating and retrieving facts. The term "entry point" is related to the
fact
- that we have multiple partitions in a WorkingMemory and you can choose
+ that we have multiple partitions in a Working Memory and you can choose
which one you are inserting into, although this use case is aimed at
event processing and covered in more detail in the Fusion manual. Most
rule based applications will work with the default entry point
alone.</para>
- <para>The KnowledgeRuntime interface provides the main interaction with
+ <para>The <code>KnowledgeRuntime</code> interface provides the main interaction with
the engine. It is available in rule consequences and process actions. In
this manual the focus is on the methods and interfaces related to rules,
and the methods pertaining to processes will be ignored for now. But
- you'll notice that the
- KnowledgeRuntime inherits methods from both the WorkingMemory and the
- ProcessRuntime, therby providing a unified API to work with processes and
+ you'll notice that the <code>KnowledgeRuntime</code> inherits methods
+ from both the <code>WorkingMemory</code> and the <code>ProcessRuntime</code>,
+ thereby providing a unified API to work with processes and
rules. When working with rules, three interfaces form the
- KnowledgeRuntime: WorkingMemoryEntryPoint, WorkingMemory and the
- KnowledgeRuntime itself.</para>
+ <code>KnowledgeRuntime</code>: <code>WorkingMemoryEntryPoint</code>,
+ <code>WorkingMemory</code> and the <code>KnowledgeRuntime</code> itself.</para>
<figure>
<title>WorkingMemoryEntryPoint</title>
@@ -106,8 +106,8 @@
<code>fireAllRules()</code>. Expert systems typically use the term
<emphasis>assert</emphasis> or <emphasis>assertion</emphasis> to
refer to facts made available to the system. However, due to
- <code>assert</code> being a keyword in most languages, we have decided
- to use the <code>insert</code> keyword; so expect to hear the two used
+ "assert" being a keyword in most languages, we have decided
+ to use the <kw>insert</kw> keyword; so expect to hear the two used
interchangeably.</para>
<!-- FIXME - I think we might want to add this sentence to the previous paragraph.
@@ -124,7 +124,7 @@
<programlisting>Cheese stilton = new Cheese("stilton");
FactHandle stiltonHandle = ksession.insert( stilton ); </programlisting>
- <para>As mentioned in the KnowledgeBase section a WorkingMemory may
+ <para>As mentioned in the Knowledge Base section, a Working Memory may
operate in two assertion modes, i.e., equality or identity, with
identity being the default.</para>
@@ -167,14 +167,14 @@
can be reprocessed. Internally, modification is actually a retract
followed by an insert; the Rule Engine removes the fact from the
<code>WorkingMemory</code> and inserts it again. You must use the
- <code>update</code> method to notify the <code>WorkingMemory</code> of
+ <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>
+ <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
+ <code>update()</code> method can only be used with objects that have
shadow proxies turned on. The update method is only available within
- Java code. On the right hand side of a rule, also the "modify"
+ Java code. On the right hand side of a rule, also the <kw>modify</kw>
statement is supported, providing simplified calls to the
object's setters.</para>
@@ -190,14 +190,15 @@
<title>WorkingMemory</title>
<para>The WorkingMemory provides access to the Agenda, permits
- query executions, and lets you access named EntyPoints,</para>
+ query executions, and lets you access named Enty Points.</para>
<figure>
<title>WorkingMemory</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-User_Guide/WorkingMemory.png"
+ <imagedata width="100%"
+ fileref="images/Chapter-User_Guide/WorkingMemory.png"
format=""></imagedata>
</imageobject>
</mediaobject>
@@ -208,7 +209,7 @@
<para>Queries are used to retrieve fact sets based on patterns,
as they are used in rules. Patterns may make use of optional
- parameters. Queries can be defined in the KnowlegeBase, from
+ parameters. Queries can be defined in the Knowlege Base, from
where they are called up to return the matching results. While
iterating over the result collection, any bound
identifier in the query can be accessed using the get(String
@@ -251,9 +252,9 @@
<section>
<title>KnowledgeRuntime</title>
- <para>The KnowledgeRuntime provides further methods that are applicable
- to both rules and processes, such as setting globals and registering
- ExitPoints.</para>
+ <para>The <code>KnowledgeRuntime</code> provides further methods that
+ are applicable to both rules and processes, such as setting globals
+ and registering <code>ExitPoints</code>.</para>
<figure>
<title>KnowledgeRuntime</title>
@@ -280,11 +281,10 @@
<programlisting>global java.util.List list</programlisting>
<para>With the Knowledge Base now aware of the global identifier and
- its type, it is now possible to call <code>ksession.setGlobal</code>
+ its type, it is now possible to call <code>ksession.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>ksession.setGlobal(identifier,
- value)</code>:</para>
+ the session use <code>ksession.setGlobal(identifier, value)</code>:</para>
<programlisting>List list = new ArrayList();
ksession.setGlobal("list", list); </programlisting>
@@ -297,9 +297,9 @@
<section>
<title>StatefulRuleSession</title>
- <para>The StatefulRuleSession is inherited by the
- StatefulKnowledgeSession and provides the rule related methods that are
- relevant from outside of the engine.</para>
+ <para>The <code>StatefulRuleSession</code> is inherited by the
+ <code>StatefulKnowledgeSession</code> and provides the rule related
+ methods that are relevant from outside of the engine.</para>
<figure>
<title>StatefulRuleSession</title>
@@ -327,7 +327,7 @@
</mediaobject>
</figure>
- <para>Agenda filters are optional implementations of the filter
+ <para><code>AgendaFilter</code> objects are optional implementations of the filter
interface which are used to allow or deny the firing of an activation.
What you filter on is entirely up to the implementation. Drools 4.0
used to supply some out of the box filters, which have not be exposed
@@ -335,8 +335,8 @@
Drools 4.0 code base can be referred to.</para>
<para>To use a filter specify it while calling
- <code>FireAllRules</code>. The following example permits only rules
- ending in the string <emphasis>Test</emphasis>. All others will be
+ <code>fireAllRules()</code>. The following example permits only rules
+ ending in the string <code>"Test"</code>. All others will be
filtered out. <programlisting>ksession.fireAllRules( new RuleNameEndsWithAgendaFilter( "Test" ) );</programlisting></para>
</section>
</section>
@@ -359,8 +359,8 @@
<orderedlist>
<listitem>
<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
+ place, either in the Consequence (the RHS itself) or the
+ main Java application process. Once the Consequence has
finished or the main Java application process calls
<code>fireAllRules()</code> the engine switches to the Agenda
Evaluation phase.</para>
@@ -378,7 +378,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center"
+ <imagedata width="100%" align="center"
fileref="images/Chapter-Rule_Engine/Two_Phase.png"
format="PNG"></imagedata>
</imageobject>
@@ -411,7 +411,8 @@
<para>The default conflict resolution strategies employed by Drools are:
Salience and LIFO (last in, first out).</para>
- <para>The most visible one is "salience" or priority, in which case a
+ <para>The most visible one is <emphasis>salience</emphasis> (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 rule with higher
salience will be preferred. LIFO priorities are based on the assigned
@@ -483,7 +484,7 @@
<para>An activation group is a set of rules bound together by the same
"activation-group" rule attribute. In this group only one rule can fire,
and after that rule has fired all the other rules are cancelled from
- the agenda. The clear()
+ the agenda. The <code>clear()</code>
method can be called at any time, which cancels all of the activations
before one has had a chance to fire.
<programlisting>ksession.getAgenda().getActivationGroup( "Group B" ).clear();</programlisting></para>
@@ -507,7 +508,7 @@
"ruleflow-group" rule attribute. These rules can only fire when the
group is activate. The group itself can only become active when the
elaboration of the ruleflow diagram reaches the node representing the
- group. Here too, the clear() method can be called at any time to
+ group. Here too, the <code>clear()</code> method can be called at any time to
cancels all activations still remaining on the Agenda.
<programlisting>ksession.getAgenda().getRuleFlowGroup( "Group C" ).clear();</programlisting></para>
</section>
@@ -521,10 +522,11 @@
you, for instance, to separate logging and auditing activities from the
main part of your application (and the rules).</para>
- <para>The KnowlegeRuntimeEventManager interface is implemented by the
- KnowledgeRuntime which provides two interfaces, WorkingMemoryEventManager
- and ProcessEventManager. We will only cover the WorkingMemoryEventManager
- here.</para>
+ <para>The <code>KnowlegeRuntimeEventManager</code> interface is
+ implemented by the <code>KnowledgeRuntime</code> which provides two
+ interfaces, <code>WorkingMemoryEventManager</code> and
+ <code>ProcessEventManager</code>. We will only cover the
+ <code>WorkingMemoryEventManager</code> here.</para>
<figure>
<title>KnowledgeRuntimeEventManager</title>
@@ -537,7 +539,7 @@
</mediaobject>
</figure>
- <para>The WorkingMemoryEventManager allows for listeners to be added and
+ <para>The <code>WorkingMemoryEventManager</code> allows for listeners to be added and
removed, so that events for the working memory and the agenda can be
listened to.</para>
@@ -546,7 +548,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-User_Guide/WorkingMemoryEventManager.png"
+ <imagedata width="100%"
+ fileref="images/Chapter-User_Guide/WorkingMemoryEventManager.png"
format=""></imagedata>
</imageobject>
</mediaobject>
@@ -578,8 +581,8 @@
<programlisting>ksession.addEventListener( new DebugWorkingMemoryEventListener() ); </programlisting>
</example>
- <para>All emitted events implement the KnowlegeRuntimeEvent interface
- which can be used to retrieve the actual KnowlegeRuntime the event
+ <para>All emitted events implement the <code>KnowlegeRuntimeEvent</code> interface
+ which can be used to retrieve the actual <code>KnowlegeRuntime</code> the event
originated from.</para>
<figure>
@@ -663,7 +666,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-User_Guide/KnowledgeRuntimeLoggerFactory.png"
+ <imagedata width="100%"
+ fileref="images/Chapter-User_Guide/KnowledgeRuntimeLoggerFactory.png"
format=""></imagedata>
</imageobject>
</mediaobject>
@@ -685,12 +689,12 @@
<para>The <code>StatelessKnowledgeSession</code> wraps the
<code>StatefulKnowledgeSession</code>, instead of extending it. Its main
focus is on decision service type scenarios. It avoids the need to call
- dispose(). Stateless sessions do not support iterative insertions and
- the method call <code>fireAllRules</code> from Java code; the act of
- calling <code>execute</code> is a single shot method that will
+ <code>dispose()</code>. Stateless sessions do not support iterative insertions and
+ the method call <code>fireAllRules()</code> from Java code; the act of
+ calling <code>execute()</code> is a single-shot method that will
internally instantiate a <code>StatefulKnowledgeSession</code>,
add all the user data and execute user commands, call
- <code>fireAllRules</code>, and then call <code>dispose()</code>. While
+ <code>fireAllRules()</code>, and then call <code>dispose()</code>. While
the main way to work with this class is via the
<code>BatchExecution</code> (a subinterface of <code>Command</code>)
as supported by the <code>CommandExecutor</code> interface, two
@@ -704,7 +708,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-User_Guide/StatelessKnowledgeSession.png"
+ <imagedata width="100%"
+ fileref="images/Chapter-User_Guide/StatelessKnowledgeSession.png"
format=""></imagedata>
</imageobject>
</mediaobject>
@@ -741,12 +746,12 @@
<para>If you wanted to insert the collection itself, and the
collection's individual elements, then
- <code>CommandFactory.newInsert( collection )</code> would do the job.</para>
+ <code>CommandFactory.newInsert(collection)</code> would do the job.</para>
<para>Methods of the <code>CommandFactory</code> create the supported
commands, all of which can be marshalled using XStream and the
<code>BatchExecutionHelper</code>.
- BatchExecutionHelper provides details on the XML format as well as how to
+ <code>BatchExecutionHelper</code> provides details on the XML format as well as how to
use Drools Pipeline to automate the marshalling of
<code>BatchExecution</code> and <code>ExecutionResults</code>.</para>
@@ -757,7 +762,7 @@
<itemizedlist>
<listitem>
- <para>The StatelessKnowledgeSession method getGlobals() returns a Globals
+ <para>The Stateless Knowledge Session method <code>getGlobals()</code> returns a Globals
instance which provides access to the session's globals. These are
shared for <emphasis>all</emphasis> execution calls. Exercise
caution regarding mutable globals because execution
@@ -792,7 +797,7 @@
</listitem>
</itemizedlist>
- <para>The CommandExecutor interface also offers the ability to export
+ <para>The <code>CommandExecutor</code> interface also offers the ability to export
data via "out" parameters. Inserted facts, globals and query results can
all be returned.</para>
@@ -845,9 +850,9 @@
</listitem>
<listitem>
- <para>Disconnect the LeftInputAdapterNode propagation, and let the
+ <para>Disconnect the Left Input Adapter Node 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>
+ added to a list on the Working Memory for later execution.</para>
</listitem>
<listitem>
@@ -874,18 +879,18 @@
</listitem>
</orderedlist>
- <para>The LeftInputAdapterNode no longer creates a Tuple, adding the
- Object, and then propagate the Tuple – instead a Command Object is
- created and added to a list in the Working Memory. This Command Object
- holds a reference to the LeftInputAdapterNode and the propagated Object.
+ <para>The <code>LeftInputAdapterNode</code> no longer creates a Tuple, adding the
+ Object, and then propagate the Tuple – instead a Command object is
+ created and added to a list in the Working Memory. This Command object
+ holds a reference to the <code>LeftInputAdapterNode</code> and the propagated object.
This stops any left-input propagations at insertion time, so that we
know that 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, which means that the
- only node remembering an insertion propagation is the right-input Object
+ memory but 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
+ memories populated, we can then iterate the list of <code>LeftInputAdatperNode</code>
Command objects calling each in turn. They will propagate down the
network attempting to join with the right-input objects, but they won't be
remembered in the left input as we know there will be no further object
@@ -893,23 +898,23 @@
<para>There is no longer an Agenda, with a priority queue to schedule
the Tuples; instead, there is simply an array for the number of rules.
- The sequence number of the RuleTerminalNode indicates the element within
- the array where to place the Activation. Once all Command Objects have
+ The sequence number of the <code>RuleTerminalNode</code> indicates the element within
+ the array where 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, we remember
the first and the last populated cell in the array. The network is
- constructed, with each RuleTerminalNode being given a sequence number
+ constructed, with each <code>RuleTerminalNode</code> being 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; 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 only a few instances,
+ <para>Typically the right-input node memories are Hash Maps, for fast
+ 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 Hash Maps provide a performance
+ increase; if we know an object type has only a few instances,
indexing is probably not advantageous, and a list can be used.</para>
- <para>Sequential mode can only be used with a StatelessSession and is
+ <para>Sequential mode can only be used with a Stateless Session and is
off by default. To turn it on, either call
<code>RuleBaseConfiguration.setSequential(true)</code>, or set the
rulebase configuration property <code>drools.sequential</code> to true.
@@ -923,7 +928,7 @@
<section>
<title>Pipeline</title>
- <para>The PipelineFactory and associated classes are there to help with
+ <para>The <code>PipelineFactory</code> and associated classes are there to help with
the automation of getting information into and out of Drools, especially
when using services such as Java Message Service (JMS), and other data
sources that aren't Java objects. Transformers
@@ -941,7 +946,8 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-User_Guide/PipelineFactory.png"
+ <imagedata width="100%"
+ fileref="images/Chapter-User_Guide/PipelineFactory.png"
format=""></imagedata>
</imageobject>
</mediaobject>
@@ -952,15 +958,18 @@
Drools use cases.</para>
<para>In Drools, a pipeline is a series of stages that operate on and
- propagate a given payload. Typically this starts with a Pipeline instance
- which is responsible for taking the payload, creating a PipelineContext
- for it and propagating that to the first Receiver stage. Two subtypes of
- Pipeline are provided, both requiring a different PipelineContext:
- StatefulKnowledgeSessionPipeline and StatelessKnowledgeSessionPipeline.
- PipelineFactory provides methods to create both of the two Pipeline subtypes.
+ propagate a given payload. Typically this starts with a <code>Pipeline</code>
+ instance which is responsible for taking the payload, creating a
+ <code>PipelineContext</code> for it and propagating that to the first
+ receiver stage. Two subtypes of <code>Pipeline</code> are provided,
+ both requiring a different <code>PipelineContext</code>:
+ <code>StatefulKnowledgeSessionPipeline</code> and
+ <code>StatelessKnowledgeSessionPipeline</code>.
+ <code>PipelineFactory</code> provides methods to create both of the two
+ <code>Pipeline</code> subtypes.
Notice that both factory methods take the relevant session as an
- argument. The construction of a StatefulKnowledgeSessionPipeline is shown
- below, where also its receiver is set.</para>
+ argument. The construction of a <code>StatefulKnowledgeSessionPipeline</code>
+ is shown below, where also its receiver is set.</para>
<example>
<title>StatefulKnowledgeSessionPipeline</title>
@@ -969,13 +978,14 @@
pipeline.setReceiver( receiver );</programlisting>
</example>
- <para>A pipeline is then made up of a chain of Stages that implement
- both the Emitter and the Receiver interfaces. The Emitter interface enables
- the stage to propagate a payload, and the Receiver interface lets it
- receive a payload. This is why the Pipeline interface only implements
- Emitter and Stage and not Receiver, as it is the first instance in the
- chain. The Stage interface allows a custom exception handler to be set on
- the Stage.</para>
+ <para>A pipeline is then made up of a chain of <code>Stage</code>s that implement
+ both the <code>Emitter</code> and the <code>Receiver</code> interfaces. The
+ <code>Emitter</code> interface enables the <code>Stage</code> to propagate
+ a payload, and the <code>Receiver</code> interface lets it
+ receive a payload. This is why the <code>Pipeline</code> interface only implements
+ <code>Emitter</code> and <code>Stage</code> and not <code>Receiver</code>, as it
+ is the first instance in the chain. The <code>Stage</code> interface allows a
+ custom exception handler to be set on the <code>Stage</code> object.</para>
<example>
<title>StageExceptionHandler</title>
@@ -985,16 +995,18 @@
</programlisting>
</example>
- <para>The Transformer interface extends Stage, Emitter and
- Receiver, providing those interface methods as a single type.
+ <para>The <code>Transformer</code> interface extends <code>Stage</code>,
+ <code>Emitter</code> and <code>Receiver</code>, providing those interface
+ methods as a single type.
Its other purpose is that of a marker interface indicating this particulare
role of the implementing class. (We have several other marker interfaces
- such as Expression and Action, both of which also extend Stage, Emitter
- and Receiver.) One of the stages should be responsible for setting a result
- value on the PipelineContext. It's the responsibility of the ResultHandler
- interface, to be implemented by the user, to process on
- these results. It may do so by inserting them into some suitable object,
- whence the user's code may retrieve them.</para>
+ such as <code>Expression</code> and <code>Action</code>, both of which also
+ extend <code>Stage</code>, <code>Emitter</code> and <code>Receiver</code>.)
+ One of the stages should be responsible for setting a result
+ value on the <code>PipelineContext</code>. It's the responsibility of the
+ <code>ResultHandler</code> interface, to be implemented by the user, to
+ process on these results. It may do so by inserting them into some suitable
+ object, whence the user's code may retrieve them.</para>
<example>
<title>StageExceptionHandler</title>
@@ -1022,7 +1034,7 @@
work like sending the object as a message.</para>
<para>Pipeline provides an adapter to insert the payload and to create
- the correct PipelineContext internally.</para>
+ the correct Pipeline Context internally.</para>
<para>In general it is easier to construct the pipelines in reverse. In
the following example XML data is loaded from disk, transformed with
@@ -1059,9 +1071,9 @@
<para>While the above example is for loading a resource from disk, it is
also possible to work from a running messaging service. Drools currently
- provides a single service for JMS, called JmsMessenger. Support for other
+ provides a single service for JMS, called <code>JmsMessenger</code>. Support for other
services will be added later. The code below shows part of a unit test which
- illustrates part of the JmsMessenger in action:</para>
+ illustrates part of the <code>JmsMessenger</code> in action:</para>
<example>
<title>Using JMS with Pipeline</title>
@@ -1138,7 +1150,7 @@
<para>A JAXBContext maintains the set of Java classes that are
bound to XML elements. Such classes may be generated from an
- XML schema, by compiling it with JAXB's schema compiler xjc.
+ XML schema, by compiling it with JAXB's schema compiler <command>xjc</command>.
Alternatively, handwritten classes can be augmented with
annotations from <code>jaxb.xml.bind.annotation</code>.</para>
@@ -1236,7 +1248,7 @@
<section>
<title>JMS Messenger</title>
- <para>This transformer creates a new JmsMessenger which runs as a service
+ <para>This transformer creates a new <code>JmsMessenger</code> which runs as a service
in its own thread. It expects an existing JNDI entry for "ConnectionFactory",
used to create the MessageConsumer which will feed into the specified pipeline.</para>
@@ -1296,16 +1308,16 @@
interacted with them was different. StatelessSession used an execute(...)
method which would insert a collection of objects as facts.
StatefulSession didn't have this method, and insert used the more
- traditional insert(...) method. The other issue was that the
+ traditional <code>insert(...)</code> method. The other issue was that the
StatelessSession did not return any results, so that users themselves
had to map globals to get results, and it wasn't possible to do anything
besides inserting objects; users could not start processes or execute
queries.</para>
<para>Drools 5.0 addresses all of these issues and more. The foundation
- for this is the CommandExecutor interface, which both the stateful and
+ for this is the <code>CommandExecutor</code> interface, which both the stateful and
stateless interfaces extend, creating consistency and
- ExecutionResults:</para>
+ <code>ExecutionResults</code>:</para>
<figure>
<title>CommandExecutor</title>
@@ -1329,9 +1341,9 @@
</mediaobject>
</figure>
- <para>The CommandFactory allows for commands to be executed on those
- sessions, the only difference being that the StatelessKnowledgeSession
- executes fireAllRules() at the end before disposing the session. The
+ <para>The <code>CommandFactory</code> allows for commands to be executed on those
+ sessions, the only difference being that the Stateless Knowledge Session
+ executes <code>fireAllRules()</code> at the end before disposing the session. The
currently supported commands are:</para>
<itemizedlist>
@@ -1368,9 +1380,9 @@
</listitem>
</itemizedlist>
- <para>InsertObject will insert a single object, with an optional "out"
- identifier. InsertElements will iterate an Iterable, inserting each of the
- elements. What this means is that a StatelessKnowledgeSession is no longer
+ <para><code>InsertObject</code> will insert a single object, with an optional "out"
+ identifier. <code>InsertElements</code> will iterate an Iterable, inserting each of the
+ elements. What this means is that a Stateless Knowledge Session is no longer
limited to just inserting objects, it can now start processes or execute
queries, and do this in any order.</para>
@@ -1384,7 +1396,7 @@
</programlisting>
</example>
- <para>The execute method always returns an ExecutionResults instance,
+ <para>The execute method always returns an <code>ExecutionResults</code> instance,
which allows access to any command results if they specify an out
identifier such as the "stilton_id" above.</para>
@@ -1402,17 +1414,17 @@
</example>
<para>The execute method only allows for a single command. That's
- where BatchExecution comes in, which represents a composite command,
+ where <code>BatchExecution</code> comes in, which represents a composite command,
created from a list of commands. Now, execute will iterate over the
list and execute each command in turn. This
means you can insert some objects, start a process, call fireAllRules and
- execute a query, all in a single execute(...) call, which is quite
+ execute a query, all in a single <code>execute(...)</code> call, which is quite
powerful.</para>
- <para>As mentioned previosly, the StatelessKnowledgeSession will execute
- fireAllRules() automatically at the end. However the keen-eyed reader
- probably has already noticed the FireAllRules command and wondered how
- that works with a StatelessKnowledgeSession. The FireAllRules command is
+ <para>As mentioned previosly, the Stateless Knowledge Session will execute
+ <code>fireAllRules()</code> automatically at the end. However the keen-eyed reader
+ probably has already noticed the <code>FireAllRules</code> command and wondered how
+ that works with a StatelessKnowledgeSession. The <code>FireAllRules</code> command is
allowed, and using it will disable the automatic execution at the end;
think of using it as a sort of manual override function.</para>
@@ -1437,14 +1449,14 @@
</example>
<para>In the above example multiple commands are executed, two of which populate
- the ExecutionResults. The query command defaults to
+ the <code>ExecutionResults</code>. The query command defaults to
use the same identifier as the query name, but it can also be mapped to a
different identifier.</para>
<para>A custom XStream marshaller can be used with the Drools Pipeline
to achieve XML scripting, which is perfect for services. Here are two
simple XML samples, one for the BatchExecution and one for the
- ExecutionResults.</para>
+ <code>ExecutionResults</code>.</para>
<example>
<title>Simple BatchExecution XML</title>
@@ -1478,7 +1490,7 @@
<para>The previously mentioned pipeline allows for a series of
Stage objects, combined to help with getting data into and out of
- sessions. There is a Stage implementing the CommandExecutor interface
+ sessions. There is a Stage implementing the <code>CommandExecutor</code> interface
that allows the pipeline to script either a stateful or stateless
session. The pipeline setup is trivial:</para>
@@ -1506,13 +1518,13 @@
</programlisting>
</example>
- <para>The key thing here to note is the use of the BatchExecutionHelper to
- provide a specially configured XStream with custom converters for our
- Command objects and the new BatchExecutor stage.</para>
+ <para>The key thing here to note is the use of the <code>BatchExecutionHelper</code>
+ to provide a specially configured XStream with custom converters for our
+ Command objects and the new <code>BatchExecutor</code> stage.</para>
<para>Using the pipeline is very simple. You must provide your own
- implementation of the ResultHandler which is called when the pipeline
- executes the ExecuteResultHandler stage.</para>
+ implementation of the <code>ResultHandler</code> which is called when the pipeline
+ executes the <code>ExecuteResultHandler</code> stage.</para>
<figure>
<title>Pipeline ResultHandler</title>
@@ -1552,7 +1564,7 @@
</programlisting>
</example>
- <para>Earlier a BatchExecution was created with Java to insert some
+ <para>Earlier a <code>BatchExecution</code> was created with Java to insert some
objects and execute a query. The XML representation to be used with the
pipeline for that example is shown below, with parameters added to
the query.</para>
@@ -1576,8 +1588,8 @@
</programlisting>
</example>
- <para>The CommandExecutor returns an ExecutionResults, and this is handled
- by the pipeline code snippet as well. A similar output for the
+ <para>The <code>CommandExecutor</code> returns an <code>ExecutionResults</code>,
+ and this is handled by the pipeline code snippet as well. A similar output for the
<batch-execution> XML sample above would be:</para>
<example>
@@ -1615,18 +1627,18 @@
</programlisting>
</example>
- <para>The BatchExecutionHelper provides a configured XStream instance to
- support the marshalling of BatchExecutions, where the resulting XML can be
+ <para>The <code>BatchExecutionHelper</code> provides a configured XStream instance to
+ support the marshalling of Batch Executions, where the resulting XML can be
used as a message format, as shown above. Configured converters only exist
- for the commands supported via the CommandFactory. The user may add other
+ for the commands supported via the Command Factory. The user may add other
converters for their user objects. This is very useful for scripting
stateless or stateful knowledge sessions, especially when services are
involved.</para>
<para>There is currently no XML schema to support schema validation.
The basic format is outlined here, and the drools-transformer-xstream module
- has an illustrative unit test in the XStreamBatchExecutionTest unit test.
- The root element is <batch-execution> and it can contain zero or
+ has an illustrative unit test in the <code>XStreamBatchExecutionTest</code>
+ unit test. The root element is <batch-execution> and it can contain zero or
more commands elements.</para>
<example>
@@ -1640,7 +1652,7 @@
<para>This contains a list of elements that represent commands, the
supported commands is limited to those Commands provided by the
- CommandFactory. The most basic of these is the <insert> element,
+ Command Factory. The most basic of these is the <insert> element,
which inserts objects. The contents of the insert element is the user
object, as dictated by XStream.</para>
@@ -1655,7 +1667,7 @@
</programlisting>
</example>
- <para>The insert element features an 'out-identifier' attribute,
+ <para>The insert element features an "out-identifier" attribute,
demanding that the inserted object will also be returned as part
of the result payload.</para>
@@ -1672,7 +1684,7 @@
<para>It's also possible to insert a collection of objects using the
<insert-elements> element. This command does not support an
- out-identifier. The org.domain.UserClass is just an illustrative user
+ out-identifier. The <code>org.domain.UserClass</code> is just an illustrative user
object that XStream would serialize.</para>
<example>
@@ -1694,7 +1706,7 @@
</programlisting>
</example>
- <para>Next, there is the <set-global> element, which sets a global
+ <para>Next, there is the <code><set-global></code> element, which sets a global
for the session.</para>
<example>
@@ -1710,12 +1722,12 @@
</programlisting>
</example>
- <para><set-global> also supports two other optional attributes, 'out'
- and 'out-identifier'. A true value for the boolean 'out' will add the
- global to the <batch-execution-results> payload, using the name
- from the 'identifier' attribute. 'out-identifier' works like 'out' but
- additionally allows you to override the identifier used in the
- <batch-execution-results> payload.</para>
+ <para><code><set-global></code> also supports two other optional attributes,
+ <kw>out</kw> and <kw>out-identifier</kw>. A true value for the boolean <kw>out</kw>
+ will add the global to the <code><batch-execution-results></code> payload,
+ using the name from the <kw>identifier</kw> attribute. <kw>out-identifier</kw>
+ works like <kw>out</kw> but additionally allows you to override the identifier
+ used in the <code><batch-execution-results></code> payload.</para>
<example>
<title>Set Global Command</title>
@@ -1735,10 +1747,10 @@
</programlisting>
</example>
- <para>There is also a <get-global> element, without contents,
- with just an 'out-identifier' attribute. (There is no need for an
- 'out' attribute because retrieving the value is the sole purpose of
- a <get-global> element.</para>
+ <para>There is also a <code><get-global></code> element, without contents,
+ with just an <kw>out-identifier</kw> attribute. (There is no need for an
+ <kw>out</kw> attribute because retrieving the value is the sole purpose of
+ a <code><get-global></code> element.</para>
<example>
<title>Get Global Command</title>
@@ -1750,11 +1762,11 @@
</programlisting>
</example>
- <para>While the 'out' attribute is useful in returning specific instances
+ <para>While the <kw>out</kw> attribute is useful in returning specific instances
as a result payload, we often wish to run actual queries. Both parameter
- and parameterless queries are supported. The 'name' attribute is the name
- of the query to be called, and the 'out-identifier' is the identifier to
- be used for the query results in the <execution-results>
+ and parameterless queries are supported. The <kw>name</kw> attribute is the name
+ of the query to be called, and the <kw>out-identifier</kw> is the identifier to
+ be used for the query results in the <code><execution-results></code>
payload.</para>
<example>
@@ -1770,10 +1782,9 @@
</programlisting>
</example>
- <para>The <start-process> command accepts optional parameters.
- Other process
- related methods will be added later, like interacting with work
- items.</para>
+ <para>The <code><start-process></code> command accepts optional
+ parameters. Other process related methods will be added later, like
+ interacting with work items.</para>
<example>
<title>Start Process Command</title>
@@ -1796,21 +1807,22 @@
<section>
<title>Marshalling</title>
- <para>The MarshallerFactory is used to marshal and unmarshal
- StatefulKnowledgeSessions.</para>
+ <para>The <code>MarshallerFactory</code> is used to marshal and unmarshal
+ Stateful Knowledge Sessions.</para>
<figure>
<title>MarshallerFactory</title>
<mediaobject>
<imageobject>
- <imagedata fileref="images/Chapter-User_Guide/MarshallerFactory.png"
+ <imagedata width="100%"
+ fileref="images/Chapter-User_Guide/MarshallerFactory.png"
format=""></imagedata>
</imageobject>
</mediaobject>
</figure>
- <para>At the simplest the MarshallerFactory can be used as follows:</para>
+ <para>At the simplest the <code>MarshallerFactory</code> can be used as follows:</para>
<example>
<title>Simple Marshaller Example</title>
@@ -1826,18 +1838,19 @@
<para>However, with marshalling you need more flexibility when dealing with
referenced user data. To achieve this we have the
- ObjectMarshallingStrategy interface. Two implementations are provided, but
+ <code>ObjectMarshallingStrategy</code> interface. Two implementations are provided, but
users can implement their own. The two supplied strategies are
- IdentityMarshallingStrategy and SerializeMarshallingStrategy.
- SerializeMarshallingStrategy is the default, as used in the example above,
- and it just calls the Serializable or Externalizable methods on a user
- instance. IdentityMarshallingStrategy instead creates an integer id for each
+ <code>IdentityMarshallingStrategy</code> and <code>SerializeMarshallingStrategy</code>.
+ <code>SerializeMarshallingStrategy</code> is the default, as used in the example above,
+ and it just calls the <code>Serializable</code> or <code>Externalizable</code> methods
+ on a user instance. <code>IdentityMarshallingStrategy</code> instead creates an integer
+ id for each
user object and stores them in a Map, while the id is written to the stream.
- When unmarshalling it accesses the IdentityMarshallingStrategy map to
+ When unmarshalling it accesses the <code>IdentityMarshallingStrategy</code> map to
retrieve the instance. This means that if you use the
- IdentityMarshallingStrategy, it is stateful for the life of the Marshaller
+ <code>IdentityMarshallingStrategy</code>, it is stateful for the life of the Marshaller
instance and will create ids and keep references to all objects that it
- attempts to marshal. Below is he code to use an IdentityMarshallingStrategy.</para>
+ attempts to marshal. Below is he code to use an Identity Marshalling Strategy.</para>
<example>
<title>IdentityMarshallingStrategy</title>
@@ -1852,14 +1865,14 @@
</example>
<para>For added flexability we can't assume that a single strategy is
- suitable. Therefore we have added the ObjectMarshallingStrategyAcceptor
- interface that each ObjectMarshallingStrategy contains. The Marshaller has a
+ suitable. Therefore we have added the <code>ObjectMarshallingStrategyAcceptor</code>
+ interface that each Object Marshalling Strategy contains. The Marshaller has a
chain of strategies, and when it attempts to read or write a user object it
iterates the strategies asking if they accept responsability for
marshalling the user object. One of the provided implementations is
- ClassFilterAcceptor. This allows strings and wild cards to be used to
+ <code>ClassFilterAcceptor</code>. This allows strings and wild cards to be used to
match class names. The default is "*.*", so in the above example the
- IdentityMarshallingStrategy is used which has a default "*.*" acceptor.</para>
+ Identity Marshalling Strategy is used which has a default "*.*" acceptor.</para>
<para>Assuming that we want to serialize all classes except for one given
package, where we will use identity lookup, we could do the following:</para>
@@ -1920,9 +1933,10 @@
</example>
<para>To use a JPA, the Environment must be set with both the
- EntityManagerFactory and the TransactionManager. If rollback occurs the
+ <code>EntityManagerFactory</code> and the <code>TransactionManager</code>.
+ If rollback occurs the
ksession state is also rolled back, so you can continue to use it after a
- rollback. To load a previously persisted StatefulKnowledgeSession you'll
+ rollback. To load a previously persisted Stateful Knowledge Session you'll
need the id, as shown below:</para>
<example>
More information about the jboss-svn-commits
mailing list