[jboss-svn-commits] JBL Code SVN: r19101 - labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Wed Mar 19 02:24:00 EDT 2008
Author: irooskov at redhat.com
Date: 2008-03-19 02:24:00 -0400 (Wed, 19 Mar 2008)
New Revision: 19101
Modified:
labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-UserGuide.xml
Log:
continuing to edit the drools user guide
Modified: labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-UserGuide.xml
===================================================================
--- labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-UserGuide.xml 2008-03-19 06:01:55 UTC (rev 19100)
+++ labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-UserGuide.xml 2008-03-19 06:24:00 UTC (rev 19101)
@@ -321,21 +321,67 @@
<para> The different parts of a rule. The <emphasis>WHEN</emphasis> part is the condition, <emphasis>THEN</emphasis> action, and <emphasis>(options)</emphasis> are optional attributes that may effect the operation of the rule.</para>
</listitem>
-
+ <listitem>
<para>B</para>
- <para>This shows a pattern which is declaring that the rule is looking for a <emphasis>Driver</emphasis> fact (the fields are listed below, in this case only <emphais>age</emphaiss> is shown). Note the green triangle, it will popup a list of options to add to the fact declaration. More fields can be added (for example, their <emphasis>location</emphasis>) and a variable name can be assigned to the fact(which ycan be used later). As well as adding more fields to this pattern, multiple field constraits can be added (for instance, age > 42 or risk > 2).</para>
-
+ <para>This shows a pattern which is declaring that the rule is looking for a <emphasis>Driver</emphasis> fact (the fields are listed below, in this case only <emphasis>age</emphasis> is shown). Note the green triangle, it will popup a list of options to add to the fact declaration. More fields can be added (for example, their <emphasis>location</emphasis>) and a variable name can be assigned to the fact(which ycan be used later). As well as adding more fields to this pattern, multiple field constraits can be added (for instance, age > 42 or risk > 2).</para>
+ </listitem>
+ <listitem>
<para>C</para>
<para>The small negation ("-") icons indicate something can be removed. 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>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>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>
- </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>D</para>
+ <para>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 <emphasis>WHEN</emphasis> part of the rule, a constraint can be added on a fact (it will give a list of facts), or another conditional element can be used, the choices of which, are:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>There is no</emphasis>, meaning the fact and constraints must not exist.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>There exists</emphasis>, meaning that there exists at least one match and will only trigger for the first match, not all.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Any of</emphasis>, meaning that any of the patterns can match. Patterns can be added to these and if only a pattern is placed, then all patterns are combined and true.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>E</para>
+
+ <para>This shows the constraint for the <emphasis>age</emphasis> field. (Looking from left to right) the green triangle allows <emphasis>assign</emphasis>ing of a variable name to the <emphasis>age</emphasis> field, which can be used later in the rule. Next is the list of constraint operations; the list changes depending on the data type. After is the value field that will be one of:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ A literal value (number, text).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A formula (calculated expression for adcanced users).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A variable (with a list to select a value from)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>After this there is a horizontal arrow icon that is for <emphasis>connective constraints</emphasis> : these are constraints which allow for alternative values to check a field against. For example: <emphasis>age is less than 42 or age is not equal to 39</emphasis> is possible this way.</para>
+ </listitem>
+ <listitem>
+ <para>F</para>
+ <para>This shows an <emphasis>action</emphasis> 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 <emphasis>reason</emphasis> field set to an explanation). There are quite a few other types of actions that can be used: an existing fact can be modified (which tells the engine the fact has changed), or a field on a fact can be set (in which case the engine doesn't know about the change, normally because a result is being set). A fact can also be restricted. In most cases the green arrow will show a list of fields that can be added. The values entered are <emphasis>literal</emphasis>, in the sense that what is typed 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 <emphasis>formula</emphasis> and the calculation will be performed (similar to a spreadsheet).</para>
+ </listitem>
+ <listitem>
+ <para>G</para>
+ <para>This is where the rule options live. In this case, only salience is used which is a numeric value representing the rules <emphasis>priority</emphasis>. This would probably be the most common option to use.</para>
+ </listitem>
+ </itemizedlist>
<section>
<title>User driven drop down lists</title>
@@ -348,14 +394,19 @@
</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>
+ <note>
+ <para>It is 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 the drop down list display different values to those used in a rule. See the section on <link linkend='Data_Enumerations'>data enumerations</link> for how these are configured.</para>
+ </note>
</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>If the package the rule is part of has a DSL configuration, what conditions or actions are added it will provide a list of <emphasis>DSL Sentences</emphasis>. Once one is chosen, 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.</para>
+
+ <note>
+ <para>The DSL capabilities in this editor are slightly less then the full set of DSL features (implementing [when] and [then] sections of the DSL only - which is no different to drools 3 in effect).</para>
+ </note>
<para>The following diagram shows the DSL sentences in action in the guided editor:</para>
@@ -384,10 +435,13 @@
</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 above example, uses a mixture of literal values, and formulas. The second constraint on the <emphasis>Person</emphasis> fact, is a formula (in this case it is doing a calculation on the persons age, and checking something against their name). Both <emphasis>age</emphasis> and <emphasis>name</emphasis> are fields of the Person fact in this case. In the 3rd line (stating <emphasis>age is less than ..</emphasis>, 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 it is a value. Simple formulas are basically pieces of code, deeming this is for experienced users only.</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>
-
+ <para>Looking at the <emphasis>Board</emphasis> pattern (the second pattern with the horizontal grey bar): this uses a top level conditional element (<emphasis>There is no</emphasis>). Meaning that the pattern is actually looking for the <emphasis>non existence</emphasis> of a fact that matches the pattern.</para>
+
+ <note>
+ <para>The <emphasis>Any of:</emphasis> means that <emphasis>EITHER</emphasis> the <emphasis>type</emphasis> field constraint is matched, or the <emphasis>name</emphasis> field is matched (to <emphasis>myname</emphasis> in the case above). Termed a Multiple field constraint, these can be nested and become complex. Overly complex rules are not recconmended though, as it may be confusing for another person to understand.</para>
+ </note>
<figure>
<title>Adding constraints</title>
@@ -398,7 +452,7 @@
</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>
+ <para>The above dialog is what will appear when adding constraints to the Person fact. In the top half are the simple options: giving the ability to either add a field straight away (a list of fields of the Person fact will be shown), or add a <emphasis>Multiple field constraint</emphasis>, of a given type. The Advanced options: add a formula (which resolves to True or False, as in the previous example: <emphasis>age < (age * 2) ....</emphasis>). A variable name can also be assigned to the Person fact (allowing the variable to be accessed on the action part of the rule).</para>
</section>
</section>
@@ -417,13 +471,13 @@
</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>
+ <para>A DSL rule is a singular. the icons to the right in the example can be used to to provide lists of conditions and actions to choose from (or else press Control + Space at the same time to show a list).</para>
</section>
<section>
<title>Spreadsheet decision tables</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>
+ <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 (more spreadsheet information can be found in the relevant chapter in the Drools Reference Guide).</para>
<figure>
<title>Spreadsheet decision table</title>
@@ -435,21 +489,21 @@
</mediaobject>
</figure>
- <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>
+ <para>To use a spreadsheet, upload an xls (the current version can also be downloaded, as per the picture above). To create a new decision table, launch the rule wizard and an option will appear to create one (after that point, upload the xls file).</para>
</section>
<section>
<title>Rule flows</title>
- <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>
+ <para>Rule flows: Rule flows allow for visual discription of the steps taken, meaning not all rules are evaluated at once, but there exists 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>
- <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>
+ <para>Similar to spreadsheets, you upload/download ruleflow files (the eclipse IDE has a graphical editor for them).</para>
</section>
<section>
- <title>Technical rules (drl)</title>
+ <title>Technical rules (DRL)</title>
- <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>
+ <para>Technical (DRL) rules are stored as text and 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 and use <emphasis>when</emphasis> and <emphasis>then</emphasis> to mark the condition and action sections respectively. Normally the IDE would be used 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.</para>
<figure>
<title>DRL technical rule</title>
@@ -465,7 +519,7 @@
<section>
<title>Functions</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>Functions are another asset type. They are NOT rules, and should only be used when necessary. The function editor is a textual editor.</para>
<figure>
<title>Function</title>
@@ -478,12 +532,12 @@
</figure>
</section>
- <section>
+ <section id="Data_Enumerations">
<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>Data enumerations are an optional asset type that can be configured 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>
+ <para>The contents of an enum config are a mapping of <property>Fact.field</property> to a list of values to be used in a drop down list. That list can either be literal, or use a utility class (which can be placed on the classpath) to load a list of strings. The strings are either a value to be shown on a drop down list, 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>
@@ -495,9 +549,12 @@
</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>In the above diagram, <emphasis>MM</emphasis> indicates a value that will be used in the rule, yet <emphasis>Mini Mal</emphasis> 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>
+ <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, a bit of code that returns a <property>java.util.List</property> (of String's) to be on the classpath of the BRMS will be needed. 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:</para>
+<screen> 'Person.age' : (new com.yourco.DataHelper()).getListOfAges()</screen>
+<para>
+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>
More information about the jboss-svn-commits
mailing list