[jboss-svn-commits] JBL Code SVN: r24143 - in labs/jbossrules/trunk/drools-docs: docbook-style-drools and 1 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Fri Nov 28 16:22:54 EST 2008
Author: ellenzhao
Date: 2008-11-28 16:22:53 -0500 (Fri, 28 Nov 2008)
New Revision: 24143
Modified:
labs/jbossrules/trunk/drools-docs/doc-authoring-guideline-and-cheatsheet.txt
labs/jbossrules/trunk/drools-docs/docbook-style-drools/
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml
Log:
added <code></code> markups
Modified: labs/jbossrules/trunk/drools-docs/doc-authoring-guideline-and-cheatsheet.txt
===================================================================
--- labs/jbossrules/trunk/drools-docs/doc-authoring-guideline-and-cheatsheet.txt 2008-11-28 16:44:33 UTC (rev 24142)
+++ labs/jbossrules/trunk/drools-docs/doc-authoring-guideline-and-cheatsheet.txt 2008-11-28 21:22:53 UTC (rev 24143)
@@ -36,6 +36,11 @@
* <tip><para></para></tip>
* <warning><para></para></warning>
+Linking syntax in DocBook 5.0+:
+-------------------------------
+http://www.sagehill.net/docbookxsl/Db5Tools.html#Db5UnivLinking
+
+
Markup program list or console output:
--------------------------------------
Property changes on: labs/jbossrules/trunk/drools-docs/docbook-style-drools
___________________________________________________________________
Name: svn:ignore
+ target
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml 2008-11-28 16:44:33 UTC (rev 24142)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml 2008-11-28 21:22:53 UTC (rev 24143)
@@ -394,8 +394,8 @@
that are activated and dependent on that fact will be cancelled. Note
that it is possible to have rules that depend on the "non existence" of
a fact, in which case retracting a fact may cause a rule to activate
- (see the 'not' and 'exist' keywords). Retraction is done using the
- FactHandle that was returned during the assert.</para>
+ (see the <code>not</code> and <code>exist</code> keywords). Retraction is done using the
+ <code>FactHandle</code> that was returned during the assert.</para>
<programlisting>Cheese stilton = new Cheese("stilton");
FactHandle stiltonHandle = session.insert( stilton );
@@ -408,15 +408,15 @@
<para>The Rule Engine must be notified of modified Facts, so that it can
be re-processed. Modification internally is actually a retract and then an
- insert; so it clears the WorkingMemory and then starts again. Use the
- modifyObject method to notify the Working Memory of changed objects, for
+ insert; so it clears the <code>WorkingMemory</code> and then starts again. Use the
+ <code>modifyObject</code> method to notify the Working Memory of changed objects, for
objects that are not able to notify the Working Memory themselves.
- Notice modifyObject always takes the modified object as a second
+ Notice <code>modifyObject</code> always takes the modified object as a second
parameter - this allows you to specify new instances for immutable
- objects. The update() method can only be used with objects that have
+ objects. The <code>update()</code> method can only be used with objects that have
shadow proxies turned on. If you do not use shadow proxies then you must
- call session.modifyRetract() before making your changes and
- session.modifyInsert() after the changes.</para>
+ call <code>session.modifyRetract()</code> before making your changes and
+ <code>session.modifyInsert()</code> after the changes.</para>
<programlisting>Cheese stilton = new Cheese("stilton");
FactHandle stiltonHandle = workingMemory.insert( stilton );
@@ -435,19 +435,18 @@
global on the LHS of a rule, make sure it is immutable. A global must
first be declared in the drl before it can be set on the session.</para>
- <programlisting>global java.util.List list </programlisting>
+ <programlisting>global java.util.List list</programlisting>
<para>With the Rule Base now aware of the global identifier and its type
- any sessions are now able to call session.setGlobal; failure to declare
+ any sessions are now able to call <code>session.setGlobal</code>; failure to declare
the global type and identifier first will result in an exception being
- thrown. To set the global on the session use
- session.setGlobal(identifier, value);</para>
+ thrown. To set the global on the session use <code>session.setGlobal(identifier, value)</code>;</para>
<programlisting>List list = new ArrayList();
session.setGlobal("list", list); </programlisting>
<para>If a rule evaluates on a global before you set it you will get a
- NullPointerException.</para>
+ <code>NullPointerException</code>.</para>
</section>
<section>
@@ -481,13 +480,11 @@
transparent lazy proxies. Shadow facts are enable by default and are not
visible from external code, not even inside code blocks on rules.</para>
- <remark>I<emphasis role="bold">MPORTANT: </emphasis>since Drools
- implements Shadow Facts as Proxies, the fact classes must <emphasis
- role="bold">either be immutable</emphasis> or <emphasis
- role="bold">should not be final</emphasis>, nor have final methods. If a
+ <important><para>Since Drools
+ implements Shadow Facts as Proxies, the fact classes must <emphasis>either be immutable</emphasis> or <emphasis>should not be final</emphasis>, nor have final methods. If a
fact class is final or have final methods and is still a mutable class,
the engine is not able to create a proper shadow fact for it and results
- in unpredictable behavior. </remark>
+ in unpredictable behavior.</para></important>
<para>Although shadow facts are a great way of ensuring the engine
integrity, they add some overhead to the the reasoning process. As so,
@@ -498,20 +495,21 @@
<title>When is it possible to disable Shadow Facts?</title>
<para>It is possible to disable shadow facts for your classes if you
- meet the following requirements:</para>
+ meet the following requirements:
- <para><emphasis role="bold">1. Immutable classes are safe:</emphasis>
+ <orderedlist>
+
+ <listitem><para><emphasis role="bold">Immutable classes are safe:</emphasis>
if a class is immutable it does not require shadow facts. Just to
clarify, a class is immutable from the engine perspective if once an
instance is asserted into the working memory, no attribute will change
- until it is retracted.</para>
+ until it is retracted.</para></listitem>
- <para><emphasis role="bold">2. Inside your rules, attributes are only
+ <listitem><para><emphasis role="bold">Inside your rules, attributes are only
changed using modify() blocks:</emphasis> both Drools dialects (MVEL
and Java) have the modify block construct. If all attribute value
changes for a given class happen inside modify() blocks, you can
- disable shadow facts for that class.</para>
-
+ disable shadow facts for that class.
<example>
<title>Example: modify() block using Java dialect</title>
@@ -543,16 +541,14 @@
age = $p.age + 1
}
end</programlisting>
- </example>
- <para><emphasis role="bold">3. In your application, attributes are
+ </example></para></listitem>
+ <listitem><para><emphasis role="bold">In your application, attributes are
only changed between calls to modifyRetract() and
modifyInsert():</emphasis> this way, the engine becomes aware that
- attributes will be changed and can prepare itself for them.</para>
-
+ attributes will be changed and can prepare itself for them.
<example>
<title>Example: safely modifying attributes in the application
code</title>
-
<programlisting> // create session
StatefulSession session = ruleBase.newStatefulSession();
@@ -572,7 +568,8 @@
person.setLikes( "chocolate" );
session.modifyInsert( handle, person ); // call modifyInsert() after the changes
</programlisting>
- </example>
+ </example></para></listitem>
+ </orderedlist></para>
</section>
<section>
@@ -616,9 +613,9 @@
<programlisting>Cheese stilton = new Cheese("stilton");
FactHandle stiltonHandle = workingMemory.insert( stilton, true ); //specifies that this is a dynamic fact </programlisting>
- <para>To make a JavaBean dynamic add a PropertyChangeSupport field
+ <para>To make a JavaBean dynamic add a <code>PropertyChangeSupport</code> field
memory along with two add/remove mothods and make sure that each setter
- notifies the PropertyChangeSupport instance of the change.</para>
+ notifies the <code>PropertyChangeSupport</code> instance of the change.</para>
<programlisting>private final PropertyChangeSupport changes = new PropertyChangeSupport( this );
...
@@ -643,17 +640,17 @@
<section>
<title>Initial Fact</title>
- <para>To support conditional elements like "not" (which will be covered
+ <para>To support conditional elements like <code>not</code> (which will be covered
later on), there is a need to "seed" the engine with something known as
the "Initial Fact". This fact is a special fact that is not intended to
be seen by the user.</para>
- <para>On the first working memory action (assert, fireAllRules) on a
+ <para>On the first working memory action (<code>assert</code>, <code>fireAllRules</code>) on a
fresh working memory, the Initial Fact will be propagated through the
RETE network. This allows rules that have no LHS, or perhaps do not use
- normal facts (such as rules that use "from" to pull data from an
+ normal facts (such as rules that use <code>from</code> to pull data from an
external source). For instance, if a new working memory is created, and
- no facts are asserted, calling the fireAllRules will cause the Initial
+ no facts are asserted, calling the <code>fireAllRules</code> will cause the Initial
Fact to propagate, possibly activating rules (otherwise, nothing would
happen as there is no other fact to start with).</para>
</section>
@@ -672,15 +669,14 @@
</mediaobject>
</figure>
- <para>The StatefulSession extends the WorkingMemory class. It simply adds
- async methods and a dispose() method. The ruleBase retains a reference to
- each StatefulSession it creates, so that it can update them when new rules
- are added, dispose() is needed to release the StatefulSession reference
- from the RuleBase, without it you can get memory leaks.</para>
+ <para>The <code>StatefulSession</code> extends the <code>WorkingMemory</code> class. It simply adds
+ async methods and a <code>dispose()</code> method. The <code>ruleBase</code> retains a reference to
+ each <code>StatefulSession</code> it creates, so that it can update them when new rules
+ are added, <code>dispose()</code> is needed to release the <code>StatefulSession</code> reference
+ from the <code>RuleBase</code>, without it you can get memory leaks.</para>
<example>
- <title>Createing a StatefulSession</title>
-
+ <title>Createing a <code>StatefulSession</code></title>
<programlisting>StatefulSession session = ruleBase.newStatefulSession();</programlisting>
</example>
</section>
@@ -690,9 +686,7 @@
<figure>
<title>StatelessSession</title>
-
<mediaobject>
-
<imageobject>
<imagedata align="center" fileref="images/Chapter-Rule_Engine/StatelessSession.png"
format="PNG" />
@@ -700,42 +694,41 @@
</mediaobject>
</figure>
- <para>The StatelessSession wraps the WorkingMemory, instead of extending
+ <para>The <code>StatelessSession</code> wraps the <code>WorkingMemory</code>, instead of extending
it, its main focus is on decision service type scenarios.</para>
<example>
- <title>Createing a StatelessSession</title>
-
+ <title>Createing a <code>StatelessSession</code></title>
<programlisting>StatelessSession session = ruleBase.newStatelessSession();
session.execute( new Cheese( "cheddar" ) );</programlisting>
</example>
<para>The API is reduced for the problem domain and is thus much simpler;
- which in turn can make maintenance of those services easier. The RuleBase
- never retains a reference to the StatelessSession, thus dispose() is not
- needed, and they only have an execute() method that takes an object, an
- array of objects or a collection of objects - there is no insert or
- fireAllRules. The execute method iterates the objects inserting each and
- calling fireAllRules() at the end; session finished. Should the session
- need access to any results information they can use the executeWithResults
- method, which returns a StatelessSessionResult. The reason for this is in
+ which in turn can make maintenance of those services easier. The <code>RuleBase</code>
+ never retains a reference to the <code>StatelessSession</code>, thus <code>dispose()</code> is not
+ needed, and they only have an <code>execute()</code> method that takes an object, an
+ array of objects or a collection of objects - there is no <code>insert</code> or
+ <code>fireAllRules</code>. The execute method iterates the objects inserting each and
+ calling <code>fireAllRules()</code> at the end; session finished. Should the session
+ need access to any results information they can use the <code>executeWithResults</code>
+ method, which returns a <code>StatelessSessionResult</code>. The reason for this is in
remoting situations you do not always want the return payload, so this way
it's optional.</para>
- <para>setAgendaFilter, setGlobal and setGlobalResolver share their state
- across sessions; so each call to execute() will use the set AgendaFilter,
+ <para><code>setAgendaFilter</code>, <code>setGlobal</code> and <code>setGlobalResolver</code> share their state
+ across sessions; so each call to <code>execute()</code> will use the set <code>AgendaFilter</code>,
or see any previous set globals etc.</para>
- <para>StatelessSessions do not currently support
- propertyChangeListeners.</para>
+ <para><code>StatelessSession</code>s do not currently support
+ <code>PropertyChangeListener</code>s.</para>
- <para>Async versions of the Execute method are supported, remember to
- override the ExecutorService implementation when in special managed thread
+ <para>Async versions of the <code>Execute</code> method are supported, remember to
+ override the <code>ExecutorService</code> implementation when in special managed thread
environments such as JEE.</para>
- <para>StatelessSessions also support sequential mode, which is a special
+ <para><code>StatelessSession</code>s also support sequential mode, which is a special
optimized mode that uses less memory and executes faster; please see the
- Sequential section for more details.</para>
+ <link xlink:href="#sequential">Sequential</link> section for more details.</para>
<figure>
<title>StatelessSessionResult</title>
@@ -749,27 +742,27 @@
</mediaobject>
</figure>
- <para>StatelessSession.executeWithResults(....) returns a minimal api to
+ <para><code>StatelessSession.executeWithResults(....)</code> returns a minimal API to
examine the session's data. The inserted Objects can be iterated over,
queries can be executed and globals retrieved. Once the
- StatelessSessionResult is serialized it loses the reference to the
- underlying WorkingMemory and RuleBase, so queries can no longer be
+ <code>StatelessSessionResult</code> is serialized it loses the reference to the
+ underlying <code>WorkingMemory</code> and <code>RuleBase</code>, so queries can no longer be
executed, however globals can still be retrieved and objects iterated. To
- retrieve globals they must be exported from the StatelessSession; the
- GlobalExporter strategy is set with StatelessSession.setGlobalExporter(
- GlobalExporter globalExporter ). Two implementations of GlobalExporter are
+ retrieve globals they must be exported from the <code>StatelessSession</code>; the
+ <code>GlobalExporter</code> strategy is set with <code>StatelessSession.setGlobalExporter(
+ GlobalExporter globalExporter )</code>. Two implementations of <code>GlobalExporter</code> are
available and users may implement their own strategies.
- CopyIdentifiersGlobalExporter copies named identifiers into a new
- GlobalResovler that is passed to the StatelessSessionResult; the
- constructor takes a String[] array of identifiers, if no identifiers are
- specified it copies all identifiers declared in the RuleBase.
- ReferenceOriginalGlobalExporter just passes a reference to the original
- Global Resolver; the latter should be used with care as identifier
- instances can be changed at any time by the StatelessSession and the
- GlobalResolver may not be serializable friendly.</para>
+ <code>CopyIdentifiersGlobalExporter</code> copies named identifiers into a new
+ <code>GlobalResovler</code> that is passed to the <code>StatelessSessionResult</code>; the
+ constructor takes a <code>String[]</code> array of identifiers, if no identifiers are
+ specified it copies all identifiers declared in the <code>RuleBase</code>.
+ <code>ReferenceOriginalGlobalExporter</code> just passes a reference to the original
+ <code>GlobalResolver</code>; the latter should be used with care as identifier
+ instances can be changed at any time by the <code>StatelessSession</code> and the
+ <code>GlobalResolver</code> may not be serializable-friendly.</para>
<example>
- <title>GlobalExporter with StatelessSessions</title>
+ <title><code>GlobalExporter</code> with <code>StatelessSession</code>s</title>
<programlisting>StatelessSession session = ruleBase.newStatelessSession();
session.setGlobalExporter( new CopyIdentifiersGlobalExporter( new String[]{"list"} ) );
@@ -803,9 +796,9 @@
<orderedlist>
<listitem>
<para>Working Memory Actions - this is where most of the work takes
- place - in either the Consequence or the main Java application
- process. Once the Consequence has finished or the main Java
- application process calls fireAllRules() the engine switches to the
+ place - in either the <code>Consequence</code> or the main Java application
+ process. Once the <code>Consequence</code> has finished or the main Java
+ application process calls <code>fireAllRules()</code> the engine switches to the
Agenda Evaluation phase.</para>
</listitem>
@@ -856,8 +849,8 @@
worrying about a "flow".</para>
<para>Custom conflict resolution strategies can be specified by setting
- the Class in the RuleBaseConfiguration method setConflictResolver, or
- using the property "drools.conflictResolver".</para>
+ the Class in the <code>RuleBaseConfiguration</code> method <code>setConflictResolver</code>, or
+ using the property <code>drools.conflictResolver</code>.</para>
</section>
<section>
@@ -876,7 +869,7 @@
"sequences" of processing, consider using agenda-groups for this
purpose.</para>
- <para>Each time setFocus(...) is called it pushes that Agenda Group onto
+ <para>Each time <code>setFocus(...)</code> is called it pushes that Agenda Group onto
a stack, when the focus group is empty it is popped off and the next one
on the stack evaluates. An Agenda Group can appear in multiple locations
on the stack. The default Agenda Group is "MAIN", all rules which do not
@@ -889,7 +882,6 @@
<figure>
<title>AgendaFilters</title>
-
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/Chapter-Rule_Engine/AgendaFilter.png" format="PNG" />
@@ -904,26 +896,25 @@
<itemizedlist>
<listitem>
- <para>RuleNameEndsWithAgendaFilter</para>
+ <para><code>RuleNameEndsWithAgendaFilter</code></para>
</listitem>
<listitem>
- <para>RuleNameEqualsAgendaFilter</para>
+ <para><code>RuleNameEqualsAgendaFilter</code></para>
</listitem>
<listitem>
- <para>RuleNameStartsWithAgendaFilter</para>
+ <para><code>RuleNameStartsWithAgendaFilter</code></para>
</listitem>
<listitem>
- <para>RuleNameMatchesAgendaFilter</para>
+ <para><code>RuleNameMatchesAgendaFilter</code></para>
</listitem>
</itemizedlist>
- <para>To use a filter specify it while calling FireAllRules. The
- following example will only allow activation of rules ending with the test <emphasis>Test</emphasis>. All others will be filtered out:</para>
-
- <programlisting>workingMemory.fireAllRules( new RuleNameEndsWithAgendaFilter( "Test" ) ); </programlisting>
+ <para>To use a filter specify it while calling <code>FireAllRules</code>. The
+ following example will only allow activation of rules ending with the test <emphasis>Test</emphasis>. All others will be filtered out:
+ <programlisting>workingMemory.fireAllRules( new RuleNameEndsWithAgendaFilter( "Test" ) );</programlisting></para>
</section>
</section>
@@ -935,12 +926,12 @@
<para>In a regular insert, you need to explicitly retract a fact. With
logical assertions, the fact that was asserted will be automatically
retracted when the conditions that asserted it in the first place are no
- longer true. (It's actually more clever then that! If there are no possible
+ longer true. (It's actually more clever than that! If there are no possible
conditions that could support the logical assertion, only then it will be
retracted).</para>
- <para>Normal insertions are said to be “STATED” (ie The Fact has been
- stated - just like the intuitive concept). Using a HashMap and a counter
+ <para>Normal insertions are said to be “STATED” (i.e. The Fact has been
+ stated - just like the intuitive concept). Using a <code>HashMap</code> and a counter
we track how many times a particular equality is STATED; this means we
count how many different instances are equal. When we logically insert an
object we are said to justify it and it is justified by the firing rule.
@@ -953,18 +944,17 @@
object it will fail and return null. If we STATE an object that has an
existing equal object that is JUSTIFIED we override the Fact - how this
override works depends on the configuration setting
- "WM_BEHAVIOR_PRESERVE". When the property is set to discard we use the
+ <code>WM_BEHAVIOR_PRESERVE</code>. When the property is set to discard we use the
existing handle and replace the existing instance with the new Object -
this is the default behavior - otherwise we override it to STATED but we
- create an new FactHandle.</para>
+ create an new <code>FactHandle</code>.</para>
<para>This can be confusing on a first read, so hopefully the flow charts
- below help. When it says that it returns a new FactHandle, this also
- indicates the Object was propagated through the network.</para>
+ below help. When it says that it returns a new <code>FactHandle</code>, this also
+ indicates the <code>Object</code> was propagated through the network.
<figure>
<title>Stated Insertion</title>
-
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/Chapter-Rule_Engine/Stated_Assertion.png"
@@ -975,14 +965,13 @@
<figure>
<title>Logical Insertion</title>
-
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/Chapter-Rule_Engine/Logical_Assertion.png"
format="PNG" />
</imageobject>
</mediaobject>
- </figure>
+ </figure></para>
<section>
<title>Example Scenario</title>
@@ -1123,7 +1112,7 @@
</section>
<section>
- <title>Sequential Mode</title>
+ <title><link linkend="sequential">Sequential Mode</link></title>
<para>With Rete you have a stateful session where objects can be asserted
and modified over time, rules can also be added and removed. Now what
More information about the jboss-svn-commits
mailing list