[jboss-svn-commits] JBL Code SVN: r19441 - labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Mon Apr 7 02:22:26 EDT 2008
Author: irooskov at redhat.com
Date: 2008-04-07 02:22:25 -0400 (Mon, 07 Apr 2008)
New Revision: 19441
Modified:
labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-DSL.xml
labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-Query.xml
labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-Rule.xml
Log:
Updated with corrections for first version of reference guide
Modified: labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-DSL.xml
===================================================================
--- labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-DSL.xml 2008-04-07 03:01:24 UTC (rev 19440)
+++ labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-DSL.xml 2008-04-07 06:22:25 UTC (rev 19441)
@@ -6,96 +6,93 @@
<para>As mentioned previously, <indexterm>
<primary>Domain Specific Languages</primary>
- </indexterm>(or DSLs) are a way of extending the rule language to your
- problem domain. They are wired in to the rule language for you, and can make
+ </indexterm>(or DSLs) are a way of extending the rule language to a
+ problem domain. They are wired in to the rule language, and can make
use of all the underlying rule language and engine features.</para>
<para>DSLs are used both in the IDE, as well as the web based BRMS. Of
- course as rules are text, you can use them even without this tooling.</para>
+ course as rules are text, they can be used even without this tooling.</para>
<section>
<title>When to use a DSL</title>
<para>DSLs can serve as a layer of separation between rule authoring (and
rule authors) and the domain objects that the engine operates on. DSLs can
- also act as "templates" of conditions or actions that are used over and
- over in your rules, perhaps only with parameters changing each time. If
- your rules need to be read and validated by less technical folk, (such as
- Business Analysts) the DSLs are definitely for you. If the conditions or
- consequences of your rules follow similar patterns which you can express
- in a template. You wish to hide away your implementation details, and
- focus on the business rule. You want to provide a controlled means of
+ also act as <emphasis>templates</emphasis> of conditions or actions that are used repeatedly in rules, perhaps only with parameters changing each time. If
+ the rules need to be read and validated by non-technical personnel, (such as
+ Business Analysts) then DSLs will be of great assistance. If the conditions or
+ consequences of the rules follow similar patterns, this can be expressed
+ in a template. DSLs are also useful when wishing to hide implementation details, while also providing a controlled means of
editing rules based on pre-defined templates.</para>
<para>DSLs have no impact on the rules at runtime, they are just a
parse/compile time feature.</para>
+<note>
<para>Note that Drools 4 DSLs are quite different from Drools 2 XML based
- DSLs. It is still possible to do Drools 2 style XML languages - if you
- require this, then take a look at the Drools 4 XML rule language, and
- consider using XSLT to map from your XML language to the Drools 4 XML
- language.</para>
+ DSLs. It is still possible to do Drools 2 style XML languages however, if it is required.</para>
+</note>
</section>
<section>
<title>Editing and managing a DSL</title>
- <para>A DSL's configuration like most things is stored in plain text. If
- you use the IDE, you get a nice graphical editor (with some validation),
+ <para>A DSL's configuration is stored in plain text. The IDE is a nice graphical editor (with some validation),
but the format of the file is quite simple, and is basically a properties
file.</para>
- <para>Note that since Drools 4.0, DSLs have become more powerful in
- allowing you to customise almost any part of the language, including
+<note>
+ <para>Since Drools 4.0, DSLs have become more powerful in
+ allowing customization to almost any part of the language, including
keywords. Regular expressions can also be used to match words/sentences if
needed (this is provided for enhanced localisation). However, not all
- features are supported by all the tools (although you can use them, the
+ features are supported by all the tools (although they can be used, the
content assistance just may not be 100% accurate in certain cases).</para>
-
+</note>
<example>
<title>Example <indexterm>
<primary>DSL</primary>
</indexterm> mapping</title>
- <programlisting>[when]This is {something}=Something(something=={something})</programlisting>
+<screen>[when]This is {something}=Something(something=={something})</screen>
</example>
- <para>Referring to the above example, the [when] refers to the scope of
- the expression: ie does it belong on the LHS or the RHS of a rule. The
- part after the [scope] is the expression that you use in the rule
+ <para>Referring to the above example, the <code>when</code> refers to the scope of
+ the expression. For instance, does it belong on the LHS or the RHS of a rule? The
+ part after the <code>scope</code> is the expression used in the rule
(typically a natural language expression, but it doesn't have to be). The
- part on the right of the "=" is the mapping into the rule language (of
- course the form of this depends on if you are talking about the RHS or the
- LHS - if its the LHS, then its the normal LHS syntax, if its the RHS then
+ part on the right of the <code>=</code> is the mapping into the rule language (the form of this depends on which side is being discussed, the RHS or the
+ LHS. If its the LHS, then its the normal LHS syntax, if its the RHS then
its fragments of Java code for instance).</para>
- <para>The parser will take the expression you specify, and extract the
+ <para>The parser will take the expression specified, and extract the
values that match where the {something} (named Tokens) appear in the
input. The values that match the tokens are then interpolated with the
corresponding {something} (named Tokens) on the right hand side of the
mapping (the target expression that the rule engine actually uses).</para>
- <para>Note also that the "sentences" above can be regular expressions.
+<note>
+ <para>The <emphasis>sentences</emphasis> above can be regular expressions.
This means the parser will match the sentence fragements that match the
- expressions. This means you can use (for instance) the '?' to indicate the
+ expressions. This means the <code>?</code> character can be used to indicate the
character before it is optional (think of each sentence as a regular
- expression pattern - this means if you want to use regex characters - you
- will need to escape them with a '\' of course.</para>
-
- <para>It is important to note that the DSL expressions are processed one
+ expression pattern. This means that to use regex characters, they will need to be escaped with a <code>\</code>.</para>
+</note>
+<important>
+ <para>The DSL expressions are processed one
line at a time. This means that in the above example, all the text after
"There is " to the end of the line will be included as the value for
"{something}" when it is interpolated into the target string. This may not
- be exactly what you want, as you may want to "chain" together different
+ be exactly what is wanted, as it may be desirable to <emphasis>chain</emphasis> together different
DSL expressions to generate a target expression. The best way around this
is to make sure that the {tokens} are enclosed with characters or words.
This means that the parser will scan along the sentence, and pluck out the
- value BETWEEN the characters (in the example below they are
- double-quotes). Note that the characters that surround the token are not
+ value <emphasis>BETWEEN</emphasis> the characters (in the example below they are
+ double-quotes). The characters that surround the token are not
included in when interpolating, just the contents between them (rather
then all the way to the end of the line, as would otherwise be the
case).</para>
-
+</important>
<para>As a rule of thumb, use quotes for textual data that a rule editor
may want to enter. You can also wrap words around the {tokens} to make
sure you enclose the data you want to capture (see other example).</para>
@@ -103,46 +100,47 @@
<example>
<title>Example with quotes</title>
- <programlisting>[when]This is "{something}" and "{another}"=Something(something=="{something}", another=="{another}")
-[when]This is {also} valid=Another(something=="{also}")</programlisting>
+<screen>[when]This is "{something}" and "{another}"=Something(something=="{something}", another=="{another}")
+[when]This is {also} valid=Another(something=="{also}")</screen>
</example>
<para>It is a good idea to try and avoid punctuation in your DSL
- expressions where possible, other then quotes and the like - keep it
- simple it things will be easier. Using a DSL can make debugging slightly
- harder when you are first building rules, but it can make the maintenance
- easier (and of course the readability of the rules).</para>
+ expressions where possible, other then quotes and the like. Using a DSL can make debugging slightly
+ harder when first building rules, but it can make the maintenance
+ easier (and the readability of the rules).</para>
- <para>The "{" and "}" characters should only be used on the left hand side
- of the mapping (the expression) to mark tokens. On the right hand side you
- can use "{" and "}" on their own if needed - such as <programlisting>if (foo) {
- doSomething(); }</programlisting> as well as with the token names as shown
+ <para>The <code>{</code> and <code>}</code> characters should only be used on the left hand side
+ of the mapping (the expression) to mark tokens. On the right hand side, use <code>{</code> and <code>}</code> on their own if needed. An example would be:</para>
+
+<screen>if (foo) {
+ doSomething(); }</screen>.
+
+<para>As well as with the token names as shown
above.</para>
- <para>Don't forget that if you are capturing strings from users, you will
- also need the quotes on the right hand side of the mapping, just like a
- normal rule, as the result of the mapping must be a valid expression in
+ <para>When capturing strings from users, the quotes will also be necessary on the right hand side of the mapping, just like a
+ normal rule; as the result of the mapping must be a valid expression in
the rule language.</para>
<example>
<title>Some more examples</title>
- <programlisting>#This is a comment to be ignored.
+<screen>#This is a comment to be ignored.
[when]There is a Person with name of "{name}"=Person(name=="{name}")
[when]Person is at least {age} years old and lives in "{location}"=Person(age > {age}, location=="{location}")
[then]Log "{message}"=System.out.println("{message}");
-[when]And = and</programlisting>
+[when]And = and</screen>
</example>
<para>Referring to the above examples, this would render the following
input as shown below: <example>
<title>Some examples as processed</title>
- <programlisting>There is a Person with name of "kitty" ---> Person(name="kitty")
+<screen>There is a Person with name of "kitty" ---> Person(name="kitty")
Person is at least 42 years old and lives in "atlanta" ---> Person(age > 42, location="atlanta")
Log "boo" ---> System.out.println("boo");
There is a Person with name of "bob" and Person is at least 30 years old and lives in "atlanta"
- ---> Person(name="kitty") and Person(age > 30, location="atlanta")</programlisting>
+ ---> Person(name="kitty") and Person(age > 30, location="atlanta")</screen>
</example></para>
</section>
Modified: labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-Query.xml
===================================================================
--- labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-Query.xml 2008-04-07 03:01:24 UTC (rev 19440)
+++ labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-Query.xml 2008-04-07 06:22:25 UTC (rev 19441)
@@ -14,17 +14,16 @@
</mediaobject>
</figure>
- <para>A query contains the structure of the LHS of a rule only (you don't
- specify "when" or "then"). It is simply a way to query the working memory
+ <para>A query contains the structure of the LHS of a rule only (<code>when</code> or <code>then</code> are not specified). It is simply a way to query the working memory
for facts that match the conditions stated. A query has an optional set of
parameters, that can also be optionally typed, if type is not given then
Object type is assumed and the engine will attempt to co-erce the values as
needed.</para>
- <para>To return the results use WorkingMemory.getQueryResults("name") -
+ <para>To return the results use <methodname>WorkingMemory.getQueryResults("name")</methodname>,
where "name" is query name. Query names are global to the RuleBase, so do
not add queries of the same name to different packages for the same Rule
- Base. This contains a list of query results, which allow you to to get to
+ Base. This contains a list of query results, which allow for access to
the objects that matched the query.</para>
<para>This example creates a simple query for all the people over the age of
@@ -33,20 +32,20 @@
<example>
<title>Query People over the age of 30</title>
- <programlisting>query "people over the age of 30"
+<screen>query "people over the age of 30"
person : Person( age > 30 )
-end</programlisting>
+end</screen>
</example>
<example>
<title>Query People over the age of X, and who live in y</title>
- <programlisting>query "people over the age of X" (int x, String y)
+<screen>query "people over the age of X" (int x, String y)
person : Person( age > x, location == y )
-end</programlisting>
+end</screen>
</example>
- <para>We iterate over the returned QueryResults using a standard 'for' loop.
+ <para>We iterate over the returned QueryResults using a standard <code>for</code> loop.
Each row returns a QueryResult which we can use to access each of the
columns in the Tuple. Those columns can be access by bound declaration name
or index position.</para>
@@ -54,7 +53,7 @@
<example>
<title>Query People over the age of 30</title>
- <programlisting>QueryResults results = workingMemory.getQueryResults( "people over the age of 30" );
+<screen>QueryResults results = workingMemory.getQueryResults( "people over the age of 30" );
System.out.println( "we have " + results.size() + " people over the age of 30" );
System.out.println( "These people are are over 30:" );
@@ -63,6 +62,6 @@
QueryResult result = ( QueryResult ) it.next();
Person person = ( Person ) result.get( "person" );
System.out.println( person.getName() + "\n" );
-}</programlisting>
+}</screen>
</example>
</section>
Modified: labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-Rule.xml
===================================================================
--- labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-Rule.xml 2008-04-07 03:01:24 UTC (rev 19440)
+++ labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-Rule.xml 2008-04-07 06:22:25 UTC (rev 19441)
@@ -328,7 +328,7 @@
<example>
<title>Pattern</title>
- <programlisting>Cheese( )</programlisting>
+<screen>Cheese( )</screen>
</example>
<para>To be able to refer to the matched object use a pattern binding
@@ -1071,9 +1071,9 @@
</section>
<section>
- <title>'and'</title>
+ <title><code>and</code></title>
- <para>The 'and' Conditional Element is used to group together other
+ <para>The <code>and</code> Conditional Element is used to group together other
Conditional Elements. The root element of the LHS is an implicit prefix
And and doesn't need to be specified. Drools supports both prefix and
infix; although prefix is the preferred option as grouping is implicit
@@ -1109,9 +1109,9 @@
</screen>
</example>
- <para>Infix 'and' is supported along with explicit grouping with
- parenthesis, should it be needed. The '&&' symbol, as an
- alternative to 'and', is deprecated although it is still supported in
+ <para>Infix <code>and</code> is supported along with explicit grouping with
+ parenthesis, should it be needed. The <code>&&</code> symbol, as an
+ alternative to <code>and</code>, is deprecated although it is still supported in
the syntax for legacy support reasons.</para>
<figure>
@@ -1135,17 +1135,17 @@
</section>
<section>
- <title>'or'</title>
+ <title><code>or</code></title>
- <para>The 'or' Conditional Element is used to group together other
+ <para>The <code>or</code> Conditional Element is used to group together other
Conditional Elements. Drools supports both prefix and infix; although
prefix is the preferred option as grouping is implicit which avoids
- confusion. The behavior of the 'or' Conditional Element is different
- than the '||' connective for constraints and restrictions in field
- constraints. The engine actually has no understanding of 'or'
+ confusion. The behavior of the <code>or</code> Conditional Element is different
+ than the <code>||</code> connective for constraints and restrictions in field
+ constraints. The engine actually has no understanding of <code>or</code>
Conditional Elements, instead via a number of different logic
transformations the rule is re-written as a number of subrules; the rule
- now has a single 'or' as the root node and a subrule per logical
+ now has a single <code>or</code> as the root node and a subrule per logical
outcome. Each subrule can activate and fire like any normal rule, there
is no special behavior or interactions between the subrules - this can
be most confusing to new rule authors.</para>
@@ -1164,14 +1164,14 @@
<example>
<title>prefixOr</title>
- <programlisting>(or Person( sex == "f", age > 60 )
+<screen>(or Person( sex == "f", age > 60 )
Person( sex == "m", age > 65 )
-</programlisting>
+</screen>
</example>
- <para>Infix 'or' is supported along with explicit grouping with
- parenthesis, should it be needed. The '||' symbol, as an alternative to
- 'or', is deprecated although it is still supported in the syntax for
+ <para>Infix <code>or</code> is supported along with explicit grouping with
+ parenthesis, should it be needed. The <code>||</code> symbol, as an alternative to
+ <code>or</code>, is deprecated although it is still supported in the syntax for
legacy support reasons.</para>
<figure>
@@ -1188,27 +1188,27 @@
<example>
<title>infixAnd</title>
- <programlisting>Cheese( cheeseType : type ) or Person( favouriteCheese == cheeseType ) //infixOr
-(Cheese( cheeseType : type ) or (Person( favouriteCheese == cheeseType ) and Person( favouriteCheese == cheeseType ) ) //infixOr with grouping</programlisting>
+<screen>Cheese( cheeseType : type ) or Person( favouriteCheese == cheeseType ) //infixOr
+(Cheese( cheeseType : type ) or (Person( favouriteCheese == cheeseType ) and Person( favouriteCheese == cheeseType ) ) //infixOr with grouping</screen>
</example>
- <para>The 'or' Conditional Element also allows for optional pattern
+ <para>The <code>or</code> Conditional Element also allows for optional pattern
binding; which means each resulting subrule will bind it's pattern to
the pattern binding.</para>
<example>
<title>or with binding</title>
- <programlisting>pensioner : (or Person( sex == "f", age > 60 )
- Person( sex == "m", age > 65 ) )</programlisting>
+<screen>pensioner : (or Person( sex == "f", age > 60 )
+ Person( sex == "m", age > 65 ) )</screen>
<para>Explicit binding on each Pattern is also allowed.</para>
- <programlisting>(or pensioner : Person( sex == "f", age > 60 )
- pensioner : Person( sex == "m", age > 65 ) )</programlisting>
+<screen>(or pensioner : Person( sex == "f", age > 60 )
+ pensioner : Person( sex == "m", age > 65 ) )</screen>
</example>
- <para>The 'or' conditional element results in multiple rule generation,
+ <para>The <code>or</code> conditional element results in multiple rule generation,
called sub rules, for each possible logically outcome. The example above
would result in the internal generation of two rules. These two rules
work independently within the Working Memory, which means both can
@@ -1221,7 +1221,7 @@
</section>
<section>
- <title>'eval'</title>
+ <title><code>eval</code></title>
<figure>
<title>eval</title>
@@ -1237,7 +1237,7 @@
(that returns a primitive boolean) to be executed. This can refer to
variables that were bound in the LHS of the rule, and functions in the
rule package. Over use of eval reduces the declaratives of your rules
- and can result in a poor performing engine. While 'evals' can be used
+ and can result in a poor performing engine. While <code>evals</code> can be used
anywhere in the Pattern the best practice is to add it as the last
conditional element in the LHS of a rule.</para>
@@ -1253,15 +1253,15 @@
<example>
<title>eval</title>
- <programlisting>p1 : Parameter()
+<screen>p1 : Parameter()
p2 : Parameter()
eval( p1.getList().containsKey(p2.getItem()) )
-eval( isValid(p1, p2) ) //this is how you call a function in the LHS - a function called "isValid"</programlisting>
+eval( isValid(p1, p2) ) //this is how you call a function in the LHS - a function called "isValid"</screen>
</example>
</section>
<section>
- <title>'not'</title>
+ <title><code>not</code></title>
<figure>
<title>not</title>
@@ -1274,32 +1274,33 @@
</mediaobject>
</figure>
- <para>'not' is first order logic's Non-Existential Quantifier and checks
- for the non existence of something in the Working Memory. Think of 'not'
+ <para><code>not</code> is first order logic's Non-Existential Quantifier and checks
+ for the non existence of something in the Working Memory. Think of <code>not</code>
as meaning "there must be none of...".</para>
- <para>A 'not' statement must be followed by parentheses around the CEs
+ <para>A <code>not</code> statement must be followed by parentheses around the CEs
that it applies to. In the simplest case of a single pattern (like
below) you may optionally omit the parentheses.</para>
<example>
<title>No Busses</title>
- <programlisting>not Bus()</programlisting>
+<screen>not Bus()</screen>
</example>
<example>
<title>No red Busses</title>
- <programlisting>not Bus(color == "red") //brackets are optional for this simple pattern
+<screen>not Bus(color == "red") //brackets are optional for this simple pattern
not ( Bus(color == "red", number == 42) ) //brackets are optional for this simple case
not ( Bus(color == "red") and Bus(color == "blue")) // not with nested 'and' infix used here as ony two patterns
- (but brackets are required).</programlisting>
+
+(but brackets are required).</screen>
</example>
</section>
<section>
- <title>'exists'</title>
+ <title><code>exists</code></title>
<figure>
<title>exists</title>
@@ -1312,7 +1313,7 @@
</mediaobject>
</figure>
- <para>'exists' is first order logic's Existential Quantifier and checks
+ <para><code>exists</code> is first order logic's Existential Quantifier and checks
for the existence of something in the Working Memory. Think of exist as
meaning "at least one..". It is different from just having the Pattern
on its own; which is more like saying "for each one of...". if you use
@@ -1320,27 +1321,27 @@
of how much data there is in working memory that matches that
condition.</para>
- <para>An 'exist' statement must be followed by parentheses around the
+ <para>An <code>exist</code> statement must be followed by parentheses around the
CEs that it applies to. In the simplest case of a single pattern (like
below) you may optionally omit the parentheses.</para>
<example>
<title>Atleast one Bus</title>
- <programlisting>exists Bus()</programlisting>
+<screen>exists Bus()</screen>
</example>
<example>
<title>Atleast one red Bus</title>
- <programlisting>exists Bus(color == "red")
+<screen>exists Bus(color == "red")
exists ( Bus(color == "red", number == 42) ) //brackets are optional
-exists ( Bus(color == "red") and Bus(color == "blue")) // exists with nested 'and' infix used here as ony two patterns</programlisting>
+exists ( Bus(color == "red") and Bus(color == "blue")) // exists with nested 'and' infix used here as ony two patterns</screen>
</example>
</section>
<section>
- <title>'forall'</title>
+ <title><code>forall</code></title>
<figure>
<title>forall</title>
@@ -1359,14 +1360,14 @@
when all facts that match the first pattern match all the remaining
patterns. Example:</para>
- <programlisting>rule "All english buses are red"
+<screen>rule "All english buses are red"
when
forall( $bus : Bus( type == 'english')
Bus( this == $bus, color = 'red' ) )
then
# all english buses are red
end
-</programlisting>
+</screen>
<para>In the above rule, we "select" all Bus object whose type is
"english". Then, for each fact that matches this pattern we evaluate the
@@ -1380,19 +1381,19 @@
<para><example>
<title>Single Pattern Forall</title>
- <programlisting>rule "All Buses are Red"
+<screen>rule "All Buses are Red"
when
forall( Bus( color == 'red' ) )
then
# all asserted Bus facts are red
end
-</programlisting>
+</screen>
</example> The above is exactly the same as writing:</para>
<para>Another example of multi-pattern forall:<example>
<title>Multi-Pattern Forall</title>
- <programlisting>rule "all employees have health and dental care programs"
+<screen>rule "all employees have health and dental care programs"
when
forall( $emp : Employee()
HealthCare( employee == $emp )
@@ -1401,7 +1402,7 @@
then
# all employees have health and dental care
end
-</programlisting>
+</screen>
</example></para>
<para>Forall can be nested inside other CEs for complete expressiveness.
@@ -1411,7 +1412,7 @@
must be used :<example>
<title>Combining Forall with Not CE</title>
- <programlisting>rule "not all employees have health and dental care"
+<screen>rule "not all employees have health and dental care"
when
not ( forall( $emp : Employee()
HealthCare( employee == $emp )
@@ -1420,18 +1421,20 @@
then
# not all employees have health and dental care
end
-</programlisting>
+</screen>
</example></para>
- <para>As a side note, forall Conditional Element is equivalent to
+<note>
+ <para>the <code>forall</code> Conditional Element is equivalent to
writing:</para>
-
- <programlisting>not( <replaceable><first pattern></replaceable> and not ( and <replaceable><remaining patterns></replaceable> ) )</programlisting>
-
- <para>Also, it is important to note that <emphasis role="bold">forall is
+</note>
+<screen>not( <replaceable><first pattern></replaceable> and not ( and <replaceable><remaining patterns></replaceable> ) )</screen>
+<important>
+ <para><emphasis><code>forall</code> is
a scope delimiter</emphasis>, so it can use any previously bound
variable, but no variable bound inside it will be available to use
outside of it.</para>
+</important>
</section>
<section>
@@ -1447,7 +1450,7 @@
</mediaobject>
</figure>
- <para>The <emphasis role="bold">from</emphasis> Conditional Element
+ <para>The <code>from</code> Conditional Element
allows users to specify a source for patterns to reason over. This
allows the engine to reason over data not in the Working Memory. This
could be a sub-field on a bound variable or the results of a method
@@ -1457,34 +1460,33 @@
using hibernate named queries.</para>
<para>The expression used to define the object source is any expression
- that follows regular MVEL syntax. I.e., it allows you to easily use
- object property navigation, execute method calls and access maps and
+ that follows regular MVEL syntax. I.e., it allows for easy use of object property navigation, execute method calls and access maps and
collections elements.</para>
<para>Here is a simple example of reasoning and binding on another
pattern sub-field:</para>
- <para><programlisting>rule "validate zipcode"
+<para><screen>rule "validate zipcode"
when
Person( $personAddress : address )
Address( zipcode == "23920W") from $personAddress
then
# zip code is ok
end
-</programlisting></para>
+</screen></para>
<para>With all the flexibility from the new expressiveness in the Drools
- engine you can slice and dice this problem many ways. This is the same
- but shows how you can use a graph notation with the 'from':</para>
+ engine, this problem can be solved in numerious ways. This is the same
+ but shows how graph notation can be used with <code>from</code>:</para>
- <para><programlisting>rule "validate zipcode"
+<para><screen>rule "validate zipcode"
when
$p : Person( )
$a : Address( zipcode == "23920W") from $p.address
then
# zip code is ok
end
-</programlisting></para>
+</screen></para>
<para>Previous examples were reasoning over a single pattern. The
<emphasis role="bold">from</emphasis> CE also support object sources
@@ -1494,14 +1496,14 @@
we want a rule that applies 10% discount to each item in an order, we
could do:</para>
- <programlisting>rule "apply 10% discount to all items over US$ 100,00 in an order"
+<screen>rule "apply 10% discount to all items over US$ 100,00 in an order"
when
$order : Order()
$item : OrderItem( value > 100 ) from $order.items
then
# apply discount to $item
end
-</programlisting>
+</screen>
<para>The above example will cause the rule to fire once for each item
whose value is greater than 100 for each given order.</para>
@@ -1525,12 +1527,12 @@
</mediaobject>
</figure>
- <para>The <emphasis role="bold">collect</emphasis> Conditional Element
- allows rules to reason over collection of objects collected from the
+ <para>The <code>collect</code> Conditional Element
+ allows rules to reason over a collection of objects collected from the
given source or from the working memory. In first oder logic terms this
is Cardinality Quantifier. A simple example:</para>
- <programlisting>import java.util.ArrayList
+<screen>import java.util.ArrayList
rule "Raise priority if system has more than 3 pending alarms"
when
@@ -1542,35 +1544,31 @@
# 3 or more alarms pending. The pending alarms
# are $alarms.
end
-</programlisting>
+</screen>
<para>In the above example, the rule will look for all pending alarms in
the working memory for each given system and group them in ArrayLists.
If 3 or more alarms are found for a given system, the rule will
fire.</para>
- <para>The <emphasis role="bold">collect</emphasis> CE result pattern can
+ <para>The <code>collect</code> CE result pattern can
be any concrete class that implements tha java.util.Collection interface
- and provides a default no-arg public constructor. I.e., you can use
- default Java collections like ArrayList, LinkedList, HashSet, etc, or
+ and provides a default no-arg public constructor. For isntance, it can be used by default in Java collections similar to ArrayList, LinkedList, HashSet, etc, or
your own class, as long as it implements the java.util.Collection
interface and provide a default no-arg public constructor.</para>
<para>Both source and result patterns can be constrained as any other
pattern.</para>
- <para>Variables bound before the <emphasis
- role="bold">collect</emphasis> CE are in the scope of both source and
- result patterns and as so, you can use them to constrain both your
- source and result patterns. Although, the <emphasis>collect( ...
- )</emphasis> is a scope delimiter for bindings, meaning that any binding
+ <para>Variables bound before the <code>collect</code> CE are in the scope of both source and
+ result patterns and as so, can be used to constrain both source and result patterns. Although, the <code>collect( ...
+ )</code> is a scope delimiter for bindings, meaning that any binding
made inside of it, is not available for use outside of it.</para>
- <para>Collect accepts nested <emphasis role="bold">from</emphasis>
- elements, so the following example is a valid use of <emphasis
- role="bold">collect</emphasis>:</para>
+ <para>Collect accepts nested <code>from</code>
+ elements, so the following example is a valid use of <code>collect</code>:</para>
- <programlisting>import java.util.LinkedList;
+<code>import java.util.LinkedList;
rule "Send a message to all mothers"
when
@@ -1582,11 +1580,11 @@
then
# send a message to all mothers
end
-</programlisting>
+</code>
</section>
<section>
- <title>'accumulate'</title>
+ <title><code>accumulate</code></title>
<figure>
<title>accumulate</title>
@@ -1598,49 +1596,47 @@
</mediaobject>
</figure>
- <para>The <emphasis role="bold">accumulate</emphasis> Conditional
- Element is a more flexible and powerful form of <emphasis
- role="bold">collect</emphasis> Conditional Element, in the sense that it
- can be used to do what <emphasis role="bold">collect</emphasis> CE does
- and also do things that <emphasis role="bold">collect</emphasis> CE is
+ <para>The <code>accumulate</code> Conditional
+ Element is a more flexible and powerful form of <code>collect</code> Conditional Element, in the sense that it
+ can be used to do what <code>collect</code> CE does
+ and also do things that <code>collect</code> CE is
not capable to do. Basically what it does is it allows a rule to iterate
over a collection of objects, executing custom actions for each of the
elements, and at the end return a result object.</para>
- <para>The general syntax of the <emphasis
- role="bold">accumulate</emphasis> CE is:</para>
+<para>The general syntax of the <code>accumulate</code> CE is:</para>
- <programlisting><replaceable><result pattern></replaceable> from accumulate( <replaceable><source pattern></replaceable>,
- init( <replaceable><init code></replaceable> ),
- action( <replaceable><action code></replaceable> ),
- reverse( <replaceable><reverse code></replaceable> ),
- result( <replaceable><result expression></replaceable> ) )
-</programlisting>
+<screen><replaceable><result pattern></replaceable> from accumulate( <replaceable><source pattern></replaceable>,
+ init( <replaceable><init code></replaceable> ),
+ action( <replaceable><action code></replaceable> ),
+ reverse( <replaceable><reverse code></replaceable> ),
+ result( <replaceable><result expression></replaceable> ) )
+</screen>
<para>The meaning of each of the elements is the following:</para>
<itemizedlist>
<listitem>
- <para><emphasis role="bold"><source pattern></emphasis>: the
+ <para><code><source pattern></code>: the
source pattern is a regular pattern that the engine will try to
match against each of the source objects.</para>
</listitem>
<listitem>
- <para><emphasis role="bold"><init code></emphasis>: this is a
+ <para><code><init code></code>: this is a
semantic block of code in the selected dialect that will be executed
once for each tuple, before iterating over the source
objects.</para>
</listitem>
<listitem>
- <para><emphasis role="bold"><action code></emphasis>: this is
+ <para><code><action code></code>: this is
a semantic block of code in the selected dialect that will be
executed for each of the source objects.</para>
</listitem>
<listitem>
- <para><emphasis role="bold"><reverse code></emphasis>: this is
+ <para><code><reverse code></code>: this is
an optional semantic block of code in the selected dialect that if
present will be executed for each source object that no longer
matches the source pattern. The objective of this code block is to
@@ -1651,27 +1647,27 @@
</listitem>
<listitem>
- <para><emphasis role="bold"><result expression></emphasis>:
+ <para><code><result expression></code>:
this is a semantic expression in the selected dialect that is
executed after all source objects are iterated.</para>
</listitem>
<listitem>
- <para><emphasis role="bold"><result pattern></emphasis>: this
+ <para><code><result pattern></code>: this
is a regular pattern that the engine tries to match against the
object returned from the <result expression>. If it matches,
- the <emphasis role="bold">accumulate</emphasis> conditional element
- evaluates to <emphasis role="bold">true</emphasis> and the engine
+ the <code>accumulate</code> conditional element
+ evaluates to <emphasis>true</emphasis> and the engine
proceeds with the evaluation of the next CE in the rule. If it does
- not matches, the <emphasis role="bold">accumulate</emphasis> CE
- evaluates to <emphasis role="bold">false</emphasis> and the engine
+ not matches, the <code>accumulate</code> CE
+ evaluates to <emphasis>false</emphasis> and the engine
stops evaluating CEs for that rule.</para>
</listitem>
</itemizedlist>
<para>It is easier to understand if we look at an example:</para>
- <programlisting>rule "Apply 10% discount to orders over US$ 100,00"
+<screen>rule "Apply 10% discount to orders over US$ 100,00"
when
$order : Order()
$total : Number( doubleValue > 100 )
@@ -1683,16 +1679,14 @@
then
# apply discount to $order
end
-</programlisting>
+</screen>
<para>In the above example, for each Order() in the working memory, the
- engine will execute the <emphasis role="bold">init code</emphasis>
+ engine will execute the <emphasis>init code</emphasis>
initializing the total variable to zero. Then it will iterate over all
- OrderItem() objects for that order, executing the <emphasis
- role="bold">action</emphasis> for each one (in the example, it will sum
+ OrderItem() objects for that order, executing the <code>action</code> for each one (in the example, it will sum
the value of all items into the total variable). After iterating over
- all OrderItem, it will return the value corresponding to the <emphasis
- role="bold">result expression</emphasis> (in the above example, the
+ all OrderItem, it will return the value corresponding to the <emphasis>result expression</emphasis> (in the above example, the
value of the total variable). Finally, the engine will try to match the
result with the Number() pattern and if the double value is greater than
100, the rule will fire.</para>
@@ -1703,16 +1697,16 @@
If the user uses any other dialect, he must comply to that dialect
specific syntax.</para>
- <para>As mentioned before, the <emphasis role="bold">reverse
+ <para>As mentioned before, the <emphasis>reverse
code</emphasis> is optional, but it is strongly recommended that the
user writes it in order to benefit from the <emphasis>improved
performance on update and retracts</emphasis>.</para>
- <para>The <emphasis role="bold">accumulate</emphasis> CE can be used to
+<para>The <code>accumulate</code> CE can be used to
execute any action on source objects. The following example instantiates
and populates a custom object:</para>
- <programlisting>rule "Accumulate using custom objects"
+<screen>rule "Accumulate using custom objects"
when
$person : Person( $likes : likes )
$cheesery : Cheesery( totalAmount > 100 )
@@ -1723,7 +1717,7 @@
result( cheesery ) );
then
// do something
-end</programlisting>
+end</screen>
<section>
<title>Accumulate Functions</title>
@@ -1738,7 +1732,7 @@
the previous section, could be written in the following way, using
Accumulate Functions:</para>
- <programlisting>rule "Apply 10% discount to orders over US$ 100,00"
+<screen>rule "Apply 10% discount to orders over US$ 100,00"
when
$order : Order()
$total : Number( doubleValue > 100 )
@@ -1747,7 +1741,7 @@
then
# apply discount to $order
end
-</programlisting>
+</screen>
<para>In the above example, sum is an AccumulateFunction and will sum
the $value of all OrderItems and return the result.</para>
@@ -1778,11 +1772,11 @@
</itemizedlist>
<para>These common functions accept any expression as input. For
- instance, if someone wants to calculate the average profit on all
+ instance, if someone wishes to calculate the average profit on all
items of an order, a rule could be written using the average
function:</para>
- <programlisting>rule "Average profit"
+<screen>rule "Average profit"
when
$order : Order()
$profit : Number()
@@ -1791,7 +1785,7 @@
then
# average profit for $order is $profit
end
-</programlisting>
+</screen>
<para>Accumulate Functions are all pluggable. That means that if
needed, custom, domain specific functions can easily be added to the
@@ -1802,9 +1796,9 @@
line to the configuration file or set a system property to let the
engine know about the new function. As an example of an Accumulate
Function implementation, the following is the implementation of the
- "average" function:</para>
+ <code>average</code> function:</para>
- <programlisting>/*
+<screen>/*
* Copyright 2007 JBoss Inc
*
* Licensed under the Apache License, Version 2.0 (the "License");
@@ -1889,19 +1883,19 @@
}
}
-</programlisting>
+</screen>
<para>The code for the function is very simple, as we could expect, as
- all the "dirty" integration work is done by the engine. Finally, to
+ all the integration work is done by the engine. Finally, to
plug the function into the engine, we added it to the configuration
file:</para>
- <programlisting>drools.accumulate.function.average = org.drools.base.accumulators.AverageAccumulateFunction
-</programlisting>
+<screen>drools.accumulate.function.average = org.drools.base.accumulators.AverageAccumulateFunction
+</screen>
- <para>Where "drools.accumulate.function." is a prefix that must always
- be used, "average" is how the function will be used in the rule file,
- and "org.drools.base.accumulators.AverageAccumulateFunction" is the
+<para>Where <code>drools.accumulate.function.</code> is a prefix that must always
+ be used, <code>average</code> is how the function will be used in the rule file,
+ and "<classname>org.drools.base.accumulators.AverageAccumulateFunction</classname> is the
fully qualified name of the class that implements the function
behavior.</para>
</section>
@@ -1914,41 +1908,40 @@
<para>The Right Hand Side (RHS) is a common name for the consequence or
action part of the rule; this part should contain a list of actions to be
executed. It is bad practice to use imperative or conditional code in the
- RHS of a rule; as a rule should be atomic in nature - "when this, then do
+ RHS of a rule; as a rule should be atomic in nature. For example; "when this, then do
this", not "when this, maybe do this". The RHS part of a rule should also
- be kept small, thus keeping it declarative and readable. If you find you
- need imperative and/or conditional code in the RHS, then maybe you should
- be breaking that rule down into multiple rules. The main purpose of the
+ be kept small, thus keeping it declarative and readable. If needing imperative and/or conditional code in the RHS, then consider breaking that rule down into multiple rules. The main purpose of the
RHS is to insert, retractor modify working memory data. To assist with
there there are a few convenience methods you can use to modify working
memory; without having to first reference a working memory
instance.</para>
- <para>"update(object, handle);" will tell the engine that an object has
+ <para><methodname>update(object, handle);</methodname> will tell the engine that an object has
changed (one that has been bound to something on the LHS) and rules may
need to be reconsidered.</para>
- <para>"insert(new Something());" will place a new object of your creation
+<para><methodname>insert(new Something</methodname> will place a new object of your creation
in working memory.</para>
- <para>"insertLogical(new Something());" is similar to insert, but the
+<para><methodname>insertLogical(new Something</methodname> is similar to insert, but the
object will be automatically retracted when there are no more facts to
support the truth of the currently firing rule.</para>
- <para>"retract(handle);" removes an object from working memory.</para>
+<para><methodname>retract(handle);</methodname> removes an object from working memory.</para>
<para>These convenience methods are basically macros that provide short
cuts to the KnowldgeHelper instance (refer to the KnowledgeHelper
interface for more advanced operations). The KnowledgeHelper interface is
- made available to the RHS code block as a variable called "drools". If you
- provide "Property Change Listeners" to your Java beans that you are
- inserting into the engine, you can avoid the need to call "update" when
- the object changes.</para>
+ made available to the RHS code block as a variable called <code>drools</code>. If
+ providing <emphasis>Property Change Listeners</emphasis> to the Java beans that are being
+ inserted into the engine, the need to call <methodname>update</methodname> when
+ the object changes can be avoided.</para>
</section>
<section>
<title>A note on auto boxing/unboxing and primitive types</title>
+ <note>
<para>Drools attempts to preserve numbers in their primitive or object
wrapper form, so a variable bound to an int primitive when used in a code
block or expression will no longer need manual unboxing; unlike Drools 3.0
@@ -1958,5 +1951,6 @@
evaluating field constraints the system attempts to coerce one of the
values into a comparable format; so a primitive is comparable to an object
wrapper.</para>
+</note>
</section>
</section>
More information about the jboss-svn-commits
mailing list