[jboss-svn-commits] JBL Code SVN: r25029 - labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Fri Jan 30 22:48:55 EST 2009
Author: tirelli
Date: 2009-01-30 22:48:55 -0500 (Fri, 30 Jan 2009)
New Revision: 25029
Added:
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-TypeDeclaration.xml
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Chapter-RuleLanguage.xml
Log:
documenting type declaration
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Chapter-RuleLanguage.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Chapter-RuleLanguage.xml 2009-01-30 20:09:01 UTC (rev 25028)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Chapter-RuleLanguage.xml 2009-01-31 03:48:55 UTC (rev 25029)
@@ -16,6 +16,8 @@
<xi:include href="Section-Function.xml" />
+ <xi:include href="Section-TypeDeclaration.xml" />
+
<xi:include href="Section-Rule.xml" />
<xi:include href="Section-Query.xml" />
Added: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-TypeDeclaration.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-TypeDeclaration.xml (rev 0)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-TypeDeclaration.xml 2009-01-31 03:48:55 UTC (rev 25029)
@@ -0,0 +1,162 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section version="5.0" xml:base="../../" xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns:m="http://www.w3.org/1998/Math/MathML"
+ xmlns:html="http://www.w3.org/1999/xhtml"
+ xmlns:db="http://docbook.org/ns/docbook">
+ <title>Type Declaration</title>
+
+ <note>
+ <para><replaceable>(updated to Drools 5.0)</replaceable></para>
+ </note>
+
+ <figure>
+ <title>type declaration</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center"
+ fileref="images/Chapter-Rule_Language/function.png"
+ format="PNG" role=""></imagedata>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Type Declarations have two main goals in the rules engine: allow the
+ declaration of new types and/or allow the declaration of meta data for
+ types.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Declaring new types: Drools works out of the box with plain POJOs
+ as facts. Although, sometimes the users may want to define the model
+ directly into the rules engine, without worrying to create their models
+ in a lower level language like Java. Another 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>
+ </listitem>
+
+ <listitem>
+ <para>Declaring meta data: 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. This meta information may be queried
+ at runtime by the engine and used in the reasoning process.</para>
+ </listitem>
+ </itemizedlist>
+
+ <section>
+ <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
+ and the keyword <emphasis role="bold">end</emphasis>.</para>
+
+ <example>
+ <title>declaring a new fact type: Address</title>
+
+ <programlisting><emphasis role="bold">declare</emphasis> Address
+ number : int
+ streetName : String
+ city : String
+<emphasis role="bold">end</emphasis>
+</programlisting>
+ </example>
+
+ <para>The previous example declares a new fact type called
+ <emphasis>Address</emphasis>. This fact type will have 3 attributes:
+ <emphasis>number</emphasis>, <emphasis>streetName</emphasis> and
+ <emphasis>city</emphasis>. Each attribute has a type that can be any valid
+ java type, including any other class created by the user or even other
+ fact types previously declared.</para>
+
+ <para>For instance, we may want to declare another fact type
+ <emphasis>Person</emphasis>:</para>
+
+ <para><example>
+ <title>declaring a new fact type: Person</title>
+
+ <programlisting><emphasis role="bold">declare</emphasis> Person
+ name : String
+ dateOfBirth : java.util.Date
+ address : Address
+<emphasis role="bold">end</emphasis>
+</programlisting>
+ </example>As we can see on the previous example,
+ <emphasis>dateOfBirth</emphasis> is of type <code>java.util.Date</code>,
+ from the java API, while <emphasis>address</emphasis> is of the previously
+ defined fact type Address.</para>
+
+ <para>You may avoid having to write the fully qualified name of a class
+ everytime you write it by using the <emphasis
+ role="bold">import</emphasis> clause, previously discussed.</para>
+
+ <para><example>
+ <title>avoiding the need to use fully qualified class names by using
+ import</title>
+
+ <programlisting><emphasis role="bold">import</emphasis> java.util.Date
+
+<emphasis role="bold">declare</emphasis> Person
+ name : String
+ dateOfBirth : Date
+ address : Address
+<emphasis role="bold">end</emphasis></programlisting>
+ </example></para>
+
+ <para>When you declare a new fact type, Drools will bytecode generate at
+ compile time a POJO that implements the fact type. The generated java
+ class will be a one-to-one javabean mapping of the type definition. So,
+ for the previous example, the generated java class would be:</para>
+
+ <para><example>
+ <title>generated java class for the previous Person fact type
+ declaration</title>
+
+ <programlisting><emphasis role="bold">public</emphasis> <emphasis
+ role="bold">class</emphasis> Person implements Serializable {
+ <emphasis role="bold">private</emphasis> String name;
+ <emphasis role="bold">private</emphasis> java.util.Date dateOfBirth;
+ <emphasis role="bold">private</emphasis> Address address;
+
+ // getters and setters
+ // equals/hashCode
+ // toString
+}
+</programlisting>
+ </example>Since it is a simple POJO, the generated class can be used
+ transparently in the rules, like any other fact.</para>
+
+ <para><example>
+ <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>
+ Person mark = new Person();
+ mark.setName("Mark");
+ insert( mark );
+<emphasis role="bold">end</emphasis>
+</programlisting>
+ </example>Although, the declared type can be used like any other POJO
+ inside your rules, the classes are only available at runtime, after the
+ DRL is compiled. It means that you will not be able to reference them
+ explicitly from your application code. You could use reflection for that,
+ but anyone that ever used reflection knows that it requires quite some
+ work to do anything useful. This way, Drools provides a simplified API
+ that allows you to manipulate such facts from your DRL file.</para>
+
+ <para></para>
+
+ <para>org.drools.rule.FactType</para>
+
+ <para></para>
+
+ <para></para>
+ </section>
+</section>
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Language/Section-TypeDeclaration.xml
___________________________________________________________________
Name: svn:executable
+ *
More information about the jboss-svn-commits
mailing list