[jboss-svn-commits] JBL Code SVN: r25877 - labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Sun Mar 29 21:50:41 EDT 2009
Author: mark.proctor at jboss.com
Date: 2009-03-29 21:50:40 -0400 (Sun, 29 Mar 2009)
New Revision: 25877
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Comments.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-ErrorMessages.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Keywords.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Overview.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Package.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Query.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Rule.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-TypeDeclaration.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-XML.xml
Log:
JBRULES-2013 Documentation patches for Drools Expert
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Comments.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Comments.xml 2009-03-30 00:43:14 UTC (rev 25876)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Comments.xml 2009-03-30 01:50:40 UTC (rev 25877)
@@ -24,8 +24,8 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-Rule_Language/single_line_comment.png"
- format="PNG" />
+ <imagedata align="center" fileref="images/Chapter-Rule_Language/single_line_comment.svg"
+ format="SVG" />
</imageobject>
</mediaobject>
</figure>
@@ -47,15 +47,15 @@
</section>
<section>
- <title>Multi line comment</title>
+ <title>Multi-line comment</title>
<figure>
- <title>Multi line comment</title>
+ <title>Multi-line comment</title>
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-Rule_Language/multi_line_comment.png"
- format="PNG" />
+ <imagedata align="center" fileref="images/Chapter-Rule_Language/multi_line_comment.svg"
+ format="SVG" />
</imageobject>
</mediaobject>
</figure>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-ErrorMessages.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-ErrorMessages.xml 2009-03-30 00:43:14 UTC (rev 25876)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-ErrorMessages.xml 2009-03-30 01:50:40 UTC (rev 25877)
@@ -15,8 +15,8 @@
<para>Drools 5 introduces standardized error messages. This standardization
aims to help users to find and resolve problems in a easier and faster way.
In this section you will learn how to identify and interpret those error
- messages as well some tips on how to solve the problems associated with
- them.</para>
+ messages, and you will also receive some tips on how to solve the problems
+ associated with them.</para>
<section>
<title>Message format</title>
@@ -59,8 +59,8 @@
<section>
<title>101: No viable alternative</title>
- <para>Most common kind of error, means that the parser came to a
- decision point but it couldn't identify an alternative. Here as some
+ <para>Indicates the most common errors, where the parser came to a
+ decision point but couldn't identify an alternative. Here are some
examples:</para>
<example>
@@ -82,7 +82,7 @@
</listitem>
</itemizedlist>
- <para>At first moment seems to be a valid syntax, but it is not (exits
+ <para>At first glance this seems to be valid syntax, but it is not (exits
!= exists). Let's take a look at next example:</para>
<example>
@@ -110,7 +110,7 @@
In this case, it is missing the rule name.</para>
<para>No viable alternative error occurs also when you have lexical
- problems. Here is a sample of lexical problem:</para>
+ problems. Here is a sample of a lexical problem:</para>
<example>
<programlisting>1: rule simple_rule
@@ -134,8 +134,8 @@
<tip>
<para>Usually the Line and Column information are accurate, but in
some cases (like unclosed quotes), the parser generates a 0:-1
- position. In this case you should check if you didn't forget to close
- quotes nor brackets.</para>
+ position. In this case you should check whether you didn't forget to close
+ quotes, apostrophes or parentheses.</para>
</tip>
</section>
@@ -170,7 +170,7 @@
reached the end of source.</para>
</tip>
- <para>The following code generates more than one error messages:</para>
+ <para>The following code generates more than one error message:</para>
<example>
<programlisting>1: package org.drools;
@@ -207,16 +207,16 @@
just replace the commas (",") by AND operator ("&&").</para>
<tip>
- <para>Some situations you can get more than one error message. Try to
+ <para>In some situations you can get more than one error message. Try to
fix one by one, starting at the first one. Some error messages are
- generated as consequences of others.</para>
+ generated merely as consequences of other errors.</para>
</tip>
</section>
<section>
<title>103: Failed predicate</title>
- <para>A validating semantic predicates evaluated to false. Usually this
+ <para>A validating semantic predicate evaluated to false. Usually these
semantic predicates are used to identify soft keywords. This sample
shows exactly this situation:</para>
@@ -249,19 +249,20 @@
</itemizedlist>
<para>The <emphasis role="bold">fdsfdsfds</emphasis> text is invalid and
- the parser couldn’t identify it as the RULE soft keyword.</para>
+ the parser couldn’t identify it as the soft keyword "rule".</para>
<tip>
- <para>This error is very similar to 102: Mismatched input but usually
- involve soft keywords.</para>
+ <para>This error is very similar to 102: Mismatched input, but usually
+ involves soft keywords.</para>
</tip>
</section>
<section>
<title>104: Trailing semi-colon not allowed</title>
- <para>This error is associated with EVAL clause (at EVAL expression you
- cannot use a semi-colon). Check this sample:</para>
+ <para>This error is associated with the "eval" clause, where its
+ expression may not be terminated with a semi-colon. Check this
+ example:</para>
<example>
<programlisting>1: rule simple_rule
@@ -272,7 +273,7 @@
</programlisting>
</example>
- <para>Due its trailling semi-colon at eval, we get this error
+ <para>Due to the trailing semi-colon within eval, we get this error
message:</para>
<itemizedlist>
@@ -282,7 +283,7 @@
</listitem>
</itemizedlist>
- <para>This is the simpler problem to fix: just remove the
+ <para>This problem is simple to fix: just remove the
semi-colon.</para>
</section>
@@ -290,9 +291,9 @@
<title>105: Early Exit</title>
<para>The recognizer came to a (..)+ EBNF subrule that must match an
- alternative at least once, but the subrule did not match anything. To
- simplify: the parser followed a path that there is no way out. This
- example tries to illustrates it:</para>
+ alternative at least once, but the subrule did not match anything.
+ Simply put: the parser has entered a branch from where there is no
+ way out. This example tries to illustrates it:</para>
<example>
<programlisting>1: template test_error
@@ -311,8 +312,8 @@
</itemizedlist>
<para>To fix this problem it is necessary to remove the numeric value
- (as it is not a valid sentence nor a valid data type to begin a new
- slot).</para>
+ as it is neither a valid data type which might begin a new template
+ slot nor a possible start for any other rule file construct.</para>
</section>
</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Keywords.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Keywords.xml 2009-03-30 00:43:14 UTC (rev 25876)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Keywords.xml 2009-03-30 01:50:40 UTC (rev 25877)
@@ -213,12 +213,12 @@
<para>Another improvement on DRL language is the ability to escape hard
keywords on rule text. This new feature enables you to use your existing
- domain objects without worring about keyword collision. To escape a word,
- simple type it between a grave accent, like this:</para>
+ domain objects without worrying about keyword collision. To escape a word,
+ simple type it between grave accents, like this:</para>
<programlisting>Holiday( `when` == "july" )</programlisting>
- <para>The escape should be used everywehere in rule text, except at code
+ <para>The escape should be used everywehere in rule text, except within code
expressions in the LHS or RHS code block. Here are examples of
usage:</para>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Overview.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Overview.xml 2009-03-30 00:43:14 UTC (rev 25876)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Overview.xml 2009-03-30 01:50:40 UTC (rev 25877)
@@ -72,14 +72,15 @@
<emphasis role="bold">then</emphasis>
<replaceable>RHS</replaceable>
<emphasis role="bold">end</emphasis>
-</programlisting>Its really that simple. Mostly punctuation is not needed,
+</programlisting>It's really that simple. Mostly punctuation is not needed,
even the double quotes for "name" are optional, as are newlines.
Attributes are simple (always optional) hints to how the rule should
behave. LHS is the conditional parts of the rule, which follows a certain
syntax which is covered below. RHS is basically a block that allows
dialect specific semantic code to be executed.</para>
- <para>It is important to note that white space is not important, EXCEPT in
+ <para>It is important to note that white space is not important,
+ <empahsis>except</empahsis> in
these case of domain specific languages, in which case each line is
processed before the following line (and spaces may be significant to the
domain language).</para>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Package.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Package.xml 2009-03-30 00:43:14 UTC (rev 25876)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Package.xml 2009-03-30 01:50:40 UTC (rev 25877)
@@ -27,13 +27,13 @@
have all the rules for a package in the same file as the package declaration
(so that is it entirely self contained).</para>
- <para>The following rail road diagram shows all the components that may make
- up a package. Note that a package MUST have a namespace and be declared
- using standard Java conventions for package names; i.e. no spaces, unlike
+ <para>The following railroad diagram shows all the components that may make
+ up a package. Note that a package <emphasis>must</emphasis> have a namespace and be declared
+ using standard Java conventions for package names; i.e., no spaces, unlike
rule names which allow spaces. In terms of the order of elements, they can
appear in any order in the rule file, with the exception of the "package"
and "expander" statements being at the top of the file, before any rules
- appear. In all cases, the semi colons are optional.</para>
+ appear. In all cases, the semicolons are optional.</para>
<figure>
<title>package</title>
@@ -82,10 +82,10 @@
<para>The expander statement (optional) is used to specify domain specific
language (DSL) configurations (which are normally stored in a separate
- file). This provides clues to the parser as how to understand what you are
+ file). This provides clues to the parser how to understand what you are
raving on about in your rules. It is important to note that in Drools 4.0
(that is different from Drools 3.x) the expander declaration is mandatory
- for the tools to provide you context assist and avoiding error reporting,
+ for the tools to provide you context assistacnce and to avoid error reporting,
but the API allows the program to apply DSL templates, even if the
expanders are not declared in the source file.</para>
</section>
@@ -110,9 +110,10 @@
consequences), to return data from the rules (like logs or values added in
rules consequence) or for the rules to interact with the application doing
callbacks. Globals are not inserted into the Working Memory so they should
- never be reasoned over, and only use them in rules LHS if the global has a
- constant immutable value. The engine is not notified and does not track
- globals value changes. Incorrect use of globals in constraints may yield
+ never be reasoned over; you should use them in rules' LHS only if the global has a
+ constant immutable value. The engine cannot be notified about value
+ changes of globals, and does not track their changes. Incorrect use
+ of globals in constraints may yield
surprising results - surprising in a bad way, like when a doctor says
"thats interesting" to a chest XRay of yours.</para>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Query.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Query.xml 2009-03-30 00:43:14 UTC (rev 25876)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Query.xml 2009-03-30 01:50:40 UTC (rev 25877)
@@ -21,19 +21,20 @@
<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
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") -
- where "name" is query name. Query names are global to the RuleBase, so do
+ parameters, each of which can also be optionally typed. If type is not
+ given then Object type is assumed. The engine will attempt to co-erce
+ the values as needed. 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
- the objects that matched the query.</para>
+ Base.</para>
- <para>This example creates a simple query for all the people over the age of
- 30</para>
+ <para>To return the results use WorkingMemory.getQueryResults("name"),
+ where "name" is the query's name. This returns a list of query results,
+ which allow you to to get to the objects that matched the query.</para>
+ <para>The first example creates a simple query for all the people over
+ the age of 30. The second one, using parameters, combines the age limit
+ with a location.</para>
+
<example>
<title>Query People over the age of 30</title>
@@ -43,16 +44,16 @@
</example>
<example>
- <title>Query People over the age of X, and who live in y</title>
+ <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)
+ <programlisting>query "people over the age of x" (int x, String y)
person : Person( age > x, location == y )
end</programlisting>
</example>
<para>We iterate over the returned QueryResults using a standard 'for' 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
+ Each element returns a QueryResult which we can use to access each of the
+ columns in the Tuple. Those columns can be accessed by bound declaration name
or index position.</para>
<example>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Rule.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Rule.xml 2009-03-30 00:43:14 UTC (rev 25876)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-Rule.xml 2009-03-30 01:50:40 UTC (rev 25877)
@@ -27,11 +27,11 @@
specific evaluation sequence or point in time, at any time during the life
time of the engine "when" this occurs, do that Rule.</para>
- <para>A rule must have a name, and be a unique name for the rule package. If
- you define a rule twice in the same DRL it produce an error while loading.
- If you add a DRL that has includes a rule name already in the package, it
- will replace the previous rule. If a rule name is to have spaces, then it
- will need to be in double quotes (it is best to always use double
+ <para>A rule must have a name, unique within its rule package. If
+ you define a rule twice in the same DRL it produces an error while loading.
+ If you add a DRL that includes a rule name already in the package, it
+ replaces the previous rule. If a rule name is to have spaces, then it
+ will need to be enclosd in double quotes (it is best to always use double
quotes).</para>
<para>Attributes are optional, and are described below (they are best kept
@@ -75,8 +75,8 @@
<title>Rule Attributes</title>
<para>Rule attributes provide a declarative way to influence the behavior
- of the rule, some are quite simple, while others are part of complex sub
- systems; such as ruleflow. To get the most from Drools you should make
+ of the rule. Some are quite simple, while others are part of complex sub
+ systems such as ruleflow. To get the most from Drools you should make
sure you have a proper understanding of each attribute.</para>
<figure>
@@ -84,139 +84,159 @@
<mediaobject>
<imageobject>
- <imagedata align="center" fileref="images/Chapter-Rule_Language/rule_attributes.png" format="PNG" />
+ <imagedata align="center" fileref="images/Chapter-Rule_Language/rule_attributes.png" format="PNG" />
</imageobject>
</mediaobject>
</figure>
<variablelist>
- <varlistentry>
- <term>no-loop</term>
+ <varlistentry>
+ <term>no-loop</term>
- <listitem>
- <para>default value : false</para>
+ <listitem>
+ <para>default value: false</para>
- <para>type : Boolean</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>
+ <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>
- <varlistentry>
- <term>lock-on-active</term>
+ <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 have 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>
+ <listitem>
+ <para>default value: false</para>
+
+ <para>type: Boolean</para>
+ <para>Whenever a ruleflow-group becomes active or an
+ agenda-group receives the focus, any rule within that
+ group that has lock-on-active set to true will not be
+ activated any more; irrespective of the origin of the
+ update, the activation of a matching rule is discarded.
+ This is a stronger version of no-loop, because the change
+ could now be caused not only by the rule itself. It's
+ ideal for calculation rules where you have a number of
+ rules that modify a fact and you don't want any rule
+ re-matching and firing again. Only when the ruleflow-group
+ is no longer active or the agenda-group loses the focus
+ those rules with lock-on-active set to true become
+ eligible again for their activations to be placed onto
+ the agenda.</para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>salience</term>
+ <varlistentry>
+ <term>salience</term>
- <listitem>
- <para>default value : 0</para>
+ <listitem>
+ <para>default value : 0</para>
- <para>type : integer</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>
+ <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>
+ <varlistentry>
+ <term>agenda-group</term>
- <listitem>
- <para>default value : MAIN</para>
+ <listitem>
+ <para>default value: MAIN</para>
+
+ <para>type: String</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>
+ <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>
+ <varlistentry>
+ <term>auto-focus</term>
- <listitem>
- <para>default value false</para>
+ <listitem>
+ <para>default value: false</para>
+
+ <para>type: Boolean</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>
+ <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>
+ <varlistentry>
+ <term>activation-group</term>
- <listitem>
- <para>default value : N/A</para>
+ <listitem>
+ <para>default value: N/A</para>
- <para>type : String</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>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>
+ <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>
+ <varlistentry>
+ <term>dialect</term>
- <listitem>
- <para>default value : as specified by the package</para>
+ <listitem>
+ <para>default value : as specified by the package</para>
- <para>type : String</para>
+ <para>type : String</para>
- <para>possible values: "java" or "mvel"</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>
+ <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>
+ <varlistentry>
+ <term>date-effective</term>
- <listitem>
- <para>default value : N/A</para>
+ <listitem>
+ <para>default value: N/A</para>
- <para>type : String, which contains a Date/Time definition</para>
+ <para>type: String, which contains a date and time definition</para>
- <para>A rule can only activate if the current date and time is after date-effective attribute.</para>
- </listitem>
- </varlistentry>
+ <para>A rule can only activate if the current date and time is after date-effective attribute.</para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>date-expires</term>
+ <varlistentry>
+ <term>date-expires</term>
- <listitem>
- <para>default value : N/A</para>
+ <listitem>
+ <para>default value: N/A</para>
- <para>type : String, which contains a Date/Time definition</para>
+ <para>type: String, which contains a date and time definition</para>
- <para>A rule cannot activate if the current date and time is after date-expires attribute.</para>
- </listitem>
- </varlistentry>
+ <para>A rule cannot activate if the current date and time is after date-expires attribute.</para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>duration</term>
+ <varlistentry>
+ <term>duration</term>
- <listitem>
- <para>default value : no default value</para>
+ <listitem>
+ <para>default value: no default value</para>
- <para>type : long</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>The duration dictates that the rule will fire after a specified duration, if it is still true.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<example>
<title>Some attribute examples</title>
@@ -235,7 +255,7 @@
<para>The Left Hand Side (LHS) is a common name for the conditional part
of the rule. It consists of zero or more Conditional Elements. If the LHS
is left empty it is re-written as eval(true), which means the rule is
- always true, and will be activated with a new Working Memory session is
+ always true, and will be activated when a new Working Memory session is
created.</para>
<figure>
@@ -249,7 +269,7 @@
</figure>
<example>
- <title>Rule Syntax Overview Example</title>
+ <title>Rule without a Conditional Element</title>
<programlisting>rule "no CEs"
when
@@ -267,21 +287,21 @@
end</programlisting>
</example>
- <para>Conditional elements work on one or more Patterns (which are
- described bellow). The most common one is "and" which is implicit when you
- have multiple Patterns in the LHS of a rule that are not connected in
- anyway. Note that an 'and' cannot have a leading declaration binding like
- 'or' - this is obvious when you think about it. A declaration can only
- reference a single Fact, when the 'and' is satisfied it matches more than
+ <para>Conditional elements work on one or more <emphasis>patterns</emphasis> (which are
+ described below). The most common one is "and" which is implicit when you
+ have multiple patterns in the LHS of a rule that are not connected in
+ any way. Note that an 'and' cannot have a leading declaration binding like
+ 'or'. This is obvious, since a declaration can only
+ reference a single fact, and when the 'and' is satisfied it matches more than
one fact - which fact would the declaration bind to?</para>
<section>
<title>Pattern</title>
- <para>The Pattern element is the most important Conditional Element. The
+ <para>The pattern element is the most important Conditional Element. The
entity relationship diagram below provides an overview of the various
- parts that make up the Pattern's constraints and how they work together;
- each is then covered in more detail with rail road diagrams and
+ parts that make up the pattern's constraints and how they work together;
+ each is then covered in more detail with railroad diagrams and
examples.</para>
<figure>
@@ -297,7 +317,7 @@
<para>At the top of the ER diagram you can see that the pattern consists
of zero or more constraints and has an optional pattern binding. The
- rail road diagram below shows the syntax for this.</para>
+ railroad diagram below shows the syntax for this.</para>
<figure>
<title>Pattern</title>
@@ -310,12 +330,12 @@
</mediaobject>
</figure>
- <para>At the simplest, with no constraints, it simply matches against a
- type, in the following case the type is "Cheese". This means the pattern
+ <para>In its simplest form, with no constraints, it simply matches against a
+ type. In the following case the type is "Cheese", which means that the pattern
will match against all Cheese objects in the Working Memory.</para>
<example>
- <title>Pattern</title>
+ <title>Simple Pattern</title>
<programlisting>Cheese( )</programlisting>
</example>
@@ -326,15 +346,15 @@
to more easily differentiation between variables and fields.</para>
<example>
- <title>Pattern</title>
+ <title>Pattern with a binding variable</title>
<programlisting>$c : Cheese( )</programlisting>
</example>
- <para>Inside of the Pattern parenthesis is where all the action happens.
+ <para>Inside of the pattern parenthesis is where all the action happens.
A constraint can be either a Field Constraint, Inline Eval (called a
predicate in 3.0) or a Constraint Group. Constraints can be separated by
- the following symbols ',', '&&' or '||'.</para>
+ the following symbols: ',', '&&' or '||'.</para>
<figure>
<title>Constraints</title>
@@ -371,7 +391,7 @@
</figure>
<para>The ',' (comma) character is used to separate constraint groups.
- It has an implicit 'and' connective semantics.<example>
+ It has implicit 'and' connective semantics.<example>
<title>Constraint Group connective ','</title>
<programlisting># Cheese type is stilton and price < 10 and age is mature.
@@ -486,21 +506,21 @@
objects follow the Java bean pattern, then fields are exposed using
"getXXX" or "isXXX" methods (these are methods that take no
arguments, and return something). You can access fields either by
- using the bean-name convention (so "getType" can be accessed as
+ using the bean naming convention (so "getType" can be accessed as
"type") - we use the standard jdk Introspector class to do this
mapping.</para>
- <para>For example, referring to our Cheese class, the following :
- Cheese(type == ...) uses the getType() method on the a cheese
+ <para>For example, referring to our Cheese class, the pattern
+ Cheese(type == ...) applies the getType() method to a Cheese
instance. If a field name cannot be found it will resort to calling
the name as a no argument method; "toString()" on the Object for
instance can be used with Cheese(toString == ..) - you use the full
- name of the method with correct capitalization, but not brackets. Do
+ name of the method with correct capitalization, but without parentheses. Do
please make sure that you are accessing methods that take no
- parameters, and are in-fact "accessors" (as in, they don't change
- the state of the object in a way that may effect the rules -
- remember that the rule engine effectively caches the results of its
- matching in between invocations to make it faster).</para>
+ parameters, and are in-fact "accessors" which don't change
+ the state of the object in a way that may effect the rules.
+ Remember that the rule engine effectively caches the results of its
+ matching in between invocations to make it faster.</para>
</section>
<section>
@@ -554,14 +574,15 @@
</mediaobject>
</figure>
- <para>You can do checks against fields that are or maybe null, using
+ <para>You can do checks against fields that are or may be null, using
== and != as you would expect, and the literal "null" keyword, like:
Cheese(type != null). If a field is null the evaluator will not
- throw an exception and will only return true if the value is a null
- check. Coercion is always attempted if the field and the value are
+ throw an exception and will only return true if the value is null.
+ Coercion is always attempted if the field and the value are
of different types; exceptions will be thrown if bad coercions are
- attempted. i.e. if "ten" is provided as a string in a number
- evaluator, where as "10" would coerce to a numeric 10. Coercion is
+ attempted. For instance, if "ten" is provided as a string in a number
+ evaluator an exception is thrown, whereas "10" would coerce to a
+ numeric 10. Coercion is
always in favor of the field type and not the value type.</para>
</section>
@@ -595,11 +616,11 @@
<para>Valid operators are dependent on the field type. Generally
they are self explanatory based on the type of data: for instance,
- for date fields, "<" means "before" and so on. "Matches" is
+ for date fields, "<" means "before". "Matches" is
only applicable to string fields, "contains" and "not contains" is
only applicable to Collection type fields. These operators can be
used with any value and coercion to the correct value for the
- evaluator and filed will be attempted, as mention in the "Values"
+ evaluator and field will be attempted, as mentioned in the "Values"
section.</para>
<simplesect>
@@ -609,7 +630,7 @@
<primary>regular expression</primary>
</indexterm>Regular Expression. Typically that regexp is a
String, but variables that resolve to a valid regexp are also
- allowed. It is important to note that <emphasis>different from
+ allowed. It is important to note that, <emphasis>different from
Java</emphasis>, if you write a String regexp directly on the
source file, <emphasis>you don't need to escape '\'</emphasis>.
Example:</para>
@@ -627,9 +648,9 @@
<para>Any valid Java <indexterm>
<primary>regular expression</primary>
</indexterm>Regular Expression can be used to match String
- fields. Returns true when the match is false. Typically that
+ fields. This operator returns true when the match is false. Typically that
regexp is a String, but variables that resolve to a valid regexp
- are also allowed.It is important to note that
+ are also allowed. It is important to note that,
<emphasis>different from Java</emphasis>, if you write a String
regexp directly on the source file, <emphasis>you don't need to
escape '\'</emphasis>. Example:</para>
@@ -664,7 +685,7 @@
<para><literal>'not contains'</literal> is used to check if a
field's <indexterm>
<primary>Collection</primary>
- </indexterm>Collection or array does not contains an
+ </indexterm>Collection or array does not contain an
object.</para>
<example>
@@ -672,23 +693,23 @@
<programlisting>CheeseCounter( cheeses not contains "cheddar" ) // not contains with a String literal
CheeseCounter( cheeses not contains $var ) // not contains with a variable</programlisting>
+ </example>
- <blockquote>
- <para><emphasis role="bold">NOTE: </emphasis>for backward
+ <blockquote>
+ <para><emphasis role="bold">NOTE: </emphasis>for backward
compatibility, the '<emphasis
role="bold">excludes</emphasis>' operator is supported as a
synonym for '<emphasis role="bold">not
contains</emphasis>'.</para>
- </blockquote>
- </example>
+ </blockquote>
</simplesect>
<simplesect>
<title>memberOf</title>
- <para><literal>'memberOf' is used to check if a field is a
+ <para><literal>'memberOf'</literal> is used to check if a field is a
member of a collection or array; that collection must be be a
- variable.</literal></para>
+ variable.</para>
<example>
<title>Literal Constraints with Collections</title>
@@ -700,9 +721,9 @@
<simplesect>
<title>not memberOf</title>
- <para><literal>'not memberOf' is used to check if a field is not
+ <para><literal>'not memberOf'</literal> is used to check if a field is not
a member of a collection or array; that collection must be be a
- variable.</literal></para>
+ variable.</para>
<example>
<title>Literal Constraints with Collections</title>
@@ -714,18 +735,17 @@
<simplesect>
<title>soundslike</title>
- <para><literal>Similar to 'matches', but checks if a word has
+ <para>Similar to <literal>'matches'</literal>, but checks if a word has
almost the same sound as the given value. Uses the 'Soundex'
algorithm
- (http://en.wikipedia.org/wiki/Soundex)</literal></para>
+ (<literal>http://en.wikipedia.org/wiki/Soundex</literal>).</para>
<example>
<title>Text with soundslike (Sounds Like)</title>
<programlisting>Cheese( name soundslike 'foobar' )</programlisting>
-
+ </example>
<para>This will match a cheese with a name of "fubar"</para>
- </example>
</simplesect>
</section>
@@ -749,7 +769,7 @@
<para>Literal Restrictions using the '==' operator, provide for
faster execution as we can index using hashing to improve
- performance;</para>
+ performance.</para>
<simplesect>
<title>Numeric</title>
@@ -794,9 +814,9 @@
<simplesect>
<title>Boolean</title>
- <para>only true or false can be used. 0 and 1 are not
- recognized, nor is <literal>Cheese ( smelly )</literal> is
- allowed</para>
+ <para>Only true or false can be used; 0 and 1 are not
+ recognized. A Boolean field alone (as in
+ <code>Cheese( smelly )</code> is not permitted.</para>
<example>
<title>Boolean Literal Restriction</title>
@@ -809,7 +829,7 @@
<title>Qualified Identifier</title>
<para>Enums can be used as well, both jdk1.4 and jdk5 style
- enums are supported - for the later you must be executing on a
+ enums are supported. For the latter you must be executing on a
jdk5 environment.</para>
<example>
@@ -854,12 +874,11 @@
<para>'likes' is our variable, our Declaration, that is bound to
the favouriteCheese field for any matching Person instance and
is used to constrain the type of Cheese in the following
- Pattern. Any valid Java variable name can be used, including
- '$'; which you will often see used to help differentiate
+ pattern. Any valid Java variable name can be used, and it may
+ be prefixed with a '$', which you will often see used to help differentiate
declarations from fields. The example below shows a declaration
- bound to the Patterns Object Type instance itself and used with
- a 'contains' operator, note the optional use of '$' this
- time.</para>
+ bound to the pattern's Object Type instance itself and used with
+ a 'contains' operator. Note the optional use of '$'.</para>
</example>
<example>
@@ -992,28 +1011,28 @@
</mediaobject>
</figure>
- <para>A <indexterm>
+ <para>An <indexterm>
<primary>Predicate</primary>
</indexterm>inline-eval constraint can use any valid dialect
expression as long as it is evaluated to a primitive boolean - avoid
- using any Drools keywords as Declaration identifiers. the expression
- must be time constant. Any previous bound variable, from the current
+ using any Drools keywords as Declaration identifiers. The expression
+ must be time constant. Any previously bound variable, from the current
or previous pattern, can be used; autovivification is also used to
- auto create field binding variables. When an identifier is found that
+ auto-create field binding variables. When an identifier is found that
is not a current variable the builder looks to see if the identifier
- is a field on the current object type, if it is, the field is auto
- created as a variable of the same name; this is autovivification of
- field variables inside of inline evals.</para>
+ is a field on the current object type, if it is, the field binding
+ is auto-created as a variable of the same name. This is called
+ autovivification of field variables inside of inline evals.</para>
- <para>This example will find all pairs of male/femal people where the
- male is 2 years older than the female; the boyAge variable is auto
- created as part of the autovivification process.</para>
+ <para>This example will find all male-female pairs where the
+ male is 2 years older than the female; the boyAge variable is
+ auto-created by the autovivification process.</para>
<example>
<title>Return Value operator</title>
<programlisting>Person( girlAge : age, sex = "F" )
-Person( eval( girlAge == boyAge + 2 ), sex = 'M' )
+Person( eval( age == girlAge + 2 ), sex = 'M' )
</programlisting>
</example>
</section>
@@ -1167,24 +1186,20 @@
</figure>
<example>
- <title>infixAnd</title>
+ <title>infixOr</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>
</example>
<para>The 'or' Conditional Element also allows for optional pattern
- binding; which means each resulting subrule will bind it's pattern to
- the pattern binding.</para>
+ binding; which means each resulting subrule will bind its pattern to
+ the pattern binding. Each pattern must be bound separately,
+ using eponymous variables:</para>
<example>
<title>or with binding</title>
- <programlisting>pensioner : (or Person( sex == "f", age > 60 )
- Person( sex == "m", age > 65 ) )</programlisting>
-
- <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>
</example>
@@ -1196,8 +1211,9 @@
match, activate and fire - there is no shortcutting.</para>
<para>The best way to think of the OR conditional element is as a
- shortcut for generating 2 additional rules. When you think of it that
- way, its clear that for a single rule there could be multiple
+ shortcut for generating two or more similar rules. When you think
+ of it that
+ way, it's clear that for a single rule there could be multiple
activations if both sides of the OR conditional element are true.</para>
</section>
@@ -1217,7 +1233,7 @@
<para>Eval is essentially a catch all which allows any semantic code
(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
+ rule package. Overuse of eval reduces the declarative-ness of your rules
and can result in a poor performing engine. While 'evals' 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>
@@ -1274,7 +1290,7 @@
<programlisting>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
+not ( Bus(color == "red") and Bus(color == "blue")) // not with nested 'and' infix used here as only two patterns
(but brackets are required).</programlisting>
</example>
</section>
@@ -1296,10 +1312,12 @@
<para>'exists' 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
- exist with a Pattern, then the rule will only activate once regardless
+ on its own; which is more like saying "for each one of...". If you use
+ exist with a Pattern, then the rule will only activate at most once,
+ regardless
of how much data there is in working memory that matches that
- condition.</para>
+ condition. Since only the existence matters, no bindings will be
+ established.</para>
<para>An 'exist' statement must be followed by parentheses around the
CEs that it applies to. In the simplest case of a single pattern (like
@@ -1312,7 +1330,7 @@
</example>
<example>
- <title>Atleast one red Bus</title>
+ <title>At least one red Bus</title>
<programlisting>exists Bus(color == "red")
exists ( Bus(color == "red", number == 42) ) //brackets are optional
@@ -1368,7 +1386,7 @@
# all asserted Bus facts are red
end
</programlisting>
- </example> The above is exactly the same as writing:</para>
+ </example></para>
<para>Another example of multi-pattern forall:<example>
<title>Multi-Pattern Forall</title>
@@ -1404,10 +1422,10 @@
</programlisting>
</example></para>
- <para>As a side note, forall Conditional Element is equivalent to
- writing:</para>
+ <para>As a side note, <code>not( forall( p1 p2 p3...))</code> is
+ equivalent to writing:</para>
- <programlisting>not( <replaceable><first pattern></replaceable> and not ( and <replaceable><remaining patterns></replaceable> ) )</programlisting>
+ <programlisting>not(p1 and not(and p2 p3...))</programlisting>
<para>Also, it is important to note that <emphasis role="bold">forall is
a scope delimiter</emphasis>, so it can use any previously bound
@@ -1493,7 +1511,8 @@
as it may produce unexpected results. Consider the example provided earlier, but
now slightly modified as follows:</para>
- <para><programlisting>rule "Assign people in North Carolina (NC) to sales region 1" ruleflow-group "test"
+ <para><programlisting>rule "Assign people in North Carolina (NC) to sales region 1"
+ruleflow-group "test"
lock-on-active true
when
$p : Person( )
@@ -1502,7 +1521,8 @@
modify ($p) {} #Assign person to sales region 1 in a modify block
end
-rule "Apply a discount to people in the city of Raleigh" ruleflow-group "test"
+rule "Apply a discount to people in the city of Raleigh"
+ruleflow-group "test"
lock-on-active true
when
$p : Person( )
@@ -1558,7 +1578,8 @@
the graph is fairly simple, an even easier solution is to modify your rules as follows:
</para>
- <para><programlisting>rule "Assign people in North Carolina (NC) to sales region 1" ruleflow-group "test"
+ <para><programlisting>rule "Assign people in North Carolina (NC) to sales region 1"
+ruleflow-group "test"
lock-on-active true
when
$p : Person(address.state == "NC" )
@@ -1566,7 +1587,8 @@
modify ($p) {} #Assign person to sales region 1 in a modify block
end
-rule "Apply a discount to people in the city of Raleigh" ruleflow-group "test"
+rule "Apply a discount to people in the city of Raleigh"
+ruleflow-group "test"
lock-on-active true
when
$p : Person(address.city == "Raleigh" )
@@ -1589,7 +1611,8 @@
the following use of <emphasis role="bold">from</emphasis> causes both rules to fire as expected:
</para>
- <para><programlisting>rule "Assign people in North Carolina (NC) to sales region 1" ruleflow-group "test"
+ <para><programlisting>rule "Assign people in North Carolina (NC) to sales region 1"
+ruleflow-group "test"
lock-on-active true
when
$p : Person($addresses : addresses)
@@ -1598,7 +1621,8 @@
modify ($p) {} #Assign person to sales region 1 in a modify block
end
-rule "Apply a discount to people in the city of Raleigh" ruleflow-group "test"
+rule "Apply a discount to people in the city of Raleigh"
+ruleflow-group "test"
lock-on-active true
when
$p : Person($addresses : addresses)
@@ -1610,7 +1634,8 @@
<para>However, the following slightly different approach does exhibit the problem:</para>
- <para><programlisting>rule "Assign people in North Carolina (NC) to sales region 1" ruleflow-group "test"
+ <para><programlisting>rule "Assign people in North Carolina (NC) to sales region 1"
+ruleflow-group "test"
lock-on-active true
when
$assessment : Assessment()
@@ -1621,7 +1646,8 @@
modify ($assessment) {} #Modify assessment in a modify block
end
-rule "Apply a discount to people in the city of Raleigh" ruleflow-group "test"
+rule "Apply a discount to people in the city of Raleigh"
+ruleflow-group "test"
lock-on-active true
when
$assessment : Assessment()
@@ -1663,9 +1689,6 @@
that checks whether the discount has already been applied. If so, the rule does not
activate.</para>
- <para>The next example shows how we can reason over the results of a
- hibernate query. The Restaurant pattern will reason over and bind with
- each result in turn:</para>
</section>
<section>
@@ -1906,7 +1929,7 @@
end
</programlisting>
- <para>In the above example, sum is an AccumulateFunction and will sum
+ <para>In the above example, sum is an Accumulate Function and will sum
the $value of all OrderItems and return the result.</para>
<para>Drools 4.0 ships with the following built in accumulate
@@ -2077,7 +2100,7 @@
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
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
+ that there are a few convenience methods you can use to modify working
memory; without having to first reference a working memory
instance.</para>
@@ -2098,7 +2121,7 @@
<para>"retract(handle);" 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
+ cuts to the KnowledgeHelper instance (refer to the KnowledgeHelper
interface for more advanced operations). The KnowledgeHelper interface is
made available to the RHS code block as a variable called "drools". If you
provide "Property Change Listeners" to your Java beans that you are
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-TypeDeclaration.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-TypeDeclaration.xml 2009-03-30 00:43:14 UTC (rev 25876)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-TypeDeclaration.xml 2009-03-30 01:50:40 UTC (rev 25877)
@@ -16,17 +16,17 @@
<para>FIXME: add syntax diagram for declare</para>
</warning>
- <para>Type Declarations have two main goals in the rules engine: allow the
- declaration of new types and/or allow the declaration of metadata for
+ <para>Type declarations have two main goals in the rules engine: to allow the
+ declaration of new types, and to allow the declaration of metadata for
types.</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Declaring new types:</emphasis> Drools works
out of the box with plain POJOs as facts. Although, sometimes the users
- may want to define the model directly into the rules engine, without
+ may want to define the model directly to the rules engine, without
worrying to create their models in a lower level language like Java.
- Another times, there is a domain model already built, but eventually the
+ At other times, there is a domain model already built, but eventually the
user wants or needs to complement this model with additional entities
that are used mainly during the reasoning process.</para>
</listitem>
@@ -100,9 +100,9 @@
<emphasis role="bold">end</emphasis></programlisting>
</example></para>
- <para>When you declare a new fact type, Drools will bytecode generate at
- compile time a POJO that implements the fact type. The generated Java
- class will be a one-to-one javabean mapping of the type definition. So,
+ <para>When you declare a new fact type, Drools will, at compile time,
+ generate bytecode implementing a POJO that represents the fact type. The generated Java
+ class will be a one-to-one Java Bean mapping of the type definition. So,
for the previous example, the generated Java class would be:</para>
<para><example>
@@ -202,7 +202,7 @@
declaration.</para>
<para>For instance, if there is a class org.drools.examples.Person, and
- one wants to declare metadata for it, just to the following:</para>
+ one wants to declare metadata for it, just write the following code:</para>
<example>
<title>declaring metadata for an existing type</title>
@@ -248,7 +248,7 @@
<para>The first important thing to realize is that a declared fact will
belong to the package where it was declared. So, for instance, in the
- example bellow, <emphasis>Person</emphasis> will belong to the
+ example below, <emphasis>Person</emphasis> will belong to the
<emphasis>org.drools.examples</emphasis> package, and so the generated
class fully qualified name will be:
<emphasis>org.drools.examples.Person</emphasis>.</para>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-XML.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-XML.xml 2009-03-30 00:43:14 UTC (rev 25876)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-XML.xml 2009-03-30 01:50:40 UTC (rev 25877)
@@ -52,7 +52,7 @@
summary of the language follows.</para>
<example>
- <title>Example <indexterm>
+ <title>A rule in XML<indexterm>
<primary>XML Rule</primary>
</indexterm></title>
@@ -206,21 +206,22 @@
</programlisting>
</example>
- <para>Referring to the above example: Notice the key parts, the
- declaration for the Drools 4, schema, imports, globals, functions, and the
- rules. Most of the elements are self explanatory if you have some
- understanding of the Drools 4 features.</para>
+ <para>In the preceding XML text you will see the typical XML
+ element, the package declaration, imports, globals, functions,
+ and the rule itself. Most of the elements are self explanatory
+ if you have some understanding of the Drools features.</para>
- <para>Imports: import the types you wish to use in the rule.</para>
+ <para>The <code>import</code> elements import the types you wish to
+ use in the rule.</para>
- <para>Globals: These are global objects that can be referred to in the
- rules.</para>
+ <para>The <code>global</code> elements define global objects that can
+ be referred to in the rules.</para>
- <para>Functions: this is a declaration of functions to be used in the
- rules. You have to specify return types, a unique name and parameters, in
- the body goes a snippet of code.</para>
+ <para>The <code>function</code> contains a function declaration, for
+ a function to be used in the rules. You have to specify a return type,
+ a unique name and parameters, in the body goes a snippet of code.</para>
- <para>Rule: see below.</para>
+ <para>The rule is discussed below.</para>
<example>
<title>Detail of rule element</title>
@@ -265,12 +266,12 @@
</programlisting>
</example>
- <para>Referring to the above rule detail:</para>
-
- <para>The rule has a LHS and RHS (conditions and consequence) sections.
+ <para>In the above detail of the rule we see that the rule has LHS
+ and RHS (conditions and consequence) sections.
The RHS is simple, it is just a block of semantic code that will be
- executed when the rule is activated. The LHS is slightly more complicated,
- certainly more so then past versions.</para>
+ executed when the rule is activated. The LHS is slightly more
+ complicated as it contains nested elements for conditional elements,
+ constraints and restrictions.</para>
<!--
@@ -285,15 +286,15 @@
<para>A key element of the LHS is the Pattern element. This allows you to
specify a type (class) and perhaps bind a variable to an instance of that
- class. Nested under the pattern object are constraints and conditional
- elements that have to be met. The Predicate and Return Value constraints
+ class. Nested under the pattern object are constraints and restrictions
+ that have to be met. The Predicate and Return Value constraints
allow Java expressions to be embedded.</para>
<para>That leaves the conditional elements, not, exists, and, or etc. They
work like their DRL counterparts. Elements that are nested under and an
"and" element are logically "anded" together. Likewise with "or" (and you
- can nest things further). "Exists" and "Not" work around Patterns, to check
- for the existence or non existence of a fact meeting its
+ can nest things further). "Exists" and "Not" work around patterns, to check
+ for the existence or nonexistence of a fact meeting the pattern's
constraints.</para>
<para>The Eval element allows the execution of a valid snippet of Java
More information about the jboss-svn-commits
mailing list