[Jboss-svn-commits] JBL Code SVN: r3732 - labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language

[<jbo...@li...>]

Author: mic...@jb...
Date: 2006-04-17 07:13:19 -0400 (Mon, 17 Apr 2006)
New Revision: 3732

Modified:
   labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Function.xml
   labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Package.xml
Log:
more goodness

Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Function.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Function.xml	2006-04-17 04:06:38 UTC (rev 3731)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Function.xml	2006-04-17 11:13:19 UTC (rev 3732)
@@ -7,16 +7,43 @@
 
     <mediaobject>
       <imageobject>
-        <imagedata align="center" fileref="function.svg" format="SVG" role=""
-                    />
+        <imagedata align="center" fileref="function.svg" format="SVG" role="" />
       </imageobject>
 
       <imageobject>
-        <imagedata align="center" fileref="function.png" format="PNG" role=""
-                    />
+        <imagedata align="center" fileref="function.png" format="PNG" role="" />
       </imageobject>
     </mediaobject>
   </figure>
 
-  <para>uuuere</para>
+  <para>Functions are a way to put semantic code in your rule source, 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, isn't that helpful). 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 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>
+
+  <para>A typica function declaration looks like:</para>
+
+  <para>function String calcSomething(String arg) {</para>
+
+  <para> return "hola !";</para>
+
+  <para>}</para>
+
+  <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. To call the function from within a rule (in a
+  consequence, or perhaps an eval, simply use the function name, and toss in
+  the parameters - just like a method call). </para>
+
+  <para>An alternative to a function, could be to use a static method in a
+  helper class: Foo.doSomething(), or perhaps pass in an instance of a helper
+  class/service as a named global (see the section on globals):
+  foo.soSomething() (where foo is a named global variable).</para>
 </section>
\ No newline at end of file

Modified: labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Package.xml
===================================================================
--- labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Package.xml	2006-04-17 04:06:38 UTC (rev 3731)
+++ labs/jbossrules/trunk/documentation/manual/en/Chapter-Rule_Language/Section-Package.xml	2006-04-17 11:13:19 UTC (rev 3732)
@@ -2,13 +2,14 @@
 <section>
   <title>Package</title>
 
-  <para>A package is basically a collection of rules kept under a namespace. A
-  package represents a namespace, which ideally is kept unique for a given
-  grouping of rules. The package name itself is just a namespace, and is not
-  related to files or folders in any way.</para>
+  <para>A package is basically a collection of rules (rules that are logically
+  related to each other - perhaps HR rules, for instance). A package
+  represents a namespace, which ideally is kept unique for a given grouping of
+  rules. The package name itself is the namespace, and is not related to files
+  or folders in any way. </para>
 
   <para>At the Package level items are things like functions, imports, global
-  data and so on. </para>
+  data and so on.</para>
 
   <para>Not that it is possible to assemble rules from multiple rule sources,
   and have one top level package configuration that all the rules are kept
@@ -56,7 +57,7 @@
 
     <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 rule. </para>
+    to use in the rule.</para>
   </section>
 
   <section>
@@ -101,7 +102,24 @@
 
     <para>Globals are global variables (although ideally, they won't change in
     value while the rules are executing). They typically are used to return
-    data, such as a log of actions, or provide data that the rules refer
-    to.</para>
+    data, such as a log of actions, or provide data or services that the rules
+    use.</para>
+
+    <para>Note that these are just named instances of objects that you pass in
+    from your application to the working memory. This means you can pass in
+    any object you want: you could pass in a service locator, or perhaps a
+    service itself. </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
+    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
+    name "email". Then in your rule consequences, you can use things like
+    email.sendSMS(number, message); etc... (you get the idea). </para>
+
+    <para>It is important to NOT use globals as a replacement for asserting
+    facts, if you do, you are bypassing most of the rule engines power, and
+    may get suprising results (surprising in a bad way, like when a doctor
+    says "thats interesting" to a chest XRay of yours).</para>
   </section>
 </section>
\ No newline at end of file