[jboss-svn-commits] JBL Code SVN: r26138 - labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Sun Apr 19 08:21:02 EDT 2009
Author: laune
Date: 2009-04-19 08:21:02 -0400 (Sun, 19 Apr 2009)
New Revision: 26138
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Function.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Overview.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Package.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-TypeDeclaration.xml
Log:
improvements
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Function.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Function.xml 2009-04-19 09:43:59 UTC (rev 26137)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Function.xml 2009-04-19 12:21:02 UTC (rev 26138)
@@ -8,10 +8,6 @@
xmlns:db="http://docbook.org/ns/docbook" xml:base="../../">
<title>Function</title>
- <note>
- <para><replaceable>(updated to Drools 4.0)</replaceable></para>
- </note>
-
<figure>
<title>function</title>
@@ -23,15 +19,14 @@
</figure>
<para>Functions are a way to put semantic code in your rule source file, as
- opposed to in normal Java classes. They can't do anything more then what you
- can do with helper classes (in fact, the compiler generates the helper class
- for you behind the scenes). The main advantage of using functions in a rule
+ opposed to in normal Java classes. They can't do anything more than what you
+ can do with helper classes. (In fact, the compiler generates the helper class
+ for you behind the scenes.) The main advantage of using functions in a rule
is that you can keep the logic all in one place, and you can change the
- functions as needed (this can be a good and bad thing). Functions are most
+ functions as needed (which can be a good or a bad thing). Functions are most
useful for invoking actions on the consequence ("then") part of a rule,
- especially if that particular action is used over and over (perhaps with
- only differing parameters for each rule - for example the contents of an
- email message).</para>
+ especially if that particular action is used over and over again, perhaps
+ with only differing parameters for each rule.</para>
<para>A typical function declaration looks like:</para>
@@ -41,18 +36,19 @@
</programlisting>
<para>Note that the "function" keyword is used, even though its not really
- part of Java. Parameters to the function are just like a normal method (and
- you don't have to have parameters if they are not needed). Return type is
- just like a normal method.</para>
+ part of Java. Parameters to the function are defined as for a method, and
+ you don't have to have parameters if they are not needed. The return type
+ is defined just like in a regular method.</para>
- <para>An alternative to the use of a function, could be to use a static
- method in a helper class: Foo.hello(). Drools 4.0 supports the use of
+ <para>Alternatively, you could use a static method in a helper class,
+ e.g., <code>Foo.hello()</code>. Drools supports the use of
function imports, so all you would need to do is:</para>
<programlisting>import function my.package.Foo.hello</programlisting>
- <para>In both cases above, to use the function, just call it by its name in
- the consequence or inside a semantic code block. Example:</para>
+ <para>Irrespective of the way the function is defined or imported, you
+ use a function by calling it by its name, in the consequence or inside
+ a semantic code block. Example:</para>
<programlisting>rule "using a static function"
when
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Overview.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Overview.xml 2009-04-19 09:43:59 UTC (rev 26137)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Overview.xml 2009-04-19 12:21:02 UTC (rev 26138)
@@ -8,17 +8,14 @@
xmlns:db="http://docbook.org/ns/docbook">
<title>Overview</title>
- <note>
- <para><replaceable>(updated to Drools 4.0)</replaceable></para>
- </note>
-
- <para>Drools 4.0 has a "native" rule language that is non XML textual
- format. This format is very light in terms of punctuation, and supports
+ <para>Drools has a "native" rule language.
+ This format is very light in terms of punctuation, and supports
natural and domain specific languages via "expanders" that allow the
language to morph to your problem domain. This chapter is mostly concerted
- with the native rule format. The Diagrams used are known as "rail road"
- diagrams, and are basically flow charts for the language terms. For the
- technically very keen, you can also refer to "DRL.g" which is the Antlr3
+ with this native rule format. The diagrams used to present the syntax are
+ known as "railroad" diagrams, and they are basically flow charts for the
+ language terms. The
+ technically very keen may also refer to "DRL.g" which is the Antlr3
grammar for the rule language. If you use the Rule Workbench, a lot of the
rule structure is done for you with content assistance, for example, type
"ru" and press ctrl+space, and it will build the rule structure for
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Package.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Package.xml 2009-04-19 09:43:59 UTC (rev 26137)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-Package.xml 2009-04-19 12:21:02 UTC (rev 26138)
@@ -8,10 +8,6 @@
xmlns:db="http://docbook.org/ns/docbook" xml:base="../../">
<title>Package</title>
- <note>
- <para><replaceable>(updated to Drools 4.0)</replaceable></para>
- </note>
-
<para>A package is a collection of rules and other related constructs, such
as imports and globals. The package members are typically related to each
other - perhaps HR rules, for instance. A package represents a namespace,
@@ -22,10 +18,10 @@
<para>It is possible to assemble rules from multiple rule sources, and have
one top level package configuration that all the rules are kept under (when
the rules are assembled). Although, it is not possible to merge into the
- same package resources declared under different names. A single Rulebase,
- can though, contain multiple packages built on it. A common structure, is to
+ same package resources declared under different names. A single Rulebase
+ may, however, contain multiple packages built on it. A common structure is to
have all the rules for a package in the same file as the package declaration
- (so that is it entirely self contained).</para>
+ (so that is it entirely self-contained).</para>
<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
@@ -62,8 +58,9 @@
<para>Import statements work like import statements in Java. You need to
specify the fully qualified paths and type names for any objects you want
- to use in the rules. Drools automatically imports classes from the same
- named Java package and from the java.lang package.</para>
+ to use in the rules. Drools automatically imports classes from the
+ Java package of the same name, and also from the package
+ <code>java.lang</code>.</para>
</section>
<section>
@@ -80,14 +77,14 @@
</mediaobject>
</figure>
- <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 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 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>
+ <para>The optional expander statement is used to specify domain specific
+ language (DSL) configurations, which are normally stored in a separate
+ file. This provides clues to the parser how to understand such
+ specific text in your rules. Since Drools 4.0, the expander declaration
+ is mandatory for the tools to provide context sensitive assistance and to
+ avoid error reporting. The API, however, allows the program to apply
+ DSL templates even if the expanders are not declared in the source
+ file.</para>
</section>
<section>
@@ -104,18 +101,18 @@
</mediaobject>
</figure>
- <para>Globals are global variables. They are used to make application
- objects available to the rules, and are typically used to provide data or
- services that the rules use (specially application services used in rule
- 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; you should use them in rules' LHS only if the global has a
+ <para>With global you define global variables. They are used to make
+ application objects available to the rules. Typically, they are used
+ to provide data or services that the rules use, especially application
+ services used in rule consequences, and to return data from the rules,
+ like logs or values added in rule consequences, or for the rules to
+ interact with the application, doing callbacks. Globals are not
+ inserted into the Working Memory, and therefore a global should never be
+ used to establish conditions in rules except when it 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>
+ changes of globals and does not track their changes. Incorrect use
+ of globals in constraints may yield surprising results - surprising
+ in a bad way.</para>
<para>If multiple packages declare globals with the same identifier they
must be of the same type and all of them will reference the same global
@@ -159,18 +156,18 @@
Hibernate query.</para>
<para>One example may be an instance of a Email service. In your
- integration code that is calling the rule engine, you get your
+ integration code that is calling the rule engine, you obtain your
emailService object, and then set it in the working memory. In the DRL,
- you declare that you have a global of type EmailService, and give it a
+ you declare that you have a global of type EmailService, and give it the
name "email". Then in your rule consequences, you can use things like
email.sendSMS(number, message).</para>
<para>Globals are not designed to share data between rules and they should
never be used for that purpose. Rules always reason and react to the
- working memory state, so if you want to "share" data between rules, assert
- the data to the working memory.</para>
+ working memory state, so if you want to pass data from rule to rule, assert
+ the data as facts into the working memory.</para>
- <para>It is strongly discouraged to set (or change) a global value from
+ <para>It is strongly discouraged to set or change a global value from
inside your rules. We recommend to you always set the value from your
application using the working memory interface.</para>
</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-TypeDeclaration.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-TypeDeclaration.xml 2009-04-19 09:43:59 UTC (rev 26137)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Language_Reference/Section-TypeDeclaration.xml 2009-04-19 12:21:02 UTC (rev 26138)
@@ -39,9 +39,9 @@
<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
+ out of the box with plain Java objects as facts. Sometimes, however, users
may want to define the model directly to the rules engine, without
- worrying to create their models in a lower level language like Java. At
+ worrying about creating models in a lower level language like Java. 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>
@@ -51,7 +51,7 @@
<para><emphasis role="bold">Declaring metadata:</emphasis> facts may
have meta information associated to them. Examples of meta information
include any kind of data that is not represented by the fact attributes
- and are consistent among all instances of that fact type. This meta
+ and is consistent among all instances of that fact type. This meta
information may be queried at runtime by the engine and used in the
reasoning process.</para>
</listitem>
@@ -61,11 +61,11 @@
<title>Declaring New Types</title>
<para>To declare a new type, all you need to do is use the keyword
- <emphasis role="bold">declare</emphasis>, followed by the list of fields
+ <emphasis role="bold">declare</emphasis>, followed by the list of fields,
and the keyword <emphasis role="bold">end</emphasis>.</para>
<example>
- <title>declaring a new fact type: Address</title>
+ <title>Declaring a new fact type: Address</title>
<programlisting><emphasis role="bold">declare</emphasis> Address
number : int
@@ -101,10 +101,10 @@
<para>You may avoid having to write the fully qualified name of a class
every time you write it by using the <emphasis
- role="bold">import</emphasis> clause, previously discussed.</para>
+ role="bold">import</emphasis> clause, as previously discussed.</para>
<para><example>
- <title>avoiding the need to use fully qualified class names by using
+ <title>Avoiding the need to use fully qualified class names by using
import</title>
<programlisting><emphasis role="bold">import</emphasis> java.util.Date
@@ -117,7 +117,8 @@
</example></para>
<para>When you declare a new fact type, Drools will, at compile time,
- generate bytecode implementing a POJO that represents the fact type. The
+ generate bytecode that implements a Java class representing 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>
@@ -137,18 +138,17 @@
// toString
}
</programlisting>
- </example>Since it is a simple POJO, the generated class can be used
- transparently in the rules, like any other fact.</para>
+ </example>Since the generated class is a simple Java class, it can
+ be used transparently in the rules, like any other fact.</para>
<para><example>
- <title>using the declared types in rules</title>
+ <title>Using the declared types in rules</title>
<programlisting><emphasis role="bold">rule</emphasis> "Using a declared Type"
<emphasis role="bold">when</emphasis>
$p : Person( name == "Bob" )
<emphasis role="bold">then</emphasis>
- System.out.println( "The name of the person is "+ )
- <emphasis>// lets insert Mark, that is Bob's mate</emphasis>
+ <emphasis>// Insert Mark, who is Bob's mate.</emphasis>
Person mark = new Person();
mark.setName("Mark");
insert( mark );
@@ -161,19 +161,19 @@
<title>Declaring Metadata</title>
<para>Metadata may be assigned to several different constructions in
- Drools, like fact types, fact attributes and rules. Drools uses the
+ Drools: fact types, fact attributes and rules. Drools uses the
<emphasis role="bold">@</emphasis> symbol to introduce metadata, and it
always uses the form:</para>
- <para><programlisting>@matadata_key( metadata_value )</programlisting>The
- parenthesis and the metadata_value are optional.</para>
+ <para><programlisting>@<emphasis>metadata_key</emphasis>( <emphasis>metadata_value</emphasis> )</programlisting>The
+ parenthesized <emphasis>metadata_value</emphasis> is optional.</para>
<para>For instance, if you want to declare a metadata attribute like
<emphasis>author</emphasis>, whose value is <emphasis>Bob</emphasis>, you
could simply write:</para>
<example>
- <title>declaring an arbitrary metadata attribute</title>
+ <title>Declaring a metadata attribute</title>
<programlisting>@author( Bob )</programlisting>
</example>
@@ -183,11 +183,11 @@
available for querying at runtime. Drools allows the declaration of
metadata both for fact types and for fact attributes. Any metadata that is
declared before the fields of a fact type are assigned to the fact type,
- while metadata declared after an attribute are assigned to the attribute
- in particular.</para>
+ while metadata declared after an attribute are assigned to that
+ particular attribute.</para>
<example>
- <title>declaring metadata attributes for fact types and
+ <title>Declaring metadata attributes for fact types and
attributes</title>
<programlisting><emphasis role="bold">import</emphasis> java.util.Date
@@ -202,12 +202,12 @@
<emphasis role="bold">end</emphasis></programlisting>
</example>
- <para>In the previous example, there are two metadata declared for the
+ <para>In the previous example, there are two metadata items declared for the
fact type (<emphasis>@author</emphasis> and
- <emphasis>@dateOfCreation</emphasis>), and two more defined for the name
+ <emphasis>@dateOfCreation</emphasis>) and two more defined for the name
attribute (<emphasis>@key</emphasis> and <emphasis>@maxLength</emphasis>).
Please note that the <emphasis>@key</emphasis> metadata has no value, and
- so the parenthesis and the value were omitted.</para>
+ so the parentheses and the value were omitted.</para>
</section>
<section>
@@ -219,11 +219,11 @@
declaration.</para>
<para>For instance, if there is a class org.drools.examples.Person, and
- one wants to declare metadata for it, just write the following
+ one wants to declare metadata for it, it's possible to write the following
code:</para>
<example>
- <title>declaring metadata for an existing type</title>
+ <title>Declaring metadata for an existing type</title>
<programlisting><emphasis role="bold">import</emphasis> org.drools.examples.Person
@@ -236,11 +236,11 @@
<para>Instead of using the import, it is also possible to reference the
class by its fully qualified name, but since the class will also be
- referenced in the rules, usually it is shorter to add the import and use
+ referenced in the rules, it is usually shorter to add the import and use
the short class name everywhere.</para>
<example>
- <title>declaring metadata using the fully qualified class name</title>
+ <title>Declaring metadata using the fully qualified class name</title>
<programlisting><emphasis role="bold">declare</emphasis> org.drools.examples.Person
<emphasis>@author</emphasis>( Bob )
@@ -255,24 +255,24 @@
<para>Declared types are usually used inside rules files, while Java
models are used when sharing the model between rules and applications.
Although, sometimes, the application may need to access and handle facts
- from the declared types, specially when the application is wrapping the
- rules engine and providing higher level, domain specific, user interfaces
+ from the declared types, especially when the application is wrapping the
+ rules engine and providing higher level, domain specific user interfaces
for rules management.</para>
<para>In such cases, the generated classes can be handled as usual with
- the Java Reflection APIs, but as we know, that usually requires a lot of
- work for small results. This way, Drools provides a simplified API for the
+ the Java Reflection API, but, as we know, that usually requires a lot of
+ work for small results. Therefore, Drools provides a simplified API for the
most common fact handling the application may want to do.</para>
<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 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</emphasis> package, and so the
+ fully qualified name of the generated class will be
<emphasis>org.drools.examples.Person</emphasis>.</para>
<example>
- <title>declaring a type in the org.drools.examples package</title>
+ <title>Declaring a type in the org.drools.examples package</title>
<programlisting><emphasis role="bold">package</emphasis> org.drools.examples
@@ -287,16 +287,16 @@
<para>Declared types, as discussed previously, are generated at knowledge
base compilation time, i.e., the application will only have access to them
- at application run time. As so, these classes are not available for direct
- reference from the application.</para>
+ at application run time. Therefore, these classes are not available for
+ direct reference from the application.</para>
- <para>Drools then provides an interface through which the users can handle
+ <para>Drools then provides an interface through which users can handle
declared types from the application code:
org.drools.definition.type.FactType. Through this interface, the user can
instantiate, read and write fields in the declared fact types.</para>
<example>
- <title>handling declared fact types through the API</title>
+ <title>Handling declared fact types through the API</title>
<programlisting>// get a reference to a knowledge base with a declared type:
KnowledgeBase kbase = ...
@@ -330,21 +330,11 @@
</example>
<para>The API also includes other helpful methods, like setting all the
- attributes at once, reading values from a Map, or read all attributes at
- once, populating a Map.</para>
+ attributes at once, reading values from a Map, or reading all attributes at
+ once, into a Map.</para>
<para>Although the API is similar to Java reflection (yet much simpler to
- use), it does not use reflection underneath, relying in much more
- performant bytecode generated accessors.</para>
-
- <para></para>
-
- <para></para>
-
- <para></para>
-
- <para></para>
-
- <para></para>
+ use), it does not use reflection underneath, relying on much more
+ performant accessors implemented in generated bytecode.</para>
</section>
</section>
More information about the jboss-svn-commits
mailing list