[jboss-svn-commits] JBL Code SVN: r26150 - in labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US: Chapter-User_Guide and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Mon Apr 20 07:50:42 EDT 2009
Author: laune
Date: 2009-04-20 07:50:42 -0400 (Mon, 20 Apr 2009)
New Revision: 26150
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Rule.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-User_Guide/Section-Building.xml
Log:
improvements
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Rule.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Rule.xml 2009-04-20 11:48:50 UTC (rev 26149)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Rule.xml 2009-04-20 11:50:42 UTC (rev 26150)
@@ -2153,42 +2153,86 @@
<section>
<title>The Right Hand Side (then)</title>
- <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
- 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
- RHS is to insert, retractor modify working memory data. To assist with
- that 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
- changed (one that has been bound to something on the LHS) and rules may
- need to be reconsidered.</para>
+ <section>
+ <title>Usage</title>
+
+ <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
+ 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
+ RHS is to insert, retractor modify working memory data. To assist with
+ that 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
+ changed (one that has been bound to something on the LHS) and rules may
+ need to be reconsidered.</para>
- <para>"update(object);" can also be used, here the KnowledgeHelper will
- lookup the facthandle for you, via an identity check, for the passed object.</para>
+ <para>"update(object);" can also be used, here the KnowledgeHelper will
+ lookup the facthandle for you, via an identity check, for the passed object.</para>
- <para>"insert(new Something());" will place a new object of your creation
- in working memory.</para>
+ <para>"insert(new Something());" will place a new object of your creation
+ in working memory.</para>
- <para>"insertLogical(new Something());" 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>"insertLogical(new Something());" 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>"retract(handle);" removes an object from working memory.</para>
+
+ <para>These convenience methods are basically macros that provide short
+ 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
+ inserting into the engine, you can avoid the need to call "update" when
+ the object changes.</para>
+ </section>
- <para>These convenience methods are basically macros that provide short
- 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
- inserting into the engine, you can avoid the need to call "update" when
- the object changes.</para>
+ <section>
+ <title>The modify Statement</title>
+
+ <para>This language extension provides a structured approach to
+ fact updates. It combines the update operation with a number of
+ setter calls to change the object's fields.</para>
+
+ <example>
+ <title>The modify statement</title>
+
+ <programlisting><emphasis role="bold">modify ( </emphasis><emphasis>fact-expression</emphasis><emphasis role="bold"> {</emphasis>
+ <emphasis>expression</emphasis> [ <emphasis role="bold">,</emphasis> <emphasis>expression</emphasis> ]
+<emphasis role="bold">}</emphasis></programlisting>
+ </example>
+
+ <para>The parenthesized fact-expression must yield a fact object reference.
+ The expression list in the block should consist of setter calls for the given
+ object, to be written without the usual object reference, which is
+ automatically prepended by the compiler.</para>
+
+ <para>The example illustrates a simple fact modification.</para>
+
+ <example>
+ <title>A modify statement</title>
+
+ <programlisting>rule "modify stilton"
+when
+ $stilton : Cheese(type == "stilton")
+then
+ modify( $stilton ){
+ setPrice( 20 ),
+ setAge( "overripe" )
+ }
+end</programlisting>
+ </example>
+
+ </section>
+
</section>
<section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-User_Guide/Section-Building.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-User_Guide/Section-Building.xml 2009-04-20 11:48:50 UTC (rev 26149)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-User_Guide/Section-Building.xml 2009-04-20 11:50:42 UTC (rev 26150)
@@ -154,12 +154,82 @@
<para>Instead of adding the resources to create definitions
programmatically it is also possible to do it by configuration, via the
ChangeSet XML. The simple XML file supports
- three elements: add, remove, and modify. Currently only the add
- element is supported, and the others will be implemented to
- support iterative changes. The following example loads a single DRL
- file.</para>
+ three elements: add, remove, and modify, each of which has a sequence
+ of <resource> subelements defining a configuration entity. The
+ following XML schema is <emphasis>not</emphasis> normative and
+ intended for illustration only.</para>
<example>
+ <title>XML Schema for ChangeSet XML (not normative)</title>
+
+ <programlisting><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ xmlns="http://drools.org/drools-5.0/change-set"
+ targetNamespace="http://drools.org/drools-5.0/change-set">
+
+ <xs:element name="change-set" type="ChangeSet"/>
+
+ <xs:complexType name="ChangeSet">
+ <xs:choice maxOccurs="unbounded">
+ <xs:element name="add" type="Operation"/>
+ <xs:element name="remove" type="Operation"/>
+ <xs:element name="modify" type="Operation"/>
+ </xs:choice>
+ </xs:complexType>
+
+ <xs:complexType name="Operation">
+ <xs:sequence>
+ <xs:element name="resource" type="Resource"
+ maxOccurs="unbounded"/>
+ </xs:sequence>
+ </xs:complexType>
+
+ <xs:complexType name="Resource">
+ <xs:sequence>
+ <!-- To be used with <resource type="DTABLE"...>> -->
+ <xs:element name="decisiontable-conf" type="DecTabConf"
+ minOccurs="0"/>
+ </xs:sequence>
+ <!-- java.net.URL, plus "classpath" protocol -->
+ <xs:attribute name="source" type="xs:string"/>
+ <xs:attribute name="type" type="ResourceType"/>
+ </xs:complexType>
+
+ <xs:complexType name="DecTabConf">
+ <xs:attribute name="input-type" type="DecTabInpType"/>
+ <xs:attribute name="worksheet-name" type="xs:string"
+ use="optional"/>
+ </xs:complexType>
+
+ <!-- according to org.drools.builder.ResourceType -->
+ <xs:simpleType name="ResourceType">
+ <xs:restriction base="xs:string">
+ <xs:enumeration value="DRL"/>
+ <xs:enumeration value="XDRL"/>
+ <xs:enumeration value="DSL"/>
+ <xs:enumeration value="DSLR"/>
+ <xs:enumeration value="DRF"/>
+ <xs:enumeration value="DTABLE"/>
+ <xs:enumeration value="PKG"/>
+ <xs:enumeration value="BRL"/>
+ <xs:enumeration value="CHANGE_SET"/>
+ </xs:restriction>
+ </xs:simpleType>
+
+ <!-- according to org.drools.builder.DecisionTableInputType -->
+ <xs:simpleType name="DecTabInpType">
+ <xs:restriction base="xs:string">
+ <xs:enumeration value="XLS"/>
+ <xs:enumeration value="CSV"/>
+ </xs:restriction>
+ </xs:simpleType>
+
+</xs:schema></programlisting>
+ </example>
+
+ <para>Currently only the add element is supported, but the others will be implemented to
+ support iterative changes. The following example loads a single DRL file.</para>
+
+ <example>
<title>Simple ChangeSet XML</title>
<programlisting><change-set xmlns='http://drools.org/drools-5.0/change-set'
@@ -185,8 +255,8 @@
<para>Currently you still need to use the API to load that ChangeSet, but
we will add support for containers such as Spring in the future, so that the
- process of creating a KnowledgeBase can be donw completely by XML configuration.
- Loading resources using the XML couldn't be simpler, as it's just another
+ process of creating a KnowledgeBase can be done completely by XML configuration.
+ Loading resources using an XML file couldn't be simpler, as it's just another
ResourceType.</para>
<example>
@@ -217,20 +287,20 @@
</programlisting>
</example>
- <para>The ChangeSet is especailly useful when working with KnowledgeAgent,
+ <para>The ChangeSet is especially useful when working with KnowledgeAgent,
as it allows for change notification and automatic rebuilding of the
KnowledgeBase, which is covered in more detail in the section on the
KnowledgeAgent, under Deploying.</para>
<para>Directories can also be specified, to add all resources
- in that folder. Currently it expected that all resources in
+ in that folder. Currently it is expected that all resources in
that folder are of the same type. If you use the KnowledgeAgent it will
provide a continous scanning for added, modified or removed resources and
rebuild the cached KnowledgeBase. The KnowledgeAgent provides more
information on this.</para>
<example>
- <title>ChangeSet XML which adds a directories contents</title>
+ <title>ChangeSet XML which adds a directory's contents</title>
<programlisting><change-set xmlns='http://drools.org/drools-5.0/change-set'
xmlns:xs='http://www.w3.org/2001/XMLSchema-instance'
More information about the jboss-svn-commits
mailing list