[jboss-svn-commits] JBL Code SVN: r19789 - labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Wed Apr 30 20:16:24 EDT 2008
Author: irooskov at redhat.com
Date: 2008-04-30 20:16:24 -0400 (Wed, 30 Apr 2008)
New Revision: 19789
Modified:
labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-XML.xml
Log:
updated Section-XML.xml for re-write
Modified: labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-XML.xml
===================================================================
--- labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-XML.xml 2008-04-30 23:12:03 UTC (rev 19788)
+++ labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-referenceguide/en/Chapter-Rule_Language/Section-XML.xml 2008-05-01 00:16:24 UTC (rev 19789)
@@ -4,11 +4,10 @@
<section>
<title>XML Rule Language</title>
- <para>As an option, Drools also supports a "native" <indexterm>
+ <para>As an option, Drools also supports a <emphasis>native</emphasis> <indexterm>
<primary>XML</primary>
- </indexterm> rule language as an alternative to DRL. This allows you to
- capture and manage your rules as XML data. Just like the non-XML DRL format,
- the XML format is parsed into the internal "AST" representation - as fast as
+ </indexterm> rule language as an alternative to DRL. This allows for the capturing and management of rules as XML data. Just like the non-XML DRL format,
+ the XML format is parsed into the internal "AST" representation, as fast as
possible (using a SAX parser). There is no external transformation step
required. All the features are available with XML that are available to
DRL.</para>
@@ -16,28 +15,34 @@
<section>
<title>When to use XML</title>
- <para>There are several scenarios that XML is desirable. However, we
- recommend that it is not a default choice, as XML is not readily human
- readable (unless you like headaches) and can create visually bloated
+ <para>There are several scenarios where XML is desirable. However, it is not recommend that it be used as a default choice, as XML is not readily human
+ readable and can create visually bloated
rules.</para>
- <para>If you do want to edit XML by hand, use a good schema aware editor
+ <para>If there is a wish to edit XML by hand, use a good schema aware editor
that provides nice hierarchical views of the XML, ideally visually
(commercial tools like XMLSpy, Oxygen etc are good, but cost money, but
then so do headache tablets).</para>
- <para>Other scenarios where you may want to use the XML format are if you
- have a tool that generates rules from some input (programmatically
+ <para>Other scenarios where the XML format may be useful are if a tool is in use that generates rules from some input (programmatically
generated rules), or perhaps interchange from another rule language, or
from another tool that emits XML (using XSLT you can easily transform
- between XML formats). Note you can always generate normal DRL as
+ between XML formats). </para>
+
+<note>
+<para>Normal DRL can always be generated as
well.</para>
+</note>
- <para>Alternatively you may be embedding Drools in a product that already
- uses XML for configuration, so you would like the rules to be in an XML
- format. You may be creating your own rule language on XML - note that you
- can always use the AST objects directly to create your own rule language
+ <para>Alternatively Drools may be being embedded in a product that already
+ uses XML for configuration, thus wishing for the rules to be in an XML
+ format or a custom rule language can be built on XML.</para>
+
+<note>
+<para>
+ AST objects can be used directly to create a custom rule language
as well (the options are many, due to the open architecture).</para>
+</note>
</section>
<section>
@@ -52,7 +57,7 @@
<primary>XML Rule</primary>
</indexterm></title>
- <programlisting><?xml version="1.0" encoding="UTF-8"?>
+<screen><?xml version="1.0" encoding="UTF-8"?>
<package name="com.sample"
xmlns="http://drools.org/drools-4.0"
@@ -199,29 +204,29 @@
</package>
-</programlisting>
+</screen>
</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
+ rules. Most of the elements are self explanatory if with some
understanding of the Drools 4 features.</para>
- <para>Imports: import the types you wish to use in the rule.</para>
+ <para>Imports: import the types to be used in the rule.</para>
<para>Globals: These are 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>
+ rules. Return types, a unique name and parameters, have to be specified in
+ the body as a snippet of code.</para>
<para>Rule: see below.</para>
<example>
<title>Detail of rule element</title>
- <programlisting><rule name="simple_rule">
+<screen><rule name="simple_rule">
<rule-attribute name="salience" value="10" />
<rule-attribute name="no-loop" value="true" />
<rule-attribute name="agenda-group" value="agenda-group" />
@@ -258,7 +263,7 @@
list1.add( $cheese );
</rhs>
</rule>
- </programlisting>
+</screen>
</example>
<para>Referring to the above rule detail:</para>
@@ -279,25 +284,22 @@
accumulate and external functions
-->
- <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
+ <para>A key element of the LHS is the Pattern element. This allows for specification of 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
allow Java expressions to be embedded.</para>
- <para>That leaves the conditional elements, not, exists, and, or etc. They
+ <para>That leaves the conditional elements, not, exists, and, or and so forth. 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
+ <code>and</code> element are logically <code>anded</code> together. Likewise with <code>or</code> (and nested further still). <code>Exists</code> and <code>Not</code> work around Patterns, to check
for the existence or non existence of a fact meeting its
constraints.</para>
<para>The Eval element allows the execution of a valid snippet of Java
- code - as long as it evaluates to a boolean (do not end it with a
- semi-colon, as it is just a fragment) - this can include calling a
+ code, as long as it evaluates to a boolean (do not end it with a
+ semi-colon, as it is just a fragment); this can include calling a
function. The Eval is less efficient then then columns, as the rule engine
- has to evaluate it each time, but it is a "catch all" feature for when you
- can express what you need to do with Column constraints.</para>
+ has to evaluate it each time, but it is a <emphasis>catch all</emphasis> feature for when expressing what needs to be achieved with Column constraints.</para>
</section>
<section>
@@ -310,19 +312,24 @@
<para>Drools comes with some utility classes to transform between formats.
This works by parsing the rules from the source format into the AST, and
- then "dumping" out to the appropriate target format. This allows you, for
- example, to write rules in DRL, and when needed, export to XML if
+ then <emphasis>dumping</emphasis> out to the appropriate target format. This allows, for
+ example, the ability to write rules in DRL, and when needed, export to XML if
necessary at some point in the future.</para>
- <para>The classes to look at if you need to do this are: <programlisting>XmlDumper - for exporting XML.
+ <para>The classes to look at to do this are:
+<screen>XmlDumper - for exporting XML.
DrlDumper - for exporting DRL.
DrlParser - reading DRL.
XmlPackageReader - reading XML.
-</programlisting> Using combinations of the above, you can convert between any
- format (including round trip). Note that DSLs will not be preserved (from
- DRLs that are using a DSL) - but they will be able to be converted.</para>
+</screen> Using combinations of the above, convertion can occur between any
+ format (including round trip). </para>
+<note>
+ <para>
+ DSLs will not be preserved (from
+ DRLs that are using a DSL), but they will be able to be converted.</para>
+</note>
-<para>Feel free to make use of XSLT to provide all sorts of possibilities
+<para>Make use of XSLT to provide all sorts of possibilities
for XML, XSLT and its ilk are what make XML powerful.</para>
</section>
More information about the jboss-svn-commits
mailing list