[jboss-svn-commits] JBL Code SVN: r18470 - in labs/jbossrules/trunk/documentation/manual/en: Chapter-BRMS and 4 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Feb 12 18:59:37 EST 2008
Author: irooskov at redhat.com
Date: 2008-02-12 18:59:37 -0500 (Tue, 12 Feb 2008)
New Revision: 18470
Modified:
labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-AdminGuide.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-Architecture.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-ExamplesAndTutorials.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-Introduction.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-UserGuide.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Examples/Section-Examples.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Rete_Algorithm.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Rules.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-What_is_a_Rule_Engine.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Why_use_a_Rule_Engine.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Comments.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-DSL.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Function.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Overview.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Package.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Query.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Rule.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-RuleFlow.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-XML.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Local_Search_Solver.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Score_calculation.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_configuration.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_examples.xml
labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_introduction.xml
labs/jbossrules/trunk/documentation/manual/en/master.xml
Log:
Spelling and grammer updated
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-AdminGuide.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-AdminGuide.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-AdminGuide.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Administration guide</title>
@@ -387,4 +389,4 @@
itself.</para>
</section>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-Architecture.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-Architecture.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-Architecture.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Architecture</title>
@@ -182,4 +184,4 @@
BRMS, it is important that you choose "drools-brms" as the component in
the list in JIRA (or else it may get lost !)</para>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-ExamplesAndTutorials.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-ExamplesAndTutorials.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-ExamplesAndTutorials.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Examples and tutorials</title>
@@ -100,4 +102,4 @@
</itemizedlist>
</section>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-Introduction.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-Introduction.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-Introduction.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Introduction</title>
@@ -100,4 +102,4 @@
</itemizedlist>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-UserGuide.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-UserGuide.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-BRMS/Section-UserGuide.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,798 +1,505 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
- <title>Quick start guide</title>
+ <title>Quick start guide</title>
- <section>
- <title>Quick start guide</title>
+ <section>
+ <title>Quick start guide</title>
- <para>If you are reading this, you must be the impatient type who wants to
- kick the tyres (and light the fires) and have a look around as soon as
- possible. This section will provide a quick end to end tour of the steps
- involved (but does not go through the concepts in detail). This assumes
- you have installed the repository correctly, and are able to access the
- main login screen.</para>
+ <para>If you are reading this, you must be the impatient type who wants to kick the tyres (and light the fires) and have a look around as soon as possible. This section will provide a quick end to end tour of the steps involved (but does not go through the concepts in detail). This assumes you have installed the repository correctly, and are able to access the main login screen.</para>
- <figure>
- <title>Main feature areas of BRMS</title>
+ <para>You can also consult the wiki: http://wiki.jboss.org/wiki/Wiki.jsp?page=RulesRepository for some tutorials and user tips (it IS a wiki, so you can even contribute your own tips and examples and even upload files if you desire !).</para>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="BRMSFeatures.png" format="PNG"
- scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
+ <figure>
+ <title>Main feature areas of BRMS</title>
- <para>The above picture shows the main feature areas of the BRMS.</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="Features.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <itemizedlist>
- <listitem>
- <para>Info: This is the initial screen, with links to
- resources.</para>
- </listitem>
+ <para>The above picture shows the main feature areas of the BRMS.</para>
- <listitem>
- <para>Rules: This is the category and business user
- perspective.</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>Info: This is the initial screen, with links to resources.</para>
+ </listitem>
- <listitem>
- <para>Package: This is where packages are configured and
- managed.</para>
- </listitem>
+ <listitem>
+ <para>Rules: This is the category and business user perspective.</para>
+ </listitem>
- <listitem>
- <para>Deployment: this is where deployment snapshots are
- managed.</para>
- </listitem>
+ <listitem>
+ <para>Package: This is where packages are configured and managed.</para>
+ </listitem>
- <listitem>
- <para>Admin: Administrative functions (categories, statuses, import
- and export)</para>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para>Deployment: this is where deployment snapshots are managed.</para>
+ </listitem>
- <section>
- <title>Supported browser platforms</title>
+ <listitem>
+ <para>Admin: Administrative functions (categories, statuses, import and export)</para>
+ </listitem>
+ </itemizedlist>
- <para>The supported server side platforms are mentioned in the
- installation guide. For browsers - the major ones are supported, this
- includes Firefox (1.5 and up), IE6 and up, Opera, Safari etc. The
- preferred browser for most platforms is firefox, it is widely available
- and free, if you have any choice at all, Firefox is the preferred
- platform, followed by safari on mac.</para>
- </section>
+ <section>
+ <title>Supported browser platforms</title>
- <para>You can also consult the wiki:
- http://wiki.jboss.org/wiki/Wiki.jsp?page=RulesRepository for some
- tutorials and user tips (it IS a wiki, so you can even contribute your own
- tips and examples and even upload files if you desire !).</para>
+ <para>The supported server side platforms are mentioned in the installation guide. For browsers - the major ones are supported, this includes Firefox (1.5 and up), IE6 and up, Opera, Safari etc. The preferred browser for most platforms is firefox, it is widely available and free, if you have any choice at all, Firefox is the preferred platform, followed by safari on mac.</para>
+ </section>
- <section>
- <title>Initial configuration</title>
+ <section>
+ <title>Initial configuration</title>
- <para>Some initial setup is required the first time. The first time the
- server starts up, it will create an empty repository, then take the
- following steps:</para>
+ <para>Some initial setup is required the first time. The first time the server starts up, it will create an empty repository, then take the following steps:</para>
- <itemizedlist>
- <listitem>
- <para>Once deployed, go to "http://<your
- server>/drools-jbrms/" (This will show the initial info screen -
- or login screen depending on the configuration).</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>Once deployed, go to "http://<your server>/drools-jbrms/" (This will show the initial info screen - or login screen depending on the configuration).</para>
+ </listitem>
- <listitem>
- <para>If it is a brand new repository, you will want to go to
- "Admin", and choose "Manage Categories"</para>
+ <listitem>
+ <para>If it is a brand new repository, you will want to go to "Admin", and choose "Manage Categories"</para>
- <para>(Add a few categories of your choosing, categories are only
- for classification, not for execution or anything else.)</para>
- </listitem>
+ <para>(Add a few categories of your choosing, categories are only for classification, not for execution or anything else.)</para>
+ </listitem>
- <listitem>
- <para>Rules need a fact model (object model) to work off, so next
- you will want to go to the Package management feature. From here you
- can click on the icon to create a new package (give it a meaningful
- name, with no spaces).</para>
- </listitem>
+ <listitem>
+ <para>Rules need a fact model (object model) to work off, so next you will want to go to the Package management feature. From here you can click on the icon to create a new package (give it a meaningful name, with no spaces).</para>
+ </listitem>
- <listitem>
- <para>To upload a model, use a jar which has the fact model (API)
- that you will be using in your rules and your code (go and make one
- now if you need to !). When you are in the model editor screen, you
- can upload a jar file, choose the package name from the list that
- you created in the previous step.</para>
- </listitem>
+ <listitem>
+ <para>To upload a model, use a jar which has the fact model (API) that you will be using in your rules and your code (go and make one now if you need to !). When you are in the model editor screen, you can upload a jar file, choose the package name from the list that you created in the previous step.</para>
+ </listitem>
- <listitem>
- <para>Now edit your package configuration (you just created) to
- import the fact types you just uploaded (add import statements), and
- save the changes.</para>
- </listitem>
+ <listitem>
+ <para>Now edit your package configuration (you just created) to import the fact types you just uploaded (add import statements), and save the changes.</para>
+ </listitem>
- <listitem>
- <para>At this point, the package is configured and ready to go (you
- generally won't have to go through that step very often).</para>
+ <listitem>
+ <para>At this point, the package is configured and ready to go (you generally won't have to go through that step very often).</para>
- <para>(Note that you can also import an existing drl package - it
- will store the rules in the repository as individual assets).</para>
- </listitem>
- </itemizedlist>
- </section>
+ <para>(Note that you can also import an existing drl package - it will store the rules in the repository as individual assets).</para>
+ </listitem>
+ </itemizedlist>
+ </section>
- <section>
- <title>Writing some rules</title>
+ <section>
+ <title>Writing some rules</title>
- <itemizedlist>
- <listitem>
- <para>Once you have at least one category and one package setup, you
- can author rules.</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>Once you have at least one category and one package setup, you can author rules.</para>
+ </listitem>
- <listitem>
- <para>There are multiple rule "formats", but from the BRMS point of
- view, they are all "assets".</para>
- </listitem>
+ <listitem>
+ <para>There are multiple rule "formats", but from the BRMS point of view, they are all "assets".</para>
+ </listitem>
- <listitem>
- <para>You create a rule by clicking the icon with the rules logo
- (the head), and from that you enter a name.</para>
- </listitem>
+ <listitem>
+ <para>You create a rule by clicking the icon with the rules logo (the head), and from that you enter a name.</para>
+ </listitem>
- <listitem>
- <para>You will also have to choose one category. Categories provide
- a way of viewing rules that is separate to packages (and you can
- make rules appear in multiple packages) - think of it like
- tagging.</para>
- </listitem>
+ <listitem>
+ <para>You will also have to choose one category. Categories provide a way of viewing rules that is separate to packages (and you can make rules appear in multiple packages) - think of it like tagging.</para>
+ </listitem>
- <listitem>
- <para>Chose the "Business rule (guided editor)" formats.</para>
- </listitem>
+ <listitem>
+ <para>Chose the "Business rule (guided editor)" formats.</para>
+ </listitem>
- <listitem>
- <para>This will open a rule modeler, which is a guided editor. You
- can add and edit conditions and actions based on the model that is
- in use in the current package. Also, any DSL sentence templates
- setup for the package will be available.</para>
- </listitem>
+ <listitem>
+ <para>This will open a rule modeler, which is a guided editor. You can add and edit conditions and actions based on the model that is in use in the current package. Also, any DSL sentence templates setup for the package will be available.</para>
+ </listitem>
- <listitem>
- <para>When you are done with rule editing, you can check in the
- changes (save), or you can validate or "view source" (for the
- effective source).</para>
- </listitem>
+ <listitem>
+ <para>When you are done with rule editing, you can check in the changes (save), or you can validate or "view source" (for the effective source).</para>
+ </listitem>
- <listitem>
- <para>You can also add/remove categories from the rule editor, and
- other attributes such as documentation (if you aren't sure what to
- do, write a document in natural language describing the rule, and
- check it in, that can also serve as a template later)</para>
- </listitem>
- </itemizedlist>
- </section>
+ <listitem>
+ <para>You can also add/remove categories from the rule editor, and other attributes such as documentation (if you aren't sure what to do, write a document in natural language describing the rule, and check it in, that can also serve as a template later)</para>
+ </listitem>
+ </itemizedlist>
+ </section>
- <section>
- <title>Finding stuff</title>
+ <section>
+ <title>Finding stuff</title>
- <para>In terms of navigating, you can either use the Rules feature,
- which shows things grouped by categories, or you can use the Package
- feature, and view by package (and rule type). If you know the name or
- part of the name of an asset, you can also use the "Quick find", start
- typing a rule name and it will return a list of matches as you type (so
- if you have a sensible naming scheme, it will make it very quick to find
- stuff).</para>
- </section>
+ <para>In terms of navigating, you can either use the Rules feature, which shows things grouped by categories, or you can use the Package feature, and view by package (and rule type). If you know the name or part of the name of an asset, you can also use the "Quick find", start typing a rule name and it will return a list of matches as you type (so if you have a sensible naming scheme, it will make it very quick to find stuff).</para>
+ </section>
- <section>
- <title>Deployment</title>
+ <section>
+ <title>Deployment</title>
- <itemizedlist>
- <listitem>
- <para>After you have edited some rules in a package, you can click
- on the package feature, open the package that you wish, and build
- the whole package.</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>After you have edited some rules in a package, you can click on the package feature, open the package that you wish, and build the whole package.</para>
+ </listitem>
- <listitem>
- <para>If that succeeds, then you will be able to download a binary
- package file which can be deployed into a runtime system.</para>
- </listitem>
+ <listitem>
+ <para>If that succeeds, then you will be able to download a binary package file which can be deployed into a runtime system.</para>
+ </listitem>
- <listitem>
- <para>You can also take a "snapshot" of a package for deployment.
- This freezes the package at that point in time, so any concurrent
- changes to not effect the package. It also makes the package
- available on a URL of the form: "http://<your
- server>/drools-jbrms/org.drools.brms.JBRMS/packages/<packageName>/<snapshotName>"
- (where you can use that URL and downloads will be covered in the
- section on deployment).</para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
+ <listitem>
+ <para>You can also take a "snapshot" of a package for deployment. This freezes the package at that point in time, so any concurrent changes to not effect the package. It also makes the package available on a URL of the form: "http://<your server>/drools-jbrms/org.drools.brms.JBRMS/packages/<packageName>/<snapshotName>" (where you can use that URL and downloads will be covered in the section on deployment).</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ </section>
- <section>
- <title>BRMS concepts</title>
+ <section>
+ <title>BRMS concepts</title>
- <section>
- <title>Rules are assets</title>
+ <section>
+ <title>Rules are assets</title>
- <para>As the BRMS can manage many different types of rules (and more),
- they are all classed as "assets". An asset is anything that can be
- stored as a version in the repository. This includes decision tables,
- models, DSLs and more. Sometimes the word "rule" will be used to really
- mean "asset" (ie the things you can do also apply to the other asset
- types). You can think of asset as a lot like a file in a folder. Assets
- are grouped together for viewing, or to make a package for deployment
- etc.</para>
- </section>
+ <para>As the BRMS can manage many different types of rules (and more), they are all classed as "assets". An asset is anything that can be stored as a version in the repository. This includes decision tables, models, DSLs and more. Sometimes the word "rule" will be used to really mean "asset" (ie the things you can do also apply to the other asset types). You can think of asset as a lot like a file in a folder. Assets are grouped together for viewing, or to make a package for deployment etc.</para>
+ </section>
- <section>
- <title>Categorisation</title>
+ <section>
+ <title>Categorisation</title>
- <figure>
- <title>Categories</title>
+ <figure>
+ <title>Categories</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="CatZoom.png" format="PNG"
- scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="CatZoom.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>Categories allow rules (assets) to be labeled (or tagged) with any
- number of categories that you define. This means that you can then view
- a list of rules that match a specific category. Rules can belong to any
- number of categories. In the above diagram, you can see this can in
- effect create a folder/explorer like view of assets. The names can be
- anything you want, and are defined by the BRMS administrator (you can
- also remove/add new categories - you can only remove them if they are
- not currently in use).</para>
+ <para>Categories allow rules (assets) to be labeled (or tagged) with any number of categories that you define. This means that you can then view a list of rules that match a specific category. Rules can belong to any number of categories. In the above diagram, you can see this can in effect create a folder/explorer like view of assets. The names can be anything you want, and are defined by the BRMS administrator (you can also remove/add new categories - you can only remove them if they are not currently in use).</para>
- <para>Generally categories are created with meaningful name that match
- the area of the business the rule applies to (if the rule applies to
- multiple areas, multiple categories can be attached). Categories can
- also be used to "tag" rules as part of their life-cycle, for example to
- mark as "Draft" or "For Review".</para>
+ <para>Generally categories are created with meaningful name that match the area of the business the rule applies to (if the rule applies to multiple areas, multiple categories can be attached). Categories can also be used to "tag" rules as part of their life-cycle, for example to mark as "Draft" or "For Review".</para>
- <figure>
- <title>Assets can have multiple categories</title>
+ <figure>
+ <title>Assets can have multiple categories</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="CatEdit.png" format="PNG"
- scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="CatEdit.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>The view above shows the category editor/viewer that is seen when
- you open an asset. In this example you can see the asset belongs to 2
- categories, with a "+" button to add additional items (use the trash can
- item to remove them). This means that when either category is used to
- show a list of assets, you will see that asset.</para>
+ <para>The view above shows the category editor/viewer that is seen when you open an asset. In this example you can see the asset belongs to 2 categories, with a "+" button to add additional items (use the trash can item to remove them). This means that when either category is used to show a list of assets, you will see that asset.</para>
- <para>In the above example, the first Category "Finance" is a "top
- level" category. The second one: "HR/Awards/QAS" is a still a single
- category, but its a nested category: Categories are hierarchical. This
- means there is a category called "HR", which contains a category
- "Awards" (it will in fact have more sub-categories of course), and
- "Awards" has a sub-category of QAS. The screen shows this as
- "HR/Awards/QAS" - its very much like a folder structure you would have
- on your hard disk (the notable exception is of course that rules can
- appear in multiple places).</para>
+ <para>In the above example, the first Category "Finance" is a "top level" category. The second one: "HR/Awards/QAS" is a still a single category, but its a nested category: Categories are hierarchical. This means there is a category called "HR", which contains a category "Awards" (it will in fact have more sub-categories of course), and "Awards" has a sub-category of QAS. The screen shows this as "HR/Awards/QAS" - its very much like a folder structure you would have on your hard disk (the notable exception is of course that rules can appear in multiple places).</para>
- <para>When you open an asset to view or edit, it will show a list of
- categories that it currently belongs to If you make a change (remove or
- add a category) you will need to save the asset - this will create a new
- item in the version history. Changing the categories of a rule has no
- effect on its execution.</para>
+ <para>When you open an asset to view or edit, it will show a list of categories that it currently belongs to If you make a change (remove or add a category) you will need to save the asset - this will create a new item in the version history. Changing the categories of a rule has no effect on its execution.</para>
- <figure>
- <title>Creating categories</title>
+ <figure>
+ <title>Creating categories</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="AdminCats.png" format="PNG"
- scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="AdminCats.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>The above view shows the administration screen for setting up
- categories (there) are no categories in the system by default. As the
- categories can be hierarchical you chose the "parent" category that you
- want to create a sub-category for. From here categories can also be
- removed (but only if they are not in use by any current versions of
- assets).</para>
+ <para>The above view shows the administration screen for setting up categories (there) are no categories in the system by default. As the categories can be hierarchical you chose the "parent" category that you want to create a sub-category for. From here categories can also be removed (but only if they are not in use by any current versions of assets).</para>
- <para>As a general rule, an asset should only belong to 1 or 2
- categories at a time. Categories are critical in cases where you have
- large numbers of rules. The hierarchies do not need to be too deep, but
- should be able to see how this can help you break down rules/assets into
- manageable chunks. Its ok if its not clear at first, you are free to
- change categories as you go.</para>
- </section>
+ <para>As a general rule, an asset should only belong to 1 or 2 categories at a time. Categories are critical in cases where you have large numbers of rules. The hierarchies do not need to be too deep, but should be able to see how this can help you break down rules/assets into manageable chunks. Its ok if its not clear at first, you are free to change categories as you go.</para>
+ </section>
- <section>
- <title>The asset editor</title>
+ <section>
+ <title>The asset editor</title>
- <figure>
- <title>The Asset editor view</title>
+ <figure>
+ <title>The Asset editor view</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="AssetEditor.png" format="PNG"
- scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="AssetEditor.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>The above diagram shows the "asset editor" with some annotated
- areas. The asset editor is where all rule changes are made. Below is a
- list which describes the different parts of the editor.</para>
+ <para>The above diagram shows the "asset editor" with some annotated areas. The asset editor is where all rule changes are made. Below is a list which describes the different parts of the editor.</para>
- <itemizedlist>
- <listitem>
- <para>A</para>
+ <itemizedlist>
+ <listitem>
+ <para>A</para>
- <para>This is where the "editor widget" lives - exactly what form
- the editor takes depends on the asset or rule type.</para>
- </listitem>
+ <para>This is where the "editor widget" lives - exactly what form the editor takes depends on the asset or rule type.</para>
+ </listitem>
- <listitem>
- <para>B</para>
+ <listitem>
+ <para>B</para>
- <para>This is the documentation area - a free text area where
- descriptions of the rule can live. It is encouraged to write a plain
- description in the rule here before editing.</para>
- </listitem>
+ <para>This is the documentation area - a free text area where descriptions of the rule can live. It is encouraged to write a plain description in the rule here before editing.</para>
+ </listitem>
- <listitem>
- <para>C</para>
+ <listitem>
+ <para>C</para>
- <para>These are the actions - for saving, archiving, changing status
- etc. Archiving is the equivalent of deleting an asset.</para>
- </listitem>
+ <para>These are the actions - for saving, archiving, changing status etc. Archiving is the equivalent of deleting an asset.</para>
+ </listitem>
- <listitem>
- <para>D</para>
+ <listitem>
+ <para>D</para>
- <para>This has the asset name, as well as the list of categories
- that the asset belongs to.</para>
- </listitem>
+ <para>This has the asset name, as well as the list of categories that the asset belongs to.</para>
+ </listitem>
- <listitem>
- <para>E</para>
+ <listitem>
+ <para>E</para>
- <para>This section contains read-only meta data, including when
- changes were made, and by whom.</para>
+ <para>This section contains read-only meta data, including when changes were made, and by whom.</para>
- <para>"Modified on:" - this is the last modified date.</para>
+ <para>"Modified on:" - this is the last modified date.</para>
- <para>"By:" - who made the last change.</para>
+ <para>"By:" - who made the last change.</para>
- <para>"Note:" - this is the comment made when the asset was last
- updated (ie why a change was made)</para>
+ <para>"Note:" - this is the comment made when the asset was last updated (ie why a change was made)</para>
- <para>"Version:" - this is a number which is incremented by 1 each
- time a change is checked in (saved).</para>
+ <para>"Version:" - this is a number which is incremented by 1 each time a change is checked in (saved).</para>
- <para>"Created on:" - the date and time the asset was
- created.</para>
+ <para>"Created on:" - the date and time the asset was created.</para>
- <para>"Created by:" - this initial author of the asset.</para>
+ <para>"Created by:" - this initial author of the asset.</para>
- <para>"Format:" - the short format name of the type of asset.</para>
- </listitem>
+ <para>"Format:" - the short format name of the type of asset.</para>
+ </listitem>
- <listitem>
- <para>F</para>
+ <listitem>
+ <para>F</para>
- <para>This shows what package the asset belong to (you can also
- change it from here).</para>
- </listitem>
+ <para>This shows what package the asset belong to (you can also change it from here).</para>
+ </listitem>
- <listitem>
- <para>G</para>
+ <listitem>
+ <para>G</para>
- <para>This is some more (optional) meta data (taken from the Dublin
- Core meta data standard)</para>
- </listitem>
+ <para>This is some more (optional) meta data (taken from the Dublin Core meta data standard)</para>
+ </listitem>
- <listitem>
- <para>H</para>
+ <listitem>
+ <para>H</para>
- <para>This will show the version history list when requested.</para>
- </listitem>
- </itemizedlist>
- </section>
+ <para>This will show the version history list when requested.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
- <section>
- <title>Rule authoring</title>
+ <section>
+ <title>Rule authoring</title>
- <para>The BRMS supports a (growing) list of formats of assets (rules).
- Here the key ones are described. Some of these are covered in other
- parts of the manual, and the detail will not be repeated here.</para>
+ <para>The BRMS supports a (growing) list of formats of assets (rules). Here the key ones are described. Some of these are covered in other parts of the manual, and the detail will not be repeated here.</para>
- <section>
- <title>Business rules with the guided editor</title>
+ <section>
+ <title>Business rules with the guided editor</title>
- <para>Guided editor style "Business rules": (also known as "BRL
- format"). These rules use the guided GUI which controls and propts
- user input based on knowledge of the object model. This can also be
- augmented with DSL sentences.</para>
+ <para>Guided editor style "Business rules": (also known as "BRL format"). These rules use the guided GUI which controls and prompts user input based on knowledge of the object model. This can also be augmented with DSL sentences.</para>
- <para>IMPORTANT: to use the BRL guided editor, someone will need to
- have you package configured before hand.</para>
+ <para>IMPORTANT: to use the BRL guided editor, someone will need to have you package configured before hand.</para>
- <para>Also note that there is a guided editor in the Eclipse plug in,
- most of the details in this section can also apply to it.</para>
+ <para>Also note that there is a guided editor in the Eclipse plug in, most of the details in this section can also apply to it.</para>
- <figure>
- <title>The guided BRL editor</title>
+ <figure>
+ <title>The guided BRL editor</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="GuidedEditor.png"
- format="PNG" scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="GuidedEditor.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>The above diagram shows the editor in action. The following
- description apply to the letter boxes in the diagram above:</para>
+ <para>The above diagram shows the editor in action. The following description apply to the letter boxes in the diagram above:</para>
- <para>A: The different parts of a rule. The "WHEN" part is the
- condition, "THEN" action, and "(options)" are optional attributes that
- may effect the operation of the rule.</para>
+ <para>A: The different parts of a rule. The "WHEN" part is the condition, "THEN" action, and "(options)" are optional attributes that may effect the operation of the rule.</para>
- <para>B: This shows a pattern which is declaring that the rule is
- looking for a "Driver" fact (the fields are listed below, in this case
- just "age"). Note the green triangle, it will popup a list of options
- to add to the fact declaration: you can add more fields (eg their
- "location"), or you can assign a variable name to the fact (which you
- can use later on if needs be). As well as adding more fields to this
- pattern - you can add "multiple field" constraints - ie constraints
- that span across fields (eg age > 42 or risk > 2). The popup
- dialog shows the options.</para>
+ <para>B: This shows a pattern which is declaring that the rule is looking for a "Driver" fact (the fields are listed below, in this case just "age"). Note the green triangle, it will popup a list of options to add to the fact declaration: you can add more fields (eg their "location"), or you can assign a variable name to the fact (which you can use later on if needs be). As well as adding more fields to this pattern - you can add "multiple field" constraints - ie constraints that span across fields (eg age > 42 or risk > 2). The popup dialog shows the options.</para>
- <para>C: The small "-" icons indicate you can remove something - in
- this case it would remove the whole Driver fact declaration. If its
- the one below, it would remove just the age constraint.</para>
+ <para>C: The small "-" icons indicate you can remove something - in this case it would remove the whole Driver fact declaration. If its the one below, it would remove just the age constraint.</para>
- <para>D: The "+" symbols allow you to add more patterns to the
- condition or the action part of the rule, or more attributes. In all
- cases, a popup option box is provided. For the "WHEN" part of the
- rule, you can choose to add a constraint on a fact (it will give you a
- list of facts), or you can use another conditional element, the
- choices which are : "There is no" - which means the fact+constraints
- must not exist, "There exists" - which means that there exists at
- least one match (but there only needs to be one - it will not trigger
- for each match), and "Any of" - which means that any of the patterns
- can match (you then add patterns to these higher level patterns). If
- you just put a fact (like is shown above) then all the patterns are
- combined together so they are all true ("and").</para>
+ <para>D: The "+" symbols allow you to add more patterns to the condition or the action part of the rule, or more attributes. In all cases, a popup option box is provided. For the "WHEN" part of the rule, you can choose to add a constraint on a fact (it will give you a list of facts), or you can use another conditional element, the choices which are : "There is no" - which means the fact+constraints must not exist, "There exists" - which means that there exists at least one match (but there only needs to be one - it will not trigger for each match), and "Any of" - which means that any of the patterns can match (you then add patterns to these higher level patterns). If you just put a fact (like is shown above) then all the patterns are combined together so they are all true ("and").</para>
- <para>E: This shows the constraint for the "age" field. (Looking from
- left to right) the green triangle allows you to "assign" a variable
- name to the "age" field, which you may use later on in the rule. Next
- is the list of constraint operations - this list changes depending on
- the data type. After that is the value field - the value field will be
- one of: a) a literal value (eg number, text), b) a "formula" - in
- which case it is an expression which is calculated (this is for
- advanced users) or b) a variable (in which case a list will be
- provided to choose values from). After this there is a horizontal
- arrow icon, this is for "connective constraints" : these are
- constraints which allow you to have alternative values to check a
- field against, for example: "age is less than 42 or age is not equal
- to 39" is possibly this way.</para>
+ <para>E: This shows the constraint for the "age" field. (Looking from left to right) the green triangle allows you to "assign" a variable name to the "age" field, which you may use later on in the rule. Next is the list of constraint operations - this list changes depending on the data type. After that is the value field - the value field will be one of: a) a literal value (eg number, text), b) a "formula" - in which case it is an expression which is calculated (this is for advanced users) or b) a variable (in which case a list will be provided to choose values from). After this there is a horizontal arrow icon, this is for "connective constraints" : these are constraints which allow you to have alternative values to check a field against, for example: "age is less than 42 or age is not equal to 39" is possibly this way.</para>
- <para>F: This shows an "action" of the rule, a rule consists of a list
- of actions. In this case, we are asserting/inserting a new fact, which
- is a rejection (with the "reason" field set to an explanation). There
- are quite a few other types of actions you can use: you can modify an
- existing fact (which tells the engine the fact has changed) - or you
- can simply set a field on a fact (in which case the engine doesn't
- know about the change - normally because you are setting a result).
- You can also retract a fact. In most cases the green arrow will give
- you a list of fields you can add so you can change the value. The
- values you enter are "literal" - in the sense that what you type is
- what the value is. If it needs to be a calculation, then add an "=" at
- the start of the value - this will be interpreted as a "formula" (for
- advanced users only) ! and the calculation will be performed (not
- unlike a spreadsheet).</para>
+ <para>F: This shows an "action" of the rule, a rule consists of a list of actions. In this case, we are asserting/inserting a new fact, which is a rejection (with the "reason" field set to an explanation). There are quite a few other types of actions you can use: you can modify an existing fact (which tells the engine the fact has changed) - or you can simply set a field on a fact (in which case the engine doesn't know about the change - normally because you are setting a result). You can also retract a fact. In most cases the green arrow will give you a list of fields you can add so you can change the value. The values you enter are "literal" - in the sense that what you type is what the value is. If it needs to be a calculation, then add an "=" at the start of the value - this will be interpreted as a "formula" (for advanced users only) ! and the calculation will be performed (not unlike a spreadsheet).</para>
- <para>G: This is where the rule options live. In this case, only
- salience is used which is a numeric value representing the rules
- "priority". This would probably be the most common option to
- use.</para>
+ <para>G: This is where the rule options live. In this case, only salience is used which is a numeric value representing the rules "priority". This would probably be the most common option to use.</para>
- <section>
- <title>User driven drop down lists</title>
+ <section>
+ <title>User driven drop down lists</title>
- <figure>
- <title>Data enumeration showing as a drop down list</title>
+ <figure>
+ <title>Data enumeration showing as a drop down list</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="EnumDropDown.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="EnumDropDown.png"
- format="PNG" scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
+ <para>Note that is it possible to limit field values to items in a pre configured list. This list is configured as part of the package (using a data enumeration to provide values for the drop down list). These values can be a fixed list, or (for example) loaded from a database. This is useful for codes, and other fields where there are set values. It is also possible to have what is displayed on screen, in a drop down, be different to the value (or code) used in a rule. See the section on data enumerations for how these are configured.</para>
+ </section>
- <para>Note that is it possible to limit field values to items in a
- pre configured list. This list is configured as part of the package
- (using a data enumeration to provide values for the drop down list).
- These values can be a fixed list, or (for example) loaded from a
- database. This is useful for codes, and other fields where there are
- set values. It is also possible to have what is displayed on screen,
- in a drop down, be different to the value (or code) used in a rule.
- See the section on data enumerations for how these are
- configured.</para>
- </section>
+ <section>
+ <title>Augmenting with DSL sentences</title>
+
+ <para>If the package the rule is part of has a dsl configuration, when when you add conditions or actions, then it will provide a list of "DSL Sentences" which you can choose from - when you choose one, it will add a row to the rule - where the DSL specifies values come from a user, then a edit box (text) will be shown (so it ends up looking a bit like a form). This is optional, and there is another DSL editor. Please note that the DSL capabilities in this editor are slightly less then the full set of DSL features (basically you can do [when] and [then] sections of the DSL only - which is no different to drools 3 in effect).</para>
- <para>Augmenting with DSL sentences: If the package the rule is part
- of has a dsl configuration, when when you add conditions or actions,
- then it will provide a list of "DSL Sentences" which you can choose
- from - when you choose one, it will add a row to the rule - where the
- DSL specifies values come from a user, then a edit box (text) will be
- shown (so it ends up looking a bit like a form). This is optional, and
- there is another DSL editor. Please note that the DSL capabilities in
- this editor are slightly less then the full set of DSL features
- (basically you can do [when] and [then] sections of the DSL only -
- which is no different to drools 3 in effect).</para>
+ <para>The following diagram shows the DSL sentences in action in the guided editor:</para>
+
+ <figure>
+ <title>DSL in guided editor</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="GuidedDSL.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ </section>
+
+ <section>
+ <title>A more complex example:</title>
+
+ <figure>
+ <title>A more complex BRL example</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="GuidedComplex.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>In the above example, you can see it is using a mixture of literal values, and formulas. The second constraint on the "Person" fact, is a formula (in this case it is doing a silly calculation on the persons age, and checking something against their name - both "age" and "name" are fields of the Person fact in this case. In the 3rd line (which says "age is less than .." - it is also using a formula, although, in this case the formula does a calculation and returns a value (which is used in the comparison) - in the former case, it had to return True or False (in this case, its a value). Obvious formulas are basically pieces of code - so this is for experienced users only.</para>
- <para>The following diagram shows the DSL sentences in action in the
- guided editor:</para>
+ <para>Looking at the "Board" pattern (the second pattern with the horizontal grey bar): this uses a top level conditional element ("There is no") - this means that the pattern is actually looking for the "non existence" of a fact that matches the pattern. Note the "Any of:" - this means that EITHER the "type" field constraint is matched, or the "name" field is matched (to "myname" in the case above). This is what is termed a Multiple field constraint (you can nest these, and have it as complex as you like, depending on how much you want the next person to hate you: Some paraphrased advice: Write your rules in such as way as if the person who has to read/maintain them is a psychopath, has a gun, and knows where you live).</para>
+
+ <figure>
+ <title>Adding constraints</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="GuidedLHSConstraints.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The above dialog is what you will get when you want to add constraints to the Person fact. In the top half are the simple options: you can either add a field straight away (a list of fields of the Person fact will be shown), or you can add a "Multiple field constraint" - of a given type (which is described above). The Advanced options: you can add a formula (which resolves to True or False - this is like in the example above: "age < (age * 2) ...."). You can also assign a Variable name to the Person fact (which means you can then access that variable on the action part of the rule, to set a value etc).</para>
+ </section>
+ </section>
- <figure>
- <title>DSL in guided editor</title>
+ <section>
+ <title>DSL rules</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="GuidedDSL.png" format="PNG"
- scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
+ <para>DSL rules are textual rules, that use a language configuration asset to control how they appear.</para>
- <para>A more complex example:</para>
+ <figure>
+ <title>DSL rule</title>
- <figure>
- <title>A more complex BRL example</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="DSLRule.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="GuidedComplex.png"
- format="PNG" scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
+ <para>A dsl rule is a single rule. Referring to the picture above, you can a text editor. You can use the icons to the right to provide lists of conditions and actions to choose from (or else press Control + Space at the same time to pop up a list).</para>
+ </section>
- <para>In the above example, you can see it is using a mixture of
- literal values, and formulas. The second constraint on the "Person"
- fact, is a formula (in this case it is doing a silly calculation on
- the persons age, and checking something against their name - both
- "age" and "name" are fields of the Person fact in this case. In the
- 3rd line (which says "age is less than .." - it is also using a
- formula, although, in this case the formula does a calculation and
- returns a value (which is used in the comparison) - in the former
- case, it had to return True or False (in this case, its a value).
- Obvious formulas are basically pieces of code - so this is for
- experienced users only.</para>
+ <section>
+ <title>Spreadsheet decision tables</title>
- <para>Looking at the "Board" pattern (the second pattern with the
- horizontal grey bar): this uses a top level conditional element
- ("There is no") - this means that the pattern is actually looking for
- the "non existence" of a fact that matches the pattern. Note the "Any
- of:" - this means that EITHER the "type" field constraint is matched,
- or the "name" field is matched (to "myname" in the case above). This
- is what is termed a Multiple field constraint (you can nest these, and
- have it as complex as you like, depending on how much you want the
- next person to hate you: Some paraphrased advice: Write your rules in
- such as way as the person who has to read/maintain them is a
- psychopath, has a gun, and knows where you live).</para>
+ <para>Multiple rules can be stored in a spreadsheet (each row is a rule). The details of the spreadsheet are not covered in this chapter (as there is a separate chapter for them).</para>
- <figure>
- <title>Adding constraints</title>
+ <figure>
+ <title>Spreadsheet decision table</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="GuidedLHSConstraints.png"
- format="PNG" scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="DecisionTable.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>The above dialog is what you will get when you want to add
- constraints to the Person fact. In the top half are the simple
- options: you can either add a field straight away (a list of fields of
- the Person fact will be shown), or you can add a "Multiple field
- constraint" - of a given type (which is described above). The Advanced
- options: you can add a formula (which resolves to True or False - this
- is like in the example above: "age < (age * 2) ...."). You can also
- assign a Variable name to the Person fact (which means you can then
- access that variable on the action part of the rule, to set a value
- etc).</para>
- </section>
+ <para>To use a spreadsheet, you upload an xls (and can download the current version, as per the picture above). To create a new decision table, when you launch the rule wizard, you will get an option to create one (after that point, you can upload the xls file).</para>
+ </section>
- <section>
- <title>DSL rules</title>
+ <section>
+ <title>Rule flows</title>
- <para>DSL rules are textual rules, that use a language configuration
- asset to control how they appear.</para>
+ <para>Rule flows: Rule flows allow you to visually describe the steps taken - so not all rules are evaluated at once, but there is a flow of logic. Rule flows are not covered in this chapter on the BRMS, but you can use the IDE to graphically draw ruleflows, and upload the .rfm file to the BRMS.</para>
- <figure>
- <title>DSL rule</title>
+ <para>Similar to spreadsheets, you upload/download ruleflow files (the eclipse IDE has a graphical editor for them). The details of Rule Flows are not discussed here.</para>
+ </section>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="DSLRule.png" format="PNG"
- scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
+ <section>
+ <title>Technical rules (drl)</title>
- <para>A dsl rule is a single rule. Referring to the picture above, you
- can a text editor. You can use the icons to the right to provide lists
- of conditions and actions to choose from (or else press Control +
- Space at the same time to pop up a list).</para>
- </section>
+ <para>Technical (drl) rules are stored as text - they can be managed in the BRMS. A DRL can either be a whole chunk of rules, or an individual rule. if its an individual rule, no package statement or imports are required (in fact, you can skip the "rule" statement altogether, just use "when" and "then" to mark the condition and action sections respectively). Normally you would use the IDE to edit raw DRL files, since it has all the advanced tooling and content assistance and debugging, however there are times when a rule may have to deal with something fairly technical. In any typical package of rules, you generally have a been for some "technical rules" - you can mix and match all the rule types together of course.</para>
- <section>
- <title>Spreadsheet decision tables</title>
+ <figure>
+ <title>DRL technical rule</title>
- <para>Multiple rules can be stored in a spreadsheet (each row is a
- rule). The details of the spreadsheet are not covered in this chapter
- (as there is a separate chapter for them).</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="DRLRule.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
- <figure>
- <title>Spreadsheet decision table</title>
+ <section>
+ <title>Functions</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="DecisionTable.png"
- format="PNG" scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
+ <para>Functions are another asset type. They are NOT rules, and should only be used when necessary. The function editor is a textual editor. Functions</para>
- <para>To use a spreadsheet, you upload an xls (and can download the
- current version, as per the picture above). To create a new decision
- table, when you launch the rule wizard, you will get an option to
- create one (after that point, you can upload the xls file).</para>
- </section>
+ <figure>
+ <title>Function</title>
- <section>
- <title>Rule flows</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="Function.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
- <para>Rule flows: Rule flows allow you to visually describe the steps
- taken - so not all rules are evaluated at once, but there is a flow of
- logic. Rule flows are not covered in this chapter on the BRMS, but you
- can use the IDE to graphically draw ruleflows, and upload the .rfm
- file to the BRMS.</para>
+ <section>
+ <title>Data enumerations (drop down list configurations)</title>
- <para>Similar to spreadsheets, you upload/download ruleflow files (the
- eclipse IDE has a graphical editor for them). The details of Rule
- Flows are not discussed here.</para>
- </section>
+ <para>Data enumerations are an optional asset type that technical folk can configure to provide drop down lists for the guided editor. These are stored and edited just like any other asset, and apply to the package that they belong to.</para>
- <section>
- <title>Technical rules (drl)</title>
+ <para>The contents of an enum config are a mapping of Fact.field to a list of values to be used in a drop down. That list can either be literal, or use a utility class (which you put on the classpath) to load a list of strings. The strings are either a value to be shown on a drop down, or a mapping from the code value (what ends up used in the rule) and a display value (see the example below, using the '=').</para>
- <para>Technical (drl) rules are stored as text - they can be managed
- in the BRMS. A DRL can either be a whole chunk of rules, or an
- individual rule. if its an individual rule, no package statement or
- imports are required (in fact, you can skip the "rule" statement
- altogether, just use "when" and "then" to mark the condition and
- action sections respectively). Normally you would use the IDE to edit
- raw DRL files, since it has all the advanced tooling and content
- assistance and debugging, however there are times when a rule may have
- to deal with something fairly technical. In any typical package of
- rules, you generally have a been for some "technical rules" - you can
- mix and match all the rule types together of course.</para>
+ <figure>
+ <title>Data enumeration</title>
- <figure>
- <title>DRL technical rule</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="EnumConfig.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>In the above diagram - the "MM" indicates a value that will be used in the rule, yet "Mini Mal" will be displayed in the GUI.</para>
+
+ <para>Getting data lists from external data sources: It is possible to have the BRMS call a piece of code which will load a list of Strings. To do this, you will need a bit of code that returns a java.util.List (of String's) to be on the classpath of the BRMS. Instead of specifying a list of values in the BRMS itself - the code can return the list of Strings (you can use the "=" inside the strings if you want to use a different display value to the rule value, as normal). For example, in the 'Person.age' line above, you could change it to: <programlisting> 'Person.age' : (new com.yourco.DataHelper()).getListOfAges()</programlisting> This assumes you have a class called "DataHelper" which has a method "getListOfAges()" which returns a List of strings (and is on the classpath). You can of course mix these "dynamic" enumerations with fixed lists. You could for example load from a database using JDBC. The data enumerations are loaded the first time you use the guided editor !
in a session. If you have any guided editor sessions open - you will need to close and then open the rule to see the change. To check the enumeration is loaded - if you go to the Package configuration screen, you can "save and validate" the package - this will check it and provide any error feedback.</para>
+ </section>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="DRLRule.png" format="PNG"
- scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
- </section>
+
- <section>
- <title>Functions</title>
+ <section>
+ <title>Advanced enumaration concepts</title>
- <para>Functions are another asset type. They are NOT rules, and should
- only be used when necessary. The function editor is a textual editor.
- Functions</para>
+ <para>There are a few other advanced things you can do with data enumerations.</para>
- <figure>
- <title>Function</title>
+ <para>Drop down lists that depend on field values: Lets imagine a simple fact model, we have a class called Vehicle, which has 2 fields: "engineType" and "fuelType". We want to have a choice for the "engineType" of "Petrol" or "Diesel". Now, obviously the choice type for fuel must be dependent on the engine type (so for Petrol we have ULP and PULP, and for Diesel we have BIO and NORMAL). We can express this dependency in an enumerattion as:</para>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="Function.png" format="PNG"
- scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
- </section>
-
- <section>
- <title>Data enumerations (drop down list configurations)</title>
-
- <para>Data enumerations are an optional asset type that technical folk
- can configure to provide drop down lists for the guided editor. These
- are stored and edited just like any other asset, and apply to the
- package that they belong to.</para>
-
- <para>The contents of an enum config are a mapping of Fact.field to a
- list of values to be used in a drop down. That list can either be
- literal, or use a utility class (which you put on the classpath) to
- load a list of strings. The strings are either a value to be shown on
- a drop down, or a mapping from the code value (what ends up used in
- the rule) and a display value (see the example below, using the
- '=').</para>
-
- <figure>
- <title>Data enumeration</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="EnumConfig.png" format="PNG"
- scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
- </section>
-
- <para>In the above diagram - the "MM" indicates a value that will be
- used in the rule, yet "Mini Mal" will be displayed in the GUI.</para>
-
- <para>Getting data lists from external data sources: It is possible to
- have the BRMS call a piece of code which will load a list of Strings. To
- do this, you will need a bit of code that returns a java.util.List (of
- String's) to be on the classpath of the BRMS. Instead of specifying a
- list of values in the BRMS itself - the code can return the list of
- Strings (you can use the "=" inside the strings if you want to use a
- different display value to the rule value, as normal). For example, in
- the 'Person.age' line above, you could change it to: <programlisting>
- 'Person.age' : (new com.yourco.DataHelper()).getListOfAges()
-</programlisting> This assumes you have a class called "DataHelper" which has
- a method "getListOfAges()" which returns a List of strings (and is on
- the classpath). You can of course mix these "dynamic" enumerations with
- fixed lists. You could for example load from a database using JDBC. The
- data enumerations are loaded the first time you use the guided editor in
- a session. If you have any guided editor sessions open - you will need
- to close and then open the rule to see the change. To check the
- enumeration is loaded - if you go to the Package configuration screen,
- you can "save and validate" the package - this will check it and provide
- any error feedback.</para>
-
- <section>
- <title>Advanced enumaration concepts</title>
-
- <para>There are a few other advanced things you can do with data
- enumerations.</para>
-
- <para>Drop down lists that depend on field values: Lets imagine a
- simple fact model, we have a class called Vehicle, which has 2 fields:
- "engineType" and "fuelType". We want to have a choice for the
- "engineType" of "Petrol" or "Diesel". Now, obviously the choice type
- for fuel must be dependent on the engine type (so for Petrol we have
- ULP and PULP, and for Diesel we have BIO and NORMAL). We can express
- this dependency in an enumeration as:</para>
-
<programlisting>
'Vehicle.engineType' : ['Petrol', 'Diesel']
'Vehicle.fuelType[engineType=Petrol]' : ['ULP', 'PULP' ]
@@ -1237,10 +944,6 @@
file, you can construct a java.utils.Properties object, and pass it in
to the RuleBase methods.</para>
- <para>
- Please also note that the "file" property must contain a full path, it is not relative to the "dir" property.
- </para>
-
<para>Referring to the above example, the "keys" in the properties
are:</para>
@@ -1371,4 +1074,4 @@
updated.</para>
</section>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Examples/Section-Examples.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Examples/Section-Examples.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Examples/Section-Examples.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,56 +1,32 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
- <title>Getting the examples</title>
+ <title></title>
+ <section>
- <para>Make sure the Drools Eclipse plugin is installed, which needs 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>
+ <title>Getting the examples</title>
- <section>
- <title>Hello World</title>
+ <para>Make sure the Drools Eclipse plugin is installed, which needs 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>
+ </section>
+ <section>
+ <title>Hello World</title>
- <programlisting><emphasis role="bold">Name:</emphasis> Hello World
+ <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">Rules file:</emphasis> HelloWorld.drl
-<emphasis role="bold">Objective:</emphasis> demonstrate basic rules in use
-</programlisting>
+<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 rulebases and sessions
- and how to add audit logging and debug outputs, this information is
- ommitted from other examples as it's all very similar. PackageBuilder is
- used to turn a drl source file into Package objects which the RuleBase can
- consume, addPackageFromDrl takes a Reader interface as the parameter.
- Reader can be used to retrieve a source drl file from various locations,
- in this case the drl file is being retrieved from the classpath as an
- InputStream which we turn into a Reader by wrapping it with
- InputStreamReader; but it could come the disk or a url. The use of the
- Reader interface means that Drools does not have to care. In this case we
- only add a single drl source file, but multiple drl files can be added and
- all are merged into a single Package. All drl files added to the
- PackageBuilder must declare themselves in the same package namespace, if
- you wish to build a Package in a different namespace a new instance of
- PackageBuilder must be created; multiple packages of differerent
- namespaces can be added to the same RuleBase. When all the drl files have
- been added we should check the builder for errors; while the RuleBase will
- validate the packge it will only have access to the error information as a
- String, so if you wish to debug the error information you should do it on
- the builder instance. Once we know the builder is error free get the
- Package, instantiate a RuleBase from the RuleBaseFactory and add the
- package.</para>
+ <para>The "Hello World" example shows a simple example of rules usage, and both the MVEL and Java dialects.</para>
- <example>
- <title>HelloWorld example: Creating the RuleBase and Session</title>
+ <para>In this example it will be shown how to build rulebases and sessions and how to add audit logging and debug outputs, this information is ommitted from other examples as it's all very similar. PackageBuilder is used to turn a drl source file into Package objects which the RuleBase can consume, addPackageFromDrl takes a Reader interface as the parameter. Reader can be used to retrieve a source drl file from various locations, in this case the drl file is being retrieved from the classpath as an InputStream which we turn into a Reader by wrapping it with InputStreamReader; but it could come the disk or a url. The use of the Reader interface means that Drools does not have to care. In this case we only add a single drl source file, but multiple drl files can be added and all are merged into a single Package. All drl files added to the PackageBuilder must declare themselves in the same package namespace, if you wish to build a Package in a different namespace a new insta!
nce of PackageBuilder must be created; multiple packages of differerent namespaces can be added to the same RuleBase. When all the drl files have been added we should check the builder for errors; while the RuleBase will validate the packge it will only have access to the error information as a String, so if you wish to debug the error information you should do it on the builder instance. Once we know the builder is error free get the Package, instantiate a RuleBase from the RuleBaseFactory and add the package.</para>
- <programlisting>//read in the source
+ <example>
+ <title>HelloWorld example: Creating the RuleBase and Session</title>
+
+ <programlisting>//read in the source
Reader source = new InputStreamReader( HelloWorldExample.class.getResourceAsStream( "HelloWorld.drl" ) );
PackageBuilder builder = new PackageBuilder();
@@ -72,41 +48,30 @@
ruleBase.addPackage( pkg );
StatefulSession session = ruleBase.newStatefulSession();</programlisting>
- </example>
+ </example>
- <para>Drools has an event model that exposes much of whats happening
- internally, two default debug listeners are supplied
- DebugAgendaEventListener and DebugWorkingMemoryEventListener which print
- out debug event information to the err console, adding listeners to a
- session is trivial and shown below. The WorkingMemoryFileLogger provides
- execution auditing which can be viewed in a graphical viewer; it's
- actually a specialised implementation built on the agenda and working
- memory listeners, when the engine has finished executing
- logger.writeToDisk() must be called.</para>
+ <para>Drools has an event model that exposes much of what's happening internally, two default debug listeners are supplied DebugAgendaEventListener and DebugWorkingMemoryEventListener which print out debug event information to the err console, adding listeners to a session is trivial and shown below. The WorkingMemoryFileLogger provides execution auditing which can be viewed in a graphical viewer; it's actually a specialised implementation built on the agenda and working memory listeners, when the engine has finished executing logger.writeToDisk() must be called.</para>
- <para>Most of the examples use the Audit logging features of Drools to
- record execution flow for later inspection.</para>
+ <para>Most of the examples use the Audit logging features of Drools to record execution flow for later inspection.</para>
- <example>
- <title>HelloWorld example: Event logging and Auditing</title>
+ <example>
+ <title>HelloWorld example: Event logging and Auditing</title>
- <programlisting>// setup the debug listeners
+ <programlisting>// setup the debug listeners
session.addEventListener( new DebugAgendaEventListener() );
session.addEventListener( new DebugWorkingMemoryEventListener() );
// setup the audit logging
WorkingMemoryFileLogger logger = new WorkingMemoryFileLogger( session );
logger.setFileName( "log/helloworld" ); </programlisting>
- </example>
+ </example>
- <para>The single class used in this example is very simple, it has two
- fields: the message, which is a String and the status which can be either
- the int HELLO or the int GOODBYE.</para>
+ <para>The single class used in this example is very simple, it has two fields: the message, which is a String and the status which can be either the int HELLO or the int GOODBYE.</para>
- <example>
- <title>HelloWorld example: Message Class</title>
+ <example>
+ <title>HelloWorld example: Message Class</title>
- <programlisting>public static class Message {
+ <programlisting>public static class Message {
public static final int HELLO = 0;
public static final int GOODBYE = 1;
@@ -114,19 +79,14 @@
private int status;
...
}</programlisting>
- </example>
+ </example>
- <para>A single Message object is created with the message "Hello World"
- and status HELLO and then inserted into the engine, at which point
- fireAllRules() is executed. Remember all the network evaluation is done
- during the insert time, by the time the program execution reaches the
- fireAllRules() method it already knows which rules are fully matches and
- able to fire.</para>
+ <para>A single Message object is created with the message "Hello World" and status HELLO and then inserted into the engine, at which point fireAllRules() is executed. Remember all the network evaluation is done during the insert time, by the time the program execution reaches the fireAllRules() method it already knows which rules are fully matches and able to fire.</para>
- <example>
- <title>HelloWorld example: Execution</title>
+ <example>
+ <title>HelloWorld example: Execution</title>
- <programlisting>Message message = new Message();
+ <programlisting>Message message = new Message();
message.setMessage( "Hello World" );
message.setStatus( Message.HELLO );
session.insert( message );
@@ -136,51 +96,45 @@
logger.writeToDisk();
session.dispose(); </programlisting>
- </example>
+ </example>
- <para>To execute the example from Java.</para>
+ <para>To execute the example from Java.</para>
- <para><orderedlist>
- <listitem>
- <para>Open the class org.drools.examples.FibonacciExample in your
- Eclipse IDE</para>
- </listitem>
+ <orderedlist>
+ <listitem>
+ <para>Open the class org.drools.examples.FibonacciExample in your Eclipse IDE</para>
+ </listitem>
- <listitem>
- <para>Right-click the class an select "Run as..." -> "Java
- application"</para>
- </listitem>
- </orderedlist></para>
+ <listitem>
+ <para>Right-click the class an select "Run as..." -> "Java application"</para>
+ </listitem>
+ </orderedlist>
- <para>If we put a breakpoint on the fireAllRules() method and select the
- session variable we can see that the "Hello World" view is already
- activated and on the Agenda, showing that all the pattern matching work
- was already done during the insert.</para>
+ <para>If we put a breakpoint on the fireAllRules() method and select the session variable we can see that the "Hello World" view is already activated and on the Agenda, showing that all the pattern matching work was already done during the insert.</para>
- <figure>
- <title>Hello World : fireAllRules Agenda View</title>
+ <figure>
+ <title>Hello World : fireAllRules Agenda View</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="helloworld_agenda1.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="helloworld_agenda1.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>The may application print outs go to to System.out while the debug
- listener print outs go to System.err.</para>
+ <para>The may application print outs go to to System.out while the debug listener print outs go to System.err.</para>
- <example>
- <title>HelloWorld example: Console.out</title>
+ <example>
+ <title>HelloWorld example: Console.out</title>
- <programlisting>Hello World
-Goodbyte cruel world</programlisting>
- </example>
+ <programlisting>Hello World
+Goodbye cruel world</programlisting>
+ </example>
- <example>
- <title>HelloWorld example: Console.err</title>
+ <example>
+ <title>HelloWorld example: Console.err</title>
- <programlisting>==>[ActivationCreated(0): rule=Hello World;
+ <programlisting>==>[ActivationCreated(0): rule=Hello World;
tuple=[fid:1:1:org.drools.examples.HelloWorldExample$Message at 17cec96]]
[ObjectInserted: handle=[fid:1:1:org.drools.examples.HelloWorldExample$Message at 17cec96];
object=org.drools.examples.HelloWorldExample$Message at 17cec96]
@@ -195,31 +149,16 @@
[BeforeActivationFired: rule=Good Bye;
tuple=[fid:1:2:org.drools.examples.HelloWorldExample$Message at 17cec96]]
[AfterActivationFired(4): rule=Good Bye] </programlisting>
- </example>
+ </example>
- <para>The <emphasis role="bold">LHS (when)</emphasis> section of the rule
- states that it will be activated for each <emphasis>Message</emphasis>
- object inserted into the working memory whose <emphasis>status</emphasis>
- is <emphasis>Message.HELLO</emphasis>. Besides that, two variable binds
- are created: "<emphasis>message</emphasis>" variable is bound to the
- <emphasis>message</emphasis> attribute and "<emphasis>m</emphasis>"
- variable is bound to the <emphasis>object matched pattern</emphasis>
- itself.</para>
+ <para>The <emphasis role="bold">LHS (when)</emphasis> section of the rule states that it will be activated for each <emphasis>Message</emphasis> object inserted into the working memory whose <emphasis>status</emphasis> is <emphasis>Message.HELLO</emphasis>. Besides that, two variable binds are created: "<emphasis>message</emphasis>" variable is bound to the <emphasis>message</emphasis> attribute and "<emphasis>m</emphasis>" variable is bound to the <emphasis>object matched pattern</emphasis> itself.</para>
- <para>The <emphasis role="bold">RHS (consequence, then)</emphasis> section
- of the rule is written using the MVEL expression language, as declared by
- the rule's attribute <emphasis>dialect</emphasis>. After printing the
- content of the <emphasis>message</emphasis> bound variable to the default
- console, the rule changes the values of the <emphasis>message</emphasis>
- and <emphasis>status</emphasis> attributes of the <emphasis>m</emphasis>
- bound variable; using MVEL's 'modify' keyword which allows you to apply a
- block of setters in one statement, with the engine being automatically
- notified of the changes at the end of the block.</para>
+ <para>The <emphasis role="bold">RHS (consequence, then)</emphasis> section of the rule is written using the MVEL expression language, as declared by the rule's attribute <emphasis>dialect</emphasis>. After printing the content of the <emphasis>message</emphasis> bound variable to the default console, the rule changes the values of the <emphasis>message</emphasis> and <emphasis>status</emphasis> attributes of the <emphasis>m</emphasis> bound variable; using MVEL's 'modify' keyword which allows you to apply a block of setters in one statement, with the engine being automatically notified of the changes at the end of the block.</para>
- <example>
- <title>HelloWorld example: rule "Hello World"</title>
+ <example>
+ <title>HelloWorld example: rule "Hello World"</title>
- <programlisting>rule "Hello World"
+ <programlisting>rule "Hello World"
dialect "mvel"
when
m : Message( status == Message.HELLO, message : message )
@@ -228,110 +167,89 @@
modify ( m ) { message = "Goodbyte cruel world",
status = Message.GOODBYE };
end</programlisting>
- </example>
+ </example>
- <para>We can add a break point into the DRL for when modify is called
- during the execution of the "Hello World" consequence and inspect the
- Agenda view again. Notice this time we "Debug As" a "Drools application"
- and not a "Java application".</para>
+ <para>We can add a break point into the DRL for when modify is called during the execution of the "Hello World" consequence and inspect the Agenda view again. Notice this time we "Debug As" a "Drools application" and not a "Java application".</para>
- <para><orderedlist>
- <listitem>
- <para>Open the class org.drools.examples.FibonacciExample in your
- Eclipse IDE</para>
- </listitem>
+ <orderedlist>
+ <listitem>
+ <para>Open the class org.drools.examples.FibonacciExample in your Eclipse IDE</para>
+ </listitem>
- <listitem>
- <para>Right-click the class an select "Debug as..." -> "Drools
- application"</para>
- </listitem>
- </orderedlist>Now we can see that the other rule "Good Bye" which uses
- the java dialect is activated and placed on the agenda.</para>
+ <listitem>
+ <para>Right-click the class an select "Debug as..." -> "Drools application"</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Now we can see that the other rule "Good Bye" which uses the java dialect is activated and placed on the agenda.</para>
- <figure>
- <title>Hello World : rule "Hello World" Agenda View</title>
+ <figure>
+ <title>Hello World : rule "Hello World" Agenda View</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="helloworld_agenda2.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="EX_helloworld_agenda2.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>The "Good Bye" rule is similar to the "Hello World" rule but matches
- Message objects whose status is Message.GOODBYE instead, printing its
- message to the default console, it specifies the "java" dialect.</para>
+ <para>The "Good Bye" rule is similar to the "Hello World" rule but matches Message objects whose status is Message.GOODBYE instead, printing its message to the default console, it specifies the "java" dialect.</para>
- <example>
- <title>HelloWorld example: rule "Good Bye"</title>
+ <example>
+ <title>HelloWorld example: rule "Good Bye"</title>
- <programlisting>rule "Good Bye"
+ <programlisting>rule "Good Bye"
dialect "java"
when
Message( status == Message.GOODBYE, message : message )
then
System.out.println( message );
end</programlisting>
- </example>
+ </example>
- <para>If you remember at the start of this example in the java code we
- created a WorkingMemoryFileLogger and called logger.writeToDisk() at the
- end, this created an audit log file that can be shown in the Audit view.
- We use the audit view in many of the examples to try and understand the
- example execution flow. In the view below we can see the object is
- inserted which creates an activation for the "Hello World" rule, the
- activation is then executed which updated the Message object causing the
- "Good Bye" rule to activate, the "Good Bye" rule then also executes. When
- an event in the Audit view is select it highlights the origin event in
- green, so below the Activation created event is highlighted in greed as
- the origin of the Activation executed event.</para>
+ <para>If you remember at the start of this example in the java code we created a WorkingMemoryFileLogger and called logger.writeToDisk() at the end, this created an audit log file that can be shown in the Audit view. We use the audit view in many of the examples to try and understand the example execution flow. In the view below we can see the object is inserted which creates an activation for the "Hello World" rule, the activation is then executed which updated the Message object causing the "Good Bye" rule to activate, the "Good Bye" rule then also executes. When an event in the Audit view is select it highlights the origin event in green, so below the Activation created event is highlighted in greed as the origin of the Activation executed event.</para>
- <figure>
- <title>Hello World : Audit View</title>
+ <figure>
+ <title>Hello World : Audit View</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="helloworld_auditview1.png" />
- </imageobject>
- </mediaobject>
- </figure>
- </section>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="helloworld_auditview1.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
- <section>
- <title>State Example</title>
+ <section>
+ <title>State Example</title>
- <para>This example is actually implemented in three different versions to
- demonstrate different ways of implementing the same basic behavior: rules
- forward chaining, i.e., the ability the engine has to evaluate, activate
- and fire rules in sequence, based on changes on the facts in the working
- memory.</para>
+ <para>This example is actually implemented in three different versions to demonstrate different ways of implementing the same basic behavior: rules forward chaining, i.e., the ability the engine has to evaluate, activate and fire rules in sequence, based on changes on the facts in the working memory.</para>
+
+ <section>
+ <title>Understanding the State Example</title>
- <section>
- <title>Understanding the State Example</title>
-
- <para><programlisting><emphasis role="bold">Name:</emphasis> State Example
+ <screen><emphasis role="bold">Name:</emphasis> State Example
<emphasis role="bold">Main class:</emphasis> org.drools.examples.StateExampleUsingSalience
<emphasis role="bold">Type:</emphasis> java application
<emphasis role="bold">Rules file:</emphasis> StateExampleUsingSalience.drl
-<emphasis role="bold">Objective:</emphasis> Demonstrates basic rule use and Conflict Resolution for rule firing priority.</programlisting>Each
- State class has fields for its name and its current state (see
- org.drools.examples.State class). The two possible states for each
- objects are:</para>
+<emphasis role="bold">Objective:</emphasis> Demonstrates basic rule use and Conflict Resolution for rule firing priority.</screen>
- <itemizedlist>
- <listitem>
- <para>NOTRUN</para>
- </listitem>
+ <para>Each State class has fields for its name and its current state (see org.drools.examples.State class). The two possible states for each objects are:</para>
- <listitem>
- <para>FINISHED</para>
- </listitem>
- </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>NOTRUN</para>
+ </listitem>
- <example>
- <title>State Classs</title>
+ <listitem>
+ <para>FINISHED</para>
+ </listitem>
+ </itemizedlist>
- <programlisting>public class State {
+ <example>
+ <title>State Class</title>
+
+ <programlisting>public class State {
public static final int NOTRUN = 0;
public static final int FINISHED = 1;
@@ -342,18 +260,14 @@
... setters and getters go here...
}</programlisting>
- </example>
+ </example>
- <para>Ignore the PropertyChangeSupport for now, that will be explained
- later. In the example we create four State objects with names: A, B, C
- and D. Initially all are set to state NOTRUN, which is default for the
- used constructor. Each instance is asserted in turn into the session and
- then fireAllRules() is called.</para>
+ <para>Ignore the PropertyChangeSupport for now, that will be explained later. In the example we create four State objects with names: A, B, C and D. Initially all are set to state NOTRUN, which is default for the used constructor. Each instance is asserted in turn into the session and then fireAllRules() is called.</para>
- <example>
- <title>Salience State Example Execution</title>
+ <example>
+ <title>Salience State Example Execution</title>
- <programlisting>State a = new State( "A" );
+ <programlisting>State a = new State( "A" );
State b = new State( "B" );
State c = new State( "C" );
final State d = new State( "D" );
@@ -373,97 +287,78 @@
session.fireAllRules();
session.dispose(); // Stateful rule session must always be disposed when finished</programlisting>
- </example>
+ </example>
- <para>To execute the application:</para>
+ <para>To execute the application:</para>
- <para><orderedlist>
- <listitem>
- <para>Open the class org.drools.examples.StateExampleUsingSalience
- in your Eclipse IDE</para>
- </listitem>
+ <orderedlist>
+ <listitem>
+ <para>Open the class org.drools.examples.StateExampleUsingSalience in your Eclipse IDE</para>
+ </listitem>
- <listitem>
- <para>Right-click the class an select "Run as..." -> "Java
- application"</para>
- </listitem>
- </orderedlist></para>
+ <listitem>
+ <para>Right-click the class an select "Run as..." -> "Java application"</para>
+ </listitem>
+ </orderedlist>
- <para>And you will see the following output in the Eclipse console
- output:</para>
+ <para>And you will see the following output in the Eclipse console output:</para>
- <example>
- <title>Salience State Example Console Output</title>
+ <example>
+ <title>Salience State Example Console Output</title>
- <programlisting>A finished
+ <programlisting>A finished
B finished
C finished
D finished
</programlisting>
- </example>
+ </example>
- <para>There are four rules in total, first a Bootstrap rule fires
- setting A to state FINISHED which then causes B to change to state
- FINISHED. C and D are both dependent on B - causing a conflict which is
- resolved by setting salience values. First lets look at how this was
- executed</para>
+ <para>There are four rules in total, first a Bootstrap rule fires setting A to state FINISHED which then causes B to change to state FINISHED. C and D are both dependent on B - causing a conflict which is resolved by setting salience values. First lets look at how this was executed</para>
- <para>The best way to understand what is happening is to use the "Audit
- Log" feature to graphically see the results of each operation. The Audit
- log was generated when the example was previously run. To view the Audit
- log in Eclipse:</para>
+ <para>The best way to understand what is happening is to use the "Audit Log" feature to graphically see the results of each operation. The Audit log was generated when the example was previously run. To view the Audit log in Eclipse:</para>
- <orderedlist>
- <listitem>
- <para>If the "Audit View" is not visible, click on:
- "Window"->"Show View"->"Other..."->"Drools"->"Audit
- View"</para>
- </listitem>
+ <orderedlist>
+ <listitem>
+ <para>If the "Audit View" is not visible, click on: "Window"->"Show View"->"Other..."->"Drools"->"Audit View"</para>
+ </listitem>
- <listitem>
- <para>In the "Audit View" click in the "Open Log" button and select
- the file "<drools-examples-drl-dir>/log/state.log"</para>
- </listitem>
- </orderedlist>
+ <listitem>
+ <para>In the "Audit View" click in the "Open Log" button and select the file "<drools-examples-drl-dir>/log/state.log"</para>
+ </listitem>
+ </orderedlist>
- <para>After that, the "Audit view" will look like the following
- screenshot.</para>
+ <para>After that, the "Audit view" will look like the following screenshot.</para>
- <figure>
- <title>Salience State Example Audit View</title>
+ <figure>
+ <title>Salience State Example Audit View</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="state_example_audit1.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="state_example_audit1.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>Reading the log in the "Audit View", top to down, we see every
- action and the corresponding changes in the working memory. This way we
- see that the assertion of the State "A" object with the "NOTRUN" state
- activates the "Bootstrap" rule, while the assertions of the other state
- objects have no immediate effect.</para>
+ <para>Reading the log in the "Audit View", top to down, we see every action and the corresponding changes in the working memory. This way we see that the assertion of the State "A" object with the "NOTRUN" state activates the "Bootstrap" rule, while the assertions of the other state objects have no immediate effect.</para>
- <example>
- <title>Salience State Example: Rule "Bootstrap"</title>
+ <example>
+ <title>Salience State Example: Rule "Bootstrap"</title>
- <programlisting>rule Bootstrap
+ <programlisting>rule Bootstrap
when
a : State(name == "A", state == State.NOTRUN )
then
System.out.println(a.getName() + " finished" );
a.setState( State.FINISHED );
end</programlisting>
- </example>
+ </example>
- <para>The execution of "Bootstrap" rule changes the state of "A" to
- "FINISHED", that in turn activates the "A to B" rule.</para>
+ <para>The execution of "Bootstrap" rule changes the state of "A" to "FINISHED", that in turn activates the "A to B" rule.</para>
- <example>
- <title>Salience State Example: Rule "A to B"</title>
+ <example>
+ <title>Salience State Example: Rule "A to B"</title>
- <programlisting>rule "A to B"
+ <programlisting>rule "A to B"
when
State(name == "A", state == State.FINISHED )
b : State(name == "B", state == State.NOTRUN )
@@ -472,37 +367,24 @@
b.setState( State.FINISHED );
end
</programlisting>
- </example>
+ </example>
- <para>The execution of "A to B" rule changes the state of "B" to
- "FINISHED", which activates both rules "B to C" and "B to D", placing
- both Activations onto the Agenda. In this moment the two rules may fire
- and are said to be in conflict. The conflict resolution strategy allows
- the engine's Agenda to decide which rule to fire. As the "B to C" rule
- has a <emphasis role="bold">higher salience value</emphasis> (10 versus
- the default salience value of 0), it fires first, modifying the "C"
- object to state "FINISHED". The Audit view above shows the modification
- of the State object in the rule "A to B" which results in two
- highlighted activations being in conflict. The Agenda view can also be
- used to investigate the state of the Agenda, debug points can be placed
- in the rules themselves and the Agenda view opened; the screen shot
- below shows the break point in the rule "A to B" and the state of the
- Agenda with the two conflicting rules.</para>
+ <para>The execution of "A to B" rule changes the state of "B" to "FINISHED", which activates both rules "B to C" and "B to D", placing both Activations onto the Agenda. In this moment the two rules may fire and are said to be in conflict. The conflict resolution strategy allows the engine's Agenda to decide which rule to fire. As the "B to C" rule has a <emphasis role="bold">higher salience value</emphasis> (10 versus the default salience value of 0), it fires first, modifying the "C" object to state "FINISHED". The Audit view above shows the modification of the State object in the rule "A to B" which results in two highlighted activations being in conflict. The Agenda view can also be used to investigate the state of the Agenda, debug points can be placed in the rules themselves and the Agenda view opened; the screen shot below shows the break point in the rule "A to B" and the state of the Agenda with the two conflicting rules.</para>
- <figure>
- <title>State Example Agenda View</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="state_example_agenda1.png" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <example>
- <title>Salience State Example: Rule "B to C"</title>
-
- <programlisting>rule "B to C"
+ <figure>
+ <title>State Example Agenda View</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="state_example_agenda1.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <example>
+ <title>Salience State Example: Rule "B to C"</title>
+
+ <programlisting>rule "B to C"
salience 10
when
State(name == "B", state == State.FINISHED )
@@ -512,15 +394,14 @@
c.setState( State.FINISHED );
end
</programlisting>
- </example>
+ </example>
- <para>The "B to D" rule fires last, modifying the "D" object to state
- "FINISHED".</para>
-
- <example>
- <title>Salience State Example: Rule "B to D"</title>
-
- <programlisting>rule "B to D"
+ <para>The "B to D" rule fires last, modifying the "D" object to state "FINISHED".</para>
+
+ <example>
+ <title>Salience State Example: Rule "B to D"</title>
+
+ <programlisting>rule "B to D"
when
State(name == "B", state == State.FINISHED )
d : State(name == "D", state == State.NOTRUN )
@@ -528,77 +409,46 @@
System.out.println(d.getName() + " finished" );
d.setState( State.FINISHED );
end</programlisting>
- </example>
-
- <para>There are no more rules to execute and so the engine stops.</para>
-
- <para>Another notable concept in this example is the use of <emphasis
- role="bold">dynamic facts</emphasis>, which is the
- PropertyChangeListener part. As mentioned previously in the
- documentation, in order for the engine to see and react to fact's
- properties change, the application must tell the engine that changes
- occurred. This can be done explicitly in the rules, by calling the
- <emphasis role="bold">update()</emphasis> memory action, or implicitly
- by letting the engine know that the facts implement
- PropertyChangeSupport as defined by the <emphasis>Javabeans
- specification</emphasis>. This example demonstrates how to use
- PropertyChangeSupport to avoid the need for explicit update() calls in
- the rules. To make use of this feature, make sure your facts implement
- the PropertyChangeSupport as the org.drools.example.State class does and
- use the following code to insert the facts into the working
- memory:</para>
-
- <example>
- <title>Inserting a Dynamic Fact</title>
-
- <programlisting>// By setting dynamic to TRUE, Drools will use JavaBean
+ </example>
+
+ <para>There are no more rules to execute and so the engine stops.</para>
+
+ <para>Another notable concept in this example is the use of <emphasis role="bold">dynamic facts</emphasis>, which is the PropertyChangeListener part. As mentioned previously in the documentation, in order for the engine to see and react to fact's properties change, the application must tell the engine that changes occurred. This can be done explicitly in the rules, by calling the <emphasis role="bold">update()</emphasis> memory action, or implicitly by letting the engine know that the facts implement PropertyChangeSupport as defined by the <emphasis>Javabeans specification</emphasis>. This example demonstrates how to use PropertyChangeSupport to avoid the need for explicit update() calls in the rules. To make use of this feature, make sure your facts implement the PropertyChangeSupport as the org.drools.example.State class does and use the following code to insert the facts into the working memory:</para>
+
+ <example>
+ <title>Inserting a Dynamic Fact</title>
+
+ <programlisting>// By setting dynamic to TRUE, Drools will use JavaBean
// PropertyChangeListeners so you don't have to call update().
final boolean dynamic = true;
session.insert( fact,
dynamic );
</programlisting>
- </example>
-
- <para>When using PropertyChangeListeners each setter must implement a
- little extra code to do the notification, here is the state setter for
- thte org.drools.examples.State class:</para>
-
- <example>
- <title>Setter Example with PropertyChangeSupport</title>
-
- <programlisting>public void setState(final int newState) {
+ </example>
+
+ <para>When using PropertyChangeListeners each setter must implement a little extra code to do the notification, here is the state setter for thte org.drools.examples.State class:</para>
+
+ <example>
+ <title>Setter Example with PropertyChangeSupport</title>
+
+ <programlisting>public void setState(final int newState) {
int oldState = this.state;
this.state = newState;
this.changes.firePropertyChange( "state",
oldState,
newState );
}</programlisting>
- </example>
+ </example>
- <para>There are two other State examples: StateExampleUsingAgendGroup
- and StateExampleWithDynamicRules. Both execute from A to B to C to D, as
- just shown, the StateExampleUsingAgendGroup uses agenda-groups to
- control the rule conflict and which one fires first and
- StateExampleWithDynamicRules shows how an additional rule can be added
- to an already running WorkingMemory with all the existing data applying
- to it at runtime.</para>
-
- <para>Agenda groups are a way to partition the agenda into groups and
- controlling which groups can execute. All rules by default are in the
- "MAIN" agenda group, by simply using the "agenda-group" attribute you
- specify a different agenda group for the rule. A working memory
- initially only has focus on the "MAIN" agenda group, only when other
- groups are given the focus can their rules fire; this can be achieved by
- either using the method setFocus() or the rule attribute "auto-focus".
- "auto-focus" means that the rule automatically sets the focus to it's
- agenda group when the rule is matched and activated. It is this
- "auto-focus" that enables "B to C" to fire before "B to D".</para>
-
- <example>
- <title>Agenda Group State Example: Rule "B to C"</title>
-
- <programlisting>rule "B to C"
+ <para>There are two other State examples: StateExampleUsingAgendGroup and StateExampleWithDynamicRules. Both execute from A to B to C to D, as just shown, the StateExampleUsingAgendGroup uses agenda-groups to control the rule conflict and which one fires first and StateExampleWithDynamicRules shows how an additional rule can be added to an already running WorkingMemory with all the existing data applying to it at runtime.</para>
+
+ <para>Agenda groups are a way to partition the agenda into groups and controlling which groups can execute. All rules by default are in the "MAIN" agenda group, by simply using the "agenda-group" attribute you specify a different agenda group for the rule. A working memory initially only has focus on the "MAIN" agenda group, only when other groups are given the focus can their rules fire; this can be achieved by either using the method setFocus() or the rule attribute "auto-focus". "auto-focus" means that the rule automatically sets the focus to it's agenda group when the rule is matched and activated. It is this "auto-focus" that enables "B to C" to fire before "B to D".</para>
+
+ <example>
+ <title>Agenda Group State Example: Rule "B to C"</title>
+
+ <programlisting>rule "B to C"
agenda-group "B to C"
auto-focus true
when
@@ -609,16 +459,14 @@
c.setState( State.FINISHED );
drools.setFocus( "B to D" );
end</programlisting>
- </example>
+ </example>
- <para>The rule "B to C" calls "drools.setFocus( "B to D" );" which gives
- the agenda group "B to D" focus allowing its active rules to fire; which
- allows the rule "B to D" to fire.</para>
+ <para>The rule "B to C" calls "drools.setFocus( "B to D" );" which gives the agenda group "B to D" focus allowing its active rules to fire; which allows the rule "B to D" to fire.</para>
- <example>
- <title>Agenda Group State Example: Rule "B to D"</title>
+ <example>
+ <title>Agenda Group State Example: Rule "B to D"</title>
- <programlisting>rule "B to D"
+ <programlisting>rule "B to D"
agenda-group "B to D"
when
State(name == "B", state == State.FINISHED )
@@ -627,16 +475,14 @@
System.out.println(d.getName() + " finished" );
d.setState( State.FINISHED );
end</programlisting>
- </example>
+ </example>
- <para>The example StateExampleWithDynamicRules adds another rule to the
- RuleBase after fireAllRules(), the rule it adds is just another State
- transition.</para>
+ <para>The example StateExampleWithDynamicRules adds another rule to the RuleBase after fireAllRules(), the rule it adds is just another State transition.</para>
- <example>
- <title>Dynamic State Example: Rule "D to E"</title>
+ <example>
+ <title>Dynamic State Example: Rule "D to E"</title>
- <programlisting>rule "D to E"
+ <programlisting>rule "D to E"
when
State(name == "D", state == State.FINISHED )
e : State(name == "E", state == State.NOTRUN )
@@ -644,51 +490,42 @@
System.out.println(e.getName() + " finished" );
e.setState( State.FINISHED );
end</programlisting>
- </example>
+ </example>
- <para>It gives the following expected output:</para>
+ <para>It gives the following expected output:</para>
- <example>
- <title>Dynamic Sate Example Output</title>
-
- <programlisting>A finished
+ <example>
+ <title>Dynamic Sate Example Output</title>
+
+ <programlisting>A finished
B finished
C finished
D finished
E finished
</programlisting>
- </example>
- </section>
- </section>
+ </example>
+
+ </section>
+
+ </section>
- <section>
- <title>Banking Tutorial</title>
+ <section>
+ <title>Banking Tutorial</title>
- <programlisting><emphasis role="bold">Name:</emphasis> BankingTutorial
+ <screen><emphasis role="bold">Name:</emphasis> BankingTutorial
<emphasis role="bold">Main class:</emphasis> org.drools.tutorials.banking.*
<emphasis role="bold">Type:</emphasis> java application
<emphasis role="bold">Rules file:</emphasis> org.drools.tutorials.banking.*
-<emphasis role="bold">Objective:</emphasis> tutorial that builds up knowledge of pattern matching, basic sorting and calculation rules.</programlisting>
+<emphasis role="bold">Objective:</emphasis> tutorial that builds up knowledge of pattern matching, basic sorting and calculation rules.</screen>
- <para>This tutorial will demonstrate the process of developing a complete
- personal banking application that will handle credits, debits, currencies
- and that will use a set of design patterns that have been created for the
- process. In order to make the examples documented here clear and modular,
- I will try and steer away from re-visiting existing code to add new
- functionality, and will instead extend and inject where
- appropriate.</para>
+ <para>This tutorial will demonstrate the process of developing a complete personal banking application that will handle credits, debits, currencies and that will use a set of design patterns that have been created for the process. In order to make the examples documented here clear and modular, I will try and steer away from re-visiting existing code to add new functionality, and will instead extend and inject where appropriate.</para>
- <para>The RuleRunner class is a simple harness to execute one or more drls
- against a set of data. It compiles the Packages and creates the RuleBase
- for each execution, this allows us to easy execute each scenario and see
- the outputs. In reality this is not a good solution for a production
- system where the RuleBase should be built just once and cached, but for
- the purposes of this tutorial it shall suffice.</para>
+ <para>The RuleRunner class is a simple harness to execute one or more drls against a set of data. It compiles the Packages and creates the RuleBase for each execution, this allows us to easy execute each scenario and see the outputs. In reality this is not a good solution for a production system where the RuleBase should be built just once and cached, but for the purposes of this tutorial it shall suffice.</para>
- <example>
- <title>Banking Tutorial : RuleRunner</title>
+ <example>
+ <title>Banking Tutorial : RuleRunner</title>
- <programlisting>public class RuleRunner {
+ <programlisting>public class RuleRunner {
public RuleRunner() {
}
@@ -718,54 +555,49 @@
workingMemory.fireAllRules();
}
}</programlisting>
- </example>
+ </example>
- <para>This is our first Example1.java class it loads and executes a single
- drl file "Example.drl" but inserts no data.</para>
+ <para>This is our first Example1.java class it loads and executes a single drl file "Example.drl" but inserts no data.</para>
- <example>
- <title>Banking Tutorial : Java Example1</title>
+ <example>
+ <title>Banking Tutorial : Java Example1</title>
- <programlisting>public class Example1 {
+ <programlisting>public class Example1 {
public static void main(String[] args) throws Exception {
new RuleRunner().runRules( new String[] { "Example1.drl" },
new Object[0] );
}
}</programlisting>
- </example>
+ </example>
- <para>And this is the first simple rule to execute. It has a single "eval"
- condition that will alway be true, thus this rul will always match and
- fire.</para>
+ <para>And this is the first simple rule to execute. It has a single "eval" condition that will alway be true, thus this rul will always match and fire.</para>
- <example>
- <title>Banking Tutorial : Rule Example1</title>
+ <example>
+ <title>Banking Tutorial : Rule Example1</title>
- <programlisting>rule "Rule 01"
+ <programlisting>rule "Rule 01"
when
eval (1==1)
then
System.out.println("Rule 01 Works");
endh</programlisting>
- </example>
+ </example>
- <para>The output for the rule is below, the rule matches and executes the
- single print statement.</para>
+ <para>The output for the rule is below, the rule matches and executes the single print statement.</para>
- <example>
- <title>Banking Tutorial : Output Example1</title>
+ <example>
+ <title>Banking Tutorial : Output Example1</title>
- <programlisting>Loading file: Example1.drl
+ <programlisting>Loading file: Example1.drl
Rule 01 Works</programlisting>
- </example>
+ </example>
- <para>The next step is to assert some simple facts and print them out.
- </para>
+ <para>The next step is to assert some simple facts and print them out. </para>
- <example>
- <title>Banking Tutorial : Java Example2</title>
+ <example>
+ <title>Banking Tutorial : Java Example2</title>
- <programlisting>public class Example2 {
+ <programlisting>public class Example2 {
public static void main(String[] args) throws Exception {
Number[] numbers = new Number[] {wrap(3), wrap(1), wrap(4), wrap(1), wrap(5)};
new RuleRunner().runRules( new String[] { "Example2.drl" },
@@ -776,41 +608,31 @@
return new Integer(i);
}
}</programlisting>
- </example>
+ </example>
- <para>This doesn’t use any specific facts but instead asserts a set of
- java.lang.Integer’s. This is not considered "best practice" as a number of
- a collection is not a fact, it is not a thing. A Bank acount has a number,
- its balance, thus the Account is the fact; but to get started asserting
- Integers shall suffice for demonstration purposes as the complexity is
- built up.</para>
+ <para>This doesn’t use any specific facts but instead asserts a set of java.lang.Integer’s. This is not considered "best practice" as a number of a collection is not a fact, it is not a thing. A Bank acount has a number, its balance, thus the Account is the fact; but to get started asserting Integers shall suffice for demonstration purposes as the complexity is built up.</para>
- <para>Now we will create a simple rule to print out these numbers.</para>
+ <para>Now we will create a simple rule to print out these numbers.</para>
- <example>
- <title>Banking Tutorial : Rule Example2</title>
+ <example>
+ <title>Banking Tutorial : Rule Example2</title>
- <programlisting>rule "Rule 02"
+ <programlisting>rule "Rule 02"
when
Number( $intValue : intValue )
then
System.out.println("Number found with value: " + $intValue);
end</programlisting>
- </example>
+ </example>
- <para>Once again, this rule does nothing special. It identifies any facts
- that are Numbers and prints out the values. Notice the user of interfaces
- here, we inserted Integers but the pattern matching engine is able to
- match the interfaces and super classes of the asserted objects.</para>
+ <para>Once again, this rule does nothing special. It identifies any facts that are Numbers and prints out the values. Notice the user of interfaces here, we inserted Integers but the pattern matching engine is able to match the interfaces and super classes of the asserted objects.</para>
- <para>The output shows the drl being loaded, the facts inserted and then
- the matched and fired rules. We can see that each inserted number is
- matched and fired and thus printed.</para>
+ <para>The output shows the drl being loaded, the facts inserted and then the matched and fired rules. We can see that each inserted number is matched and fired and thus printed.</para>
- <example>
- <title>Banking Tutorial : Output Example2</title>
+ <example>
+ <title>Banking Tutorial : Output Example2</title>
- <programlisting>Loading file: Example2.drl
+ <programlisting>Loading file: Example2.drl
Inserting fact: 3
Inserting fact: 1
Inserting fact: 4
@@ -822,16 +644,14 @@
Number found with value: 1
Number found with value: 3
</programlisting>
- </example>
+ </example>
- <para>here are probably a hundred and one better ways to sort numbers; but
- we will need to apply some cashflows in date order when we start looking
- at banking rules so let’s look at a simple rule based example.</para>
+ <para>here are probably a hundred and one better ways to sort numbers; but we will need to apply some cashflows in date order when we start looking at banking rules so let’s look at a simple rule based example.</para>
- <example>
- <title>Banking Tutorial : Java Example3</title>
+ <example>
+ <title>Banking Tutorial : Java Example3</title>
- <programlisting>public class Example3 {
+ <programlisting>public class Example3 {
public static void main(String[] args) throws Exception {
Number[] numbers = new Number[] {wrap(3), wrap(1), wrap(4), wrap(1), wrap(5)};
new RuleRunner().runRules( new String[] { "Example3.drl" },
@@ -842,15 +662,14 @@
return new Integer(i);
}
}</programlisting>
- </example>
+ </example>
- <para>Again we insert our Integers as before, this time the rule is
- slightly different:</para>
+ <para>Again we insert our Integers as before, this time the rule is slightly different:</para>
- <example>
- <title>Banking Tutorial : Rule Example3</title>
+ <example>
+ <title>Banking Tutorial : Rule Example3</title>
- <programlisting>rule "Rule 03"
+ <programlisting>rule "Rule 03"
when
$number : Number( )
not Number( intValue < $number.intValue )
@@ -858,22 +677,16 @@
System.out.println("Number found with value: " + $number.intValue() );
retract( $number );
end</programlisting>
- </example>
+ </example>
- <para>The first line of the rules identifies a Number and extracts the
- value. The second line ensures that there does not exist a smaller number
- than the one found. By executing this rule, we might expect to find only
- one number - the smallest in the set. However, the retraction of the
- number after it has been printed, means that the smallest number has been
- removed, revealing the next smallest number, and so on. </para>
+ <para>The first line of the rules identifies a Number and extracts the value. The second line ensures that there does not exist a smaller number than the one found. By executing this rule, we might expect to find only one number - the smallest in the set. However, the retraction of the number after it has been printed, means that the smallest number has been removed, revealing the next smallest number, and so on. </para>
- <para>So, the output we generate is, notice the numbers are now sorted
- numerically.</para>
+ <para>So, the output we generate is, notice the numbers are now sorted numerically.</para>
- <example>
- <title>Banking Tutorial : Output Example3</title>
+ <example>
+ <title>Banking Tutorial : Output Example3</title>
- <programlisting>Loading file: Example3.drl
+ <programlisting>Loading file: Example3.drl
Inserting fact: 3
Inserting fact: 1
Inserting fact: 4
@@ -885,15 +698,14 @@
Number found with value: 4
Number found with value: 5
</programlisting>
- </example>
+ </example>
- <para>Now we want to start moving towards our personal accounting rules.
- The first step is to create a Cashflow POJO.</para>
+ <para>Now we want to start moving towards our personal accounting rules. The first step is to create a Cashflow POJO.</para>
- <example>
- <title>Banking Tutoria : Class Cashflow</title>
+ <example>
+ <title>Banking Tutoria : Class Cashflow</title>
- <programlisting>public class Cashflow {
+ <programlisting>public class Cashflow {
private Date date;
private double amount;
@@ -926,17 +738,14 @@
return "Cashflow[date=" + date + ",amount=" + amount + "]";
}
}</programlisting>
- </example>
+ </example>
- <para>The Cashflow has two simple attributes, a date and an amount. I have
- added a toString method to print it and overloaded the constructor to set
- the values. The Example4 java code inserts 5 Cashflow objecst with varying
- dates and amounts.</para>
+ <para>The Cashflow has two simple attributes, a date and an amount. I have added a toString method to print it and overloaded the constructor to set the values. The Example4 java code inserts 5 Cashflow objecst with varying dates and amounts.</para>
- <example>
- <title>Banking Tutorial : Java Example4</title>
+ <example>
+ <title>Banking Tutorial : Java Example4</title>
- <programlisting>public class Example4 {
+ <programlisting>public class Example4 {
public static void main(String[] args) throws Exception {
Object[] cashflows = {
new Cashflow(new SimpleDate("01/01/2007"), 300.00),
@@ -950,31 +759,28 @@
cashflows );
}
}</programlisting>
- </example>
+ </example>
- <para>SimpleDate is a simple class that extends Date and takes a String as
- input. It allows for pre-formatted Data classes, for convienience. The
- code is listed below</para>
+ <para>SimpleDate is a simple class that extends Date and takes a String as input. It allows for pre-formatted Data classes, for convienience. The code is listed below</para>
- <example>
- <title>Banking Tutorial : Java SimpleDate</title>
+ <example>
+ <title>Banking Tutorial : Java SimpleDate</title>
- <programlisting>public class SimpleDate extends Date {
+ <programlisting>public class SimpleDate extends Date {
private static final SimpleDateFormat format = new SimpleDateFormat("dd/MM/yyyy");
public SimpleDate(String datestr) throws Exception {
setTime(format.parse(datestr).getTime());
}
}</programlisting>
- </example>
+ </example>
- <para>Now, let’s look at rule04.drl to see how we print the sorted
- Cashflows:</para>
+ <para>Now, let’s look at rule04.drl to see how we print the sorted Cashflows:</para>
- <example>
- <title>Banking Tutorial : Rule Example4</title>
+ <example>
+ <title>Banking Tutorial : Rule Example4</title>
- <programlisting>rule "Rule 04"
+ <programlisting>rule "Rule 04"
when
$cashflow : Cashflow( $date : date, $amount : amount )
not Cashflow( date < $date)
@@ -982,18 +788,14 @@
System.out.println("Cashflow: "+$date+" :: "+$amount);
retract($cashflow);
end</programlisting>
- </example>
+ </example>
- <para>Here, we identify a Cashflow and extract the date and the amount. In
- the second line of the rules we ensure that there is not a Cashflow with
- an earlier date than the one found. In the consequences, we print the
- Cashflow that satisfies the rules and then retract it, making way for the
- next earliest Cashflow. So, the output we generate is:</para>
+ <para>Here, we identify a Cashflow and extract the date and the amount. In the second line of the rules we ensure that there is not a Cashflow with an earlier date than the one found. In the consequences, we print the Cashflow that satisfies the rules and then retract it, making way for the next earliest Cashflow. So, the output we generate is:</para>
- <example>
- <title>Banking Tutorial : Output Example4</title>
+ <example>
+ <title>Banking Tutorial : Output Example4</title>
- <programlisting>Loading file: Example4.drl
+ <programlisting>Loading file: Example4.drl
Inserting fact: Cashflow[date=Mon Jan 01 00:00:00 GMT 2007,amount=300.0]
Inserting fact: Cashflow[date=Fri Jan 05 00:00:00 GMT 2007,amount=100.0]
Inserting fact: Cashflow[date=Thu Jan 11 00:00:00 GMT 2007,amount=500.0]
@@ -1005,17 +807,14 @@
Cashflow: Sun Jan 07 00:00:00 GMT 2007 :: 800.0
Cashflow: Thu Jan 11 00:00:00 GMT 2007 :: 500.0
</programlisting>
- </example>
+ </example>
- <para>Here we extend our Cashflow to give a TypedCashflow which can be
- CREDIT or DEBIT. Ideally, we would just add this to the Cashflow type, but
- so that we can keep all the examples simple, we will go with the
- extensions.</para>
+ <para>Here we extend our Cashflow to give a TypedCashflow which can be CREDIT or DEBIT. Ideally, we would just add this to the Cashflow type, but so that we can keep all the examples simple, we will go with the extensions.</para>
- <example>
- <title>Banking Tutoria : Class TypedCashflow</title>
+ <example>
+ <title>Banking Tutoria : Class TypedCashflow</title>
- <programlisting>public class TypedCashflow extends Cashflow {
+ <programlisting>public class TypedCashflow extends Cashflow {
public static final int CREDIT = 0;
public static final int DEBIT = 1;
@@ -1044,17 +843,16 @@
return "TypedCashflow[date=" + getDate() + ",type=" + (type == CREDIT ? "Credit" : "Debit") + ",amount=" + getAmount() + "]";
}
}</programlisting>
- </example>
+ </example>
- <para>There are lots of ways to improve this code, but for the sake of the
- example this will do.</para>
+ <para>There are lots of ways to improve this code, but for the sake of the example this will do.</para>
- <para>Nows lets create the Example5 runner.</para>
+ <para>Nows lets create the Example5 runner.</para>
- <example>
- <title>Banking Tutorial : Java Example5</title>
+ <example>
+ <title>Banking Tutorial : Java Example5</title>
- <programlisting>public class Example5 {
+ <programlisting>public class Example5 {
public static void main(String[] args) throws Exception {
Object[] cashflows = {
new TypedCashflow(new SimpleDate("01/01/2007"),
@@ -1073,18 +871,16 @@
cashflows );
}
}</programlisting>
- </example>
+ </example>
- <para>Here, we simply create a set of Cashflows which are either CREDIT or
- DEBIT Cashflows and supply them and rule05.drl to the RuleEngine. </para>
+ <para>Here, we simply create a set of Cashflows which are either CREDIT or DEBIT Cashflows and supply them and rule05.drl to the RuleEngine. </para>
- <para>Now, let’s look at rule0 Example5.drl to see how we print the sorted
- Cashflows:</para>
+ <para>Now, let’s look at rule0 Example5.drl to see how we print the sorted Cashflows:</para>
- <example>
- <title>Banking Tutorial : Rule Example5</title>
+ <example>
+ <title>Banking Tutorial : Rule Example5</title>
- <programlisting>rule "Rule 05"
+ <programlisting>rule "Rule 05"
when
$cashflow : TypedCashflow( $date : date,
$amount : amount,
@@ -1095,21 +891,16 @@
System.out.println("Credit: "+$date+" :: "+$amount);
retract($cashflow);
end</programlisting>
- </example>
+ </example>
- <para>Here, we identify a Cashflow with a type of CREDIT and extract the
- date and the amount. In the second line of the rules we ensure that there
- is not a Cashflow of type CREDIT with an earlier date than the one found.
- In the consequences, we print the Cashflow that satisfies the rules and
- then retract it, making way for the next earliest Cashflow of type
- CREDIT.</para>
+ <para>Here, we identify a Cashflow with a type of CREDIT and extract the date and the amount. In the second line of the rules we ensure that there is not a Cashflow of type CREDIT with an earlier date than the one found. In the consequences, we print the Cashflow that satisfies the rules and then retract it, making way for the next earliest Cashflow of type CREDIT.</para>
- <para>So, the output we generate is</para>
+ <para>So, the output we generate is</para>
- <example>
- <title>Banking Tutorial : Output Example5</title>
+ <example>
+ <title>Banking Tutorial : Output Example5</title>
- <programlisting>Loading file: Example5.drl
+ <screen>Loading file: Example5.drl
Inserting fact: TypedCashflow[date=Mon Jan 01 00:00:00 GMT 2007,type=Credit,amount=300.0]
Inserting fact: TypedCashflow[date=Fri Jan 05 00:00:00 GMT 2007,type=Credit,amount=100.0]
Inserting fact: TypedCashflow[date=Thu Jan 11 00:00:00 GMT 2007,type=Credit,amount=500.0]
@@ -1118,21 +909,15 @@
Credit: Mon Jan 01 00:00:00 GMT 2007 :: 300.0
Credit: Fri Jan 05 00:00:00 GMT 2007 :: 100.0
Credit: Thu Jan 11 00:00:00 GMT 2007 :: 500.0
-</programlisting>
- </example>
+</screen>
+ </example>
- <para>Here we are going to process both CREDITs and DEBITs on 2 bank
- accounts to calculate the account balance. In order to do this, I am going
- to create two separate Account Objects and inject them into the Cashflows
- before passing them to the Rule Engine. The reason for this is to provide
- easy access to the correct Bank Accounts without having to resort to
- Helper classes. Let’s take a look at the Account class first. This is a
- simple POJO with an account number and balance:</para>
+ <para>Here we are going to process both CREDITs and DEBITs on 2 bank accounts to calculate the account balance. In order to do this, I am going to create two separate Account Objects and inject them into the Cashflows before passing them to the Rule Engine. The reason for this is to provide easy access to the correct Bank Accounts without having to resort to Helper classes. Let’s take a look at the Account class first. This is a simple POJO with an account number and balance:</para>
- <example>
- <title>Banking Tutoria : Class Account</title>
+ <example>
+ <title>Banking Tutoria : Class Account</title>
- <programlisting>public class Account {
+ <programlisting>public class Account {
private long accountNo;
private double balance = 0;
@@ -1163,15 +948,14 @@
return "Account[" + "accountNo=" + accountNo + ",balance=" + balance + "]";
}
}</programlisting>
- </example>
+ </example>
- <para>Now let’s extend our TypedCashflow to give AllocatedCashflow
- (allocated to an account).</para>
+ <para>Now let’s extend our TypedCashflow to give AllocatedCashflow (allocated to an account).</para>
- <example>
- <title>Banking Tutoria : Class AllocatedCashflow</title>
+ <example>
+ <title>Banking Tutoria : Class AllocatedCashflow</title>
- <programlisting>public class AllocatedCashflow extends TypedCashflow {
+ <programlisting>public class AllocatedCashflow extends TypedCashflow {
private Account account;
public AllocatedCashflow() {
@@ -1201,16 +985,14 @@
",amount=" + getAmount() + "]";
}
}</programlisting>
- </example>
+ </example>
- <para>Now, let’s java code for Example5 execution. Here we create two
- Account objects and inject one into each cashflow as appropriate. For
- simplicity I have simply included them in the constructor.</para>
+ <para>Now, let’s java code for Example5 execution. Here we create two Account objects and inject one into each cashflow as appropriate. For simplicity I have simply included them in the constructor.</para>
- <example>
- <title>Banking Tutorial : Java Example5</title>
+ <example>
+ <title>Banking Tutorial : Java Example5</title>
- <programlisting>public class Example6 {
+ <programlisting>public class Example6 {
public static void main(String[] args) throws Exception {
Account acc1 = new Account(1);
Account acc2 = new Account(2);
@@ -1242,15 +1024,14 @@
cashflows );
}
}</programlisting>
- </example>
+ </example>
- <para>Now, let’s look at rule Example06.drl to see how we apply each
- cashflow in date order and calculate and print the balance. </para>
+ <para>Now, let’s look at rule Example06.drl to see how we apply each cashflow in date order and calculate and print the balance. </para>
- <example>
- <title>Banking Tutorial : Rule Example6</title>
+ <example>
+ <title>Banking Tutorial : Rule Example6</title>
- <programlisting>rule "Rule 06 - Credit"
+ <programlisting>rule "Rule 06 - Credit"
when
$cashflow : AllocatedCashflow( $account : account,
$date : date, $amount : amount,
@@ -1277,19 +1058,14 @@
" - new balance: " + $account.getBalance());
retract($cashflow);
end</programlisting>
- </example>
+ </example>
- <para>Here, we have separate rules for CREDITs and DEBITs, however we do
- not specify a type when checking for earlier cashflows. This is so that
- all cashflows are applied in date order regardless of which type of
- cashflow type they are. In the rule section we identify the correct
- account to work with and in the consequences we update it with the
- cashflow amount.</para>
+ <para>Here, we have separate rules for CREDITs and DEBITs, however we do not specify a type when checking for earlier cashflows. This is so that all cashflows are applied in date order regardless of which type of cashflow type they are. In the rule section we identify the correct account to work with and in the consequences we update it with the cashflow amount.</para>
- <example>
- <title>Banking Tutorial : Output Example6</title>
+ <example>
+ <title>Banking Tutorial : Output Example6</title>
- <programlisting>Loading file: Example6.drl
+ <programlisting>Loading file: Example6.drl
Inserting fact: AllocatedCashflow[account=Account[accountNo=1,balance=0.0],date=Mon Jan 01 00:00:00 GMT 2007,type=Credit,amount=300.0]
Inserting fact: AllocatedCashflow[account=Account[accountNo=1,balance=0.0],date=Mon Feb 05 00:00:00 GMT 2007,type=Credit,amount=100.0]
Inserting fact: AllocatedCashflow[account=Account[accountNo=2,balance=0.0],date=Sun Mar 11 00:00:00 GMT 2007,type=Credit,amount=500.0]
@@ -1321,65 +1097,52 @@
Debit: Mon May 07 00:00:00 BST 2007 :: 900.0
Account: 1 - new balance: -800.0
</programlisting>
- </example>
- </section>
+ </example>
+
+ </section>
+
+ <section>
+ <title>Fibonacci Example</title>
- <section>
- <title>Fibonacci Example</title>
-
- <programlisting><emphasis role="bold">Name:</emphasis> Fibonacci
+ <screen><emphasis role="bold">Name:</emphasis> Fibonacci
<emphasis role="bold">Main class:</emphasis> org.drools.examples.FibonacciExample
<emphasis role="bold">Type:</emphasis> java application
<emphasis role="bold">Rules file:</emphasis> Fibonacci.drl
-<emphasis role="bold">Objective:</emphasis> Demonsrates Recursion, 'not' CEs and Cross Product Matching</programlisting>
+<emphasis role="bold">Objective:</emphasis> Demonsrates Recursion, 'not' CEs and Cross Product Matching</screen>
- <para>The Fibonacci Numbers, <ulink
- url="http://en.wikipedia.org/wiki/Fibonacci_number">http://en.wikipedia.org/wiki/Fibonacci_number</ulink>,
- invented by Leonardo of Pisa, <ulink
- url="http://en.wikipedia.org/wiki/Fibonacci">http://en.wikipedia.org/wiki/Fibonacci</ulink>,
- are obtained by starting with 0 and 1, and then produce the next Fibonacci
- number by adding the two previous Fibonacci numbers. The first Fibonacci
- numbers for n = 0, 1,... are: * 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89,
- 144, 233, 377, 610, 987, 1597, 2584, 4181, 6765, 10946... The Fibonacci
- Example demonstrates recursion and conflict resolution with Salience
- values.</para>
+ <para>The Fibonacci Numbers, <ulink url="http://en.wikipedia.org/wiki/Fibonacci_number">http://en.wikipedia.org/wiki/Fibonacci_number</ulink>, invented by Leonardo of Pisa, <ulink url="http://en.wikipedia.org/wiki/Fibonacci">http://en.wikipedia.org/wiki/Fibonacci</ulink>, are obtained by starting with 0 and 1, and then produce the next Fibonacci number by adding the two previous Fibonacci numbers. The first Fibonacci numbers for n = 0, 1,... are: * 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987, 1597, 2584, 4181, 6765, 10946... The Fibonacci Example demonstrates recursion and conflict resolution with Salience values.</para>
- <para>A single fact Class is used in this example, Fibonacci. It has two
- fields, sequence and value. The sequence field is used to indicate the
- position of the object in the Fibonacci number sequence and the value
- field shows the value of that Fibonacci object for that sequence
- position.</para>
+ <para>A single fact Class is used in this example, Fibonacci. It has two fields, sequence and value. The sequence field is used to indicate the position of the object in the Fibonacci number sequence and the value field shows the value of that Fibonacci object for that sequence position.</para>
- <example>
- <title>Fibonacci Class</title>
+ <example>
+ <title>Fibonacci Class</title>
- <programlisting>public static class Fibonacci {
+ <programlisting>public static class Fibonacci {
private int sequence;
private long value;
... setters and getters go here...
}</programlisting>
- </example>
+ </example>
- <para>Execute the example:</para>
+ <para>Execute the example:</para>
- <para><orderedlist>
- <listitem>
- <para>Open the class org.drools.examples.FibonacciExample in your
- Eclipse IDE</para>
- </listitem>
+ <orderedlist>
+ <listitem>
+ <para>Open the class <classname>org.drools.examples.FibonacciExample</classname> in your Eclipse IDE</para>
+ </listitem>
- <listitem>
- <para>Right-click the class an select "Run as..." -> "Java
- application"</para>
- </listitem>
- </orderedlist>And the Eclipse show the following output in it's console,
- "...snip..." shows repeated bits removed to save space:</para>
+ <listitem>
+ <para>Right-click the class an select "Run as..." -> "Java application"</para>
+ </listitem>
+ </orderedlist>
+
+ <para>And Eclipse shows the following output in its console, "...snip..." shows repeated bits removed to save space:</para>
- <example>
- <title>Fibonacci Example Console Output</title>
+ <example>
+ <title>Fibonacci Example Console Output</title>
- <programlisting>recurse for 50
+ <programlisting>recurse for 50
recurse for 49
recurse for 48
recurse for 47
@@ -1400,36 +1163,23 @@
49 == 7778742049
50 == 12586269025
</programlisting>
- </example>
+ </example>
- <para>To kick this off from java we only insert a single Fibonacci object,
- with a sequence of 50, a recurse rule is then used to insert the other 49
- Fibonacci objects. This example doesn't use PropertyChangeSupport and uses
- the MVEL dialect, this means we can use the <emphasis
- role="bold">modify</emphasis> keyword, which allows a block setter action
- which also notifies the engine of changes.</para>
+ <para>To kick this off from java we only insert a single Fibonacci object, with a sequence of 50, a recurse rule is then used to insert the other 49 Fibonacci objects. This example doesn't use PropertyChangeSupport and uses the MVEL dialect, this means we can use the <emphasis role="bold">modify</emphasis> keyword, which allows a block setter action which also notifies the engine of changes.</para>
- <example>
- <title>Fibonacci Example Execution</title>
+ <example>
+ <title>Fibonacci Example Execution</title>
- <programlisting>session.insert( new Fibonacci( 50 ) );
+ <programlisting>session.insert( new Fibonacci( 50 ) );
session.fireAllRules();</programlisting>
- </example>
+ </example>
- <para>The recurse rule is very simple, it matches each asserted Fibonacci
- object with a value of -1, it then creates and asserts a new Fibonacci
- object with a sequence of one less than the currently matched object. Each
- time a Fibonacci object is added, as long as one with a "sequence == 1"
- does not exist, the rule re-matches again and fires; causing the
- recursion. The 'not' conditional element is used to stop the rule matching
- once we have all 50 Fibonacci objects in memory. The rule also has a
- salience value, this is because we need to have all 50 Fibonacci objects
- asserted before we execute the Bootstrap rule.</para>
+ <para>The recurse rule is very simple, it matches each asserted Fibonacci object with a value of -1, it then creates and asserts a new Fibonacci object with a sequence of one less than the currently matched object. Each time a Fibonacci object is added, as long as one with a "sequence == 1" does not exist, the rule re-matches again and fires; causing the recursion. The 'not' conditional element is used to stop the rule matching once we have all 50 Fibonacci objects in memory. The rule also has a salience value, this is because we need to have all 50 Fibonacci objects asserted before we execute the Bootstrap rule.</para>
- <example>
- <title>Fibonacci Example : Rule "Recurse"</title>
+ <example>
+ <title>Fibonacci Example : Rule "Recurse"</title>
- <programlisting>rule Recurse
+ <programlisting>rule Recurse
salience 10
when
f : Fibonacci ( value == -1 )
@@ -1438,94 +1188,64 @@
insert( new Fibonacci( f.sequence - 1 ) );
System.out.println( "recurse for " + f.sequence );
end</programlisting>
- </example>
+ </example>
- <para>The audit view shows the original assertion of the Fibonacci object
- with a sequence of 50, this was done from Java land. From there the audit
- view shows the continual recursion of the rule, each asserted Fibonacci
- causes the "Recurse" rule to become activate again, which then
- fires.</para>
+ <para>The audit view shows the original assertion of the Fibonacci object with a sequence of 50, this was done from Java land. From there the audit view shows the continual recursion of the rule, each asserted Fibonacci causes the "Recurse" rule to become activate again, which then fires.</para>
- <figure>
- <title>Fibonacci Example "Recurse" Audit View 1</title>
+ <figure>
+ <title>Fibonacci Example "Recurse" Audit View 1</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="fibonacci1.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="fibonacci1.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>When a Fibonacci with a sequence of 2 is asserted the "Bootstrap"
- rule is matched and activated along with the "Recurse" rule.</para>
+ <para>When a Fibonacci with a sequence of 2 is asserted the "Bootstrap" rule is matched and activated along with the "Recurse" rule.</para>
- <example>
- <title>Fibonacci Example : Rule "Bootstrap"</title>
+ <example>
+ <title>Fibonacci Example : Rule "Bootstrap"</title>
- <programlisting>rule Bootstrap
+ <programlisting>rule Bootstrap
when
f : Fibonacci( sequence == 1 || == 2, value == -1 ) // this is a multi-restriction || on a single field
then
modify ( f ){ value = 1 };
System.out.println( f.sequence + " == " + f.value );
end</programlisting>
- </example>
+ </example>
- <para>At this point the Agenda looks like the figure shown below. However
- the "Bootstrap" rule does not fire as the "Recurse" rule has a higher
- salience.</para>
+ <para>At this point the Agenda looks like the figure shown below. However the "Bootstrap" rule does not fire as the "Recurse" rule has a higher salience.</para>
- <figure>
- <title>Fibonacci Example "Recurse" Agenda View 1</title>
+ <figure>
+ <title>Fibonacci Example "Recurse" Agenda View 1</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="fibonacci_agenda1.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="fibonacci_agenda1.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>When a Fibonacci with a sequence of 1 is asserted the "Bootstrap"
- rule is matched again, causing two activations for this rule; note that
- the "Recurse" rule does not match and activate because the 'not
- conditional element stops the rule matching when a Fibonacci with a
- sequence of 1 exists.</para>
+ <para>When a Fibonacci with a sequence of 1 is asserted the "Bootstrap" rule is matched again, causing two activations for this rule; note that the "Recurse" rule does not match and activate because the 'not conditional element stops the rule matching when a Fibonacci with a sequence of 1 exists.</para>
- <figure>
- <title>Fibonacci Example "Recurse" Agenda View 2</title>
+ <figure>
+ <title>Fibonacci Example "Recurse" Agenda View 2</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="fibonacci_agenda2.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="fibonacci_agenda2.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>Once we have two Fibonacci objects both with values not equal to -1
- the "calculate" rule is able to match; remember it was the "Bootstrap"
- rule that set the Fibonacci's with sequences 1 and 2 to values of 1. At
- this point we have 50 Fibonacci objects in the Working Memory and we some
- how need to select the correct ones to calculate each of their values in
- turn. With three Fibonacci patterns in a rule with no field constriants to
- correctly constrain the available cross products we have 50x50x50 possible
- permutations, thats 125K possible rule firings. The "Calculate" rule uses
- the field constraints to correctly constraint the thee Fibonacci patterns
- and in the correct order; this technique is called "cross product
- matching". The first pattern finds any Fibonacci with a value != -1 and
- binds both the pattern and the field. The second Fibonacci does too but it
- adds an additional field constraint to make sure that its sequence is one
- greater than the Fibonacci bound to f1. When this rule first fires we know
- that only sequences 1 and 2 have values of 1 and the two constraints
- ensure that f1 references sequence 1 and f2 references sequence2. The
- final pattern finds the Fibonacci of a value == -1 with a sequence one
- greater than f2. At this point we have three Fibonacci objects correctly
- selected from the available cross products and we can do the maths
- calculating the value for Fibonacci sequence = 3.</para>
+ <para>Once we have two Fibonacci objects both with values not equal to -1 the "calculate" rule is able to match; remember it was the "Bootstrap" rule that set the Fibonacci's with sequences 1 and 2 to values of 1. At this point we have 50 Fibonacci objects in the Working Memory and we some how need to select the correct ones to calculate each of their values in turn. With three Fibonacci patterns in a rule with no field constriants to correctly constrain the available cross products we have 50x50x50 possible permutations, thats 125K possible rule firings. The "Calculate" rule uses the field constraints to correctly constraint the thee Fibonacci patterns and in the correct order; this technique is called "cross product matching". The first pattern finds any Fibonacci with a value != -1 and binds both the pattern and the field. The second Fibonacci does too but it adds an additional field constraint to make sure that its sequence is one greater than the Fibonacci bound to f!
1. When this rule first fires we know that only sequences 1 and 2 have values of 1 and the two constraints ensure that f1 references sequence 1 and f2 references sequence2. The final pattern finds the Fibonacci of a value == -1 with a sequence one greater than f2. At this point we have three Fibonacci objects correctly selected from the available cross products and we can do the maths calculating the value for Fibonacci sequence = 3.</para>
- <example>
- <title>Fibonacci Example : Rule "Calculate"</title>
+ <example>
+ <title>Fibonacci Example : Rule "Calculate"</title>
- <programlisting>rule Calculate
+ <programlisting>rule Calculate
when
f1 : Fibonacci( s1 : sequence, value != -1 ) // here we bind sequence
f2 : Fibonacci( sequence == (s1 + 1 ), value != -1 ) // here we don't, just to demonstrate the different way bindings can be used
@@ -1535,98 +1255,75 @@
System.out.println( s3 + " == " + f3.value ); // see how you can access pattern and field bindings
end
</programlisting>
- </example>
+ </example>
- <para>The MVEL modify keyword updated the value of the Fibonacci object
- bound to f3, this means we have a new Fibonacci object with a value != -1,
- this allows the "Calculate" rule to rematch and calculate the next
- Fibonacci number. The Audit view below shows the how the firing of the
- last "Bootstrap" modifies the Fibonacci object enabling the "Calculate"
- rule to match, which then modifies another Fibonacci object allowing the
- "Calculate" rule to rematch. This continues till the value is set for all
- Fibonacci objects.</para>
+ <para>The MVEL modify keyword updated the value of the Fibonacci object bound to f3, this means we have a new Fibonacci object with a value != -1, this allows the "Calculate" rule to rematch and calculate the next Fibonacci number. The Audit view below shows the how the firing of the last "Bootstrap" modifies the Fibonacci object enabling the "Calculate" rule to match, which then modifies another Fibonacci object allowing the "Calculate" rule to rematch. This continues till the value is set for all Fibonacci objects.</para>
- <figure>
- <title>Fibonacci Example "Bootstrap" Audit View 1</title>
+ <figure>
+ <title>Fibonacci Example "Bootstrap" Audit View 1</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="fibonacci4.png" />
- </imageobject>
- </mediaobject>
- </figure>
- </section>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="fibonacci4.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
- <section>
- <title>Golfing Example</title>
+ <section>
+ <title>Golfing Example</title>
- <programlisting><emphasis role="bold">Name:</emphasis> Golfing
+ <screen><emphasis role="bold">Name:</emphasis> Golfing
<emphasis role="bold">Main class:</emphasis> org.drools.examples.GolfingExample
<emphasis role="bold">Type:</emphasis> java application
<emphasis role="bold">Rules file:</emphasis> golf.drl
<emphasis role="bold">Objective:</emphasis> Configuration example that finds the solution from a large number of available cross products
-</programlisting>
+</screen>
- <para>The golf example solves a "riddle" style problem that is simple
- enough to state in sentences, but for which a conventional algorithmic
- solition is not obvious. It does this by searching for a suitable
- combination from a "space" of possible solutions.</para>
+ <para>The golf example solves a "riddle" style problem that is simple enough to state in sentences, but for which a conventional algorithmic solition is not obvious. It does this by searching for a suitable combination from a "space" of possible solutions.</para>
+
+ <section>
+ <title>The riddle</title>
- <section>
- <title>The riddle</title>
+ <para>The problem is written as a riddle:</para>
- <para>The problem is written as a riddle:</para>
+ <orderedlist>
+ <listitem>
+ <para>A foursome of golfers is standing at a tee, in a line from left to right.</para>
+ </listitem>
- <orderedlist>
- <listitem>
- <para>A foursome of golfers is standing at a tee, in a line from
- left to right.</para>
- </listitem>
+ <listitem>
+ <para>Each golfer wears different colored pants; one is wearing red pants.</para>
+ </listitem>
- <listitem>
- <para>Each golfer wears different colored pants; one is wearing red
- pants.</para>
- </listitem>
+ <listitem>
+ <para>The golfer to Fred’s immediate right is wearing blue pants.</para>
+ </listitem>
- <listitem>
- <para>The golfer to Fred’s immediate right is wearing blue
- pants.</para>
- </listitem>
+ <listitem>
+ <para>Joe is second in line.</para>
+ </listitem>
- <listitem>
- <para>Joe is second in line.</para>
- </listitem>
+ <listitem>
+ <para>Bob is wearing plaid pants.</para>
+ </listitem>
- <listitem>
- <para>Bob is wearing plaid pants.</para>
- </listitem>
+ <listitem>
+ <para>Tom isn’t in position one or four, and he isn’t wearing the hideous orange pants.</para>
+ </listitem>
+ </orderedlist>
- <listitem>
- <para>Tom isn’t in position one or four, and he isn’t wearing the
- hideous orange pants.</para>
- </listitem>
- </orderedlist>
+ <para>The immediate thing about this riddle, is that a solution is not obvious (of course ! it wouldn't be a riddle otherwise !). It also isn't obvious how to write an algorithm to solve it (if it is for you - then you can take a break now, go have a coffee or someting to reward your uber intellect).</para>
- <para>The immediate thing about this riddle, is that a solution is not
- obvious (of course ! it wouldn't be a riddle otherwise !). It also isn't
- obvious how to write an algorithm to solve it (if it is for you - then
- you can take a break now, go have a coffee or someting to reward your
- uber intellect).</para>
+ <para>Instead of thinking about how to solve it, we can be lazy and use rules instead. So we don't attempt to solve it, we just state the problem in rules, and let the engine derive the solution.</para>
+ </section>
+
+ <section>
+ <title>Launching the example</title>
- <para>Instead of thinking about how to solve it, we can be lazy and use
- rules instead. So we don't attempt to solve it, we just state the
- problem in rules, and let the engine derive the solution.</para>
- </section>
+ <para>The supporting code is in the GolfingExample.java class. There is an inner class "Golfer" which represents a golf player, it has their name, position (1 to 4 meaning left to right), and their pants color, as simple properties.</para>
- <section>
- <title>Launching the example</title>
-
- <para>The supporting code is in the GolfingExample.java class. There is
- an inner class "Golfer" which represents a golf player, it has their
- name, position (1 to 4 meaning left to right), and their pants color, as
- simple properties.</para>
-
- <programlisting>String[] names = new String[] { "Fred", "Joe", "Bob", "Tom" };
+ <screen>String[] names = new String[] { "Fred", "Joe", "Bob", "Tom" };
String[] colors = new String[] { "red", "blue", "plaid", "orange" };
int[] positions = new int[] { 1, 2, 3, 4 };
@@ -1636,70 +1333,48 @@
session.insert( new Golfer( names[n], colors[c], positions[p]) );
}
}
-} </programlisting>
+} </screen>
- <para>The above listing shows the interesting part of the supporting
- code. Note that we have arrays representing each name, color, and
- position. We then go through a nested loop inserting instances of Golfer
- - so in the working memory we will have all combinations of name, color
- and position. It is then the job of the rules to find the appropriate
- one.</para>
+ <para>The above listing shows the interesting part of the supporting code. Note that we have arrays representing each name, color, and position. We then go through a nested loop inserting instances of Golfer - so in the working memory we will have all combinations of name, color and position. It is then the job of the rules to find the appropriate one.</para>
- <para>Launching the code as a java application should yield the
- following output:</para>
+ <para>Launching the code as a java application should yield the following output:</para>
- <programlisting>Fred 1 orange
+ <programlisting>Fred 1 orange
Joe 2 blue
Bob 4 plaid
Tom 3 red </programlisting>
- <para>This shows that the rule(s) have found a suitable solution.</para>
- </section>
+ <para>This shows that the rule(s) have found a suitable solution.</para>
+ </section>
- <section>
- <title>The matching rule</title>
+ <section>
+ <title>The matching rule</title>
- <para>The solution in rules is quite simple, it is a single rule which
- expresses the constraints as stated in the riddle. Effectively, we can
- interpret the riddle as a series of constraints on our object model.
- Given that we have enough "combinations" in the working memory, all we
- have to do is express the constraints in a rule and the engine will
- match it with a solution (we don't really care how it does it, as long
- as it works !).</para>
+ <para>The solution in rules is quite simple, it is a single rule which expresses the constraints as stated in the riddle. Effectively, we can interpret the riddle as a series of constraints on our object model. Given that we have enough "combinations" in the working memory, all we have to do is express the constraints in a rule and the engine will match it with a solution (we don't really care how it does it, as long as it works !).</para>
- <para>There is one rule in the solution, in golf.drl, called "find
- solution". The rule is made up of 5 patterns, with constraints that map
- to items in the riddle.</para>
+ <para>There is one rule in the solution, in golf.drl, called "find solution". The rule is made up of 5 patterns, with constraints that map to items in the riddle.</para>
- <programlisting>$fred : Golfer( name == "Fred" ) </programlisting>
+ <programlisting>$fred : Golfer( name == "Fred" ) </programlisting>
- <para>In the above pattern, we are simply matching a Golfer who is
- called fred, and binding it to a variable called $fred. All that we know
- is that there is a golfer called fred.</para>
+ <para>In the above pattern, we are simply matching a Golfer who is called fred, and binding it to a variable called $fred. All that we know is that there is a golfer called fred.</para>
- <programlisting>$joe : Golfer( name == "Joe",
+ <programlisting>$joe : Golfer( name == "Joe",
position == 2,
position != $fred.position,
color != $fred.color ) </programlisting>
- <para>The next pattern says that we have a golfer named Joe, in position
- 2 ("second in line"). Now, we also know that he must NOT be in the same
- position as fred (of course !) and have different color pants. So far,
- nothing that amazing.</para>
+ <para>The next pattern says that we have a golfer named Joe, in position 2 ("second in line"). Now, we also know that he must NOT be in the same position as fred (of course !) and have different color pants. So far, nothing that amazing.</para>
- <programlisting>$bob : Golfer( name == "Bob",
+ <programlisting>$bob : Golfer( name == "Bob",
position != $fred.position,
position != $joe.position,
color == "plaid",
color != $fred.color,
color != $joe.color ) </programlisting>
- <para>Refering to the above, we also know there is a golfer called Bob,
- who wears plaid pants - once again that all we know about him. but of
- course, we add in the constraints that he must be in a different
- position to fred, joe, and also have different colored pants.</para>
+ <para>Refering to the above, we also know there is a golfer called Bob, who wears plaid pants - once again that all we know about him. but of course, we add in the constraints that he must be in a different position to fred, joe, and also have different colored pants.</para>
- <programlisting>$tom : Golfer( name == "Tom",
+ <programlisting>$tom : Golfer( name == "Tom",
position != 1,
position != 4,
position != $fred.position,
@@ -1710,102 +1385,53 @@
color != $joe.color,
color != $bob.color ) </programlisting>
- <para>(referring to the above) We also know that there is a guy called
- Tom, who doesn't wear the Orange pants, AND he is not in position 1, or
- 4. Of course we also add in the other constraints (he must be in a
- different position to the others so far, and have a different
- color).</para>
+ <para>(referring to the above) We also know that there is a guy called Tom, who doesn't wear the Orange pants, AND he is not in position 1, or 4. Of course we also add in the other constraints (he must be in a different position to the others so far, and have a different color).</para>
- <programlisting>Golfer( position == ( $fred.position + 1 ),
+ <programlisting>Golfer( position == ( $fred.position + 1 ),
color == "blue",
this in ( $joe, $bob, $tom ) ) </programlisting>
- <para>Finally, we know that the golfer on the right of Fred (position +
- 1), is in blue pants. We also add in the constraint that he must be
- either Joe, Bob or Tom (as Fred can't be beside himself, well he can I
- guess, but not in the sense we mean here !) - note the use of "this" to
- refer to the current pattern, we don't really care who "this" is, just
- who they are not. Maybe if Fred was really really happy they this
- wouldn't work, but lets assume otherwise for now.</para>
+ <para>Finally, we know that the golfer on the right of Fred (position + 1), is in blue pants. We also add in the constraint that he must be either Joe, Bob or Tom (as Fred can't be beside himself, well he can I guess, but not in the sense we mean here !) - note the use of "this" to refer to the current pattern, we don't really care who "this" is, just who they are not. Maybe if Fred was really really happy they this wouldn't work, but lets assume otherwise for now.</para>
- <para>Thats it ! We have expressed the rule as constraints that map to
- the ones expressed in the riddle, yet we haven't had to solve the
- riddle, the engine does that for us.</para>
- </section>
+ <para>Thats it ! We have expressed the rule as constraints that map to the ones expressed in the riddle, yet we haven't had to solve the riddle, the engine does that for us.</para>
+ </section>
- <section>
- <title>Conclustion</title>
+ <section>
+ <title>Conclusion</title>
- <para>This simple example shows how you can express a problem
- declaratively, and let the engine solve the problem for you, by making
- use of combinations. This is an often useful technique, as it allows you
- to express rules as a statement of the problem you are trying to
- solve.</para>
+ <para>This simple example shows how you can express a problem declaratively, and let the engine solve the problem for you, by making use of combinations. This is an often useful technique, as it allows you to express rules as a statement of the problem you are trying to solve.</para>
- <para>Of course, care must be taken. Using combinatorics like this can
- cause performance problems when there are large numbers of facts (eg in
- this case, if there were a larger number of golfers, or colors/positions
- etc - possibilities). When the fact count grows, the combinations the
- engine has to deal with can explode exponentially, making this not very
- efficient. However, in cases where the rules are perhaps complex, the
- problem is hard, but the fact numbers are relatively low, this approach
- can be very very useful and help you solve problems that would otherwise
- be very hard.</para>
- </section>
- </section>
+ <para>Of course, care must be taken. Using combinatorics like this can cause performance problems when there are large numbers of facts (eg in this case, if there were a larger number of golfers, or colors/positions etc - possibilities). When the fact count grows, the combinations the engine has to deal with can explode exponentially, making this not very efficient. However, in cases where the rules are perhaps complex, the problem is hard, but the fact numbers are relatively low, this approach can be very very useful and help you solve problems that would otherwise be very hard.</para>
+ </section>
- <section>
- <title>Trouble Ticket</title>
+ <section>
+ <title>Trouble Ticket</title>
- <para>The trouble ticket example shows how to use the duration attribute
- for temporal rules, and also includes an alternative version using a
- dsl.</para>
+ <para>The trouble ticket example shows how to use the duration attribute for temporal rules, and also includes an alternative version using a dsl.</para>
- <programlisting><emphasis role="bold">Name:</emphasis> TroubleTicket
+ <programlisting><emphasis role="bold">Name:</emphasis> TroubleTicket
<emphasis role="bold">Main class:</emphasis> org.drools.examples.TroubleTicketExample, org.drools.examples.TroubleTicketExampleWithDSL
<emphasis role="bold">Type:</emphasis> java application
<emphasis role="bold">Rules file:</emphasis> TroubleTicket.drl, TroubleTicketWithDSL.dslr
<emphasis role="bold">Objective:</emphasis> Show temporal rules in action
</programlisting>
- <para>The trouble ticket example is based around the idea of raising a
- "ticket" (ie an issue) with a vendor (these are the vendors rules). Each
- customer has a subscription class assigned to it (eg Gold, Silver etc) and
- their class determines how the ticket is treated with respect to time, and
- escalating the issue. The normal drl version will be discussed here, but
- logically the DSL version is the same (it just uses a DSL defined language
- instead of the normal DRL).</para>
+ <para>The trouble ticket example is based around the idea of raising a "ticket" (ie an issue) with a vendor (these are the vendors rules). Each customer has a subscription class assigned to it (eg Gold, Silver etc) and their class determines how the ticket is treated with respect to time, and escalating the issue. The normal drl version will be discussed here, but logically the DSL version is the same (it just uses a DSL defined language instead of the normal DRL).</para>
- <para>We have 2 types of facts, Customer and Ticket. A Ticket belongs to
- one and only one customer. A Customer has a name and a "subscription" type
- (Gold, Silver or Platinum). A ticket also has a "status" - which
- determines (obviously) what state it is in. The state may be set
- externally, or by the rules engine (eg it starts out "New", and then the
- system user determines that it is "Done" at some later point). The rules
- exist to ensure that the tickets are escalated appropriately based on the
- customer subscription class.</para>
+ <para>We have 2 types of facts, Customer and Ticket. A Ticket belongs to one and only one customer. A Customer has a name and a "subscription" type (Gold, Silver or Platinum). A ticket also has a "status" - which determines (obviously) what state it is in. The state may be set externally, or by the rules engine (eg it starts out "New", and then the system user determines that it is "Done" at some later point). The rules exist to ensure that the tickets are escalated appropriately based on the customer subscription class.</para>
- <para>Customers can choose Silver, Gold, or Platinum (in order of
- increasing responsiveness). Platinum subscriptions also come with a set of
- steak knives, and a personal butler to lodge the ticket for you (but
- obviously it costs more).</para>
+ <para>Customers can choose Silver, Gold, or Platinum (in order of increasing responsiveness). Platinum subscriptions also come with a set of steak knives, and a personal butler to lodge the ticket for you (but obviously it costs more).</para>
+ </section>
+
+ <section>
+ <title>Executing the Example</title>
- <section>
- <title>Executing the Example</title>
+ <para>The example creates 4 customers, with their name and subscription class, it then creates 4 tickets for each of the customers, note that the ticket takes the customer in the constructor (that sets up the object relationship. The tickets and the customers are then inserted. Notice that we keep a fact handle - which we will use to notify the engine that that specific ticket changed later on. The last line has the all important fireAllRules(), which tells the engine to take action on the data it has.</para>
- <para>The example creates 4 customers, with their name and subscription
- class, it then creates 4 tickets for each of the customers, note that
- the ticket takes the customer in the constructor (that sets up the
- object relationship. The tickets and the customers are then inserted.
- Notice that we keep a fact handle - which we will use to notify the
- engine that that specific ticket changed later on. The last line has the
- all important fireAllRules(), which tells the engine to take action on
- the data it has.</para>
+ <example>
+ <title>Trouble Ticket Example : Creating and Inserting Facts</title>
- <example>
- <title>Trouble Ticket Example : Creating and Inserting Facts</title>
-
- <programlisting>Customer a = new Customer( "A",
+ <programlisting>Customer a = new Customer( "A",
"Gold" );
Customer b = new Customer( "B",
"Platinum" );
@@ -1830,13 +1456,11 @@
session.insert( t4 );
session.fireAllRules();</programlisting>
- </example>
+ </example>
- <para>We have the "New Ticket" rule which has the highest priority
- (salience of 10 - the default is zero), The purpose of this is simply to
- log the fact that a new ticket has arrived in the system:</para>
+ <para>We have the "New Ticket" rule which has the highest priority (salience of 10 - the default is zero), The purpose of this is simply to log the fact that a new ticket has arrived in the system:</para>
- <programlisting>rule "New Ticket"
+ <programlisting>rule "New Ticket"
salience 10
when
customer : Customer( )
@@ -1845,75 +1469,46 @@
System.out.println( "New : " + ticket );
end </programlisting>
- <para>Note that we are "joining" the ticket fact with the customer fact.
- It's not really needed in this case, as we don't do anything (yet) with
- the customer fact. If you look in the TroubleTicketExample.java, you
- will also see that the facts are being inserted into the engine - note
- that we assert BOTH Customer and Ticket object (even though the ticket
- belongs to a customer - this allows the engine to join the objects
- together how it wants - this is what is meant by "relational"
- programming - we let the rule engine define what the relationships are.
- For instance, although the code is structured so that a ticket belongs
- to a customer, we may be interested in looking at tickets from different
- customers of the same type in the future).</para>
+ <para>Note that we are "joining" the ticket fact with the customer fact. It's not really needed in this case, as we don't do anything (yet) with the customer fact. If you look in the TroubleTicketExample.java, you will also see that the facts are being inserted into the engine - note that we assert BOTH Customer and Ticket object (even though the ticket belongs to a customer - this allows the engine to join the objects together how it wants - this is what is meant by "relational" programming - we let the rule engine define what the relationships are. For instance, although the code is structured so that a ticket belongs to a customer, we may be interested in looking at tickets from different customers of the same type in the future).</para>
- <para>If we run the rules, we should expect that the "New Ticket" rule
- will be activated for all tickets, so looking at the audit log view (by
- opening the file which was saved automatically when the rules were
- run):</para>
+ <para>If we run the rules, we should expect that the "New Ticket" rule will be activated for all tickets, so looking at the audit log view (by opening the file which was saved automatically when the rules were run):</para>
- <figure>
- <title>Audit view</title>
+ <figure>
+ <title>Audit view</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="tt_audit_view.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="tt_audit_view.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>Referring to the above audit log, we can see each customer
- asserted, but nothing happens. As soon as the first ticket gets
- asserted, it joins it with the customer, and creates some activations:
- one is the "new ticket" rule, the other is for the appropriate priority
- (which we will show below). Note that items in the above view do not
- mean the rule fired at that point.</para>
+ <para>Referring to the above audit log, we can see each customer asserted, but nothing happens. As soon as the first ticket gets asserted, it joins it with the customer, and creates some activations: one is the "new ticket" rule, the other is for the appropriate priority (which we will show below). Note that items in the above view do not mean the rule fired at that point.</para>
- <para>Also, don't forget to use "fireAllRules()" - a common mistake !
- (In this case we are using a statefull session, so this is
- necessary).</para>
+ <para>Also, don't forget to use "fireAllRules()" - a common mistake ! (In this case we are using a statefull session, so this is necessary).</para>
- <para>If we run the rules, we should expect that the "New Ticket" rule
- will be activated for all tickets, so looking at the audit log view (by
- opening the file which was saved automatically when the rules were
- run):</para>
+ <para>If we run the rules, we should expect that the "New Ticket" rule will be activated for all tickets, so looking at the audit log view (by opening the file which was saved automatically when the rules were run):</para>
- <figure>
- <title>Audit view</title>
+ <figure>
+ <title>Audit view</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="tt_audit_view.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="tt_audit_view.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>Referring to the above audit log, we can see each customer
- asserted, but nothing happens. As soon as the first ticket gets
- asserted, it joins it with the customer, and creates some activations:
- one is the "new ticket" rule, the other is for the appropriate priority
- (which we will show below). Note that items in the above view do not
- mean the rule fired at that point.</para>
- </section>
+ <para>Referring to the above audit log, we can see each customer asserted, but nothing happens. As soon as the first ticket gets asserted, it joins it with the customer, and creates some activations: one is the "new ticket" rule, the other is for the appropriate priority (which we will show below). Note that items in the above view do not mean the rule fired at that point.</para>
+
+ </section>
+
+ <section>
+ <title>Platinum gets the best service</title>
- <section>
- <title>Platinum gets the best service</title>
+ <para>All the wonderful platinum customers have to get great service, so first thing to note is that as soon as a ticket arrives, we escalate if it is for a platinum customer:</para>
- <para>All the wonderful platinum customers have to get great service, so
- first thing to note is that as soon as a ticket arrives, we escalate if
- it is for a platinum customer:</para>
-
- <programlisting>rule "Platinum Priority"
+ <programlisting>rule "Platinum Priority"
when
customer : Customer( subscription == "Platinum" )
ticket : Ticket( customer == customer, status == "New" )
@@ -1922,18 +1517,16 @@
update( ticket );
end </programlisting>
- <para>Here we are joining Ticket to customer again (customer ==
- customer), but we are also checking that the customer is "Platinum".
- When this is the case, we set the ticket status to "Escalate" and call
- update (which tells the engine that the ticket has changed).</para>
- </section>
+ <para>Here we are joining Ticket to customer again (customer == customer), but we are also checking that the customer is "Platinum". When this is the case, we set the ticket status to "Escalate" and call update (which tells the engine that the ticket has changed).</para>
+
+ </section>
+
+ <section>
+ <title>Silver and Gold</title>
- <section>
- <title>Silver and Gold</title>
+ <para>For silver and gold class, its a similar story to platinum:</para>
- <para>For silver and gold class, its a similar story to platinum:</para>
-
- <programlisting>rule "Silver Priority"
+ <programlisting>rule "Silver Priority"
duration 3000
when
customer : Customer( subscription == "Silver" )
@@ -1953,21 +1546,16 @@
update( ticket );
end </programlisting>
- <para>In this case, note the use of "duration XXX" - XXX is the number
- of milliseconds to wait to check that this rule holds true. Should it do
- so, after XXX milliseconds, then the action takes effect. So in the
- above case, after 3 seconds the "Silver" priority kicks in, but after 1
- second "Gold" does. In both cases the tickets are escalated (just like
- with platinum. This is what we mean by temporal rules (rules that take
- effect over time).</para>
- </section>
+ <para>In this case, note the use of "duration XXX" - XXX is the number of milliseconds to wait to check that this rule holds true. Should it do so, after XXX milliseconds, then the action takes effect. So in the above case, after 3 seconds the "Silver" priority kicks in, but after 1 second "Gold" does. In both cases the tickets are escalated (just like with platinum. This is what we mean by temporal rules (rules that take effect over time).</para>
- <section>
- <title>Escalating</title>
+ </section>
+
+ <section>
+ <title>Escalating</title>
- <para>The actual escalation of a ticket happens in a rule:</para>
+ <para>The actual escalation of a ticket happens in a rule:</para>
- <programlisting>rule "Escalate"
+ <programlisting>rule "Escalate"
when
customer : Customer( )
ticket : Ticket( customer == customer, status == "Escalate" )
@@ -1975,26 +1563,18 @@
sendEscalationEmail( customer, ticket );
end </programlisting>
- <para>In this case, the action is to call a function which sends an
- email (the function is defined down the bottom of the drl file). This
- rule reacts to the rules which update the ticket and set its status to
- escalate.</para>
- </section>
+ <para>In this case, the action is to call a function which sends an email (the function is defined down the bottom of the drl file). This rule reacts to the rules which update the ticket and set its status to escalate.</para>
- <para>In the code that launches the example, we have a "sleep" to make
- sure all this happens (and print out the results). Note also that after
- the rules are fired, we modify the status of the Customer "C" to "Done" -
- and then tell the engine. This causes it to evaluate and fire the rule
- that looks for "tickets" that are "Done" (in which is just logs a
- message).</para>
+ <para>In the code that launches the example, we have a "sleep" to make sure all this happens (and print out the results). Note also that after the rules are fired, we modify the status of the Customer "C" to "Done" - and then tell the engine. This causes it to evaluate and fire the rule that looks for "tickets" that are "Done" (in which is just logs a message).</para>
+
+ </section>
+
+ <section>
+ <title>Running it</title>
- <section>
- <title>Running it</title>
+ <para>Running the example (by launching the TroubleTicket.java class as an application) should yield the output:</para>
- <para>Running the example (by launching the TroubleTicket.java class as
- an application) should yield the output:</para>
-
- <programlisting>New : [Ticket [Customer D : Silver] : New]
+ <programlisting>New : [Ticket [Customer D : Silver] : New]
New : [Ticket [Customer C : Silver] : New]
New : [Ticket [Customer B : Platinum] : New]
New : [Ticket [Customer A : Gold] : New]
@@ -2005,192 +1585,132 @@
Email : [Ticket [Customer D : Silver] : Escalate]
[[ awake ]] </programlisting>
- <figure>
- <title>Audit log</title>
+ <figure>
+ <title>Audit log</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="tt_audit_firing.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="tt_audit_firing.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>Referring to the above audit log, we can see the events as they
- happen. Once the rules start firing, the first items are the "Activation
- Executed" for the new tickets, as expected (they do nothing, just log
- the fact). Note the "Activation executed" item for the platinum ticket -
- that is the next one to go (remember it has the default salience, so it
- happens after the "New ticket" rule, but otherwise it is immediate -
- there is no "duration" delay for it). The platinum activation results in
- a Object modification (which is the escalation) - this in turn creates
- an activation record for the "escalate ticket" rule - which is what we
- wanted. Straight after that it executes the action to escalate the
- ticket.</para>
+ <para>Referring to the above audit log, we can see the events as they happen. Once the rules start firing, the first items are the "Activation Executed" for the new tickets, as expected (they do nothing, just log the fact). Note the "Activation executed" item for the platinum ticket - that is the next one to go (remember it has the default salience, so it happens after the "New ticket" rule, but otherwise it is immediate - there is no "duration" delay for it). The platinum activation results in a Object modification (which is the escalation) - this in turn creates an activation record for the "escalate ticket" rule - which is what we wanted. Straight after that it executes the action to escalate the ticket.</para>
- <para>The next event to occur is due to the: <programlisting>t3.setStatus( "Done" );
+ <para>The next event to occur is due to the:</para>
+ <programlisting>t3.setStatus( "Done" );
session.update( ft3,
t3 );
-</programlisting> in the code (outside of rules) - this simulates a customer
- service officer maarking a ticket as done (and of course, uses the fact
- handle we kept from before). This results in a cancelled activation (as
- we no longer have a New Silvert customer ticket - it is done) and a new
- activation to log the fact it was done.</para>
+</programlisting>
+ <para>in the code (outside of rules) - this simulates a customer service officer maarking a ticket as done (and of course, uses the fact handle we kept from before). This results in a cancelled activation (as we no longer have a New Silvert customer ticket - it is done) and a new activation to log the fact it was done.</para>
- <para>In all the excitement, in parallel the engine has been watching
- the time pass, and it happens that the Gold tickets start to escalate,
- and then silver (as expected).</para>
- </section>
- </section>
+ <para>In all the excitement, in parallel the engine has been watching the time pass, and it happens that the Gold tickets start to escalate, and then silver (as expected).</para>
+
+ </section>
+ </section>
+
<!-- Trouble Ticket example -->
+
+ <section>
+ <title>Pricing Rule Decision Table Example</title>
- <section>
- <title>Pricing Rule Decision Table Example</title>
+ <para>The Pricing Rule decision table demonstrates the use of a decision table in a spreadsheet (XLS format) in calculating the retail cost of an insurance policy. The purpose of the set of rules provided is to calculate a base price, and an additional discount for a car driver applying for a specific policy. The drivers age, history and the policy type all contribute to what the basic premium is, and an additional chunk of rules deals with refining this with a subtractive percentage discount.</para>
- <para>The Pricing Rule decision table demonstrates the use of a decision
- table in a spreadsheet (XLS format) in calculating the retail cost of an
- insurance policy. The purpose of the set of rules provided is to calculate
- a base price, and an additional discount for a car driver applying for a
- specific policy. The drivers age, history and the policy type all
- contribute to what the basic premium is, and an additional chunk of rules
- deals with refining this with a subtractive percentage discount.</para>
-
- <programlisting><emphasis role="bold">Name:</emphasis> Example Policy Pricing
+ <programlisting><emphasis role="bold">Name:</emphasis> Example Policy Pricing
<emphasis role="bold">Main class:</emphasis> org.drools.examples.PricingRuleDTExample
<emphasis role="bold">Type:</emphasis> java application
<emphasis role="bold">Rules file:</emphasis> ExamplePolicyPricing.xls
<emphasis role="bold">Objective:</emphasis> demonstrate spreadsheet based decision tables. </programlisting>
- <section>
- <title>Executing the example</title>
+ <section>
+ <title>Executing the example</title>
- <para>Open the PricingRuleDTExample.java and execute it as a Java
- application. It should produce the following console output:</para>
+ <para>Open the PricingRuleDTExample.java and execute it as a Java application. It should produce the following console output:</para>
- <programlisting>Cheapest possible
+ <programlisting>Cheapest possible
BASE PRICE IS: 120
DISCOUNT IS: 20 </programlisting>
- <para>The code to the execute the example is very similar to the other
- examples. The rules are loaded, the facts inserted and a stateless
- session is used. What is different is how the rules are obtained:</para>
+ <para>The code to the execute the example is very similar to the other examples. The rules are loaded, the facts inserted and a stateless session is used. What is different is how the rules are obtained:</para>
- <programlisting>SpreadsheetCompiler compiler = new SpreadsheetCompiler();
+ <programlisting>SpreadsheetCompiler compiler = new SpreadsheetCompiler();
String drl = compiler.compile(getSpreadsheetStream(), InputType.XLS);
</programlisting>
- <para>Note the use of the SpreadsheetCompiler class. It is what takes
- the XLS (as a binary InputStream to the XLS file), and outputs ordinary
- DRL (which is then dealt with in the usual way). You can (if you like)
- also print out the DRL. If you use the BRMS, all this is of course taken
- care of for you.</para>
+ <para>Note the use of the SpreadsheetCompiler class. It is what takes the XLS (as a binary InputStream to the XLS file), and outputs ordinary DRL (which is then dealt with in the usual way). You can (if you like) also print out the DRL. If you use the BRMS, all this is of course taken care of for you.</para>
- <para>There are 2 facts used in this example, Driver, and Policy. Both
- are used with their default values. The Driver is 30 years old, has had
- no prior claims and currently has a risk profile of LOW. The Policy
- being applied for is COMPREHENSIVE, and the policy has not yet been
- approved.</para>
- </section>
+ <para>There are 2 facts used in this example, Driver, and Policy. Both are used with their default values. The Driver is 30 years old, has had no prior claims and currently has a risk profile of LOW. The Policy being applied for is COMPREHENSIVE, and the policy has not yet been approved.</para>
+ </section>
+
+ <section>
+ <title>The decision table</title>
- <section>
- <title>The decision table</title>
+ <para>In this decision table, each row is a rule, and each column is a condition or an action.</para>
- <para>In this decision table, each row is a rule, and each column is a
- condition or an action.</para>
+ <figure>
+ <title>Decision table configuration</title>
- <figure>
- <title>Decision table configuration</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="DT_Config.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="DT_Config.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <para>Referring to the above, we have the RuleSet declaration, which provides the package name. There are also other optional items you can have here, such as Variables for global variables, and Imports for importing classes. In this case, the namespace of the rules is the same as the fact classes we are using, so we can omit it.</para>
- <para>Referring to the above, we have the RuleSet declaration, which
- provides the package name. There are also other optional items you can
- have here, such as Variables for global variables, and Imports for
- importing classes. In this case, the namespace of the rules is the same
- as the fact classes we are using, so we can omit it.</para>
+ <para>Moving further down, we can see the RuleTable declaration. The name after this (Pricing bracket) is used as the prefix for all the generated rules. Below that, we have CONDITION or ACTION - this indicates the purpose of the column (ie does it form part of the condition, or an action of a rule that will be generated).</para>
- <para>Moving further down, we can see the RuleTable declaration. The
- name after this (Pricing bracket) is used as the prefix for all the
- generated rules. Below that, we have CONDITION or ACTION - this
- indicates the purpose of the column (ie does it form part of the
- condition, or an action of a rule that will be generated).</para>
+ <para>You can see there is a Driver which is spanned across 3 cells, this means the template expressions below it apply to that fact. So we look at the drivers age range (which uses $1 and $2 with comma separated values), locationRiskProfile, and priorClaims in the respective columns. In the action columns, we are setting the policy base price, and then logging a message.</para>
- <para>You can see there is a Driver which is spanned across 3 cells,
- this means the template expressions below it apply to that fact. So we
- look at the drivers age range (which uses $1 and $2 with comma separated
- values), locationRiskProfile, and priorClaims in the respective columns.
- In the action columns, we are setting the policy base price, and then
- logging a message.</para>
+ <figure>
+ <title>Base price calculation</title>
- <figure>
- <title>Base price calculation</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="DT_Table1.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="DT_Table1.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <para>Referring to the above, we can see there are broad category brackets (indicated by the comment in the left most column). As we know the details of our driver and their policy, we can tell (with a bit of thought) that they should match row number 18, as they have no prior accidents, and are 30 years old. This gives us a base price of 120.</para>
- <para>Referring to the above, we can see there are broad category
- brackets (indicated by the comment in the left most column). As we know
- the details of our driver and their policy, we can tell (with a bit of
- thought) that they should match row number 18, as they have no prior
- accidents, and are 30 years old. This gives us a base price of
- 120.</para>
+ <figure>
+ <title>Discount calculation</title>
- <figure>
- <title>Discount calculation</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="DT_Table2.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <mediaobject>
- <imageobject>
- <imagedata fileref="DT_Table2.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <para>Referring to the above, we are seeing if there is any discount we can give our driver. Based on the Age bracket, number of priot claims, and the policy type, a discount is provided. In our case, the drive is 3, with no priors, and they are applying for COMPREHENSIVE, this means we can give a discount of 20%. Note that this is actually a separate table, but in the same worksheet. This different templates apply.</para>
- <para>Referring to the above, we are seeing if there is any discount we
- can give our driver. Based on the Age bracket, number of priot claims,
- and the policy type, a discount is provided. In our case, the drive is
- 3, with no priors, and they are applying for COMPREHENSIVE, this means
- we can give a discount of 20%. Note that this is actually a separate
- table, but in the same worksheet. This different templates apply.</para>
+ <para>It is important to note that decision tables generate rules, this means they aren't simply top down logic, but more a means to capture data that generate rules (this is a subtle difference that confuses some people). The evaluation of the rules is not "top down" necessarily, all the normal indexing and mechanics of the rule engine still apply.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Shopping Example</title>
- <para>It is important to note that decision tables generate rules, this
- means they aren't simply top down logic, but more a means to capture
- data that generate rules (this is a subtle difference that confuses some
- people). The evaluation of the rules is not "top down" necessarily, all
- the normal indexing and mechanics of the rule engine still apply.</para>
- </section>
- </section>
-
- <section>
- <title>Shopping Example</title>
-
- <programlisting><emphasis role="bold">Name:</emphasis>Shopping Example
+ <programlisting><emphasis role="bold">Name:</emphasis>Shopping Example
<emphasis role="bold">Main class:</emphasis> org.drools.examples.ShoppingExample
<emphasis role="bold">Type:</emphasis> java application
<emphasis role="bold">Rules file:</emphasis> Shopping.drl
<emphasis role="bold">Objective:</emphasis> demonstrate truth maintenance, accumulate
</programlisting>
- <para>The shopping example simulates a very simple shopping cart type
- application, where the idea is to track a users purchases in a stateful
- session, and apply discounts as appropriate.</para>
+ <para>The shopping example simulates a very simple shopping cart type application, where the idea is to track a users purchases in a stateful session, and apply discounts as appropriate.</para>
+
+ <section>
+ <title>Running the example</title>
- <section>
- <title>Running the example</title>
+ <para>The following is a listing of the interesting parts that are used to launch the example:</para>
- <para>The following is a listing of the interesting parts that are used
- to launch the example:</para>
-
- <programlisting>Customer mark = new Customer( "mark",
+ <programlisting>Customer mark = new Customer( "mark",
0 );
session.insert( mark );
Product shoes = new Product( "shoes",
@@ -2208,31 +1728,25 @@
System.out.println( "Customer mark has returned the hat" );
session.fireAllRules(); </programlisting>
- <para>Refering the the above listing, we can see there is a Customer
- ("mark"), and there are 2 Products ("shoes" and "hat") which are
- available for Purchase. In this case, a Purchase combines a customer
- with a product (and a product has a price attribute).</para>
+ <para>Refering the the above listing, we can see there is a Customer ("mark"), and there are 2 Products ("shoes" and "hat") which are available for Purchase. In this case, a Purchase combines a customer with a product (and a product has a price attribute).</para>
- <para>Note that after we fireAllRules(), we then retract the purchase of
- a hat (but leave the purchase of shoes in). Running the example as a
- java application should see the following output:</para>
+ <para>Note that after we fireAllRules(), we then retract the purchase of a hat (but leave the purchase of shoes in). Running the example as a java application should see the following output:</para>
- <programlisting>Customer mark just purchased hat
+ <programlisting>Customer mark just purchased hat
Customer mark just purchased shoes
Customer mark now has a shopping total of 120.0
Customer mark now has a discount of 10
Customer mark has returned the hat
Customer mark now has a discount of 0 </programlisting>
- </section>
- <section>
- <title>Discounts and purchases</title>
+ </section>
- <para>We want to give discounts to customers who purchase stuff of
- enough value. This discount could also be removed should the customer
- decide not to purchase enough to fall within the threshold.</para>
+ <section>
+ <title>Discounts and purchases</title>
- <programlisting>rule "Purchase notification"
+ <para>We want to give discounts to customers who purchase stuff of enough value. This discount could also be removed should the customer decide not to purchase enough to fall within the threshold.</para>
+
+ <programlisting>rule "Purchase notification"
salience 10
when
@@ -2259,20 +1773,15 @@
System.out.println( "Customer " + $c.name + " now has a discount of " + $d.amount );
end </programlisting>
- <para>The "Purchase notification" rule simply makes note of the purchase
- event for a given customer. The "Discount removed notification" rule
- removes the customer discount (by checking for the non existence of a
- discount for that customer). The "Discount awarded notification" simply
- makes not of the fact that the discount was applied.</para>
- </section>
+ <para>The "Purchase notification" rule simply makes note of the purchase event for a given customer. The "Discount removed notification" rule removes the customer discount (by checking for the non existence of a discount for that customer). The "Discount awarded notification" simply makes not of the fact that the discount was applied.</para>
+ </section>
+
+ <section>
+ <title>Calculating the discount</title>
- <section>
- <title>Calculating the discount</title>
+ <para>Calculating the discount is done with a single rule, using the higher order logic of "accumulate".</para>
- <para>Calculating the discount is done with a single rule, using the
- higher order logic of "accumulate".</para>
-
- <programlisting>rule "Apply 10% discount if total purcahses is over 100"
+ <programlisting>rule "Apply 10% discount if total purcahses is over 100"
no-loop true
dialect "java"
when
@@ -2285,110 +1794,64 @@
System.out.println( "Customer " + $c.getName() + " now has a shopping total of " + $i );
end </programlisting>
- <para>An interesting part of this rule is the "accumulate": this is
- saying to accumulate a total (sum) of the $price of a product
- (product.price) for all Purchase facts that belong to the customer ($c).
- The result of this is a Double. The rule then checks to see if this
- total is greater then 100. If it is, it applies the discount (of 10),
- and then inserts a logical fact of the Discount object.</para>
+ <para>An interesting part of this rule is the "accumulate": this is saying to accumulate a total (sum) of the $price of a product (product.price) for all Purchase facts that belong to the customer ($c). The result of this is a Double. The rule then checks to see if this total is greater then 100. If it is, it applies the discount (of 10), and then inserts a logical fact of the Discount object.</para>
- <para>The purpose of the logical insertion of the Discount, is to
- automatically retract the Discount object should the total of the
- purchases not add up to > 100 (when the LHS is no longer satisified,
- restract the resulting logical assertions - this is what is meant by
- "truth maintenance"). The act of inserting the Discount, causes the
- "Discount awarded notification" rule to activate. However, should the
- discount fact be retracted, the "Discount removed notification" will
- activate, resulting in the customers discount being wiped out. In the
- example you can see this happen, as after the first fireAllRules(), a
- purchase is retracted, causing the total to fall below 100, which means
- the conditions that satisfied the "Apply 10% discount..." rule no longer
- apply, hence the logical fact of "Discount" is automatically
- retracted.</para>
- </section>
- </section>
+ <para>The purpose of the logical insertion of the Discount, is to automatically retract the Discount object should the total of the purchases not add up to > 100 (when the LHS is no longer satisified, restract the resulting logical assertions - this is what is meant by "truth maintenance"). The act of inserting the Discount, causes the "Discount awarded notification" rule to activate. However, should the discount fact be retracted, the "Discount removed notification" will activate, resulting in the customers discount being wiped out. In the example you can see this happen, as after the first fireAllRules(), a purchase is retracted, causing the total to fall below 100, which means the conditions that satisfied the "Apply 10% discount..." rule no longer apply, hence the logical fact of "Discount" is automatically retracted.</para>
+ </section>
+ </section>
- <section>
- <section>
- <title>Pet Store Example</title>
+ <section>
+ <title>Pet Store Example</title>
- <programlisting><emphasis role="bold">Name:</emphasis> Pet Store
+ <programlisting><emphasis role="bold">Name:</emphasis> Pet Store
<emphasis role="bold">Main class:</emphasis> org.drools.examples.PetStore
<emphasis role="bold">Type:</emphasis> Java application
<emphasis role="bold">Rules file:</emphasis> PetStore.drl
<emphasis role="bold">Objective:</emphasis> Demonstrate use of Agenda Groups, Global Variables and integration with a GUI (including callbacks from within the Rules)
</programlisting>
- <para>The Pet Store example shows how to integrate Rules with a GUI (in
- this case a Swing based Desktop application). Within the rules file, it
- shows how to use agenda groups and auto-focus to control which of a set
- of rules is allowed to fire at any given time. It also shows mixing of
- Java and MVEL dialects within the rules, the use of accumulate functions
- and calling of Java functions from within the ruleset.</para>
+ <para>The Pet Store example shows how to integrate Rules with a GUI (in this case a Swing based Desktop application). Within the rules file, it shows how to use agenda groups and auto-focus to control which of a set of rules is allowed to fire at any given time. It also shows mixing of Java and MVEL dialects within the rules, the use of accumulate functions and calling of Java functions from within the ruleset.</para>
- <para>Like the rest of the the samples, all the Java Code is contained
- in one file. The PetStore.java contains the following principal classes
- (in addition to several minor classes to handle Swing Events)</para>
+ <para>Like the rest of the the samples, all the Java Code is contained in one file. The PetStore.java contains the following principal classes (in addition to several minor classes to handle Swing Events)</para>
- <para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="italic"> Petstore</emphasis> - containing
- the main() method that we will look at shortly.</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="italic"> Petstore</emphasis> - containing the main() method that we will look at shortly.</para>
+ </listitem>
- <listitem>
- <para><emphasis role="italic">PetStoreUI</emphasis> - responsible
- for creating and displaying the Swing based GUI. It contains
- several smaller classes , mainly for responding to various GUI
- events such as mouse and button clicks.</para>
- </listitem>
+ <listitem>
+ <para><emphasis role="italic">PetStoreUI</emphasis> - responsible for creating and displaying the Swing based GUI. It contains several smaller classes , mainly for responding to various GUI events such as mouse and button clicks.</para>
+ </listitem>
- <listitem>
- <para><emphasis role="italic">TabelModel</emphasis> - for holding
- the table data. Think of it as a JavaBean that extends the Swing
- AbstractTableModel class.</para>
- </listitem>
+ <listitem>
+ <para><emphasis role="italic">TabelModel</emphasis> - for holding the table data. Think of it as a JavaBean that extends the Swing AbstractTableModel class.</para>
+ </listitem>
- <listitem>
- <para><emphasis role="italic">CheckoutCallback</emphasis> - Allows
- the GUI to interact with the Rules.</para>
- </listitem>
+ <listitem>
+ <para><emphasis role="italic">CheckoutCallback</emphasis> - Allows the GUI to interact with the Rules.</para>
+ </listitem>
- <listitem>
- <para><emphasis role="italic">Ordershow </emphasis> - the items
- that we wish to buy.</para>
- </listitem>
+ <listitem>
+ <para><emphasis role="italic">Ordershow </emphasis> - the items that we wish to buy.</para>
+ </listitem>
- <listitem>
- <para><emphasis role="italic">Purchase</emphasis> - Details of the
- order and the products we are buying.</para>
- </listitem>
+ <listitem>
+ <para><emphasis role="italic">Purchase</emphasis> - Details of the order and the products we are buying.</para>
+ </listitem>
- <listitem>
- <para><emphasis role="italic">Product</emphasis> - JavaBean
- holding details of the product available for purchase, and it's
- price.</para>
- </listitem>
- </itemizedlist>
- </para>
+ <listitem>
+ <para><emphasis role="italic">Product</emphasis> - JavaBean holding details of the product available for purchase, and it's price.</para>
+ </listitem>
+ </itemizedlist>
- <para>Much of the Java code is either JavaBeans (simple enough to
- understand) or Swing based. We will touch on some Swing related points
- in the this tutorial , but a good place to get more Swing component
- information is <ulink
- url="???"><uri>http://java.sun.com/docs/books/tutorial/uiswing/</uri>available
- at the Sun Swing website.<citebiblioid /></ulink></para>
+ <para>Much of the Java code is either JavaBeans (simple enough to understand) or Swing based. We will touch on some Swing related points in the this tutorial , but a good place to get more Swing component information is <ulink url="???"><uri>http://java.sun.com/docs/books/tutorial/uiswing/</uri> available at the Sun Swing website.<citebiblioid /></ulink></para>
- <para>There are two important Rules related pieces of Java code in
- <emphasis role="italic">Petstore.java</emphasis>.</para>
+ <para>There are two important Rules related pieces of Java code in <emphasis role="italic">Petstore.java</emphasis>.</para>
- <para>
- <example>
- <title>Creating the PetStore RuleBase - extract from PetStore.java
- main() method</title>
+ <example>
+ <title>Creating the PetStore RuleBase - extract from PetStore.java main() method</title>
- <programlisting>PackageBuilder builder = new PackageBuilder();
+ <programlisting>PackageBuilder builder = new PackageBuilder();
builder.addPackageFromDrl( new InputStreamReader(
PetStore.class.getResourceAsStream( "PetStore.drl" ) ) );
RuleBase ruleBase = RuleBaseFactory.newRuleBase();
@@ -2405,27 +1868,16 @@
PetStoreUI ui = new PetStoreUI( stock, new CheckoutCallback( ruleBase ) );
ui.createAndShowGUI();
</programlisting>
- </example>
- </para>
+ </example>
- <para>This code above loads the rules (drl) file from the classpath.
- Unlike other examples where the facts are asserted and fired straight
- away, this example defers this step to later. The way it does this is
- via the second last line where the PetStoreUI is created using a
- constructor the passes in the Vector called stock containing products ,
- and an instance of the CheckoutCallback class containing the RuleBase
- that we have just loaded.</para>
+ <para>This code above loads the rules (drl) file from the classpath. Unlike other examples where the facts are asserted and fired straight away, this example defers this step to later. The way it does this is via the second last line where the PetStoreUI is created using a constructor the passes in the Vector called stock containing products, and an instance of the CheckoutCallback class containing the RuleBase that we have just loaded.</para>
- <para>The actual Javacode that fires the rules is within the <emphasis
- role="italic">CheckoutCallBack.checkout()</emphasis> method. This is
- triggered (eventually) when the 'Checkout' button is pressed by the
- user.</para>
+ <para>The actual Javacode that fires the rules is within the <emphasis role="italic">CheckoutCallBack.checkout()</emphasis> method. This is triggered (eventually) when the 'Checkout' button is pressed by the user.</para>
- <example>
- <title>Firing the Rules - extract from the CheckOutCallBack.checkout()
- method</title>
+ <example>
+ <title>Firing the Rules - extract from the CheckOutCallBack.checkout() method</title>
- <programlisting>public String checkout(JFrame frame, List items) throws FactException {
+ <programlisting>public String checkout(JFrame frame, List items) throws FactException {
Order order = new Order();
//Iterate through list and add to cart
@@ -2450,49 +1902,23 @@
return order.toString();
}
</programlisting>
- </example>
+ </example>
- <para>Two items get passed into this method; A handle to the JFrame
- Swing Component surrounding the output text frame (bottom of the GUI if
- / when you run the component). The second item is a list of order items;
- this comes from the TableModel the stores the information from the
- 'Table' area at the top right section of the GUI.</para>
+ <para>Two items get passed into this method; A handle to the JFrame Swing Component surrounding the output text frame (bottom of the GUI if / when you run the component). The second item is a list of order items; this comes from the TableModel the stores the information from the 'Table' area at the top right section of the GUI.</para>
- <para>The <emphasis role="italic">for()</emphasis> loop transforms the
- list of order items coming from the GUI into the Order JavaBean (also
- contained in the PetStore.java file). Note that it would be possible to
- refer to the Swing dataset directly within the rules, but it is better
- coding practice to do it this way (using Simple Java Objects). It means
- that we are not tied to Swing if we wanted to transform the sample into
- a Web application.</para>
+ <para>The <emphasis role="italic">for()</emphasis> loop transforms the list of order items coming from the GUI into the Order JavaBean (also contained in the PetStore.java file). Note that it would be possible to refer to the Swing dataset directly within the rules, but it is better coding practice to do it this way (using Simple Java Objects). It means that we are not tied to Swing if we wanted to transform the sample into a Web application.</para>
- <para>It is important to note that <emphasis role="bold">all state in
- this example is stored in the Swing components, and that the rules are
- effectively stateless. </emphasis>Each time the 'Checkout' button is
- pressed, this code copies the contents of the Swing
- <emphasis>TableModel</emphasis> into the Session / Working
- Memory.</para>
+ <para>It is important to note that <emphasis role="bold">all state in this example is stored in the Swing components, and that the rules are effectively stateless. </emphasis>Each time the 'Checkout' button is pressed, this code copies the contents of the Swing <emphasis>TableModel</emphasis> into the Session / Working Memory.</para>
- <para>Within this code, there are nine calls to the working memory. The
- first of these creates a new workingMemory (statefulSession) from the
- Rulebase - remember that we passed in this Rulebase when we created the
- CheckoutCallBack class in the <emphasis role="italic">main()</emphasis>
- method. The next two calls pass in two objects that we will hold as Gl
- obal variables in the rules - the Swing text area and Swing frame that
- we will use for writing messages later.</para>
+ <para>Within this code, there are nine calls to the working memory. The first of these creates a new workingMemory (statefulSession) from the Rulebase - remember that we passed in this Rulebase when we created the CheckoutCallBack class in the <emphasis role="italic">main()</emphasis> method. The next two calls pass in two objects that we will hold as Global variables in the rules - the Swing text area and Swing frame that we will use for writing messages later.</para>
- <para>More inserts put information on products into the working memory,
- as well as the order list. The final call is the standard e <emphasis
- role="italic">fireAllRules()</emphasis>. Next, we look at what this
- method causes to happen within the Rules file.</para>
+ <para>More inserts put information on products into the working memory, as well as the order list. The final call is the standard <emphasis role="italic">fireAllRules()</emphasis>. Next, we look at what this method causes to happen within the Rules file.</para>
+
+ <example>
+ <title>Package, Imports , Globals and Dialect - extract (1) from PetStore.drl</title>
- <para>
- <example>
- <title>Package, Imports , Globals and Dialect - extract (1) from
- PetStore.drl</title>
+ <programlisting>package org.drools.examples
- <programlisting>package org.drools.examples
-
import org.drools.WorkingMemory
import org.drools.examples.PetStore.Order
import org.drools.examples.PetStore.Purchase
@@ -2507,32 +1933,16 @@
dialect "mvel"
</programlisting>
- </example>
- </para>
+ </example>
+
+ <para>The first part of the <emphasis role="italic">PetStore.drl</emphasis> file contains the standard package and import statement to make various Java classes available to the rules. We've seen the dialect been defaulted to "mvel" before in other examples. What is new are the two globals <emphasis>frame and textArea. </emphasis>These hold references to the Swing JFrame and Textarea components that were previous passed by the Java code calling the <emphasis>setGlobal() </emphasis>method. Unlike normal variables in Rules , which expire as soon as the rule has fired, Global variables retain their value for the lifetime of the (Stateful in this case) Session.</para>
- <para>The first part of the <emphasis
- role="italic">PetStore.drl</emphasis> file contains the standard package
- and import statement to make various Java classes available to the
- rules. We've seen the dialect been defaulted to "mvel" before in other
- examples. What is new are the two globals <emphasis>frame and textArea.
- </emphasis>These hold references to the Swing JFrame and Textarea
- components that were previous passed by the Java code calling the
- <emphasis>setGlobal() </emphasis>method. Unlike normal variables in
- Rules , which expire as soon as the rule has fired, Global variables
- retain their value for the lifetime of the (Stateful in this case)
- Session.</para>
+ <para>The next extract (below) is from the <emphasis role="bold">end</emphasis> of the PetStore.drl file. It contains two functions that are referenced by the rules that we will look at shortly.</para>
+
+ <example>
+ <title>Java Functions in the Rules - extract (2) from PetStore.drl</title>
- <para>The next extract (below) is from the <emphasis
- role="bold">end</emphasis> of the PetStore.drl file. It contains two
- functions that are referenced by the rules that we will look at
- shortly.</para>
-
- <para>
- <example>
- <title>Java Functions in the Rules - extract (2) from
- PetStore.drl</title>
-
- <programlisting>function void doCheckout(JFrame frame, WorkingMemory workingMemory) {
+ <programlisting>function void doCheckout(JFrame frame, WorkingMemory workingMemory) {
Object[] options = {"Yes",
"No"};
@@ -2577,42 +1987,29 @@
return true;
}
</programlisting>
- </example>
- </para>
+ </example>
+
- <para>Having these functions in the rules file makes the PetStore sample
- more compact - in real life you probably have the functions in a file of
- their own (within the same rules package), or as a static method on a
- standard Java class (and import them using the <emphasis
- role="bold">import function my.package.Foo.hello
- </emphasis>syntax).</para>
+ <para>Having these functions in the rules file makes the PetStore sample more compact - in real life you probably have the functions in a file of their own (within the same rules package), or as a static method on a standard Java class (and import them using the <emphasis role="bold">import function my.package.Foo.hello </emphasis>syntax).</para>
- <para>The above functions are</para>
+ <para>The above functions are</para>
- <para><itemizedlist>
- <listitem>
- <para><emphasis role="italic">doCheckout()</emphasis> - Displays a
- dialog asking the user if they wish to checkout. If they do, focus
- is set to the <emphasis role="italic">checkOut</emphasis>
- agenda-group, allowing rules in that group to (potentially)
- fire.</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="italic">doCheckout()</emphasis> - Displays a dialog asking the user if they wish to checkout. If they do, focus is set to the <emphasis role="italic">checkOut</emphasis> agenda-group, allowing rules in that group to (potentially) fire.</para>
+ </listitem>
- <listitem>
- <para><emphasis role="italic">requireTank()</emphasis> - Displays
- a dialog asking the user if they wish to buy a tank. If so, a new
- FishTank <emphasis role="italic">Product</emphasis> added to the
- orderlist in working memory.</para>
- </listitem>
- </itemizedlist>We'll see later the rules that call these functions.The
- next set of examples are from the PetStore rules themselves. The first
- extract is the one that happens to fire first (partly because it has the
- <emphasis role="italic">auto-focus</emphasis> attibute set to
- true).<example>
- <title>Putting each (individual) item into working memory - extract
- (3) from PetStore.drl</title>
+ <listitem>
+ <para><emphasis role="italic">requireTank()</emphasis> - Displays a dialog asking the user if they wish to buy a tank. If so, a new FishTank <emphasis role="italic">Product</emphasis> added to the orderlist in working memory.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>We'll see later the rules that call these functions.The next set of examples are from the PetStore rules themselves. The first extract is the one that happens to fire first (partly because it has the <emphasis role="italic">auto-focus</emphasis> attibute set to true).</para>
+
+ <example>
+ <title>Putting each (individual) item into working memory - extract (3) from PetStore.drl</title>
- <programlisting>// insert each item in the shopping cart into the Working Memory
+ <programlisting>// insert each item in the shopping cart into the Working Memory
rule "Explode Cart"
agenda-group "init"
auto-focus true
@@ -2628,51 +2025,30 @@
end
</programlisting>
- </example></para>
+ </example>
- <para>This rule matches against all orders that do not yet have an
- Order.grossTotal calculated . It loops for each purchase item in that
- order. Some of the <emphasis role="italic">Explode Cart</emphasis> Rule
- should be familiar ; the rule name, the salience (suggesting of the
- order that the rules should be fired in) and the dialect set to
- <emphasis role="italic">java</emphasis>. There are three new
- items:</para>
+ <para>This rule matches against all orders that do not yet have an Order.grossTotal calculated . It loops for each purchase item in that order. Some of the <emphasis role="italic">Explode Cart</emphasis> Rule should be familiar ; the rule name, the salience (suggesting of the order that the rules should be fired in) and the dialect set to <emphasis role="italic">java</emphasis>. There are three new items:</para>
- <para>
- <itemizedlist>
- <listitem>
- <para role="bold"><emphasis role="bold">agenda-group "init"
- </emphasis>- the name of the agenda group. In this case, there is
- only one rule in the group. However, nothing in Java code / nor a
- rule sets the focus to this group , so it relies on the next
- attibute for it's chance to fire.</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para role="bold"><emphasis role="bold">agenda-group "init" </emphasis>- the name of the agenda group. In this case, there is only one rule in the group. However, nothing in Java code / nor a rule sets the focus to this group , so it relies on the next attibute for it's chance to fire.</para>
+ </listitem>
- <listitem>
- <para><emphasis role="bold">auto-focus true - </emphasis>This is
- the only rule in the sample, so when <emphasis
- role="italic">fireAllRules()</emphasis> is called from within the
- Java code, this rule is the first to get a chance to fire.</para>
- </listitem>
+ <listitem>
+ <para><emphasis role="bold">auto-focus true - </emphasis>This is the only rule in the sample, so when <emphasis role="italic">fireAllRules()</emphasis> is called from within the Java code, this rule is the first to get a chance to fire.</para>
+ </listitem>
- <listitem>
- <para><emphasis role="bold">drools.setFocus() </emphasis>This sets
- the focus to the <emphasis role="italic">show items </emphasis>and
- <emphasis role="italic">evaluate</emphasis> agenda groups in turn
- , giving their rules a chance to fire. In practice , we loop
- through all items on the order, inserting them into memory, then
- firing the other rules after each insert.</para>
- </listitem>
- </itemizedlist>
- </para>
+ <listitem>
+ <para><emphasis role="bold">drools.setFocus() </emphasis>This sets the focus to the <emphasis role="italic">show items </emphasis>and <emphasis role="italic">evaluate</emphasis> agenda groups in turn , giving their rules a chance to fire. In practice , we loop through all items on the order, inserting them into memory, then firing the other rules after each insert.</para>
+ </listitem>
+ </itemizedlist>
- <para>The next two listings shows the rules within the <emphasis
- role="italic">show items </emphasis>and <emphasis
- role="italic">evaluate</emphasis> agenda groups. We look at them in the
- order that they are called.<example>
- <title>Show Items in the GUI extract (4) from PetStore.drl</title>
+ <para>The next two listings shows the rules within the <emphasis role="italic">show items </emphasis>and <emphasis role="italic">evaluate</emphasis> agenda groups. We look at them in the order that they are called.</para>
+
+ <example>
+ <title>Show Items in the GUI extract (4) from PetStore.drl</title>
- <programlisting>rule "Show Items"
+ <programlisting>rule "Show Items"
agenda-group "show items"
dialect "mvel"
when
@@ -2682,27 +2058,16 @@
textArea.append( $p.product + "\n");
end
</programlisting>
- </example></para>
+ </example>
- <para>The <emphasis role="italic">show items</emphasis> agenda-group has
- only one rule, also called <emphasis role="italic">Show Items</emphasis>
- (note the difference in case). For each purchase on the order currently
- in the working memory (session) it logs details to the text area (at the
- bottom of the GUI). The <emphasis role="italic">textArea</emphasis>
- variable used to do this is one of the Global Variables we looked at
- earlier.</para>
+ <para>The <emphasis role="italic">show items</emphasis> agenda-group has only one rule, also called <emphasis role="italic">Show Items</emphasis> (note the difference in case). For each purchase on the order currently in the working memory (session) it logs details to the text area (at the bottom of the GUI). The <emphasis role="italic">textArea</emphasis> variable used to do this is one of the Global Variables we looked at earlier.</para>
- <para>The <emphasis role="italic">evaluate</emphasis> Agenda group also
- gains focus from the <emphasis role="italic">explode cart
- </emphasis>rule above. This Agenda group has two rules (below) <emphasis
- role="italic">Free Fish Food Sample </emphasis> and <emphasis
- role="italic">Suggest Tank</emphasis>.</para>
+ <para>The <emphasis role="italic">evaluate</emphasis> Agenda group also gains focus from the <emphasis role="italic">explode cart </emphasis>rule above. This Agenda group has two rules (below) <emphasis role="italic">Free Fish Food Sample </emphasis> and <emphasis role="italic">Suggest Tank</emphasis>.</para>
- <para>
- <example>
- <title>Evaluate Agenda Group extract (5) from PetStore.drl</title>
+ <example>
+ <title>Evaluate Agenda Group extract (5) from PetStore.drl</title>
- <programlisting>// Free Fish Food sample when we buy a Gold Fish if we haven't already bought
+ <programlisting>// Free Fish Food sample when we buy a Gold Fish if we haven't already bought
// Fish Food and dont already have a Fish Food Sample
rule "Free Fish Food Sample"
agenda-group "evaluate"
@@ -2733,94 +2098,62 @@
requireTank(frame, drools.getWorkingMemory(), $order, $fishTank, $total);
end
</programlisting>
- </example>
- </para>
+ </example>
+
- <para>The <emphasis role="italic">Free Fish Food Sample</emphasis> rule
- will only fire if</para>
+ <para>The <emphasis role="italic">Free Fish Food Sample</emphasis> rule will only fire if</para>
- <para>
- <itemizedlist>
- <listitem>
- <para>We <emphasis role="italic">don't </emphasis>already have any
- fish food.</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>We <emphasis role="italic">don't </emphasis>already have any fish food.</para>
+ </listitem>
- <listitem>
- <para>We <emphasis role="italic">don't</emphasis> already have a
- free fish food sample.</para>
- </listitem>
+ <listitem>
+ <para>We <emphasis role="italic">don't</emphasis> already have a free fish food sample.</para>
+ </listitem>
- <listitem>
- <para>We <emphasis role="italic">do</emphasis> have a Gold Fish in
- our order.</para>
- </listitem>
- </itemizedlist>
- </para>
+ <listitem>
+ <para>We <emphasis role="italic">do</emphasis> have a Gold Fish in our order.</para>
+ </listitem>
+ </itemizedlist>
- <para>If the rule does fire, it creates a new product (Fish Food
- Sample), and adds it to the Order in working memory.</para>
+ <para>If the rule does fire, it creates a new product (Fish Food Sample), and adds it to the Order in working memory.</para>
- <para>The <emphasis role="italic">Suggest Tank</emphasis> rule will only
- fire if</para>
+ <para>The <emphasis role="italic">Suggest Tank</emphasis> rule will only fire if</para>
- <para>
- <itemizedlist>
- <listitem>
- <para>We <emphasis role="italic">don't </emphasis>already have a
- Fish Tank in our order</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>We <emphasis role="italic">don't </emphasis>already have a Fish Tank in our order</para>
+ </listitem>
- <listitem>
- <para>If we <emphasis role="italic">can</emphasis> find more than
- 5 Gold Fish Products in our order.</para>
- </listitem>
- </itemizedlist>
- </para>
+ <listitem>
+ <para>If we <emphasis role="italic">can</emphasis> find more than 5 Gold Fish Products in our order.</para>
+ </listitem>
+ </itemizedlist>
- <para>If the rule does fire, it calls the <emphasis
- role="italic">requireTank</emphasis>() function that we looked at
- earlier (showing a Dialog to the user, and adding a Tank to the order /
- working memory if confirmed). When calling the <emphasis
- role="italic">requireTank</emphasis>() function the rule passes the
- global <emphasis role="italic">frame</emphasis> variable so that the
- function has a handle to the Swing GUI.</para>
+ <para>If the rule does fire, it calls the <emphasis role="italic">requireTank</emphasis>() function that we looked at earlier (showing a Dialog to the user, and adding a Tank to the order / working memory if confirmed). When calling the <emphasis role="italic">requireTank</emphasis>() function the rule passes the global <emphasis role="italic">frame</emphasis> variable so that the function has a handle to the Swing GUI.</para>
- <para>The next rule we look at is <emphasis role="italic">do
- checkout.</emphasis><example>
- <title>Doing the Checkout - extract (6) from PetStore.drl</title>
+ <para>The next rule we look at is <emphasis role="italic">do checkout.</emphasis></para>
+
+ <example>
+ <title>Doing the Checkout - extract (6) from PetStore.drl</title>
- <programlisting>rule "do checkout"
+ <programlisting>rule "do checkout"
dialect "java"
when
then
doCheckout(frame, drools.getWorkingMemory());
end</programlisting>
- </example></para>
+ </example>
- <para>The <emphasis role="italic">do checkout</emphasis> rule has
- <emphasis role="bold">no agenda-group set and no auto-focus
- attribute</emphasis>. As such, is is deemed part of the default (MAIN)
- agenda-group - the same as the other non PetStore examples where agenda
- groups are not used. This group gets focus by default when all the
- rules/agenda-groups that explicity had focus set to them have run their
- course.</para>
+ <para>The <emphasis role="italic">do checkout</emphasis> rule has <emphasis role="bold">no agenda-group set and no auto-focus attribute</emphasis>. As such, is is deemed part of the default (MAIN) agenda-group - the same as the other non PetStore examples where agenda groups are not used. This group gets focus by default when all the rules/agenda-groups that explicity had focus set to them have run their course.</para>
- <para>There is no LHS to the rule, so the RHS will always call the
- <emphasis role="italic">doCheckout</emphasis>() function. When calling
- the <emphasis role="italic">doCheckout</emphasis>() function the rule
- passes the global <emphasis role="italic">frame</emphasis> variable so
- the function has a handle to the Swing GUI. As we saw earlier, the
- <emphasis role="italic">doCheckout</emphasis>() function shows a
- confirmation dialog to the user. If confirmed, the function sets the
- focus to the <emphasis role="italic">checkout</emphasis> agenda-group,
- allowing the next lot of rules to fire.</para>
+ <para>There is no LHS to the rule, so the RHS will always call the <emphasis role="italic">doCheckout</emphasis>() function. When calling the <emphasis role="italic">doCheckout</emphasis>() function the rule passes the global <emphasis role="italic">frame</emphasis> variable so the function has a handle to the Swing GUI. As we saw earlier, the <emphasis role="italic">doCheckout</emphasis>() function shows a confirmation dialog to the user. If confirmed, the function sets the focus to the <emphasis role="italic">checkout</emphasis> agenda-group, allowing the next lot of rules to fire.</para>
- <para>
- <example>
- <title>Checkout Rules- extract (7) from PetStore.drl</title>
+ <example>
+ <title>Checkout Rules- extract (7) from PetStore.drl</title>
- <programlisting>rule "Gross Total"
+ <programlisting>rule "Gross Total"
agenda-group "checkout"
dialect "mvel"
when
@@ -2853,206 +2186,135 @@
textArea.append( "discountedTotal total=" + $order.discountedTotal + "\n" );
end
</programlisting>
- </example>
- </para>
+ </example>
- <para>There are three rules in the <emphasis
- role="italic">checkout</emphasis> agenda-group</para>
+ <para>There are three rules in the <emphasis role="italic">checkout</emphasis> agenda-group</para>
- <para><itemizedlist>
- <listitem>
- <para><emphasis role="bold">Gross Total </emphasis> - if we
- haven't already calculated the gross total, accumulates the
- product prices into a total, puts this total into working memory,
- and displays it via the Swing TextArea (using the <emphasis
- role="italic">textArea </emphasis>global variable yet
- again).</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">Gross Total </emphasis> - if we haven't already calculated the gross total, accumulates the product prices into a total, puts this total into working memory, and displays it via the Swing TextArea (using the <emphasis role="italic">textArea </emphasis>global variable yet again).</para>
+ </listitem>
- <listitem>
- <para><emphasis role="bold">Apply 5% Discount</emphasis> - if our
- gross total is between 10 and 20, then calculate the discounted
- total and add it to working memory / display in the text
- area.</para>
- </listitem>
+ <listitem>
+ <para><emphasis role="bold">Apply 5% Discount</emphasis> - if our gross total is between 10 and 20, then calculate the discounted total and add it to working memory / display in the text area.</para>
+ </listitem>
- <listitem>
- <para><emphasis role="bold">Apply 10% Discount</emphasis> - if our
- gross total is equal to or greater than 20, calculate the
- discounted total and add it to working memory / display in the
- text area.</para>
- </listitem>
- </itemizedlist>Now we've run through what happens in the code, lets
- have a look at what happens when we run the code for real. The <emphasis
- role="italic">PetStore.java </emphasis>example contains a <emphasis
- role="italic">main()</emphasis> method, so it can be run as a standard
- Java application (either from the command line or via the IDE). This
- assumes you have your classpath set correctly (see the start of the
- examples section for more information).s.</para>
+ <listitem>
+ <para><emphasis role="bold">Apply 10% Discount</emphasis> - if our gross total is equal to or greater than 20, calculate the discounted total and add it to working memory / display in the text area.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Now we've run through what happens in the code, lets have a look at what happens when we run the code for real. The <emphasis role="italic">PetStore.java </emphasis>example contains a <emphasis role="italic">main()</emphasis> method, so it can be run as a standard Java application (either from the command line or via the IDE). This assumes you have your classpath set correctly (see the start of the examples section for more information).</para>
- <para>The first screen that we see is the Pet Store Demo. It has a List
- of available products (top left) , an empty list of selected products
- (top right), checkout and reset buttons (middle) and an empty system
- messages area (bottom).</para>
+ <para>The first screen that we see is the Pet Store Demo. It has a List of available products (top left) , an empty list of selected products (top right), checkout and reset buttons (middle) and an empty system messages area (bottom).</para>
- <para><figure>
- <title>Figure 1 - PetStore Demo just after Launch</title>
+ <figure>
+ <title>Figure 1 - PetStore Demo just after Launch</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="1-PetStore-Start-Screen.png" />
- </imageobject>
- </mediaobject>
- </figure>To get to this point, the following things have
- happened:</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="1-PetStore-Start-Screen.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>To get to this point, the following things have happened:</para>
- <para><orderedlist>
- <listitem>
- <para>The <emphasis role="italic">main()</emphasis> method has run
- and loaded the RuleBase <emphasis role="bold">but not yet fired
- the rules</emphasis>. This is the only rules related code to run
- so far.</para>
- </listitem>
+ <orderedlist>
+ <listitem>
+ <para>The <emphasis role="italic">main()</emphasis> method has run and loaded the RuleBase <emphasis role="bold">but not yet fired the rules</emphasis>. This is the only rules related code to run so far.</para>
+ </listitem>
- <listitem>
- <para>A new <emphasis role="italic">PetStoreUI</emphasis> class is
- created and given a handle to the RuleBase (for later use).</para>
- </listitem>
+ <listitem>
+ <para>A new <emphasis role="italic">PetStoreUI</emphasis> class is created and given a handle to the RuleBase (for later use).</para>
+ </listitem>
- <listitem>
- <para>Various Swing Components do their stuff, and the above
- screen is shown and <emphasis role="bold">waits for user
- input</emphasis>.</para>
- </listitem>
- </orderedlist>Clicking on various products from the list might give
- you a screen similar to the one below.</para>
+ <listitem>
+ <para>Various Swing Components do their stuff, and the above screen is shown and <emphasis role="bold">waits for user input</emphasis>.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Clicking on various products from the list might give you a screen similar to the one below.</para>
- <para><figure>
- <title>Figure 2 - PetStore Demo with Products Selected</title>
+ <figure>
+ <title>Figure 2 - PetStore Demo with Products Selected</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="2-stock-added-to-order-list.png" />
- </imageobject>
- </mediaobject>
- </figure>Note that <emphasis role="bold">no rules code has been fired
- here</emphasis>. This is only swing code, listening for the mouse click
- event, and added the clicked product to the
- <emphasis>TableModel</emphasis> object for display in the top right hand
- section (as an aside , this is a classic use of the Model View
- Controller - MVC - design pattern).</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="2-stock-added-to-order-list.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Note that <emphasis role="bold">no rules code has been fired here</emphasis>. This is only swing code, listening for the mouse click event, and added the clicked product to the <emphasis>TableModel</emphasis> object for display in the top right hand section (as an aside , this is a classic use of the Model View Controller - MVC - design pattern).</para>
- <para>It is only when we press the <emphasis
- role="bold">Checkout</emphasis> that we fire our business rules, in
- roughly the same order that we walked through the code earlier.</para>
+ <para>It is only when we press the <emphasis role="bold">Checkout</emphasis> that we fire our business rules, in roughly the same order that we walked through the code earlier.</para>
- <para>
- <orderedlist>
- <listitem>
- <para>The <emphasis
- role="italic">CheckOutCallBack.checkout()</emphasis> method is
- called (eventually) by the Swing class waiting for the click on
- the checkout button. This inserts the data from the
- <emphasis>TableModel</emphasis> object (top right hand side of the
- GUI), and handles from the GUI into the session / working memory.
- It then fires the rules.</para>
- </listitem>
+ <orderedlist>
+ <listitem>
+ <para>The <emphasis role="italic">CheckOutCallBack.checkout()</emphasis> method is called (eventually) by the Swing class waiting for the click on the checkout button. This inserts the data from the <emphasis>TableModel</emphasis> object (top right hand side of the GUI), and handles from the GUI into the session / working memory. It then fires the rules.</para>
+ </listitem>
- <listitem>
- <para>The <emphasis role="italic">Explode Cart</emphasis> rule is
- the first to fire, given that has <emphasis
- role="italic">auto-focus </emphasis>set to true. It loops through
- all the products in the cart, makes sure the products are in the
- working memory, then gives the <emphasis role="italic">Show
- Items</emphasis> and <emphasis role="italic">Evaluation</emphasis>
- agenda groups a chance to fire. The rules in these groups, add the
- contents of the cart to the text area (bottom), decide whether or
- not to give us free fish food and whether to ask if we want to buy
- a fish tank (Figure 3 below).</para>
- </listitem>
- </orderedlist>
+ <listitem>
+ <para>The <emphasis role="italic">Explode Cart</emphasis> rule is the first to fire, given that has <emphasis role="italic">auto-focus </emphasis>set to true. It loops through all the products in the cart, makes sure the products are in the working memory, then gives the <emphasis role="italic">Show Items</emphasis> and <emphasis role="italic">Evaluation</emphasis> agenda groups a chance to fire. The rules in these groups, add the contents of the cart to the text area (bottom), decide whether or not to give us free fish food and whether to ask if we want to buy a fish tank (Figure 3 below).</para>
+ </listitem>
+ </orderedlist>
- <figure>
- <title>Figure 3 - Do we want to buy a fish tank?</title>
+ <figure>
+ <title>Figure 3 - Do we want to buy a fish tank?</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="3-purchase-suggestion.png" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="3-purchase-suggestion.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <orderedlist>
- <listitem>
- <para>The <emphasis role="italic">Do Checkout</emphasis> rule is
- the next to fire as it (a) No other agenda group currently has
- focus and (b) it is part of the default (MAIN) agenda group. It
- always calls the<emphasis role="italic"> doCheckout() function
- </emphasis>which displays a 'Would you like to Checkout?' Dialog
- Box.</para>
- </listitem>
+ <orderedlist>
+ <listitem>
+ <para>The <emphasis role="italic">Do Checkout</emphasis> rule is the next to fire as it (a) No other agenda group currently has focus and (b) it is part of the default (MAIN) agenda group. It always calls the<emphasis role="italic"> doCheckout() function </emphasis>which displays a 'Would you like to Checkout?' Dialog Box.</para>
+ </listitem>
- <listitem>
- <para>The <emphasis role="italic">doCheckout() function</emphasis>
- sets the focus to the <emphasis role="italic">checkout
- </emphasis>agenda-group, giving the rules in that group the option
- to fire.</para>
- </listitem>
+ <listitem>
+ <para>The <emphasis role="italic">doCheckout() function</emphasis> sets the focus to the <emphasis role="italic">checkout </emphasis>agenda-group, giving the rules in that group the option to fire.</para>
+ </listitem>
- <listitem>
- <para>The rules in the the <emphasis
- role="italic">checkout</emphasis> agenda-group, display the
- contents of the cart and apply the appropriate discount.</para>
- </listitem>
+ <listitem>
+ <para>The rules in the the <emphasis role="italic">checkout</emphasis> agenda-group, display the contents of the cart and apply the appropriate discount.</para>
+ </listitem>
- <listitem>
- <para><emphasis role="bold">Swing then waits for user
- input</emphasis> to either checkout more products (and to cause
- the rules to fire again) or to close the GUI - Figure 4
- below.</para>
- </listitem>
- </orderedlist>
- </para>
+ <listitem>
+ <para><emphasis role="bold">Swing then waits for user input</emphasis> to either checkout more products (and to cause the rules to fire again) or to close the GUI - Figure 4 below.</para>
+ </listitem>
+ </orderedlist>
- <para>
- <figure>
- <title>Figure 4 - Petstore Demo after all rules have fired.</title>
+ <figure>
+ <title>Figure 4 - Petstore Demo after all rules have fired.</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="4-Petstore-final-screen.png" />
- </imageobject>
- </mediaobject>
- </figure>
- </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="4-Petstore-final-screen.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>Should we choose, we could add more System.out calls to
- demonstrate this flow of events. The current output of the console fo
- the above sample is as per the listing below.</para>
+ <para>Should we choose, we could add more System.out calls to demonstrate this flow of events. The current output of the console of the above sample is as per the listing below.</para>
+
+ <example>
+ <title>Console (System.out) from running the PetStore GUI</title>
- <para>
- <example>
- <title>Console (System.out) from running the PetStore GUI</title>
-
- <programlisting>Adding free Fish Food Sample to cart
+ <programlisting>Adding free Fish Food Sample to cart
SUGGESTION: Would you like to buy a tank for your 6 fish? - Yes</programlisting>
- </example>
- </para>
+ </example>
+
- <para>Todo : Add Audit and Agenda Views for this sample.</para>
- </section>
- </section>
+ <!---<para>Todo : Add Audit and Agenda Views for this sample.</para>-->
+ </section>
- <section>
- <title>Honest Politician Example</title>
+ <section>
+ <title>Honest Politician Example</title>
- <para>The honest politician example demonstrates truth maintenance with
- logical assertions, the basic premise is that an object can only exist
- while a statement is true. A rule's consequence can logical insert an
- object with the insertLogical method, this means the object will only
- remain in the working memory as long as the rule that logically inserted
- it remains true, when the rule is no longer true the object is
- automatically retracted.</para>
+ <para>The honest politician example demonstrates truth maintenance with logical assertions, the basic premise is that an object can only exist while a statement is true. A rule's consequence can logical insert an object with the insertLogical method, this means the object will only remain in the working memory as long as the rule that logically inserted it remains true, when the rule is no longer true the object is automatically retracted.</para>
<para>In this example there is Politician class with a name and a boolean
value for honest state, four politicians with honest state set to true are
@@ -3093,9 +2355,9 @@
I'm an evil corporation and I have corrupted blair
We are all Doomed!!! Democracy is Dead
</programlisting>
- </example>As soon as there is one ore more honest politcians in the
+ </example>As soon as there is one more more honest politcians in the
working memory a new Hope object is logically asserted, this object will
- only exist while there is atleast one or more honest politicians, the
+ only exist while there is at least one or more honest politicians, the
moment all politicians are dishonest then the Hope object will be
automatically retracted. This rule is given a salience of 10 to make sure
it fires before any other rules, as at this stage the "Hope is Dead" rule
@@ -3198,6 +2460,7 @@
currently selected blue highlighted area. Once Hope is retracted "Hope is
dead" activates and fires printing "We are all Doomed!!! Democracy is
Dead".</para>
+
</section>
<section>
@@ -3657,7 +2920,7 @@
</section>
</section>
- <section>
+
<section>
<title>Number Guess</title>
@@ -3694,7 +2957,7 @@
the addPackageFromDrl() method ) is the same as the previous examples.
There is a additional line to add the RuleFlow (NumberGuess.rfm) as you
have the option of specifying different ruleflows for the same RuleBase.
- Otherwise the RuleBase is created in the same manner as before .</para>
+ Otherwise the RuleBase is created in the same manner as before.</para>
<example>
<title>Starting the RuleFlow - extract 2 from NumberGuessExample.java
@@ -3864,7 +3127,7 @@
declares the dialect is set to MVEL, various Java classes are imported.
In total, there are five rules in this file:</para>
- <para><orderedlist>
+ <orderedlist>
<listitem>
<para>Get User Guess, the Rule we examined above.</para>
</listitem>
@@ -3886,7 +3149,9 @@
<para>A Rule that notifies the user that all guesses have been
used up.</para>
</listitem>
- </orderedlist>One point of integration between the standard Rules and
+ </orderedlist>
+
+ <para>One point of integration between the standard Rules and
the RuleFlow is via the 'ruleflow-group' attribute on the rules (as
dicussed above). A <emphasis role="bold">second point of integration
between the Rules File (drl) and the Rules Flow .rf files </emphasis>is
@@ -3961,7 +3226,7 @@
<para>A summary of what is happening in this sample is:</para>
- <para>
+
<orderedlist>
<listitem>
<para>Main() method of NumberGuessExample.java loads RuleBase,
@@ -4026,10 +3291,10 @@
correctly, or we run out of guesses.</para>
</listitem>
</orderedlist>
- </para>
+
</section>
- </section>
+
<section>
<title>Miss Manners and Benchmarking</title>
@@ -4054,10 +3319,6 @@
<title>Miss Manners' Guests</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" contentwidth="300"
- fileref="guests_at_table.svg" format="SVG" scalefit="1" />
- </imageobject>
<imageobject>
<imagedata align="center" fileref="guests_at_table.png"
@@ -4153,14 +3414,9 @@
<title>Manners Activity Diagram</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" contentwidth="400"
- fileref="manners_activity_diagram.svg" format="SVG"
- scalefit="1" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="manners_activity_diagram.png"
+ <imagedata align="center" fileref="manners_activity_diagram.png"
format="PNG" scalefit="1" />
</imageobject>
</mediaobject>
@@ -4215,7 +3471,7 @@
<para>Manners has been around a long time and is a contrived benchmark
meant to exercise the cross product joins and agenda, many people not
- understanding this tweak the example to achieve better perfmance,
+ understanding this tweak the example to achieve better performance,
making their use of the Manners benchmark pointless. Known cheats to
Miss Manners are:</para>
@@ -4458,13 +3714,9 @@
<title>Rete Diagram</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" contentdepth="500"
- fileref="make_path.svg" format="SVG" scalefit="1" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="make_path.png" format="PNG"
+ <imagedata align="center" fileref="make_path.png" format="PNG"
scalefit="1" />
</imageobject>
</mediaobject>
@@ -4692,7 +3944,7 @@
<mediaobject>
<imageobject>
- <imagedata fileref="conway1.jpg" />
+ <imagedata fileref="conway1.png" />
</imageobject>
</mediaobject>
</figure>
@@ -4742,7 +3994,7 @@
<mediaobject>
<imageobject>
- <imagedata fileref="conway2.jpg" />
+ <imagedata fileref="conway2.png" />
</imageobject>
</mediaobject>
</figure>
@@ -4823,7 +4075,7 @@
<mediaobject>
<imageobject>
- <imagedata fileref="conway_ruleflow_generation.png" />
+ <imagedata fileref="conway_ruleflow_generation.png" />
</imageobject>
</mediaobject>
</figure>
@@ -4964,84 +4216,58 @@
</example>
</section>
- <section>
- <title>Insurance Company Risk Factor and Policy price (using BRMS)</title>
+ <section>
+ <title>Insurance Company Risk Factor and Policy price (using BRMS)</title>
- <programlisting><emphasis role="bold">Name:</emphasis> drools-insurance
+ <screen><emphasis role="bold">Name:</emphasis> drools-insurance
<emphasis role="bold">Type:</emphasis> java web application
<emphasis role="bold">Rules file:</emphasis> exported repository from brms, repository_export.xml
-<emphasis role="bold">Objective:</emphasis> Demonstrates how to use, organize, deploy and execute a rulebase from BRMS</programlisting>
+<emphasis role="bold">Objective:</emphasis> Demonstrates how to use, organize, deploy and execute a rulebase from BRMS</screen>
- <section>
- <title>BRMS editors</title>
+ <section>
+ <title>BRMS editors</title>
- <para>The BRMS has many GUI editors, and textual editors. This discusses
- a few example rules using some of the GUI features:</para>
+ <para>The BRMS has many GUI editors, and textual editors. This discusses a few example rules using some of the GUI features:</para>
- <figure>
- <title>Guided editor</title>
+ <figure>
+ <title>Guided editor</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="BRMS_Guided.png" format="PNG"
- scalefit="2" />
- </imageobject>
- </mediaobject>
- </figure>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="BRMS_Guided.png" format="PNG" scalefit="2" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>The above example shows the guided editor in action. This is a
- slightly more complex example, as a few bound variables are used. We are
- binding "$driver" to the Driver fact, and also binding driverId to the
- id field of the driver (which is then used in the SupplementalInfo fact
- - to join the driverId with the actual driver id). Note the use of the
- ruleflow-group to specify what step of the processing this rule applies
- to.</para>
+ <para>The above example shows the guided editor in action. This is a slightly more complex example, as a few bound variables are used. We are binding "$driver" to the Driver fact, and also binding driverId to the id field of the driver (which is then used in the SupplementalInfo fact - to join the driverId with the actual driver id). Note the use of the ruleflow-group to specify what step of the processing this rule applies to.</para>
- <figure>
- <title>DSL Editor</title>
+ <figure>
+ <title>DSL Editor</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="BRMS_DSL.png" format="PNG" scalefit="2" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="BRMS_DSL.png" format="PNG"
- scalefit="2" />
- </imageobject>
- </mediaobject>
- </figure>
+ <para>The above shows the editor using a DSL. In this case the "guided editor" was used - this is not a text area, but only provides text boxes to "fill in the blanks" as specified in the DSL configuration. Note you can also use text based DSLs where there is not this restriction.</para>
+ </section>
- <para>The above shows the editor using a DSL. In this case the "guided
- editor" was used - this is not a text area, but only provides text boxes
- to "fill in the blanks" as specified in the DSL configuration. Note you
- can also use text based DSLs where there is not this restriction.</para>
- </section>
+ <section>
+ <title>Introduction</title>
- <section>
- <title>Introduction</title>
+ <para>Insurance, in law and economics, is a form of risk management primarily used to hedge against the risk of a contingent loss. Insurance is defined as the equitable transfer of the risk of a loss, from one entity to another, in exchange for a premium. Insurer, in economics, is the company that sells the insurance. Insurance rate is a factor used to determine the amount, called the premium, to be charged for a certain amount of insurance coverage. Risk management, the practice of appraising and controlling risk, has evolved as a discrete field of study and practice.</para>
+ </section>
- <para>Insurance, in law and economics, is a form of risk management
- primarily used to hedge against the risk of a contingent loss. Insurance
- is defined as the equitable transfer of the risk of a loss, from one
- entity to another, in exchange for a premium. Insurer, in economics, is
- the company that sells the insurance. Insurance rate is a factor used to
- determine the amount, called the premium, to be charged for a certain
- amount of insurance coverage. Risk management, the practice of
- appraising and controlling risk, has evolved as a discrete field of
- study and practice.</para>
- </section>
+ <section>
+ <title>The insurance logic</title>
- <section>
- <title>The insurance logic</title>
+ <para>If you have a poor driving record, you may need to look into high risk auto insurance. Accidents increase these rates as well. If you have a low experience for example less than 3 years as a licensed driver, insurance companies believe that the chances that you will be involved in a traffic accident are higher than someone more expert.</para>
- <para>If you have a poor driving record, you may need to look into high
- risk auto insurance. Accidents increase these rates as well. If you have
- a low experience for example less than 3 years as a licensed driver,
- insurance companies believe that the chances that you will be involved
- in a traffic accident are higher than someone more expert.</para>
-
- <para>Who you are also plays a factor. Men are considered more of a risk
- than women. Teens are considered more of a risk than adults as well if
- you have some younger driver in family like your 20 years old son.
- <programlisting>
-rule "Young male single driver"
+ <para>Who you are also plays a factor. Men are considered more of a risk than women. Teens are considered more of a risk than adults as well if you have some younger driver in family like your 20 years old son.</para>
+
+ <screen>rule "Young male single driver"
ruleflow-group "risk assessment"
when
$driver : Driver( genre == Driver.MALE, age < 25, maritalState == Driver.SINGLE )
@@ -5056,12 +4282,11 @@
then
$driver.updateInsuranceFactor(1.2);
end
-</programlisting></para>
+</screen>
- <para>Extra coverage over glasses, additional car and accessories, like
- your expansive "pimped" sound system will increase your insurance final
- price, not the risk factor. <programlisting>
-ruleflow-group "insurancecalcule"
+ <para>Extra coverage over glasses, additional car and accessories, like your expansive "pimped" sound system will increase your insurance final price, not the risk factor. </para>
+
+ <screen>ruleflow-group "insurancecalcule"
salience 20
when
not Rejection()
@@ -5073,16 +4298,11 @@
($access.getAlarmSystemValue() * 0.10) +
($access.getArmorValue() * 0.20) +
($access.getSoundSystemValue() * 0.30 ));
-</programlisting></para>
+</screen>
- <para>This example uses the previously explained <emphasis
- role="bold">RuleFlow</emphasis> feature, the following diagram gives you
- an overview of the insurance factor and calculate logic: As you can see,
- we first calculate the insurance factor, if the driver matches with some
- rejection condition we don't execute the group that contains the Policy
- price calculus, just returning and not approved policy <para>
- <programlisting>
-ruleflow-group "insurancecalcule"
+ <para>This example uses the previously explained <emphasis role="bold">RuleFlow</emphasis> feature, the following diagram gives you an overview of the insurance factor and calculate logic: As you can see, we first calculate the insurance factor, if the driver matches with some rejection condition we don't execute the group that contains the Policy price calculus, just returning and not approved policy </para>
+
+ <screen>ruleflow-group "insurancecalcule"
salience 10
when
not Rejection()
@@ -5090,90 +4310,70 @@
$policy : Policy( approved == true, bp : basePrice, ip : insurancePrice )
then
$policy.setInsurancePrice((bp * ifactor) + ip);
-</programlisting>
- </para></para>
+</screen>
- <para><figure>
- <title>The insurance rule flow</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="insurance-ruleflow.png"
- format="PNG" scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure></para>
- </section>
+ <figure>
+ <title>The insurance rule flow</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="insurance-ruleflow.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
- <section>
- <title>Downloading and installing the BRMS</title>
-
- <itemizedlist>
- <listitem>
- <para>Download the latest version of BRMS from
- http://cruisecontrol.jboss.com/cc/artifacts/jboss-rules</para>
- </listitem>
-
- <listitem>
- <para>Deploy BRMS WAR file into JBoss4.2 AS or JBossWeb, other
- containers can be used as well possibly with some tweaking of
- dependencies (check this url if you using a different application
- server
- http://wiki.jboss.org/wiki/Wiki.jsp?page=JBRMSjsfdependencies).</para>
- </listitem>
-
- <listitem>
- <para>Check you can access and run the BRMS.</para>
- </listitem>
-
- <listitem>
- <para>Check out the demo project from the Drools subversion
- repository
- http://anonsvn.labs.jboss.com/labs/jbossrules/trunk/drools-examples/drools-insurance/</para>
- </listitem>
-
- <listitem>
- <para>Import the demo business rules insurance repository file into
- BRMS, the compressed can be found at "files" folder in the demo
- project. To do this, open the "files" directory, unzip the file
- there locally, and then go to the "Admin" section and "Manage
- import/export" of the BRMS, select the file, and press "Import" -
- follow instructions.</para>
- </listitem>
-
- <listitem>
- <para>Navigate through the BRMS web application to see how things
- are placed and organized and try to create some rules.</para>
- </listitem>
-
- <listitem>
- <para>Go to the "Packages" feature and build the package (you should
- see no errors).</para>
- </listitem>
-
- <listitem>
- <para>Now go to the "Deployment" feature, when you click on the
- package, it will show you one snapshot (which was part of the
- import, you can create more if you like from the previous
- step).</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Deploying the insurance example in your application
- server</title>
-
- <itemizedlist>
- <listitem>
- <para>Go into your downloaded project and execute <programlisting>mvn clean package</programlisting></para>
- </listitem>
-
- <listitem>
- <para>You should see the RuleAgent downloadomg the pre-compiled
- package from brms, if something goes wrong and all tests fails,
- check if the BRMS is up and running and try rebuild the package
- snapshot. <programlisting>Running org.acme.insurance.test.DriverTest
+ <section>
+ <title>Downloading and installing the BRMS</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Download the latest version of BRMS from http://cruisecontrol.jboss.com/cc/artifacts/jboss-rules</para>
+ </listitem>
+
+ <listitem>
+ <para>Deploy BRMS WAR file into JBoss4.2 AS or JBossWeb, other containers can be used as well possibly with some tweaking of dependencies (check this url if you using a different application server http://wiki.jboss.org/wiki/Wiki.jsp?page=JBRMSjsfdependencies).</para>
+ </listitem>
+
+ <listitem>
+ <para>Check you can access and run the BRMS.</para>
+ </listitem>
+
+ <listitem>
+ <para>Check out the demo project from the Drools subversion repository http://anonsvn.labs.jboss.com/labs/jbossrules/trunk/drools-examples/drools-insurance/</para>
+ </listitem>
+
+ <listitem>
+ <para>Import the demo business rules insurance repository file into BRMS, the compressed can be found at "files" folder in the demo project. To do this, open the "files" directory, unzip the file there locally, and then go to the "Admin" section and "Manage import/export" of the BRMS, select the file, and press "Import" - follow instructions.</para>
+ </listitem>
+
+ <listitem>
+ <para>Navigate through the BRMS web application to see how things are placed and organized and try to create some rules.</para>
+ </listitem>
+
+ <listitem>
+ <para>Go to the "Packages" feature and build the package (you should see no errors).</para>
+ </listitem>
+
+ <listitem>
+ <para>Now go to the "Deployment" feature, when you click on the package, it will show you one snapshot (which was part of the import, you can create more if you like from the previous step).</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Deploying the insurance example in your application server</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Go into your downloaded project and execute <programlisting>mvn clean package</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para>You should see the RuleAgent downloadomg the pre-compiled package from brms, if something goes wrong and all tests fails, check if the BRMS is up and running and try rebuild the package snapshot.</para>
+
+ <screen>Running org.acme.insurance.test.DriverTest
RuleAgent(insuranceconfig) INFO (Wed Sep 18 14:11:44 BRT 2007): Configuring with newInstance=true, secondsToRefresh=30
RuleAgent(insuranceconfig) INFO (Wed Sep 18 14:11:44 BRT 2007): Configuring package provider : URLScanner monitoring URLs:
http://localhost:8080/drools-jbrms/org.drools.brms.JBRMS/package/org.acme.insurance.base/InsuranceDemo
@@ -5207,32 +4407,25 @@
Results :
Tests run: 16, Failures: 0, Errors: 0, Skipped: 0
-</programlisting></para>
- </listitem>
- </itemizedlist>
- </section>
+</screen>
+ </listitem>
+ </itemizedlist>
+ </section>
- <section>
- <title>Running the example from the web page</title>
-
- <para>After running and packing you are able to deploy the war into your
- application server, just following the previous instructions for BRMS,
- then point your browser to the example url, that should be something
- like this http://localhost:8080/drools-insurance. Just play around the
- example and change some values and press the execute button, after the
- rules fired the result will be displayed in the bottom of the
- page.</para>
-
- <para><figure>
- <title>The insurance web page</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="insurance-website.png"
- format="PNG" scalefit="2" />
- </imageobject>
- </mediaobject>
- </figure></para>
- </section>
- </section>
-</section>
\ No newline at end of file
+ <section>
+ <title>Running the example from the web page</title>
+
+ <para>After running and packing you are able to deploy the war into your application server, just following the previous instructions for BRMS, then point your browser to the example url, that should be something like this http://localhost:8080/drools-insurance. Just play around the example and change some values and press the execute button, after the rules fired the result will be displayed in the bottom of the page.</para>
+
+ <figure>
+ <title>The insurance web page</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="insurance-website.png" format="PNG" scalefit="2" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ </section>
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Rete_Algorithm.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Rete_Algorithm.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Rete_Algorithm.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Rete Algorithm</title>
@@ -23,12 +25,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="Rete_Nodes.svg" format="SVG" />
+ <imagedata align="center" fileref="Rete_Nodes.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="Rete_Nodes.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
@@ -53,12 +51,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="Object_Type_Nodes.svg" format="SVG" />
+ <imagedata align="center" fileref="Object_Type_Nodes.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="Object_Type_Nodes.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
@@ -77,12 +71,9 @@
<title>AlphaNodes</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="Alpha_Nodes.svg" format="SVG" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="Alpha_Nodes.png" format="PNG" />
+ <imagedata align="center" fileref="Alpha_Nodes.png" format="PNG" />
</imageobject>
</mediaobject>
</figure>
@@ -100,7 +91,7 @@
fields, to each other. The objects may be the same or different types. By
convention we refer to the two inputs as left and right. The left input for
a BetaNode is generally a list of objects; in Drools this is a Tuple. The
- right input is a single object. Two Nots can be used to implement 'exists'
+ right input is a single object. Two Nodes can be used to implement 'exists'
checks. BetaNodes also have memory. The left input is called the Beta Memory
and remembers all incoming tuples. The right input is called the Alpha
Memory and remembers all incoming objects. Drools extends Rete by
@@ -117,12 +108,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="Join_Node.svg" format="SVG" />
+ <imagedata align="center" fileref="Join_Node.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="Join_Node.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
@@ -173,13 +160,10 @@
<title>Node Sharing</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="Node_Sharing.svg" format="SVG" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="Node_Sharing.png" format="PNG" />
+ <imagedata align="center" fileref="Node_Sharing.png" format="PNG" />
</imageobject>
</mediaobject>
</figure>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Rules.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Rules.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Rules.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Knowledge Representation</title>
@@ -237,12 +239,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="Male_People.svg" format="SVG" />
+ <imagedata align="center" fileref="Male_People.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="Male_People.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
@@ -275,7 +273,7 @@
<programlisting>
- Person( eyeColour == "blue"|| == "green" )
+ Person( eyeColour == "blue"||"green" )
</programlisting>
@@ -375,4 +373,4 @@
<para></para>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>The Drools Rule Engine</title>
@@ -22,12 +24,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="Authoring.svg" format="SVG" />
+ <imagedata align="center" fileref="Authoring.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="Authoring.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
@@ -46,12 +44,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="Runtime.svg" format="SVG" />
+ <imagedata align="center" fileref="Runtime.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="Runtime.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
</section>
@@ -64,24 +58,20 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="PackageBuilder.svg" format="SVG" />
+ <imagedata align="center" fileref="PackageBuilder.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="PackageBuilder.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
<para>Four classes are used for authoring: DrlParser, XmlParser,
ProcessBuilder and PackageBuilder. The two parser classes produce "descr"
(description) AST models from a provided Reader instance. ProcessBuilder
- reads in an xstream serialisation representation of the Rule Flow.
+ reads in an xstream serialization representation of the Rule Flow.
PackageBuilder provides convienience APIs so that you can mostly forget
about those classes. The three convenience methods are
"addPackageFromDrl", "addPackageFromXml" and addRuleFlow - all take an
instance of Reader as an argument. The example below shows how to build a
- package that includes both XML, DRL and rule files and a ruleflow file,
+ package that includes both XML and DRL rule files and a ruleflow file,
which are in the classpath. Note that all added package sources must be of
the same package namespace for the current PackageBuilder instance!</para>
@@ -117,13 +107,9 @@
<title>PackageBuilderConfiguration</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="PackageBuilderConfiguration.svg"
- format="SVG" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="PackageBuilderConfiguration.png"
+ <imagedata align="center" fileref="PackageBuilderConfiguration.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -140,11 +126,11 @@
droosl-compiler jar has the default settings in its META-INF
directory.</para>
- <para>Currently the PackageBulderConfiguration handles the registry of
+ <para>Currently the PackageBuilderConfiguration handles the registry of
Accumulate functions, registry of Dialects and the main
ClassLoader.</para>
- <para>Drools has a pluggeable Dialect system, which allows other languages
+ <para>Drools has a pluggable Dialect system, which allows other languages
to compile and execution expressions and blocks, the two currently
supported dialects are Java and MVEL. Each has its own
DialectConfiguration Implementation; the javadocs provide details for each
@@ -155,12 +141,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="JavaDialectConfiguration.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="JavaDialectConfiguration.png"
+ <imagedata align="center" fileref="JavaDialectConfiguration.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -228,12 +209,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="JavaDialectConfiguration.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="MVELDialectConfiguration.png"
+ <imagedata align="center" fileref="MVELDialectConfiguration.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -248,12 +224,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="RuleBaseFactory.svg" format="SVG" />
+ <imagedata align="center" fileref="RuleBaseFactory.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="RuleBaseFactory.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
@@ -274,12 +246,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="RuleBase.svg" format="SVG" />
+ <imagedata align="center" fileref="RuleBase.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="RuleBase.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
@@ -335,12 +303,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="RuleBaseConfiguration.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="RuleBaseConfiguration.png"
+ <imagedata align="center" fileref="RuleBaseConfiguration.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -355,12 +318,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="StatefulSession.svg" format="SVG" />
+ <imagedata align="center" fileref="WorkingMemory.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="WorkingMemory.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
@@ -422,7 +381,7 @@
<para>Equality means the Working Memory uses a HashMap to store all
asserted Objects. New instance assertions will only return a new
- FactHandle if a no equal classes have been asserted.</para>
+ FactHandle if a not equal classes have been asserted.</para>
</section>
<section>
@@ -454,7 +413,7 @@
parameter - this allows you to specify new instances for immutable
objects. The update() method can only be used with objects that have
shadow proxies turned on. If you do not use shadow proxies then you must
- call session.modifyRestract() before making your changes and
+ call session.modifyRetract() before making your changes and
session.modifyInsert() after the changes.</para>
<programlisting>Cheese stilton = new Cheese("stilton");
@@ -479,7 +438,7 @@
<para>With the Rule Base now aware of the global identifier and its type
any sessions are now able to call session.setGlobal; failure to declare
the global type and identifier first will result in an exception being
- thrown. to set the global on the session use
+ thrown. To set the global on the session use
session.setGlobal(identifier, value);</para>
<programlisting>List list = new ArrayList();
@@ -517,14 +476,14 @@
notify the rule engine.</para>
<para>Drools 4.0 has full support for Shadow Facts implemented as
- transparent lazy proxies. Shadow facts are enable by default and are not
+ transparent lazy proxies. Shadow facts are enabled by default and are not
visible from external code, not even inside code blocks on rules.</para>
<para>Although shadow facts are a great way of ensuring the engine
integrity, they add some overhead to the the reasoning process. As so,
Drools 4.0 supports fine grained control over them with the ability to
enable/disable them for each individual class. To disable shadow fact
- for all classes set the following property in a configuration file of
+ for all classes set the following property in a configuration file or
system property:</para>
<programlisting>drools.shadowProxy = false</programlisting>
@@ -621,18 +580,14 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="WorkingMemory.svg" format="SVG" />
+ <imagedata align="center" fileref="StatefulSession.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="StatefulSession.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
<para>The StatefulSession extends the WorkingMemory class. It simply adds
async methods and a dispose() method. The ruleBase retains a reference to
- each StatefulSession is creates, so that it can update them when new rules
+ each StatefulSession it creates, so that it can update them when new rules
are added, dispose() is needed to release the StatefulSession reference
from the RuleBase, without it you can get memory leaks.</para>
@@ -650,13 +605,9 @@
<title>StatelessSession</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="StatelessSession.svg"
- format="SVG" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="StatelessSession.png"
+ <imagedata align="center" fileref="StatelessSession.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -672,7 +623,7 @@
session.execute( new Cheese( "cheddar" ) );</programlisting>
</example>
- <para>The api is reduced for the problem domain and is thus much simpler;
+ <para>The API is reduced for the problem domain and is thus much simpler;
which in turn can make maintenance of those services easier. The RuleBase
never retains a reference to the StatelessSession, thus dispose() is not
needed, and they only have an execute() method that takes an object, an
@@ -696,20 +647,16 @@
environments such as JEE.</para>
<para>StatelessSessions also support sequential mode, which is a special
- optimised mode that uses less memory and executes faster; please see the
+ optimized mode that uses less memory and executes faster; please see the
Sequential section for more details.</para>
<figure>
<title>StatelessSessionResult</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="StatelessSessionResult.svg"
- format="SVG" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="StatelessSessionResult.png"
+ <imagedata align="center" fileref="StatelessSessionResult.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -717,9 +664,9 @@
<para>StatelessSession.executeWithResults(....) returns a minimal api to
examine the sessions data. The inserted Objects can be iterated over,
- querries can be executed and globals retrieved. Once the
- StatelessSessionResult is serialised it loses the reference to the
- underlying WorkingMemory and RuleBase, so querries can no longer be
+ queries can be executed and globals retrieved. Once the
+ StatelessSessionResult is serialized it loses the reference to the
+ underlying WorkingMemory and RuleBase, so queries can no longer be
executed, however globals can still be retrieved and objects iterated. To
retrieve globals they must be exported from the StatelessSession; the
GlobalExporter strategy is set with StatelessSession.setGlobalExporter(
@@ -728,11 +675,11 @@
CopyIdentifiersGlobalExporter copies named identifiers into a new
GlobalResovler that is passed to the StatelessSessionResult; the
constructor takes a String[] array of identifiers, if no identifiers are
- specified it copies all identifiers declaredin the RuleBase.
+ specified it copies all identifiers declared in the RuleBase.
ReferenceOriginalGlobalExporter just passes a reference to the original
- Global Resolver; the later should be used with care as identifier
+ Global Resolver; the latter should be used with care as identifier
instances can be changed at any time by the StatelessSession and the
- GlobalResolver may not be serialisable freindly.</para>
+ GlobalResolver may not be serializable freindly.</para>
<example>
<title>GlobalExporter with StatelessSessions</title>
@@ -752,12 +699,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="Agenda.svg" format="SVG" />
+ <imagedata align="center" fileref="Agenda.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="Agenda.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
@@ -792,12 +735,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="Two_Phase.svg" format="SVG" />
+ <imagedata align="center" fileref="Two_Phase.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="Two_Phase.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
@@ -814,13 +753,13 @@
instance, firing ruleA may cause ruleB to be removed from the
agenda).</para>
- <para>The default conflict resolution strategies emplyed by Drools are:
+ <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
user can specify that a certain rule has a higher priority (by giving it
- a higher number) then other rules. In that case, the higher salience
- rule will always be preferred. LIFO priorities based on the assigned
+ a higher number) than other rules. In that case, the higher salience
+ rule will always be preferred. LIFO priorities are based on the assigned
Working Memory Action counter value, multiple rules created from the
same action have the same value - execution of these are considered
arbitrary.</para>
@@ -846,7 +785,7 @@
<para>They are sometimes known as "modules" in CLIPS terminology. Agenda
groups are a handy way to create a "flow" between grouped rules. You can
switch the group which has focus either from within the rule engine, or
- from the API. If you rules have a clear need for multiple "phases" or
+ from the API. If your rules have a clear need for multiple "phases" or
"sequences" of processing, consider using agenda-groups for this
purpose.</para>
@@ -866,16 +805,12 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="AgendaFilter.svg" format="SVG" />
+ <imagedata align="center" fileref="AgendaFilter.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="AgendaFilter.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
- <para>Filters are optional implementations of a the filter interface
+ <para>Filters are optional implementations of the filter interface
which are used to allow/or deny an activation from firing (what you
filter on, is entirely up to the implementation). Drools provides the
following convenience default implementations</para>
@@ -914,8 +849,8 @@
<para>In a regular insert, you need to explicitly retract a fact. With
logical assertions, the fact that was asserted will be automatically
retracted when the conditions that asserted it in the first place are no
- longer true (it's actually more clever then that! If there are no possible
- conditions that could support the logical assertion, only then will it be
+ longer true. (It's actually more clever then that! If there are no possible
+ conditions that could support the logical assertion, only then it will be
retracted).</para>
<para>Normal insertions are said to be “STATED” (ie The Fact has been
@@ -946,12 +881,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="Stated_Assertion.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="Stated_Assertion.png"
+ <imagedata align="center" fileref="Stated_Assertion.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -962,12 +892,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="Logical_Assertion.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="Logical_Assertion.png"
+ <imagedata align="center" fileref="Logical_Assertion.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -1044,12 +969,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="WorkingMemoryEventListener.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="WorkingMemoryEventListener.png"
+ <imagedata align="center" fileref="WorkingMemoryEventListener.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -1060,12 +980,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="AgendaEventListener.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="AgendaEventListener.png"
+ <imagedata align="center" fileref="AgendaEventListener.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -1076,18 +991,13 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="RuleFlowEventListener.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="RuleFlowEventListener.png"
+ <imagedata align="center" fileref="RuleFlowEventListener.png"
format="PNG" />
</imageobject>
</mediaobject>
</figure>
- <para>Both stateful and statless sessions implement the EventManager
+ <para>Both stateful and stateless sessions implement the EventManager
interface, which allows event listeners to be added to the session.</para>
<figure>
@@ -1095,12 +1005,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="EventManager.svg" format="SVG" />
+ <imagedata align="center" fileref="EventManager.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="EventManager.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
@@ -1221,10 +1127,10 @@
probably not of an advantage and an Object list can be used.</para>
<para>Sequential mode can only be used with a StatelessSession and is off
- by default. To turn on either set the RuleBaseConfiguration.setSequentail
+ by default. To turn on either set the RuleBaseConfiguration.setSequential
to true or set the rulebase.conf property drools.sequential to true.
Sequential mode can fallback to a dynamic agenda with setSequentialAgenda
to either SequentialAgenda.SEQUENTIAL or SequentialAgenda.DYNAMIC setter
or the "drools.sequential.agenda" property</para>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-What_is_a_Rule_Engine.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-What_is_a_Rule_Engine.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-What_is_a_Rule_Engine.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>What is a Rule Engine?</title>
@@ -97,7 +99,7 @@
<para>Drools implements and extends the <indexterm>
<primary>Rete</primary>
- </indexterm> Rete algorith, <indexterm>
+ </indexterm> Rete algorithm, <indexterm>
<primary>Leaps</primary>
</indexterm> Leaps use to be supported but was removed due to poor
maintenance. The Drools <indexterm>
@@ -130,17 +132,13 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="Rule_Engine.svg" format="SVG" />
+ <imagedata align="center" fileref="Rule_Engine.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="Rule_Engine.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
<para>A Production Rule System's Inference Engine is stateful and able to
- enforce truthfulness - called Truth Maintence. A logical relationship can
+ enforce truthfulness - called Truth Maintenance. A logical relationship can
be declared by actions which means the action's state depends on the
inference remaining true; when it is no longer true the logical dependent
action is undone. The "Honest Politician" is an example of Truth
@@ -168,7 +166,7 @@
Forward Chaining and Backward Chaining; systems that implement both are
called Hybrid Production Rule Systems. Understanding these two modes of
operation are key to understanding why a Production Rule System is
- different and how to get the best from them. Forward chaing is
+ different and how to get the best from them. Forward chaining is
'data-driven' and thus reactionary - facts are asserted into the working
memory which results in one or more rules being concurrently true and
scheduled for execution by the Agenda - we start with a fact, it
@@ -180,12 +178,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="Forward_Chaining.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="Forward_Chaining.png"
+ <imagedata align="center" fileref="Forward_Chaining.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -204,15 +197,10 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="Backward_Chaining.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="Backward_Chaining.png"
+ <imagedata align="center" fileref="Backward_Chaining.png"
format="PNG" />
</imageobject>
</mediaobject>
</figure>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Why_use_a_Rule_Engine.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Why_use_a_Rule_Engine.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Engine/Section-Why_use_a_Rule_Engine.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Why use a Rule Engine?</title>
@@ -100,11 +102,11 @@
<listitem>
<para>Understandable Rules</para>
- <para>By creating object models and optionally Domain Specific
+ <para>By creating object models and, optionally, Domain Specific
Languages that model your problem domain you can set yourself up to
- write rules that look very close to natural language. They lend
+ write rules that are very close to natural language. They lend
themselves to logic that is understandable to, possibly nontechnical,
- domain experts as they are expressed in their language. (as all the
+ domain experts as they are expressed in their language (as all the
program plumbing, the "How", is in the usual code, hidden
away).</para>
</listitem>
@@ -119,7 +121,7 @@
answer, some more explanation is required. The reason why there is no
"traditional" approach is possibly one of the following: <itemizedlist>
<listitem>
- <para>The problem is just too fiddly for traditional code.</para>
+ <para>The problem is just too fiddle for traditional code.</para>
<para>The problem may not be complex, but you can't see a
non-fragile way of building it.</para>
@@ -239,11 +241,11 @@
<para>Many people have also implemented data-driven systems successfully
in the past (where there are control tables that store meta-data that
- changes your applications behavior) - these can work well when the control
- can remain very limited. However, they can quickly grow out of control if
- extended to much (such that only the original creators can change the
- applications behavior) or they cause the application to stagnate as they
- are too inflexible.</para>
+ changes your applications behavior) - these can work well when the
+ control can remain very limited. However, they can quickly grow out of
+ control if extended to much (such that only the original creators can
+ change the applications behavior) or they cause the application to
+ stagnate as they are too inflexible.</para>
</section>
<section>
@@ -266,4 +268,4 @@
removed and added without requiring changes to other rules that are
unrelated.</para>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Comments.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Comments.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Comments.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Comments</title>
@@ -18,12 +20,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="single_line_comment.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="single_line_comment.png"
+ <imagedata align="center" fileref="single_line_comment.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -53,12 +50,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="multi_line_comment.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="multi_line_comment.png"
+ <imagedata align="center" fileref="multi_line_comment.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -77,4 +69,4 @@
in the right hand side of a rule */
end </programlisting>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-DSL.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-DSL.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-DSL.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Domain Specific Languages</title>
@@ -186,6 +188,7 @@
can do things like:</para>
<example>
+ <title>Chaining DSL Expressions</title>
<programlisting>There is a person called Bob who is happy
Or
There is a person called Mike who is sad
@@ -384,4 +387,4 @@
either need to use the drools-ant task, or otherwise use the code shown in
sections above.</para>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Function.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Function.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Function.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Function</title>
@@ -11,12 +13,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="function.svg" format="SVG" role="" />
+ <imagedata align="center" fileref="function.png" format="PNG" role="" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="function.png" format="PNG" role="" />
- </imageobject>
</mediaobject>
</figure>
@@ -59,4 +57,4 @@
System.out.println( hello( "Bob" ) );
end
</programlisting>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Overview.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Overview.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Overview.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Overview</title>
@@ -275,4 +277,4 @@
<para>Of course, you can have words as part of a method name in camel
case, like notSomething() - there are no issues with that scenario.</para>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Package.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Package.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Package.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Package</title>
@@ -33,12 +35,9 @@
<title>package</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="package.svg" format="SVG" role="" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="package.png" format="PNG" role="" />
+ <imagedata align="center" fileref="package.png" format="PNG" role="" />
</imageobject>
</mediaobject>
</figure>
@@ -50,12 +49,9 @@
<title>import</title>
<mediaobject>
- <imageobject>
- <imagedata fileref="import.svg" format="SVG" />
- </imageobject>
<imageobject>
- <imagedata fileref="import.png" format="PNG" />
+ <imagedata fileref="import.png" format="PNG" />
</imageobject>
</mediaobject>
</figure>
@@ -73,12 +69,9 @@
<title>expander</title>
<mediaobject>
- <imageobject>
- <imagedata fileref="expander.svg" format="SVG" />
- </imageobject>
<imageobject>
- <imagedata fileref="expander.png" format="PNG" />
+ <imagedata fileref="expander.png" format="PNG" />
</imageobject>
</mediaobject>
</figure>
@@ -100,12 +93,9 @@
<title>global</title>
<mediaobject>
- <imageobject>
- <imagedata fileref="global.svg" format="SVG" />
- </imageobject>
<imageobject>
- <imagedata fileref="global.png" format="PNG" />
+ <imagedata fileref="global.png" format="PNG" />
</imageobject>
</mediaobject>
</figure>
@@ -179,4 +169,4 @@
inside your rules. We recommend to you always set the value from your
application using the working memory interface.</para>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Query.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Query.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Query.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Query</title>
@@ -7,12 +9,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="query.svg" format="SVG" role="" />
+ <imagedata align="center" fileref="query.png" format="PNG" role="" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="query.png" format="PNG" role="" />
- </imageobject>
</mediaobject>
</figure>
@@ -67,4 +65,4 @@
System.out.println( person.getName() + "\n" );
}</programlisting>
</example>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Rule.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Rule.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Rule.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Rule</title>
@@ -6,13 +8,9 @@
<title>rule</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="rule.svg" format="SVG" role="" />
+ <imageobject>
+ <imagedata align="center" fileref="rule.png" format="PNG" role="" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="rule.png" format="PNG" role="" />
- </imageobject>
</mediaobject>
</figure>
@@ -82,154 +80,141 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="rule_attributes.svg" format="SVG" />
+ <imagedata align="center" fileref="rule_attributes.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="rule_attributes.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
- <section>
- <title>no-loop</title>
+ <variablelist>
+ <varlistentry>
+ <term>no-loop</term>
+
+ <listitem>
+ <para>default value : false</para>
+
+ <para>type : Boolean</para>
+
+ <para>When the Rule's consequence modifies a fact it may cause the Rule to activate again, causing recursion. Setting no-loop to true means the attempt to create the Activation for the current set of data will be ignored.</para>
+ </listitem>
+
+ </varlistentry>
+
+ <varlistentry>
+ <term>lock-on-active</term>
+
+ <listitem>
+ <para>default value : false</para>
+
+ <para>type : Boolean</para>
+
+ <para>when a ruleflow-group becomes active or an agenda-group receives the focus any rules that ahve lock-on-active set to try cannot place activations onto the agenda, the rules are matched and the resulting activations discarded. This is a stronger version of no-loop. It's ideally for calculation rules where you have a number of rules that will modify a fact and you don't want any rule re-matching and firing. In summary fire these currently active rules and only these rules, no matter how the data changes, do not allow any more activations for the rules with the attribute set to true. When the ruleflow-group is no longer active or agenda-group loses the focus those rules with lock-on-active set to true can once again add activations onto the agenda.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>salience</term>
+
+ <listitem>
+ <para>default value : 0</para>
+
+ <para>type : integer</para>
+
+ <para>Each rule has a salience attribute that can be assigned an Integer number, defaults to zero, the Integer and can be negative or positive. Salience is a form of priority where rules with higher salience values are given higher priority when ordered in the Activation queue.</para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term>agenda-group</term>
+
+ <listitem>
+ <para>default value : MAIN</para>
+
+ <para>type : String</para>
+
+ <para>Agenda group's allow the user to partition the Agenda providing more execution control. Only rules in the focus group are allowed to fire.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>auto-focus</term>
+
+ <listitem>
+ <para>default value false</para>
+
+ <para>type : Boolean</para>
+
+ <para>When a rule is activated if the <literal>auto-focus value is true and the Rule's </literal> <literal>agenda-group</literal> does not have focus then it is given focus, allowing the rule to potentially fire.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>activation-group</term>
+
+ <listitem>
+ <para>default value : N/A</para>
+
+ <para>type : String</para>
+
+ <para>Rules that belong to the same named activation-group will only fire exclusively. In other words, the first rule in an activation-group to fire will cancel the other rules activations (stop them from firing). The Activation group attribute is any string, as long as the string is identical for all the rules you need to be in the one group.</para>
+
+ <para>NOTE: this used to be called Xor group, but technically its not quite an Xor, but you may hear people mention Xor group, just swap that term in your mind with activation-group.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>dialect</term>
+
+ <listitem>
+ <para>default value : as specified by the package</para>
+
+ <para>type : String</para>
+
+ <para>possible values: "java" or "mvel"</para>
+
+ <para>The dialect species the language to be used for any code
+ expressions in the LHS or the RHS code block. Currently two dialects are available, Java and MVEL. While the dialect can be specified at the package level, this attribute allows the package definition to be overridden.</para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term>date-effective</term>
+
+ <listitem>
+ <para>default value : N/A</para>
+
+ <para>type : String, which contains a Date/Time definition</para>
+
+ <para>A rule can only activate if the current date and time is after date-effective attribute.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>date-exptires</term>
+
+ <listitem>
+ <para>default value : N/A</para>
+
+ <para>type : String, which contains a Date/Time definition</para>
+
+ <para>A rule cannot activate if the current date and time is after date-expires attribute.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>duration</term>
+
+ <listitem>
+ <para>default value : no default value</para>
+
+ <para>type : long</para>
+
+ <para>The duration dictates that the rule will fire after a specified duration, if it is still true.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
- <para>default value : false</para>
-
- <para>type : Boolean</para>
-
- <para>When the Rule's consequence modifies a fact it may cause the Rule
- to activate again, causing recursion. Setting no-loop to true means the
- attempt to create the Activation for the current set of data will be
- ignored.</para>
- </section>
-
- <section>
- <title>lock-on-active</title>
-
- <para>default value : false</para>
-
- <para>type : Boolean</para>
-
- <para>when a ruleflow-group becomes active or an agenda-group receives
- the focus any rules that ahve lock-on-active set to try cannot place
- activations onto the agenda, the rules are matched and the resulting
- activations discarded. This is a stronger version of no-loop. It's
- idealy for calculation rules where you have a number of rules that will
- modify a fact and you don't want any rule re-matching and firing. In
- summary fire these currently active rules and only these rules, no
- matter how the data changes, do not allow any more activations for the
- rules with the attribute set to true. When the ruleflow-group is no
- longer active or agenda-group loses the focus those rules with
- lock-on-active set to true can once again add activations onto the
- agenda.</para>
- </section>
-
- <section>
- <title>salience</title>
-
- <para>default value : 0</para>
-
- <para>type : integer</para>
-
- <para>Each rule has a salience attribute that can be assigned an Integer
- number, defaults to zero, the Integer and can be negative or positive.
- Salience is a form of priority where rules with higher salience values
- are given higher priority when ordered in the Activation queue.</para>
- </section>
-
- <section>
- <title>agenda-group</title>
-
- <para>default value : MAIN</para>
-
- <para>type : String</para>
-
- <para>Agenda group's allow the user to partition the Agenda providing
- more execution control. Only rules in the focus group are allowed to
- fire.</para>
- </section>
-
- <section>
- <title>auto-focus</title>
-
- <para>default value false</para>
-
- <para>type : Boolean</para>
-
- <para>When a rule is activated if the <literal>auto-focus value is true
- and the Rule's </literal> <literal>agenda-group</literal> does not have
- focus then it is given focus, allowing the rule to potentially
- fire.</para>
- </section>
-
- <section>
- <title>activation-group</title>
-
- <para>default value : N/A</para>
-
- <para>type : String</para>
-
- <para>Rules that belong to the same named activation-group will only
- fire exclusively. In other words, the first rule in an activation-group
- to fire will cancel the other rules activations (stop them from firing).
- The Activation group attribute is any string, as long as the string is
- identical for all the rules you need to be in the one group.</para>
-
- <para>NOTE: this used to be called Xor group, but technically its not
- quite an Xor, but you may hear people mention Xor group, just swap that
- term in your mind with activation-group.</para>
- </section>
-
- <section>
- <title>dialect</title>
-
- <para>default value : as specified by the package</para>
-
- <para>type : String</para>
-
- <para>possible values: "java" or "mvel"</para>
-
- <para>The dialect species the language to be used for any code
- expressions in the LHS or the RHS code block. Currently two dialects are
- available, Java and MVEL. While the dialect can be specified at the
- package level, this attribute allows the package definition to be
- overridden.</para>
- </section>
-
- <section>
- <title>date-effective</title>
-
- <para>default value : N/A</para>
-
- <para>type : String, which contains a Date/Time definition</para>
-
- <para>A rule can only activate if the current date and time is after
- date-effective attribute.</para>
- </section>
-
- <section>
- <title>date-exptires</title>
-
- <para>default value : N/A</para>
-
- <para>type : String, which contains a Date/Time definition</para>
-
- <para>A rule cannot activate if the current date and time is after
- date-expires attribute.</para>
- </section>
-
- <section>
- <title>duration</title>
-
- <para>default value : no default value</para>
-
- <para>type : long</para>
-
- <para>The duration dictates that the rule will fire after a specified
- duration, if it is still true.</para>
- </section>
-
<example>
<title>Some attribute examples</title>
@@ -255,12 +240,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="lhs.svg" format="SVG" role="" />
+ <imagedata align="center" fileref="lhs.png" format="PNG" role="" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="lhs.png" format="PNG" role="" />
- </imageobject>
</mediaobject>
</figure>
@@ -305,14 +286,9 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="patternER.svg" format="SVG"
+ <imagedata align="center" fileref="patternER.png" format="PNG"
role="" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="patternER.png" format="PNG"
- role="" />
- </imageobject>
</mediaobject>
</figure>
@@ -325,14 +301,9 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="pattern.svg" format="SVG"
+ <imagedata align="center" fileref="pattern.png" format="PNG"
role="" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="pattern.png" format="PNG"
- role="" />
- </imageobject>
</mediaobject>
</figure>
@@ -367,14 +338,9 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="constraints.svg" format="SVG"
+ <imagedata align="center" fileref="constraints.png" format="PNG"
role="" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="constraints.png" format="PNG"
- role="" />
- </imageobject>
</mediaobject>
</figure>
@@ -383,14 +349,9 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="constraint.svg" format="SVG"
+ <imagedata align="center" fileref="constraint.png" format="PNG"
role="" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="constraint.png" format="PNG"
- role="" />
- </imageobject>
</mediaobject>
</figure>
@@ -398,13 +359,9 @@
<title>Group Constraint</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="constraintGroup.svg"
- format="SVG" role="" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="constraintGroup.png"
+ <imagedata align="center" fileref="constraintGroup.png"
format="PNG" role="" />
</imageobject>
</mediaobject>
@@ -496,13 +453,9 @@
<title>fieldConstraint</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="fieldConstraint.svg"
- format="SVG" role="" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="fieldConstraint.png"
+ <imagedata align="center" fileref="fieldConstraint.png"
format="PNG" role="" />
</imageobject>
</mediaobject>
@@ -515,13 +468,9 @@
<title>restriction</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="restriction.svg" format="SVG"
- role="" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="restriction.png" format="PNG"
+ <imagedata align="center" fileref="restriction.png" format="PNG"
role="" />
</imageobject>
</mediaobject>
@@ -563,12 +512,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="literal.svg" format="SVG" />
+ <imagedata align="center" fileref="literal.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="literal.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
@@ -577,12 +522,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="qualifiedIdentifier.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="qualifiedIdentifier.png"
+ <imagedata align="center" fileref="qualifiedIdentifier.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -592,13 +532,9 @@
<title>variable</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="identifier.svg"
- format="SVG" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="identifier.png"
+ <imagedata align="center" fileref="identifier.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -609,12 +545,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="returnValue.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="returnValue.png"
+ <imagedata align="center" fileref="returnValue.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -639,12 +570,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="singleValueRestriction.svg"
- format="SVG" role="" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="singleValueRestriction.png"
+ <imagedata align="center" fileref="singleValueRestriction.png"
format="PNG" role="" />
</imageobject>
</mediaobject>
@@ -658,12 +584,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="operator.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="operator.png"
+ <imagedata align="center" fileref="operator.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -817,12 +738,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="literalRestriction.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="literalRestriction.png"
+ <imagedata align="center" fileref="literalRestriction.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -908,13 +824,9 @@
<title>variableRestriction</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="variableRestriction.svg"
- format="SVG" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="variableRestriction.png"
+ <imagedata align="center" fileref="variableRestriction.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -964,13 +876,8 @@
<mediaobject>
<imageobject>
<imagedata align="center"
- fileref="returnValueRestriction.svg" format="SVG" />
+ fileref="returnValueRestriction.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center"
- fileref="returnValueRestriction.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
@@ -1009,15 +916,9 @@
<mediaobject>
<imageobject>
<imagedata align="center"
- fileref="compoundValueRestriction.svg" format="SVG"
+ fileref="compoundValueRestriction.png" format="PNG"
role="" />
</imageobject>
-
- <imageobject>
- <imagedata align="center"
- fileref="compoundValueRestriction.png" format="PNG"
- role="" />
- </imageobject>
</mediaobject>
</figure>
@@ -1045,12 +946,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="multiRestriction.svg"
- format="SVG" role="" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="multiRestriction.png"
+ <imagedata align="center" fileref="multiRestriction.png"
format="PNG" role="" />
</imageobject>
</mediaobject>
@@ -1061,12 +957,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="restrictionGroup.svg"
- format="SVG" role="" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="restrictionGroup.png"
+ <imagedata align="center" fileref="restrictionGroup.png"
format="PNG" role="" />
</imageobject>
</mediaobject>
@@ -1092,12 +983,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="inlineEvalConstraint.svg"
- format="SVG" />
- </imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="inlineEvalConstraint.png"
+ <imagedata align="center" fileref="inlineEvalConstraint.png"
format="PNG" />
</imageobject>
</mediaobject>
@@ -1178,14 +1064,9 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="prefixAnd.svg" format="SVG"
+ <imagedata align="center" fileref="prefixAnd.png" format="PNG"
role="" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="prefixAnd.png" format="PNG"
- role="" />
- </imageobject>
</mediaobject>
</figure>
@@ -1217,14 +1098,9 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="infixAnd.svg" format="SVG"
+ <imagedata align="center" fileref="infixAnd.png" format="PNG"
role="" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="infixAnd.png" format="PNG"
- role="" />
- </imageobject>
</mediaobject>
</figure>
@@ -1257,14 +1133,9 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="orPrefix.svg" format="SVG"
+ <imagedata align="center" fileref="prefixOr.png" format="PNG"
role="" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="prefixOr.png" format="PNG"
- role="" />
- </imageobject>
</mediaobject>
</figure>
@@ -1286,14 +1157,9 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="infixOr.svg" format="SVG"
+ <imagedata align="center" fileref="infixOr.png" format="PNG"
role="" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="infixOr.png" format="PNG"
- role="" />
- </imageobject>
</mediaobject>
</figure>
@@ -1340,12 +1206,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="eval.svg" format="SVG" role="" />
+ <imagedata align="center" fileref="eval.png" format="PNG" role="" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="eval.png" format="PNG" role="" />
- </imageobject>
</mediaobject>
</figure>
@@ -1383,12 +1245,9 @@
<title>not</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="not.svg" format="SVG" role="" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="not.png" format="PNG" role="" />
+ <imagedata align="center" fileref="not.png" format="PNG" role="" />
</imageobject>
</mediaobject>
</figure>
@@ -1424,12 +1283,9 @@
<title>exists</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="exists.svg" format="SVG" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="exists.png" format="PNG" />
+ <imagedata align="center" fileref="exists.png" format="PNG" />
</imageobject>
</mediaobject>
</figure>
@@ -1468,12 +1324,9 @@
<title>forall</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="forall.svg" format="SVG" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="forall.png" format="PNG" />
+ <imagedata align="center" fileref="forall.png" format="PNG" />
</imageobject>
</mediaobject>
</figure>
@@ -1567,12 +1420,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="from.svg" format="SVG" />
+ <imagedata align="center" fileref="from.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="from.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
@@ -1647,12 +1496,9 @@
<title>collect</title>
<mediaobject>
- <imageobject>
- <imagedata align="center" fileref="collect.svg" format="SVG" />
- </imageobject>
<imageobject>
- <imagedata align="center" fileref="collect.png" format="PNG" />
+ <imagedata align="center" fileref="collect.png" format="PNG" />
</imageobject>
</mediaobject>
</figure>
@@ -1725,12 +1571,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="accumulate.svg" format="SVG" />
+ <imagedata align="center" fileref="accumulate.png" format="PNG" />
</imageobject>
-
- <imageobject>
- <imagedata align="center" fileref="accumulate.png" format="PNG" />
- </imageobject>
</mediaobject>
</figure>
@@ -2095,4 +1937,4 @@
values into a comparable format; so a primitive is comparable to an object
wrapper.</para>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-RuleFlow.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-RuleFlow.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-RuleFlow.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Rule Flow</title>
@@ -7,7 +9,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="RuleFlow.png" format="PNG" role="" />
+ <imagedata align="center" fileref="RuleFlow.png" format="PNG" role="" />
</imageobject>
</mediaobject>
</figure>
@@ -56,7 +58,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="RuleFlowSimple.png" format="PNG"
+ <imagedata align="center" fileref="RuleFlowSimple.png" format="PNG"
role="" />
</imageobject>
</mediaobject>
@@ -88,7 +90,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="RFNewWizard.png" format="PNG"
+ <imagedata align="center" fileref="RFNewWizard.png" format="PNG"
role="" />
</imageobject>
</mediaobject>
@@ -109,7 +111,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="RFNameGroups.png" format="PNG"
+ <imagedata align="center" fileref="RFNameGroups.png" format="PNG"
role="" />
</imageobject>
</mediaobject>
@@ -129,7 +131,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="RFGroupProperties.png"
+ <imagedata align="center" fileref="RFGroupProperties.png"
format="PNG" role="" />
</imageobject>
</mediaobject>
@@ -157,7 +159,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="RFComplex.png" format="PNG"
+ <imagedata align="center" fileref="RFComplex.png" format="PNG"
role="" />
</imageobject>
</mediaobject>
@@ -182,7 +184,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="RFSplitType.png" format="PNG"
+ <imagedata align="center" fileref="RFSplitType.png" format="PNG"
role="" />
</imageobject>
</mediaobject>
@@ -206,7 +208,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="RFEditConstraints.png"
+ <imagedata align="center" fileref="RFEditConstraints.png"
format="PNG" role="" />
</imageobject>
</mediaobject>
@@ -221,7 +223,7 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="RFConstraintEditor.png"
+ <imagedata align="center" fileref="RFConstraintEditor.png"
format="PNG" role="" />
</imageobject>
</mediaobject>
@@ -293,7 +295,7 @@
<title>The different types of ruleflow nodes</title>
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="ruleflow_nodes.png" format="PNG" role="" />
+ <imagedata align="center" fileref="ruleflow_nodes.png" format="PNG" role="" />
</imageobject>
</mediaobject>
</figure>
@@ -355,4 +357,4 @@
</para>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-XML.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-XML.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-XML.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>XML Rule Language</title>
@@ -319,8 +321,10 @@
</programlisting> Using combinations of the above, you can convert between any
format (including round trip). Note that DSLs will not be preserved (from
DRLs that are using a DSL) - but they will be able to be converted.</para>
+
+<para>Feel free to make use of XSLT to provide all sorts of possibilities
+ for XML, XSLT and its ilk are what make XML powerful.</para>
+
</section>
- <para>Feel free to make use of XSLT to provide all sorts of possibilities
- for XML, XSLT and its ilk are what make XML powerful.</para>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Local_Search_Solver.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Local_Search_Solver.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Local_Search_Solver.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Local search solver</title>
@@ -32,9 +34,9 @@
<para>An algorithm that checks every possible solution (even with pruning)
can easily run for a couple of years on a single real-life planning
- problem. Most of the time, we 're happy with a feasible solution found in
+ problem. Most of the time, we are happy with a feasible solution found in
a limited amount of time. Local search tends to find a feasible solution
- relatively fast. Because it acts very much like a human, it's also pretty
+ relatively fast. Because it acts very much like a human, it is also pretty
natural to program.</para>
<para>Local search solves a problem making a move on the current solution
@@ -79,10 +81,6 @@
<mediaobject>
<imageobject>
- <imagedata fileref="singleMoveNQueens04.svg" format="SVG" />
- </imageobject>
-
- <imageobject>
<imagedata fileref="singleMoveNQueens04.png" format="PNG" />
</imageobject>
</mediaobject>
@@ -272,10 +270,6 @@
<mediaobject>
<imageobject>
- <imagedata fileref="possibleMovesNQueens04.svg" format="SVG" />
- </imageobject>
-
- <imageobject>
<imagedata fileref="possibleMovesNQueens04.png" format="PNG" />
</imageobject>
</mediaobject>
@@ -340,10 +334,6 @@
<mediaobject>
<imageobject>
- <imagedata fileref="decideNextStepNQueens04.svg" format="SVG" />
- </imageobject>
-
- <imageobject>
<imagedata fileref="decideNextStepNQueens04.png" format="PNG" />
</imageobject>
</mediaobject>
@@ -365,10 +355,6 @@
<mediaobject>
<imageobject>
- <imagedata fileref="allStepsNQueens04.svg" format="SVG" />
- </imageobject>
-
- <imageobject>
<imagedata fileref="allStepsNQueens04.png" format="PNG" />
</imageobject>
</mediaobject>
@@ -414,12 +400,6 @@
<para>Notice that the logging used the <literal>toString()</literal>
method from our <literal>Move</literal> implementation: <literal>[Queen-1]
1 @ 0 => 3</literal>.</para>
-
- <para>The local search solver solves the 4 queens problem in 3 steps, by
- evaluating only 37 possible solutions (3 steps with 12 moves each + 1
- starting solution), which is only fraction of all 256 possible solutions.
- It solves 16 queens in 31 steps, by evaluating only 7441 out of
- 18446744073709551616 possible solutions.</para>
</section>
<section>
@@ -480,10 +460,6 @@
<mediaobject>
<imageobject>
- <imagedata fileref="decideNextStepNQueens04.svg" format="SVG" />
- </imageobject>
-
- <imageobject>
<imagedata fileref="decideNextStepNQueens04.png" format="PNG" />
</imageobject>
</mediaobject>
@@ -673,10 +649,6 @@
<para>Generates a random number for each accepted move and if it's
below the move's accept chance, it picks it as the next move.</para>
-
- <programlisting> <forager>
- <foragerType>FIRST_RANDOMLY_ACCEPTED</foragerType>
- </forager></programlisting>
</section>
</section>
</section>
@@ -722,12 +694,6 @@
<programlisting> <finish>
<maximumHouresSpend>1</maximumHouresSpend>
</finish></programlisting>
-
- <para>Notice that if you use this finish, you will most likely sacrifice
- reproducability. The best solution will depend on real-time process
- speed, not only because it influences the amount of steps taken, but
- also because time gradient based algoritms (such as simulated annealing)
- will probably act differently on each run.</para>
</section>
<section>
@@ -795,4 +761,4 @@
before finishing.</para>
</section>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Score_calculation.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Score_calculation.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Score_calculation.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Score calculation with a rule engine</title>
@@ -18,11 +20,11 @@
line</title>
<programlisting>rule "multipleQueensHorizontal"
- when
- $q1 : Queen($id : id, $y : y);
- $q2 : Queen(id > $id, y == $y);
- then
- insertLogical(new UnweightedConstraintOccurrence("multipleQueensHorizontal", $q1, $q2));
+ when
+ $q1 : Queen($id : id, $y : y);
+ $q2 : Queen(id > $id, y == $y);
+ then
+ // trigger a change in the score
end</programlisting>
</example>
@@ -37,10 +39,6 @@
<mediaobject>
<imageobject>
- <imagedata fileref="unsolvedNQueens04.svg" format="SVG" />
- </imageobject>
-
- <imageobject>
<imagedata fileref="unsolvedNQueens04.png" format="PNG" />
</imageobject>
</mediaobject>
@@ -146,39 +144,29 @@
<programlisting>global SimpleScoreCalculator scoreCalculator;
rule "multipleQueensHorizontal"
- when
- $q1 : Queen($id : id, $y : y);
- $q2 : Queen(id > $id, y == $y);
- then
- insertLogical(new UnweightedConstraintOccurrence("multipleQueensHorizontal", $q1, $q2));
+ when
+ $q1 : Queen($id : id, $y : y);
+ $q2 : Queen(id > $id, y == $y);
+ then
+ insertLogical(new WorkaroundMultiplePatternAccumulate("multipleQueensHorizontal", $q1, $q2));
end
-// multipleQueensVertical is obsolete because it is always 0
-
rule "multipleQueensAscendingDiagonal"
- when
- $q1 : Queen($id : id, $ascendingD : ascendingD);
- $q2 : Queen(id > $id, ascendingD == $ascendingD);
- then
- insertLogical(new UnweightedConstraintOccurrence("multipleQueensAscendingDiagonal", $q1, $q2));
+ // ...
end
rule "multipleQueensDescendingDiagonal"
- when
- $q1 : Queen($id : id, $descendingD : descendingD);
- $q2 : Queen(id > $id, descendingD == $descendingD);
- then
- insertLogical(new UnweightedConstraintOccurrence("multipleQueensDescendingDiagonal", $q1, $q2));
+ // ...
end
-rule "hardConstraintsBroken"
- when
- $occurrenceCount : Number() from accumulate(
- $unweightedConstraintOccurrence : UnweightedConstraintOccurrence(),
- count($unweightedConstraintOccurrence)
- );
- then
- scoreCalculator.setScore(- $occurrenceCount.intValue());
+rule "constraintsBroken"
+ when
+ $hardConstraintCount : Number() from accumulate(
+ $w : WorkaroundMultiplePatternAccumulate(),
+ count($w)
+ );
+ then
+ scoreCalculator.setScore(- $hardConstraintCount);
end</programlisting>
<para>Optionally, you can also weigh your constraints differently, by
@@ -194,27 +182,27 @@
<programlisting>// Warning: This currently triggers backwards chaining instead of forward chaining and seriously hurts performance and scalability.
rule "constraintsBroken"
- when
- $multipleQueensHorizontal : Long()
- from accumulate(
- $q1 : Queen($id : id, $y : y)
- and Queen(id > $id, y == $y),
- count($q1)
- );
- $multipleQueensAscendingDiagonal : Long()
- from accumulate(
- $q2 : Queen($id : id, $ascendingD : ascendingD)
- and Queen(id > $id, ascendingD == $ascendingD),
- count($q2)
- );
- $multipleQueensDescendingDiagonal : Long()
- from accumulate(
- $q3 : Queen($id : id, $descendingD : descendingD)
- and Queen(id > $id, descendingD == $descendingD),
- count($q3)
- );
- then
- scoreCalculator.setScore(- (5 * $multipleQueensHorizontal) - $multipleQueensAscendingDiagonal - $multipleQueensDescendingDiagonal);
+ when
+ $multipleQueensHorizontal : Long()
+ from accumulate(
+ $q1 : Queen($id : id, $y : y)
+ and Queen(id > $id, y == $y),
+ count($q1)
+ );
+ $multipleQueensAscendingDiagonal : Long()
+ from accumulate(
+ $q2 : Queen($id : id, $ascendingD : ascendingD)
+ and Queen(id > $id, ascendingD == $ascendingD),
+ count($q2)
+ );
+ $multipleQueensDescendingDiagonal : Long()
+ from accumulate(
+ $q3 : Queen($id : id, $descendingD : descendingD)
+ and Queen(id > $id, descendingD == $descendingD),
+ count($q3)
+ );
+ then
+ scoreCalculator.setScore(- (5 * $multipleQueensHorizontal) - $multipleQueensAscendingDiagonal - $multipleQueensDescendingDiagonal);
end</programlisting>
</section>
@@ -283,4 +271,4 @@
</listitem>
</itemizedlist>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_configuration.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_configuration.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_configuration.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,8 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Solver configuration</title>
-
- <section>
+<!--
+<section>
<title>Types of solvers</title>
<para>Different solvers solve problems in different ways. Each type has
@@ -153,6 +155,7 @@
simulated annealing.</para>
</section>
</section>
+-->
<section>
<title>The Solver interface</title>
@@ -269,10 +272,6 @@
<mediaobject>
<imageobject>
- <imagedata fileref="unsolvedNQueens04.svg" format="SVG" />
- </imageobject>
-
- <imageobject>
<imagedata fileref="unsolvedNQueens04.png" format="PNG" />
</imageobject>
</mediaobject>
@@ -287,10 +286,10 @@
<programlisting>public interface Solution {
- Collection<? extends Object> getFacts();
-
Solution cloneSolution();
+ Collection<? extends Object> getFacts();
+
}</programlisting>
<para>For example:</para>
@@ -303,28 +302,12 @@
}</programlisting>
- <section>
- <title>The getFacts method</title>
+ <para>Most solvers use the <literal>cloneSolution()</literal> method to
+ clone the solution each time they encounter a new best solution. The
+ <literal>NQueens</literal> implementation just clones all
+ <literal>Queen</literal> instances:</para>
- <para>All Objects returned by the <literal>getFacts()</literal> method
- will be asserted into the drools working memory. Those facts can be used
- by the score rules. For example, <literal>NQueens</literal> just returns
- all <literal>Queen</literal> instances.</para>
-
- <programlisting> public Collection<? extends Object> getFacts() {
- return queenList;
- }</programlisting>
- </section>
-
- <section>
- <title>The cloneSolution method</title>
-
- <para>Most solvers use the <literal>cloneSolution()</literal> method to
- clone the solution each time they encounter a new best solution. The
- <literal>NQueens</literal> implementation just clones all
- <literal>Queen</literal> instances:</para>
-
- <programlisting> public NQueens cloneSolution() {
+ <programlisting> public NQueens cloneSolution() {
NQueens clone = new NQueens();
List<Queen> clonedQueenList = new ArrayList<Queen>(queenList.size());
for (Queen queen : queenList) {
@@ -334,14 +317,13 @@
return clone;
}</programlisting>
- <para>The <literal>cloneSolution()</literal> method should clone no more
- and no less than the parts of the <literal>Solution</literal> that can
- change during solving. For example, in the lesson schedule example the
- lessons are cloned, but teachers, groups and timeslots are not cloned
- because only a lesson's appointed timeslot changes during
- solving:</para>
+ <para>The <literal>cloneSolution()</literal> method should clone no more
+ and no less than the parts of the <literal>Solution</literal> that can
+ change during solving. For example, in the lesson schedule example the
+ lessons are cloned, but teachers, groups and timeslots are not cloned
+ because only a lesson's appointed timeslot changes during solving:</para>
- <programlisting> /**
+ <programlisting> /**
* Clone will only deep copy the lessons
*/
public LessonSchedule cloneSolution() {
@@ -356,7 +338,15 @@
clone.lessonList = clonedLessonList;
return clone;
}</programlisting>
- </section>
+
+ <para>All Objects returned by the <literal>getFacts()</literal> method
+ will be asserted into the drools working memory. Those facts can be used
+ by the score rules. For example, <literal>NQueens</literal> just returns
+ all <literal>Queen</literal> instances.</para>
+
+ <programlisting> public Collection<? extends Object> getFacts() {
+ return queenList;
+ }</programlisting>
</section>
<section>
@@ -382,10 +372,6 @@
<mediaobject>
<imageobject>
- <imagedata fileref="solvedNQueens04.svg" format="SVG" />
- </imageobject>
-
- <imageobject>
<imagedata fileref="solvedNQueens04.png" format="PNG" />
</imageobject>
</mediaobject>
@@ -394,4 +380,4 @@
<para>After a problem is solved, you can reuse the same solver instance to
solve another problem (of the same problem type).</para>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_examples.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_examples.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_examples.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Solver examples</title>
@@ -787,4 +789,4 @@
</table>
</section>
</section>
-</section>
\ No newline at end of file
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_introduction.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_introduction.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Solver/Section-Solver_introduction.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,4 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
<section>
<title>Solver introduction</title>
@@ -33,7 +35,7 @@
<listitem>
<para><ulink
url="http://en.wikipedia.org/wiki/Travelling_salesman_problem">The
- traveling salesman problem</ulink></para>
+ traveling salesmen problem</ulink></para>
</listitem>
<listitem>
@@ -119,7 +121,7 @@
</section>
<section>
- <title>Building drools-solver and running an example</title>
+ <title>Getting started with the examples</title>
<para>No releases have been made yet, but you can easily build it from
source yourself. Check out drools from subversion and do a maven 2 build
@@ -131,31 +133,390 @@
$ mvn -Psolver -Dmaven.test.skip clean install
...</programlisting>
- <para>After that, you can run any example directly from the command line,
- for example to run the n queens example, run:</para>
+ <para>Now you will If you want to use a stable version of drools, add this
+ /drools-solver/pom.xml </para>
+ <para>After that, you can run any example directly from the command line
+ like this:</para>
+
<programlisting>$ cd drools-solver/drools-solver-examples/
$ mvn exec:exec -Dexec.mainClass="org.drools.solver.examples.nqueens.app.NQueensApp"
+...
+$ mvn exec:exec -Dexec.mainClass="org.drools.solver.examples.lessonschedule.app.LessonScheduleApp"
+...
+$ mvn exec:exec -Dexec.mainClass="org.drools.solver.examples.travelingtournament.app.simple.SimpleTravelingTournamentApp"
+...
+$ mvn exec:exec -Dexec.mainClass="org.drools.solver.examples.travelingtournament.app.smart.SmartTravelingTournamentApp"
...</programlisting>
- <para>You will use drools-solver with the latest, unstable snapshot of the
- drools rule engine. If you would rather use a stable version of the drools
- rule engine, edit <literal>/drools-solver/pom.xml</literal> and overwrite
- the drools jar versions, before building and running the examples:</para>
+ <para>You will use the latest, unstable revision of drools. If you would
+ rather use a stable version of drools, edit
+ <literal>/drools-solver/drools-solver-examples/pom.xml</literal> and
+ overwrite the drools jar versions, before runing the example:</para>
- <programlisting> <dependencyManagement>
- <dependencies>
- <dependency>
- <groupId>org.drools</groupId>
- <artifactId>drools-core</artifactId>
- <version>4.0.3</version>
- </dependency>
- <dependency>
- <groupId>org.drools</groupId>
- <artifactId>drools-compiler</artifactId>
- <version>4.0.3</version>
- </dependency>
- </dependencies>
- </dependencyManagement></programlisting>
+ <programlisting> <dependencies>
+ <dependency>
+ <groupId>org.drools</groupId>
+ <artifactId>drools-core</artifactId>
+ <version>4.0.2</version>
+ </dependency>
+ <dependency>
+ <groupId>org.drools</groupId>
+ <artifactId>drools-compiler</artifactId>
+ <version>4.0.2</version>
+ </dependency>
+
+ ...
+
+ </dependencies></programlisting>
+
+ <para>Here's a screenshot of the n queens example, which is a simple
+ example:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshotSolvedNQueens8.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
</section>
-</section>
\ No newline at end of file
+
+ <section>
+ <title>The 4 queens example</title>
+
+ <section>
+ <title>Problem statement</title>
+
+ <para>The <emphasis>n queens puzzle</emphasis> is a puzzle with the
+ follow constraints:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Use a chessboard of n rows and n columns.</para>
+ </listitem>
+
+ <listitem>
+ <para>Place n queens on the chessboard.</para>
+ </listitem>
+
+ <listitem>
+ <para>No 2 queens can attack each other. Note that a queen can
+ attack any other queen on the same horizontal, vertical or diagonal
+ line.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The most common n queens puzzle is the 8 queens puzzle, with
+ <emphasis>n = 8</emphasis>. We 'll explain drools-solver using the 4
+ queens puzzle as the primary example.</para>
+
+ <para>A proposed solution could be:</para>
+
+ <figure>
+ <title>A wrong solution for the 4 queens puzzle</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
+ fileref="partiallySolvedNQueens04Explained.png"
+ format="PNG" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The above solution is wrong because queens A1 and B0 can attack
+ each other (as can queens B0 and D0). Removing queen B0 would respect
+ the "no 2 queens can attack each other" constraint, but would break the
+ "place n queens" constraint.</para>
+ </section>
+
+ <section>
+ <title>Solution(s)</title>
+
+ <para>Below is a correct solution:</para>
+
+ <figure>
+ <title>A correct solution for the 4 queens puzzle</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="solvedNQueens04.png"
+ format="PNG" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>All the constraints have been met, so the solution is correct.
+ Note that most n queens puzzles have multiple correct solutions. We 'll
+ focus on finding a single correct solution for a given n, not on finding
+ the number of possible correct solutions for a given n.</para>
+ </section>
+
+ <section>
+ <title>Class diagram</title>
+
+ <para>Use a good domain model and it will be easier to understand and
+ solve your problem with drools-solver. We 'll use this domain model for
+ the n queens example:</para>
+
+ <figure>
+ <title>NQueens domain diagram</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="nQueensDomainDiagram.png"
+ format="PNG" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>A <literal>Queen</literal> instance has an x (its column, for
+ example: 0 is column A, 1 is column B, ...) and a y (its row, for
+ example: 0 is row 0, 1 is row 1, ...). Based on the x and y, the
+ ascending diagonal line as well as the descending diagonal line can be
+ calculated. The x and y indexes start from the upper left corner of the
+ chessboard.</para>
+
+ <table>
+ <title>A solution for the 4 queens puzzle shown in the domain
+ model</title>
+
+ <tgroup cols="6">
+ <thead>
+ <row>
+ <entry align="center">A solution</entry>
+
+ <entry align="center">Queen</entry>
+
+ <entry>x</entry>
+
+ <entry>y</entry>
+
+ <entry>ascendingD (x + y)</entry>
+
+ <entry>descendingD (x - y)</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry morerows="3"><mediaobject>
+ <imageobject>
+ <imagedata fileref="partiallySolvedNQueens04Explained.png"
+ format="PNG" />
+ </imageobject>
+ </mediaobject></entry>
+
+ <entry>A1</entry>
+
+ <entry>0</entry>
+
+ <entry>1</entry>
+
+ <entry>1 (**)</entry>
+
+ <entry>-1</entry>
+ </row>
+
+ <row>
+ <entry>B0</entry>
+
+ <entry>1</entry>
+
+ <entry>0 (*)</entry>
+
+ <entry>1 (**)</entry>
+
+ <entry>1</entry>
+ </row>
+
+ <row>
+ <entry>C2</entry>
+
+ <entry>2</entry>
+
+ <entry>2</entry>
+
+ <entry>4</entry>
+
+ <entry>0</entry>
+ </row>
+
+ <row>
+ <entry>D0</entry>
+
+ <entry>3</entry>
+
+ <entry>0 (*)</entry>
+
+ <entry>3</entry>
+
+ <entry>3</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>A single <literal>NQueens</literal> instance contains a list of
+ all <literal>Queen</literal> instances. It is the
+ <literal>Solution</literal> implementation which will be supplied to and
+ retrieved from drools-solver. Notice that in the 4 queens example,
+ NQueens's <literal>getN()</literal> method will always return 4.</para>
+
+ <para>You can find the source code of this example (as well as well as
+ several other examples) in the drools-solver-examples src
+ distribution.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Types of solvers</title>
+
+ <para>Different solvers solve problems in different ways. Each type has
+ advantages and disadvantages. We 'll roughly discuss a few of the solver
+ types here. You can safely skip this section.</para>
+
+ <section>
+ <title>Brute force</title>
+
+ <para>Brute force creates and evaluates every possible solution, usually
+ by creating a search tree.</para>
+
+ <para>Advantages:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>It finds an optimal solution. If there is more then 1 optimal
+ solution, it finds all optimal solutions.</para>
+ </listitem>
+
+ <listitem>
+ <para>It is straightforward and simple to implement.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Disadvantages:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>It has a horrible performance and scalability. Mostly unusable
+ for a real-world problem due to time constraints.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Brute force is currently not implemented in drools-solver. But we
+ have plans to implement it in the future, as a reference for validating
+ the output of the other solver types.</para>
+ </section>
+
+ <section>
+ <title>Branch and bound</title>
+
+ <para>Branch and bound is an improvement over brute force, as it prunes
+ away subsets of solutions which cannot have a better solution than the
+ best solution already found at that point.</para>
+
+ <para>Advantages:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>It finds an optimal solution. If there is more then 1 optimal
+ solution, it can find all optimal solutions if needed.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Disadvantages:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>It still scales very badly.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Branch and bound is currently not implemented in
+ drools-solver.</para>
+ </section>
+
+ <section>
+ <title>Simplex</title>
+
+ <para>Simplex turns all constraints into a big equation, which it
+ transmutes into a mathematical function without local optima. It then
+ finds an optimal solution to the planning problem by finding an optima
+ of that mathematical function.</para>
+
+ <para>Advantages:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>It finds an optimal solution.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Disadvantages:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>It's usually rather complex and mathematical to implement
+ constraints.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Drools-solver does not currently implement simplex.</para>
+ </section>
+
+ <section>
+ <title>Local search (tabu search, simulated annealing, ...)</title>
+
+ <para>Local search starts from an initial solution and evolves that
+ single solution into a better and better solution. It uses a single
+ search path of solutions. At each solution in this path it evaluates a
+ number of possible moves on the solution and applies the most suitable
+ move to take the step to the next solution.</para>
+
+ <para>Local search works a lot like a human planner: it uses a single
+ search path and moves facts around to find a good feasible
+ solution.</para>
+
+ <para>A simple local search can easily get stuck in a local optima, but
+ improvements (such as tabu search and simulated annealing) address this
+ problem.</para>
+
+ <para>Advantages:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>It's relatively simple and natural to implement constraints
+ (at least in drools-solver's implementation).</para>
+ </listitem>
+
+ <listitem>
+ <para>It's very scalable, even when adding extra constraints (at
+ least in drools-solver's implementation).</para>
+ </listitem>
+
+ <listitem>
+ <para>It generally needs to worry about less negative hard
+ constraints, because the move pattern can fulfill a number of the
+ negative hard constraints.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Disadvantages:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>It does not know when it has found an optimal solution.</para>
+ </listitem>
+
+ <listitem>
+ <para>If the optimal score is unknown (which is usually the case),
+ it must be told when to stop looking (for example based on time
+ spend, user input, ...).</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Drools-solver implements local search, including tabu search and
+ simulated annealing.</para>
+ </section>
+ </section>
+</section>
Modified: labs/jbossrules/trunk/documentation/manual/en/master.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/master.xml 2008-02-12 23:32:13 UTC (rev 18469)
+++ labs/jbossrules/trunk/documentation/manual/en/master.xml 2008-02-12 23:59:37 UTC (rev 18470)
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<book xmlns:xi="http://www.w3.org/2003/XInclude">
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
<bookinfo>
<title>Drools</title>
@@ -219,4 +219,4 @@
</part>
<index />
-</book>
\ No newline at end of file
+</book>
More information about the jboss-svn-commits
mailing list