[jboss-svn-commits] JBL Code SVN: r20483 - in labs/jbossrules/trunk/drools-docs/drools-docs-expert/en: Chapter-Decision_Tables and 5 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Sat Jun 14 13:21:47 EDT 2008
Author: mark.proctor at jboss.com
Date: 2008-06-14 13:21:47 -0400 (Sat, 14 Jun 2008)
New Revision: 20483
Added:
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Decision_Tables/Chapter-Spreadsheet.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Deployment/Chapter-DepymentAndTest.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-IDE/Chapter-QuickStart.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Chapter-JSR94.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Chapter-RuleLanguage.xml
Removed:
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Decision_Tables/Section-Spreadsheet.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-IDE/Section-QuickStart.xml
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Decision_Tables/
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Deployment/
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Examples/Chapter-Examples.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-IDE/
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Section-How_To_Use.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Section-Introduction.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Section-References.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Section-Specification.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Comments.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-DSL.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Function.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Overview.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Package.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Query.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Rule.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-XML.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/master.xml
Log:
JBRULES-1643
-better layout for chapters
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Decision_Tables
___________________________________________________________________
Name: svn:ignore
+ Thumbs.db
Copied: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Decision_Tables/Chapter-Spreadsheet.xml (from rev 20476, labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Decision_Tables/Section-Spreadsheet.xml)
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Decision_Tables/Chapter-Spreadsheet.xml (rev 0)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Decision_Tables/Chapter-Spreadsheet.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -0,0 +1,602 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns:xi="http://www.w3.org/2001/XInclude" >
+ <title>Decision tables in spreadsheets</title>
+
+ <para>Decision tables are a "precise yet compact" (ref. Wikipedia) way of
+ representing conditional logic, and are well suited to <emphasis>business</emphasis> level
+ rules.</para>
+
+ <para>Drools supports managing rules in a Spreadsheet format. Formats
+ supported are Excel, and CSV. Meaning that a variety of spreadsheet
+ programs (such as Microsoft Excel, OpenOffice.org Calc amongst others) can be utalized. It
+ is expected that web based decision table editors will be included in a near
+ future release.</para>
+
+ <para>Decision tables are an old concept (in software terms) but have proven
+ useful over the years. Very briefly speaking, in Drools decision tables are
+ a way to generate rules driven from the data entered into a spreadsheet. All
+ the usual features of a spreadsheet for data capture and manipulation can be
+ taken advantage of.</para>
+
+ <section>
+ <title>When to use Decision tables</title>
+
+ <para>Decision tables my want to be considered as a course of action if rules exist that can
+ be expressed as rule templates + data. In each row of a decision table,
+ data is collected that is combined with the templates to generate a
+ rule.</para>
+
+ <para>Many businesses already use spreadsheets for managing data,
+ calculations etc. If you are happy to continue this way, you can also
+ manage your business rules this way. This also assumes you are happy to
+ manage packages of rules in .xls or .csv files. Decision tables are not
+ recommenced for rules that do not follow a set of templates, or where
+ there are a small number of rules (or if there is a dislike towards software like excel or open office). They are ideal in the sense that there can be control over what <emphasis>parameters</emphasis> of rules can be edited, without exposing the
+ rules directly.</para>
+
+ <para>Decision tables also provide a degree of insulation from the
+ underlying object model.</para>
+ </section>
+
+ <section>
+ <title>Overview</title>
+
+ <para>Here are some examples of real world decision tables (slightly
+ edited to protect the innocent).</para>
+
+ <screenshot>
+ <screeninfo>Using excel to edit a decision table</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="excel.png" />
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <screenshot>
+ <screeninfo>Can have multiple actions for a rule row</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="actions.png" />
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <screenshot>
+ <screeninfo>Using OpenOffice</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="open_office.png" />
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>In the above examples, the technical aspects of the decision table
+ have been collapsed away (standard spreadsheet feature).</para>
+
+ <para>The rules start from row 17 (each row results in a rule). The
+ conditions are in column C, D, E etc.. (off screen are the actions). The value in the cells are quite simple, and have meaning
+ when looking at the headers in Row 16. Column B is just a description. It
+ is conventional to use color to make it obvious what the different areas
+ of the table mean.</para>
+
+<note>
+ <para>Note that although the decision tables look like they process top
+ down, this is not necessarily the case. Idealy, if the rules are able to be authored in such a way as order does not matter (simply as it makes
+ maintenance easier, as rows will not need to be shifted around all the time).</para>
+</note>
+ <para>
+ As each row is a rule, the same principles apply. As the rule engine
+ processes the facts, any rules that match may fire (some people are
+ confused by this. It is possible to clear the agenda when a rule fires
+ and simulate a very simple decision table where the first match exists).
+ Also note that you can have multiple tables on the one spreadsheet (so
+ rules can be grouped where they share common templates, yet at the end of
+ the day they are all combined into a one rule package). Decision tables
+ are essentially a tool to generate DRL rules automatically.</para>
+
+
+ <screenshot>
+ <screeninfo>A real world example using multiple tables for grouping like
+ rules</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="multi_table.png" />
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ </section>
+
+ <section>
+ <title>How decision tables work</title>
+
+ <para>The key point to keep in mind is that in a decision table, each row
+ is a rule, and each column in that row is either a condition or action for
+ that rule.</para>
+
+ <screenshot>
+ <screeninfo>Rows and columns</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="row_col.png" />
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>The spreadsheet looks for the <firstterm>RuleTable</firstterm> keyword to indicate the
+ start of a rule table (both the starting row and column). Other keywords
+ are also used to define other package level attributes (covered later). It
+ is important to keep the keywords in the one column. By convention the
+ second column ("B") is used for this, but it can be any column (convention
+ is to leave a margin on the left for notes). In the following diagram, C
+ is actually the column where it starts. Everything to the left of this is
+ ignored.</para>
+
+ <para>If we expand the hidden sections, it starts to make more sense how
+ it works; note the keywords in column C.</para>
+
+ <screenshot>
+ <screeninfo>Expanded for rule templates</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="expanded.png" />
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>Now the hidden magic which makes it work can be seen. The RuleSet
+ keyword indicates the name to be used in the <emphasis>rule package</emphasis> that all the
+ rules will come under (the name is optional, it will have a default but
+ it MUST have the <emphasis>RuleSet</emphasis> keyword) in the cell immediately to the right.</para>
+<para>
+ The other keywords visible in Column C are: Import, Sequential which will
+ be covered later. The RuleTable keyword is important as it indicates that
+ a chunk of rules will follow, based on some rule templates. After the
+ RuleTable keyword there is a name - this name is used to prefix the
+ generated rules names (the row numbers are appended to create unique rule
+ names). The column of RuleTable indicates the column in which the rules
+ start (columns to the left are ignored).</para>
+<note>
+ <para>
+ In general the keywords make up name/value pairs.
+ </para>
+</note>
+
+ <para>Referring to row 14 (the row immediately after RuleTable): the
+ keywords CONDITION and ACTION indicate that the data in the columns below
+ are for either the LHS or the RHS parts of a rule. There are other
+ attributes on the rule which can also be optionally set this way.</para>
+
+<para>Row 15 contains declarations of <firstterm>ObjectTypes</firstterm>; the content in this
+ row is optional (if this option is not in use, a blank row must be left, however this option is usually found to be quite useful). When using this row, the values in the
+ cells below (row 16) become constraints on that object type. In the above
+ case, it will generate: Person(age=="42") etc (where 42 comes from row
+ 18). In the above example, the "==" is implicit (if just a field
+ name is given it will assume that it is to look for exact matches).
+</para>
+<note>
+ <para>
+ An ObjectType declaration can span columns (via merged cells), meaning that all columns below the merged range will be combined
+ into the one set of constraints.</para>
+</note>
+
+ <para>Row 16 contains the rule templates themselves. They can
+ use the "$para" place holder to indicate where data from the cells below
+ will be populated ($param can be sued or $1, $2 etc to indicate
+ parameters from a comma separated list in a cell below). Row 17 is ignored
+ as it is textual descriptions of the rule template.</para>
+
+ <para>Row 18 to 19 shows data, which will be combined (interpolated) with
+ the templates in row 15, to generate rules. If a cell contains no data,
+ then its template is ignored (eg it means that condition, or action, does
+ not apply for that rule-row). Rule rows are read until there is a BLANK
+ row. Multiple RuleTables can exsist in a sheet. Row 20 contains another
+ keyword, and a value. The row positions of keywords like this do not
+ matter (most people put them at the top) but their column should be the
+ same one where the RuleTable or RuleSet keywords should appear (in this
+ case column C has been chosen to be significant, but column A
+ could be used instead).</para>
+
+ <para>In the above example, rules would be rendered like the following (as
+ it uses the "ObjectType" row):</para>
+<screen>//row 18
+rule "Cheese_fans_18"
+ when
+ Person(age=="42")
+ Cheese(type=="stilton")
+ then
+ list.add("Old man stilton");
+end
+</screen>
+<note>
+ <para>
+ The [age=="42"] and [type=="stilton"] are
+ interpreted as single constraints to be added to the respective ObjectType
+ in the cell above (if the cells above were spanned, then there could be
+ multiple constraints on one "column".</para>
+</note>
+ </section>
+
+ <section>
+ <title>Keywords and syntax</title>
+
+ <section>
+ <title>Syntax of templates</title>
+
+ <para>The syntax of what goes in the templates is dependent on if it is
+ a CONDITION column or ACTION column. In most cases, it is identical to
+ <emphasis>vanilla</emphasis> DRL for the LHS or RHS respectively. This means in the LHS,
+ the constraint language must be used, and in the RHS it is a snippet of
+ code to be executed.</para>
+
+<para>The <code>$param</code> place holder is used in templates to indicate where
+ data form the cell will be interpolated. You can also use <code>$1</code> to the
+ same effect. If the cell contains a comma separated list of values, $1
+ and $2 etc. may be used to indicate which positional parameter from the
+ list of values in the cell will be used.</para>
+<example>
+<para>
+If the templates is [Foo(bar == $param)] and the cell is [ 42 ] then the result will be [Foo(bar == 42)]
+If the template is [Foo(bar < $1, baz == $2)] and the cell is [42,42] then the result will be [Foo(bar > 42, baz ==42)]
+</para>
+</example>
+
+ <para>For conditions: How snippets are rendered depends on if there is
+ anything in the row above (where ObjectType declarations may appear). If
+ there is, then the snippets are rendered as individual constraints on
+ that ObjectType. If there isn't, then they are just rendered as is (with
+ values substituted). If just a plain field is entered (as in the example
+ above) then it will assume this means equality. If another
+ operator is placed at the end of the snippet, then the values will put
+ interpolated at the end of the constraint, otherwise it will look for
+ <code>$param</code> as outlined previously.</para>
+
+ <para>For consequences: How snippets are rendered also depends on if
+ there is anything in the row immediately above it. If there is nothing
+ there, the output is simple the interpolated snippets. If there is
+ something there (which would typically be a bound variable or a global
+ like in the example above) then it will append it as a method call on
+ that object (refer to the above example).</para>
+
+ <para>This may be easiest to understand with some examples below.
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="spanned_column.png" />
+ </imageobject>
+ </mediaobject>
+ </screenshot> The above shows how the Person ObjectType declaration
+ spans 2 columns in the spreadsheet, thus both constraints will appear as
+ Person(age == ... , type == ...). As before, as only the field names are
+ present in the snippet, they imply an equality test. <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="with_param.png" />
+ </imageobject>
+ </mediaobject>
+ </screenshot> The above condition example shows how you use
+ interpolation to place the values in the snippet (in this case it would
+ result in Person(age == "42")).<screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="operator_completion.png" />
+ </imageobject>
+ </mediaobject>
+ </screenshot> The above condition example show that if you put an
+ operator on the end by itself, the values will be placed after the
+ operator automatically. <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="with_binding.png" />
+ </imageobject>
+ </mediaobject>
+ </screenshot> A binding can be put in before the column
+ (the constraints will be added from the cells below). Anything can be placed in the ObjectType row (eg it could be a pre condition for the
+ columns in the spreadsheet columns that follow).<screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="consequence.png" />
+ </imageobject>
+ </mediaobject>
+ </screenshot> This shows how the consequence could be done the by
+ simple interpolation (just leave the cell above blank, the same applies
+ to condition columns). With this style anything can be placed in
+ the consequence (not just one method call).</para>
+ </section>
+
+ <section>
+ <title>Keywords</title>
+
+ <para>The following table describes the keywords that are pertinent to
+ the rule table structure.</para>
+
+ <table>
+ <title>Keywords</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Keyword</entry>
+
+ <entry>Description</entry>
+
+ <entry>Inclusion Status</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>RuleSet</entry>
+
+ <entry>The cell to the right of this contains the ruleset
+ name</entry>
+
+ <entry>One only (if left out, it will default)</entry>
+ </row>
+
+ <row>
+ <entry>Sequential</entry>
+
+ <entry>The cell to the right of this can be true or false. If
+ true, then salience is used to ensure that rules fire from the
+ top down</entry>
+
+ <entry>optional</entry>
+ </row>
+
+ <row>
+ <entry>Import</entry>
+
+ <entry>The cell to the right contains a comma separated list of
+ Java classes to import</entry>
+
+ <entry>optional</entry>
+ </row>
+
+ <row>
+ <entry>RuleTable</entry>
+
+ <entry>A cell starting with RuleTable indicates the start of a
+ definition of a rule table. The actual rule table starts the
+ next row down. The rule table is read left-to-right, and
+ top-down, until there is one BLANK ROW.</entry>
+
+ <entry>at least one. if there are more, then they are all added
+ to the one ruleset</entry>
+ </row>
+
+ <row>
+ <entry>CONDITION</entry>
+
+ <entry>Indicates that this column will be for rule
+ conditions</entry>
+
+ <entry>At least one per rule table</entry>
+ </row>
+
+ <row>
+ <entry>ACTION</entry>
+
+ <entry>Indicates that this column will be for rule
+ consequences</entry>
+
+ <entry>At least one per rule table</entry>
+ </row>
+
+ <row>
+ <entry>PRIORITY</entry>
+
+ <entry>Indicates that this columns values will set the
+ 'salience' values for the rule row. Over-rides the 'Sequential'
+ flag.</entry>
+
+ <entry>optional</entry>
+ </row>
+
+ <row>
+ <entry>DURATION</entry>
+
+ <entry>Indicates that this columns values will set the duration
+ values for the rule row.</entry>
+
+ <entry>optional</entry>
+ </row>
+
+ <row>
+ <entry>NAME</entry>
+
+ <entry>Indicates that this columns values will set the name for
+ the rule generated from that row</entry>
+
+ <entry>optional</entry>
+ </row>
+
+ <row>
+ <entry>Functions</entry>
+
+ <entry>The cell immediately to the right can contain functions
+ which can be used in the rule snippets. Drools supports
+ functions defined in the DRL, allowing logic to be embedded in
+ the rule, and changed without hard coding, use with care. Same
+ syntax as regular DRL.</entry>
+
+ <entry>optional</entry>
+ </row>
+
+ <row>
+ <entry>Variables</entry>
+
+ <entry>The cell immediately to the right can contain global
+ declarations which Drools supports. This is a type, followed by a
+ variable name. (if multiple variables are needed, comma separate
+ them).</entry>
+
+ <entry>optional</entry>
+ </row>
+
+ <row>
+ <entry>No-loop or Unloop</entry>
+
+ <entry>Placed in the header of a table, no-loop or unloop will both complete the same function of not allowing a rule (row) to loop. For this option to function correctly, there must be a value (true or false) in the cell for the option to take effect. If the cell is left blank then this option will not be set for the row.</entry>
+
+ <entry>optional</entry>
+ </row>
+
+ <row>
+ <entry>XOR-GROUP</entry>
+
+ <entry>Cell values in this column mean that the rule-row belongs
+ to the given XOR/activation group . An Activation group means
+ that only one rule in the named group will fire (ie the first
+ one to fire cancels the other rules activations).</entry>
+
+ <entry>optional</entry>
+ </row>
+
+ <row>
+ <entry>Worksheet</entry>
+
+ <entry>By default, the first worksheet is only looked at for
+ decision tables.</entry>
+
+ <entry>N/A</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <screenshot>
+ <screeninfo>Example usage of keywords for imports, functions
+ etc.</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="Key.png" />
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+
+ <screenshot>
+ <screeninfo>Example usage of keywords for imports, functions
+ etc.</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="keywords.png" />
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ </section>
+ </section>
+
+ <section>
+ <title>Creating and integrating Spreadsheet based Decision Tables</title>
+
+ <para>The API to use spreadsheet based decision tables is in the
+ drools-decisiontables module. There is really only one class to look at:
+ SpreadsheetCompiler. This class will take spreadsheets in various formats,
+ and generate rules in DRL (which you can then use in the normal way). The SpreadsheetComiler can just be used to generate
+ partial rule files if it is wished, and assemble it into a complete rule package after the
+ fact (this allows the seperation of technical and non-technical aspects of
+ the rules if needed).</para>
+
+ <para>To get started, a sample spreadsheet can be used as base. Alternatively, if the plug-in is being used (Rule Workbench IDE), the
+ wizard can generate a spreadsheet from a template (to edit it an xls compatible spreadsheet editor will need to be used). <screenshot>
+ <screeninfo>Wizard in the IDE</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="wizard.png" />
+ </imageobject>
+ </mediaobject>
+ </screenshot></para>
+ </section>
+
+ <section>
+ <title>Managing business rules in decision tables.</title>
+
+ <section>
+ <title>Workflow and collaboration.</title>
+
+ <para>Spreadsheets are well established business tools (in use for over
+ 25 years). Decision tables lend themselves to close collaboration
+ between IT and domain experts, while making the business rules clear to
+ business analysts, it is an ideal separation of concerns.</para>
+
+ <para>Typically, the whole process of authoring rules (coming up with a
+ new decision table) would be something like:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Business analyst takes a template decision table (from a
+ repository, or from IT)</para>
+ </listitem>
+
+ <listitem>
+ <para>Decision table business language descriptions are entered in
+ the table(s)</para>
+ </listitem>
+
+ <listitem>
+ <para>Decision table rules (rows) are entered (roughly)</para>
+ </listitem>
+
+ <listitem>
+ <para>Decision table is handed to a technical resource, who maps the
+ business language (descriptions) to scripts (this may involve
+ software development of course, if it is a new application or data
+ model)</para>
+ </listitem>
+
+ <listitem>
+ <para>Technical person hands back and reviews the modifications with
+ the business analyst.</para>
+ </listitem>
+
+ <listitem>
+ <para>The business analyst can continue editing the rule rows as
+ needed (moving columns around is also fine etc).</para>
+ </listitem>
+
+ <listitem>
+ <para>In parallel, the technical person can develop test cases for
+ the rules (liaising with business analysts) as these test cases can
+ be used to verify rules and rule changes once the system is
+ running.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>Using spreadsheet features</title>
+
+ <para>Features of applications like Excel can be used to provide
+ assistance in entering data into spreadsheets, such as validating
+ fields. Lists that are stored in other worksheets can bse used to provide
+ valid lists of values for cells, like in the following diagram.
+ <screenshot>
+ <screeninfo>Wizard in the IDE</screeninfo>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="lists.png" />
+ </imageobject>
+ </mediaobject>
+ </screenshot></para>
+
+ <para>Some applications provide a limited ability to keep a history of
+ changes, but it is recommended that an alternative means of revision
+ control is also used. When changes are being made to rules over time,
+ older versions are archived (many solutions exist for this which are
+ also open source, such as Subversion).
+ http://www.drools.org/Business+rules+in+decision+tables+explained</para>
+ </section>
+ </section>
+
+</chapter>
Deleted: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Decision_Tables/Section-Spreadsheet.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Decision_Tables/Section-Spreadsheet.xml 2008-06-14 16:26:55 UTC (rev 20482)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Decision_Tables/Section-Spreadsheet.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -1,602 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<section>
- <title>Decision tables in spreadsheets</title>
-
- <para>Decision tables are a "precise yet compact" (ref. Wikipedia) way of
- representing conditional logic, and are well suited to <emphasis>business</emphasis> level
- rules.</para>
-
- <para>Drools supports managing rules in a Spreadsheet format. Formats
- supported are Excel, and CSV. Meaning that a variety of spreadsheet
- programs (such as Microsoft Excel, OpenOffice.org Calc amongst others) can be utalized. It
- is expected that web based decision table editors will be included in a near
- future release.</para>
-
- <para>Decision tables are an old concept (in software terms) but have proven
- useful over the years. Very briefly speaking, in Drools decision tables are
- a way to generate rules driven from the data entered into a spreadsheet. All
- the usual features of a spreadsheet for data capture and manipulation can be
- taken advantage of.</para>
-
- <section>
- <title>When to use Decision tables</title>
-
- <para>Decision tables my want to be considered as a course of action if rules exist that can
- be expressed as rule templates + data. In each row of a decision table,
- data is collected that is combined with the templates to generate a
- rule.</para>
-
- <para>Many businesses already use spreadsheets for managing data,
- calculations etc. If you are happy to continue this way, you can also
- manage your business rules this way. This also assumes you are happy to
- manage packages of rules in .xls or .csv files. Decision tables are not
- recommenced for rules that do not follow a set of templates, or where
- there are a small number of rules (or if there is a dislike towards software like excel or open office). They are ideal in the sense that there can be control over what <emphasis>parameters</emphasis> of rules can be edited, without exposing the
- rules directly.</para>
-
- <para>Decision tables also provide a degree of insulation from the
- underlying object model.</para>
- </section>
-
- <section>
- <title>Overview</title>
-
- <para>Here are some examples of real world decision tables (slightly
- edited to protect the innocent).</para>
-
- <screenshot>
- <screeninfo>Using excel to edit a decision table</screeninfo>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="excel.png" />
- </imageobject>
- </mediaobject>
- </screenshot>
-
- <screenshot>
- <screeninfo>Can have multiple actions for a rule row</screeninfo>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="actions.png" />
- </imageobject>
- </mediaobject>
- </screenshot>
-
- <screenshot>
- <screeninfo>Using OpenOffice</screeninfo>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="open_office.png" />
- </imageobject>
- </mediaobject>
- </screenshot>
-
- <para>In the above examples, the technical aspects of the decision table
- have been collapsed away (standard spreadsheet feature).</para>
-
- <para>The rules start from row 17 (each row results in a rule). The
- conditions are in column C, D, E etc.. (off screen are the actions). The value in the cells are quite simple, and have meaning
- when looking at the headers in Row 16. Column B is just a description. It
- is conventional to use color to make it obvious what the different areas
- of the table mean.</para>
-
-<note>
- <para>Note that although the decision tables look like they process top
- down, this is not necessarily the case. Idealy, if the rules are able to be authored in such a way as order does not matter (simply as it makes
- maintenance easier, as rows will not need to be shifted around all the time).</para>
-</note>
- <para>
- As each row is a rule, the same principles apply. As the rule engine
- processes the facts, any rules that match may fire (some people are
- confused by this. It is possible to clear the agenda when a rule fires
- and simulate a very simple decision table where the first match exists).
- Also note that you can have multiple tables on the one spreadsheet (so
- rules can be grouped where they share common templates, yet at the end of
- the day they are all combined into a one rule package). Decision tables
- are essentially a tool to generate DRL rules automatically.</para>
-
-
- <screenshot>
- <screeninfo>A real world example using multiple tables for grouping like
- rules</screeninfo>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="multi_table.png" />
- </imageobject>
- </mediaobject>
- </screenshot>
- </section>
-
- <section>
- <title>How decision tables work</title>
-
- <para>The key point to keep in mind is that in a decision table, each row
- is a rule, and each column in that row is either a condition or action for
- that rule.</para>
-
- <screenshot>
- <screeninfo>Rows and columns</screeninfo>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="row_col.png" />
- </imageobject>
- </mediaobject>
- </screenshot>
-
- <para>The spreadsheet looks for the <firstterm>RuleTable</firstterm> keyword to indicate the
- start of a rule table (both the starting row and column). Other keywords
- are also used to define other package level attributes (covered later). It
- is important to keep the keywords in the one column. By convention the
- second column ("B") is used for this, but it can be any column (convention
- is to leave a margin on the left for notes). In the following diagram, C
- is actually the column where it starts. Everything to the left of this is
- ignored.</para>
-
- <para>If we expand the hidden sections, it starts to make more sense how
- it works; note the keywords in column C.</para>
-
- <screenshot>
- <screeninfo>Expanded for rule templates</screeninfo>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="expanded.png" />
- </imageobject>
- </mediaobject>
- </screenshot>
-
- <para>Now the hidden magic which makes it work can be seen. The RuleSet
- keyword indicates the name to be used in the <emphasis>rule package</emphasis> that all the
- rules will come under (the name is optional, it will have a default but
- it MUST have the <emphasis>RuleSet</emphasis> keyword) in the cell immediately to the right.</para>
-<para>
- The other keywords visible in Column C are: Import, Sequential which will
- be covered later. The RuleTable keyword is important as it indicates that
- a chunk of rules will follow, based on some rule templates. After the
- RuleTable keyword there is a name - this name is used to prefix the
- generated rules names (the row numbers are appended to create unique rule
- names). The column of RuleTable indicates the column in which the rules
- start (columns to the left are ignored).</para>
-<note>
- <para>
- In general the keywords make up name/value pairs.
- </para>
-</note>
-
- <para>Referring to row 14 (the row immediately after RuleTable): the
- keywords CONDITION and ACTION indicate that the data in the columns below
- are for either the LHS or the RHS parts of a rule. There are other
- attributes on the rule which can also be optionally set this way.</para>
-
-<para>Row 15 contains declarations of <firstterm>ObjectTypes</firstterm>; the content in this
- row is optional (if this option is not in use, a blank row must be left, however this option is usually found to be quite useful). When using this row, the values in the
- cells below (row 16) become constraints on that object type. In the above
- case, it will generate: Person(age=="42") etc (where 42 comes from row
- 18). In the above example, the "==" is implicit (if just a field
- name is given it will assume that it is to look for exact matches).
-</para>
-<note>
- <para>
- An ObjectType declaration can span columns (via merged cells), meaning that all columns below the merged range will be combined
- into the one set of constraints.</para>
-</note>
-
- <para>Row 16 contains the rule templates themselves. They can
- use the "$para" place holder to indicate where data from the cells below
- will be populated ($param can be sued or $1, $2 etc to indicate
- parameters from a comma separated list in a cell below). Row 17 is ignored
- as it is textual descriptions of the rule template.</para>
-
- <para>Row 18 to 19 shows data, which will be combined (interpolated) with
- the templates in row 15, to generate rules. If a cell contains no data,
- then its template is ignored (eg it means that condition, or action, does
- not apply for that rule-row). Rule rows are read until there is a BLANK
- row. Multiple RuleTables can exsist in a sheet. Row 20 contains another
- keyword, and a value. The row positions of keywords like this do not
- matter (most people put them at the top) but their column should be the
- same one where the RuleTable or RuleSet keywords should appear (in this
- case column C has been chosen to be significant, but column A
- could be used instead).</para>
-
- <para>In the above example, rules would be rendered like the following (as
- it uses the "ObjectType" row):</para>
-<screen>//row 18
-rule "Cheese_fans_18"
- when
- Person(age=="42")
- Cheese(type=="stilton")
- then
- list.add("Old man stilton");
-end
-</screen>
-<note>
- <para>
- The [age=="42"] and [type=="stilton"] are
- interpreted as single constraints to be added to the respective ObjectType
- in the cell above (if the cells above were spanned, then there could be
- multiple constraints on one "column".</para>
-</note>
- </section>
-
- <section>
- <title>Keywords and syntax</title>
-
- <section>
- <title>Syntax of templates</title>
-
- <para>The syntax of what goes in the templates is dependent on if it is
- a CONDITION column or ACTION column. In most cases, it is identical to
- <emphasis>vanilla</emphasis> DRL for the LHS or RHS respectively. This means in the LHS,
- the constraint language must be used, and in the RHS it is a snippet of
- code to be executed.</para>
-
-<para>The <code>$param</code> place holder is used in templates to indicate where
- data form the cell will be interpolated. You can also use <code>$1</code> to the
- same effect. If the cell contains a comma separated list of values, $1
- and $2 etc. may be used to indicate which positional parameter from the
- list of values in the cell will be used.</para>
-<example>
-<para>
-If the templates is [Foo(bar == $param)] and the cell is [ 42 ] then the result will be [Foo(bar == 42)]
-If the template is [Foo(bar < $1, baz == $2)] and the cell is [42,42] then the result will be [Foo(bar > 42, baz ==42)]
-</para>
-</example>
-
- <para>For conditions: How snippets are rendered depends on if there is
- anything in the row above (where ObjectType declarations may appear). If
- there is, then the snippets are rendered as individual constraints on
- that ObjectType. If there isn't, then they are just rendered as is (with
- values substituted). If just a plain field is entered (as in the example
- above) then it will assume this means equality. If another
- operator is placed at the end of the snippet, then the values will put
- interpolated at the end of the constraint, otherwise it will look for
- <code>$param</code> as outlined previously.</para>
-
- <para>For consequences: How snippets are rendered also depends on if
- there is anything in the row immediately above it. If there is nothing
- there, the output is simple the interpolated snippets. If there is
- something there (which would typically be a bound variable or a global
- like in the example above) then it will append it as a method call on
- that object (refer to the above example).</para>
-
- <para>This may be easiest to understand with some examples below.
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="spanned_column.png" />
- </imageobject>
- </mediaobject>
- </screenshot> The above shows how the Person ObjectType declaration
- spans 2 columns in the spreadsheet, thus both constraints will appear as
- Person(age == ... , type == ...). As before, as only the field names are
- present in the snippet, they imply an equality test. <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="with_param.png" />
- </imageobject>
- </mediaobject>
- </screenshot> The above condition example shows how you use
- interpolation to place the values in the snippet (in this case it would
- result in Person(age == "42")).<screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="operator_completion.png" />
- </imageobject>
- </mediaobject>
- </screenshot> The above condition example show that if you put an
- operator on the end by itself, the values will be placed after the
- operator automatically. <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="with_binding.png" />
- </imageobject>
- </mediaobject>
- </screenshot> A binding can be put in before the column
- (the constraints will be added from the cells below). Anything can be placed in the ObjectType row (eg it could be a pre condition for the
- columns in the spreadsheet columns that follow).<screenshot>
- <mediaobject>
- <imageobject>
- <imagedata fileref="consequence.png" />
- </imageobject>
- </mediaobject>
- </screenshot> This shows how the consequence could be done the by
- simple interpolation (just leave the cell above blank, the same applies
- to condition columns). With this style anything can be placed in
- the consequence (not just one method call).</para>
- </section>
-
- <section>
- <title>Keywords</title>
-
- <para>The following table describes the keywords that are pertinent to
- the rule table structure.</para>
-
- <table>
- <title>Keywords</title>
-
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Keyword</entry>
-
- <entry>Description</entry>
-
- <entry>Inclusion Status</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>RuleSet</entry>
-
- <entry>The cell to the right of this contains the ruleset
- name</entry>
-
- <entry>One only (if left out, it will default)</entry>
- </row>
-
- <row>
- <entry>Sequential</entry>
-
- <entry>The cell to the right of this can be true or false. If
- true, then salience is used to ensure that rules fire from the
- top down</entry>
-
- <entry>optional</entry>
- </row>
-
- <row>
- <entry>Import</entry>
-
- <entry>The cell to the right contains a comma separated list of
- Java classes to import</entry>
-
- <entry>optional</entry>
- </row>
-
- <row>
- <entry>RuleTable</entry>
-
- <entry>A cell starting with RuleTable indicates the start of a
- definition of a rule table. The actual rule table starts the
- next row down. The rule table is read left-to-right, and
- top-down, until there is one BLANK ROW.</entry>
-
- <entry>at least one. if there are more, then they are all added
- to the one ruleset</entry>
- </row>
-
- <row>
- <entry>CONDITION</entry>
-
- <entry>Indicates that this column will be for rule
- conditions</entry>
-
- <entry>At least one per rule table</entry>
- </row>
-
- <row>
- <entry>ACTION</entry>
-
- <entry>Indicates that this column will be for rule
- consequences</entry>
-
- <entry>At least one per rule table</entry>
- </row>
-
- <row>
- <entry>PRIORITY</entry>
-
- <entry>Indicates that this columns values will set the
- 'salience' values for the rule row. Over-rides the 'Sequential'
- flag.</entry>
-
- <entry>optional</entry>
- </row>
-
- <row>
- <entry>DURATION</entry>
-
- <entry>Indicates that this columns values will set the duration
- values for the rule row.</entry>
-
- <entry>optional</entry>
- </row>
-
- <row>
- <entry>NAME</entry>
-
- <entry>Indicates that this columns values will set the name for
- the rule generated from that row</entry>
-
- <entry>optional</entry>
- </row>
-
- <row>
- <entry>Functions</entry>
-
- <entry>The cell immediately to the right can contain functions
- which can be used in the rule snippets. Drools supports
- functions defined in the DRL, allowing logic to be embedded in
- the rule, and changed without hard coding, use with care. Same
- syntax as regular DRL.</entry>
-
- <entry>optional</entry>
- </row>
-
- <row>
- <entry>Variables</entry>
-
- <entry>The cell immediately to the right can contain global
- declarations which Drools supports. This is a type, followed by a
- variable name. (if multiple variables are needed, comma separate
- them).</entry>
-
- <entry>optional</entry>
- </row>
-
- <row>
- <entry>No-loop or Unloop</entry>
-
- <entry>Placed in the header of a table, no-loop or unloop will both complete the same function of not allowing a rule (row) to loop. For this option to function correctly, there must be a value (true or false) in the cell for the option to take effect. If the cell is left blank then this option will not be set for the row.</entry>
-
- <entry>optional</entry>
- </row>
-
- <row>
- <entry>XOR-GROUP</entry>
-
- <entry>Cell values in this column mean that the rule-row belongs
- to the given XOR/activation group . An Activation group means
- that only one rule in the named group will fire (ie the first
- one to fire cancels the other rules activations).</entry>
-
- <entry>optional</entry>
- </row>
-
- <row>
- <entry>Worksheet</entry>
-
- <entry>By default, the first worksheet is only looked at for
- decision tables.</entry>
-
- <entry>N/A</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <screenshot>
- <screeninfo>Example usage of keywords for imports, functions
- etc.</screeninfo>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="Key.png" />
- </imageobject>
- </mediaobject>
- </screenshot>
-
- <screenshot>
- <screeninfo>Example usage of keywords for imports, functions
- etc.</screeninfo>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="keywords.png" />
- </imageobject>
- </mediaobject>
- </screenshot>
- </section>
- </section>
-
- <section>
- <title>Creating and integrating Spreadsheet based Decision Tables</title>
-
- <para>The API to use spreadsheet based decision tables is in the
- drools-decisiontables module. There is really only one class to look at:
- SpreadsheetCompiler. This class will take spreadsheets in various formats,
- and generate rules in DRL (which you can then use in the normal way). The SpreadsheetComiler can just be used to generate
- partial rule files if it is wished, and assemble it into a complete rule package after the
- fact (this allows the seperation of technical and non-technical aspects of
- the rules if needed).</para>
-
- <para>To get started, a sample spreadsheet can be used as base. Alternatively, if the plug-in is being used (Rule Workbench IDE), the
- wizard can generate a spreadsheet from a template (to edit it an xls compatible spreadsheet editor will need to be used). <screenshot>
- <screeninfo>Wizard in the IDE</screeninfo>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="wizard.png" />
- </imageobject>
- </mediaobject>
- </screenshot></para>
- </section>
-
- <section>
- <title>Managing business rules in decision tables.</title>
-
- <section>
- <title>Workflow and collaboration.</title>
-
- <para>Spreadsheets are well established business tools (in use for over
- 25 years). Decision tables lend themselves to close collaboration
- between IT and domain experts, while making the business rules clear to
- business analysts, it is an ideal separation of concerns.</para>
-
- <para>Typically, the whole process of authoring rules (coming up with a
- new decision table) would be something like:</para>
-
- <orderedlist>
- <listitem>
- <para>Business analyst takes a template decision table (from a
- repository, or from IT)</para>
- </listitem>
-
- <listitem>
- <para>Decision table business language descriptions are entered in
- the table(s)</para>
- </listitem>
-
- <listitem>
- <para>Decision table rules (rows) are entered (roughly)</para>
- </listitem>
-
- <listitem>
- <para>Decision table is handed to a technical resource, who maps the
- business language (descriptions) to scripts (this may involve
- software development of course, if it is a new application or data
- model)</para>
- </listitem>
-
- <listitem>
- <para>Technical person hands back and reviews the modifications with
- the business analyst.</para>
- </listitem>
-
- <listitem>
- <para>The business analyst can continue editing the rule rows as
- needed (moving columns around is also fine etc).</para>
- </listitem>
-
- <listitem>
- <para>In parallel, the technical person can develop test cases for
- the rules (liaising with business analysts) as these test cases can
- be used to verify rules and rule changes once the system is
- running.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>Using spreadsheet features</title>
-
- <para>Features of applications like Excel can be used to provide
- assistance in entering data into spreadsheets, such as validating
- fields. Lists that are stored in other worksheets can bse used to provide
- valid lists of values for cells, like in the following diagram.
- <screenshot>
- <screeninfo>Wizard in the IDE</screeninfo>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="lists.png" />
- </imageobject>
- </mediaobject>
- </screenshot></para>
-
- <para>Some applications provide a limited ability to keep a history of
- changes, but it is recommended that an alternative means of revision
- control is also used. When changes are being made to rules over time,
- older versions are archived (many solutions exist for this which are
- also open source, such as Subversion).
- http://www.drools.org/Business+rules+in+decision+tables+explained</para>
- </section>
- </section>
-
-</section>
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Deployment
___________________________________________________________________
Name: svn:ignore
+ Thumbs.db
Added: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Deployment/Chapter-DepymentAndTest.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Deployment/Chapter-DepymentAndTest.xml (rev 0)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Deployment/Chapter-DepymentAndTest.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns:xi="http://www.w3.org/2001/XInclude" >
+ <title>Deployment and Testing</title>
+
+ <xi:include href="Section-Deployment.xml" />
+
+ <xi:include href="Section-Testing.xml" />
+</chapter>
\ No newline at end of file
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Examples/Chapter-Examples.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Examples/Chapter-Examples.xml 2008-06-14 16:26:55 UTC (rev 20482)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Examples/Chapter-Examples.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
-<section xmlns:xi="http://www.w3.org/2001/XInclude">
- <title></title>
+<chapter xmlns:xi="http://www.w3.org/2001/XInclude" >
+ <title>Examples</title>
<section>
<title>Getting the examples</title>
@@ -31,4 +31,4 @@
<xi:include href="Section-ConwaysGameOfLifeExample.xml" />
-</section>
+</chapter>
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-IDE
___________________________________________________________________
Name: svn:ignore
+ Thumbs.db
Copied: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-IDE/Chapter-QuickStart.xml (from rev 20476, labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-IDE/Section-QuickStart.xml)
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-IDE/Chapter-QuickStart.xml (rev 0)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-IDE/Chapter-QuickStart.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -0,0 +1,762 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns:xi="http://www.w3.org/2001/XInclude" >
+ <title>The (Eclipse based) Rule IDE</title>
+
+ <para>
+ The IDE provides developers (and very technical users) with an environment to edit and test rules in various formats, and integrate it deeply with their applications. In cases where you prefer business rules and web tooling, you will want to look at the BRMS (but using the BRMS and the IDE together is not uncommon).</para>
+
+ <para>The Drools IDE is delivered as an Eclipse plug-in, which
+ allows you to author and manage rules from within Eclipse, as well as
+ integrate rules with your application. This is an optional tool, and not all
+ components are required to be used, you can use what components are relevant
+ to you. The Drools IDE is also a part of the Red Hat Developer Studio (formerly known as JBoss IDE).</para>
+
+ <para>This guide will cover some of the features of JBoss Drools, in as far
+ as the IDE touches on them (it is assumed that the reader has some
+ familiarity with rule engines, and Drools in particular. It is important to
+ note that none of the underlying features of the rule engine are dependent
+ on Eclipse, and integrators are free to use their tools of choice, as always
+ ! Plenty of people use IntelliJ with rules, for instance.</para>
+
+ <para>Note you can get the plug-in either as a zip to download, or from an
+ update site (refer to the chapter on installation).</para>
+
+ <figure>
+ <title>Overview</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="all.jpg" format="JPG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <section>
+ <title>Features outline</title>
+
+ <para>The rules IDE has the following features</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Textual/graphical rule editor</para>
+
+ <orderedlist>
+ <listitem>
+ <para>An editor that is aware of DRL syntax, and provides content
+ assistance (including an outline view)</para>
+ </listitem>
+ <listitem>
+ <para>An editor that is aware of DSL (domain specific langauge) extensions, and provides content assistance.</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+
+ <listitem>
+ <para>RuleFlow graphical editor</para>
+ <para>You can edit visual graphs which represent a process (a rule flow). The RuleFlow can then be applied to your rule package to have imperative control.</para>
+ </listitem>
+
+ <listitem>
+ <para>Wizards to accelerate and ...</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Help you quickly create a new "rules" project</para>
+ </listitem>
+
+ <listitem>
+ <para>Create a new rule resource</para>
+ </listitem>
+
+ <listitem>
+ <para>Create a new Domain Specific language</para>
+ </listitem>
+
+ <listitem>
+ <para>Create a new decision table, guided editor, ruleflow</para>
+ </listitem>
+
+
+ </orderedlist>
+ </listitem>
+
+ <listitem>
+ <para>A domain specific language editor</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Create and manage mappings from your users language to the
+ rule language</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+
+ <listitem>
+ <para>Rule validation</para>
+
+ <orderedlist>
+ <listitem>
+ <para>As rules are entered, the rule is "built" in the background
+ and errors reported via the problem "view" where possible</para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </orderedlist>
+
+ <para>You can see the above features make use of Eclipse infrastructure
+ and features. All of the power of Eclipse is available.</para>
+ </section>
+
+ <section>
+ <title>Creating a Rule project</title>
+
+ <para>The aim of the new project wizard is to setup an executable scaffold
+ project to start using rules immediately. This will setup a basic
+ structure, classpath and sample rules and test case to get you
+ started.</para>
+
+ <figure>
+ <title>New rule project scaffolding</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="new_project1.jpg" format="JPG" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>When you choose to create a new "rule project" - you will get a choice to add some default artifacts to it (like rules, decision tables, ruleflows etc). These can serve as a starting point, and will give you something executable to play with (which you can then modify and mould to your needs). The simplest case (a hello world rule) is shown below. Feel free to experiment with the plug-in at this point.</para>
+
+ <figure>
+ <title>New rule project result</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="new_project2.png" format="JPG" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The newly created project contains an example rule file (Sample.drl)
+ in the src/rules dir and an example Java file (DroolsTest.Java) that can
+ be used to execute the rules in a Drools engine in the folder src/Java, in
+ the com.sample package. All the others jars that are necessary during
+ execution are also added to the classpath in a custom classpath container
+ called Drools Library. Rules do not have to be kept in "Java"
+ projects at all, this is just a convenience for people who are already
+ using Eclipse as their Java IDE.</para>
+
+ <para>Important note: The Drools plug-in adds a "Drools Builder"
+ capability to your Eclipse instance. This means you can enable a builder
+ on any project that will build and validate your rules when resources
+ change. This happens automatically with the Rule Project Wizard, but you
+ can also enable it manually on any project. One downside of this is if you
+ have rule files that have a large number of rules (>500 rules per file)
+ it means that the background builder may be doing a lot of work to
+ build the rules on each change. An option here is to turn off the builder,
+ or put the large rules into .rule files, where you can still use the rule
+ editor, but it won't build them in the background - to fully validate the
+ rules you will need to run them in a unit test of course.</para>
+ </section>
+
+ <section>
+ <title>Creating a new rule and wizards</title>
+
+ <para>You can create a rule simple as an empty text ".drl" file, or use
+ the wizard to do so. The wizard menu can be invoked by Control+N, or
+ choosing it from the toolbar (there will be a menu with the JBoss Drools
+ icon).</para>
+
+ <figure>
+ <title>The wizard menu</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="wizards.jpg" format="JPG" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The wizard will ask for some basic options for generating a rule
+ resource. These are just hints, you can change your mind later !. In terms
+ of location, typically you would create a top level /rules directory to
+ store your rules if you are creating a rule project, and store it in a
+ suitably named subdirectory. The package name is mandatory, and is similar
+ to a package name in Java (ie. its a namespace that groups like rules
+ together).</para>
+
+ <figure>
+ <title>New rule wizard</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="new_rule.jpg" format="JPG" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>This result of this wizard is to generate a rule skeleton to work
+ from. As with all wizards, they are candy: you don't have to use them if
+ you don't want !</para>
+ </section>
+
+ <section>
+ <title>Textual rule editor</title>
+
+ <para>The rule editor is where rule managers and developers will be
+ spending most of their time. The rule editor follows the pattern of a
+ normal text editor in Eclipse, with all the normal features of a text
+ editor. On top of this, the rule editor provides pop up content
+ assistance. You invoke popup content assistance the "normal" way by
+ pressing Control + Space at the same time.</para>
+
+ <figure>
+ <title>The rule editor in action</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="editor1.jpg" format="JPG" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The rule editor works on files that have a .drl (or .rule)
+ extension. Rules are generally grouped together as a "package" of rules
+ (like the old ruleset construct). It will also be possible to have rules
+ in individual files (grouped by being in the same package "namespace" if
+ you like). These DRL files are plain text files.</para>
+
+ <para>You can see from the example above that the package is using a
+ domain specific language (note the expander keyword, which tells the rule
+ compiler to look for a dsl file of that name, to resolve the rule
+ language). Even with the domain specific language (DSL) the rules are
+ still stored as plain text as you see on screen, which allows simpler
+ management of rules and versions (comparing versions of rules for
+ instance).</para>
+
+ <para>The editor has an outline view that is kept in sync with the
+ structure of the rules (updated on save). This provides a quick way of
+ navigating around rules by name, in a file which may have hundreds of
+ rules. The items are sorted alphabetically by default.</para>
+
+ <figure>
+ <title>The rule outline view</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="outline.jpg" format="JPG" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+
+<section>
+ <title>Guided editor (rule GUI)</title>
+ <para>
+ A new feature of the Drools IDE (since version 4) is the guided editor for rules. This is similar to the web based editor that is available in the BRMS. This allows you to build rules in a GUI driven fashion, based on your object model.
+ </para>
+
+ <figure>
+ <title>The guided editor</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="guidededitor1.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>
+ To create a rule this way, use the wizard menu. It will create a instance of a .brl file and open an editor. The guided editor works based on a .package file in the same directory as the .brl file. In this "package" file - you have the package name and import statements - just like you would in the top of a normal DRL file. So the first time you create a brl rule - you will need to ppulate the package file with the fact classes you are interested in. Once you have this the guided editor will be able to prompt you with facts/fields and build rules graphically.
+ </para>
+
+ <para>
+ The guided editor works off the model classes (fact classes) that you configure. It then is able to "render" to DRL the rule that you have entered graphically. You can do this visually - and use it as a basis for learning DRL, or you can use it and build rules of the brl directly. To do this, you can either use the drools-ant module (it is an ant task that will build up all the rule assets in a folder as a rule package - so you can then deploy it as a binary file), OR you can use the following snippet of code to convert the brl to a drl rule:
+
+ </para>
+
+ <programlisting>BRXMLPersitence read = BRXMLPersitence.getInstance();
+BRDRLPersistence write = BRDRLPersistence.getInstance();
+String brl = ... read from the .brl file as needed...
+String outputDRL = write.marshall(read.unmarshal(brl));
+//then pass the outputDRL to the PackageBuilder as normal</programlisting>
+</section>
+
+ <section>
+ <title>Views</title>
+
+ <para>When debugging an application using a Drools engine, these views
+ can be used to check the state of the Drools engine itself: the Working
+ Memory View, the Agenda View the Global Data View. To be able to use
+ these views, create breakpoints in your code invoking the working memory.
+ For example, the line where you call workingMemory.fireAllRules() is a
+ good candidate. If the debugger halts at that joinpoint, you should select
+ the working memory variable in the debug variables view. The following
+ rules can then be used to show the details of the selected working
+ memory:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The Working Memory shows all elements in the working memory of
+ the Drools working memory.</para>
+ </listitem>
+
+ <listitem>
+ <para>The Agenda View shows all elements on the agenda. For each rule
+ on the agenda, the rule name and bound variables are shown.</para>
+ </listitem>
+
+ <listitem>
+ <para>The Global Data View shows all global data currently defined in
+ the Drools working memory.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>The Audit view can be used to show audit logs that contain events
+ that were logged during the execution of a rules engine in a tree
+ view.</para>
+
+ <section>
+ <title>The Working Memory View</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="workingMemory.png" />
+ </imageobject>
+ </mediaobject>
+
+ <para>The Working Memory shows all elements in the working memory of the
+ Drools engine.</para>
+
+ <para>An action is added to the right of the view, to customize what is
+ shown:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The Show Logical Structure toggles showing the logical
+ structure of the elements in the working memory, or all their
+ details. Logical structures allow for example visualizing sets of
+ elements in a more obvious way.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>The Agenda View</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="agenda.png" />
+ </imageobject>
+ </mediaobject>
+
+ <para>The Agenda View shows all elements on the agenda. For each rule on
+ the agenda, the rule name and bound variables are shown.</para>
+
+ <para>An action is added to the right of the view, to customize what is
+ shown:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The Show Logical Structure toggles showing the logical
+ structure of the agenda item, or all their details. Logical
+ structures allow for example visualizing sets of elements in a more
+ obvious way. The logical structure of AgendaItems shows the rule
+ that is represented by the AgendaItem, and the values of all the
+ parameters used in the rule.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>The Global Data View</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="globals.png" />
+ </imageobject>
+ </mediaobject>
+
+ <para>The Global Data View shows all global data currently defined in
+ the Drools engine.</para>
+
+ <para>An action is added to the right of the view, to customize what is
+ shown:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The Show Logical Structure toggles showing the logical
+ structure of the elements in the working memory, or all their
+ details. Logical structures allow for example visualizing sets of
+ elements in a more obvious way.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>The Audit View</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="audit.jpg" scalefit="1" width="100%" />
+ </imageobject>
+ </mediaobject>
+
+ <para>The audit view can be used to visualize an audit log that can be
+ created when executing the rules engine. To create an audit log, use the
+ following code:</para>
+
+ <programlisting> WorkingMemory workingMemory = ruleBase.newWorkingMemory();
+ // create a new Working Memory Logger, that logs to file.
+ WorkingMemoryFileLogger logger = new WorkingMemoryFileLogger(workingMemory);
+ // an event.log file is created in the log dir (which must exist)
+ // in the working directory
+ logger.setFileName("log/event");
+
+ workingMemory.assertObject( ... );
+ workingMemory.fireAllRules();
+
+ // stop logging
+ logger.writeToDisk();</programlisting>
+
+ <para>Open the log by clicking the Open Log action (first action in the
+ Audit View) and select the file. The Audit view now shows all events
+ that where logged during the executing of the rules. There are different
+ types of events (each with a different icon):</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Object inserted (green square)</para>
+ </listitem>
+
+ <listitem>
+ <para>Object updated (yellow square)</para>
+ </listitem>
+
+ <listitem>
+ <para>Object removed (red square)</para>
+ </listitem>
+
+ <listitem>
+ <para>Activation created (arrow to the right)</para>
+ </listitem>
+
+ <listitem>
+ <para>Activation cancelled (arrow to the left)</para>
+ </listitem>
+
+ <listitem>
+ <para>Activation executed (blue diamond)</para>
+ </listitem>
+
+ <listitem>
+ <para>Ruleflow started / ended (process icon)</para>
+ </listitem>
+
+ <listitem>
+ <para>Ruleflow-group activated / deactivated (process icon)</para>
+ </listitem>
+
+ <listitem>
+ <para>Rule package added / removed (Drools icon)</para>
+ </listitem>
+
+ <listitem>
+ <para>Rule added / removed (Drools icon)</para>
+ </listitem>
+ </orderedlist>
+
+ <para>All these events show extra information concerning the event, like
+ the id and toString representation of the object in case of working
+ memory events (assert, modify and retract), the name of the rule and all
+ the variables bound in the activation in case of an activation event
+ (created, cancelled or executed). If an event occurs when executing an
+ activation, it is shown as a child of the activation executed event. For
+ some events, you can retrieve the "cause":</para>
+
+ <orderedlist>
+ <listitem>
+ <para>The cause of an object modified or retracted event is the last
+ object event for that object. This is either the object asserted
+ event, or the last object modified event for that object.</para>
+ </listitem>
+
+ <listitem>
+ <para>The cause of an activation cancelled or executed event is the
+ corresponding activation created event.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>When selecting an event, the cause of that event is shown in green
+ in the audit view (if visible of course). You can also right click the
+ action and select the "Show Cause" menu item. This will scroll you to
+ the cause of the selected event.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>Domain Specific Languages</title>
+
+ <para>Domain Specific Languages (dsl) allow you to create a language that
+ allows your rules to look like, rules ! Most often the domain specific
+ language reads like natural language. Typically you would look at how a
+ business analyst would describe the rule, in their own words, and then map
+ this to your object model via rule constructs. A side benefit of this is
+ that it can provide an insulation layer between your domain objects, and
+ the rules themselves (as we know you like to refactor !). A domain
+ specific language will grow as the rules grow, and works best when there
+ are common terms used over an over, with different parameters.</para>
+
+ <para>To aid with this, the rule workbench provides an editor for domain
+ specific languages (they are stored in a plain text format, so you can
+ use any editor of your choice - it uses a slightly enhanced version of the
+ "Properties" file format, simply). The editor will be invoked on any files
+ with a .dsl extension (there is also a wizard to create a sample
+ DSL).</para>
+
+ <section>
+ <title>Editing languages</title>
+
+ <figure>
+ <title>The Domain Specific Language editor</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="dsl_editor.jpg" format="JPG" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>The DSL editor provides a table view of Language Expression to
+ Rule Expression mapping. The Language expression is what is used in the
+ rules. This also feeds the content assistance for the rule editor, so
+ that it can suggest Language Expressions from the DSL configuration (the
+ rule editor loads up the DSL configuration when the rule resource is
+ loaded for editing). The Rule language mapping is the "code" for the
+ rules - which the language expression will be compiled to by the rule
+ engine compiler. For form of this Rule language depends if it is for a
+ condition or action part of a rule (it may be a snippet of Java, for
+ instance). The "scope" item indicates where the expression is targeted:
+ is it for the "when" part of the rule (LHS)? the "then" part (RHS)? Or
+ anywhere?</para>
+
+ <para>By selecting a mapping item (a row in the table) you can see the
+ expression and mapping in the greyed out fields below. Double clicking
+ or pressing the edit button will open the edit dialog. You can remove
+ items, and add new ones (you should generally only remove when you know
+ that expression is no longer in use).</para>
+
+ <figure>
+ <title>Language Mapping editor dialog</title>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="mapping_editor.jpg"
+ format="JPG" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>How it works: the "Language expression" is used to parse the rule
+ language, depending on what the "scope" is set to. When it is found in a
+ rule, the values that are market by the curly braces {value} are
+ extracted from the rule source. These values are then interpolated with
+ the "Rule mapping" expression, based on the names between the curly
+ braces. So in the example above, the natural language expression maps
+ to 2 constraints on a fact of type Person (ie the person object has the
+ age field as less than {age}, and the location value is the string of
+ {value}, where {age} and {value} are pulled out of the original rule
+ source. The Rule mapping may be a Java expression (such as if the scope
+ was "then"). If you did not wish to use a language mapping for a
+ particular rule in a drl, prefix the expression with > and the
+ compiler will not try to translate it according to the language
+ definition. Also note that domain specific languages are optional. When
+ the rule is compiled, the .dsl file will also need to be
+ available.</para>
+ </section>
+ </section>
+
+ <section>
+ <title>The Rete View</title>
+
+ <para>The Rete Tree View shows you the current Rete Network for your drl
+ file. Just click on the tab "Rete Tree" below on the DRL Editor.
+ Afterwards you can generate the current Rete Network visualization. You
+ can push and pull the nodes to arrange your optimal network overview. If
+ you got hundreds of nodes, select some of them with a frame. Then you can
+ pull groups of them. You can zoom in and out, in case not all nodes are
+ shown in the current view. For this press the button "+" oder "-".</para>
+
+ <para>There is no export function, which creates a gif or jpeg picture, in
+ the current release. Please use ctrl + alt + print to create a copy of
+ your current Eclipse window and cut it off.</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="thereteview.jpg" />
+ </imageobject>
+ </mediaobject>
+
+ <para>The Rete View is
+ an advanced feature which takes full advantage of the Eclipse Graphical Editing Framework (GEF).</para>
+
+ <para>The Rete view works only in Drools Rule Projects, where the Drools
+ Builder is set in the project´s properties.</para>
+
+ <para>If you are using Drools in an other type of project, where you are
+ not having a Drools Rule Project with the appropriate Drools Builder, you
+ can create a little workaround:</para>
+
+ <para>Set up a little Drools Rule Project next to it, putting needed
+ libraries into it and the drls you want to inspect with the Rete View.
+ Just click on the right tab below in the DRL Editor, followed by a click
+ on "Generate Rete View".</para>
+ </section>
+
+ <section>
+ <title>Large drl files</title>
+
+ <para>Depending on the JDK you use, it may be necessary to increase the
+ permanent generation max size. Both SUN and IBM jdk have a permanent
+ generation, whereas BEA JRockit does not.</para>
+
+ <para>To increase the permanent generation, start Eclipse with
+ -XX:MaxPermSize=###m</para>
+
+ <para>Example: c:\Eclipse\Eclipse.exe -XX:MaxPermSize=128m</para>
+
+ <para>Rulesets of 4,000 rules or greater should set the permanent
+ generation to atleast 128Mb.</para>
+
+ <para>(note that this may also apply to compiling large numbers of rules
+ in general - as there is generally one or more classes per rule).</para>
+
+ <para>As an alternative to the above, you may put rules in a file with the
+ ".rule" extension, and the background builder will not try to compile them
+ with each change, which may provide performance improvements if your IDE
+ becomes sluggish with very large numbers of rules.</para>
+ </section>
+
+
+ <section>
+
+ <title>Debugging rules</title>
+
+ <figure>
+ <title>Debugging</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="debug-overview.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>You can debug rules during the execution of your Drools application.
+ You can add breakpoints in the consequences of your rules, and whenever
+ such a breakpoint is uncounted during the execution of the rules, the execution
+ is halted. You can then inspect the variables known at that point and use any
+ of the default debugging actions to decide what should happen next (step over,
+ continue, etc.). You can also use the debug views to inspect the content of the
+ working memory and agenda.</para>
+
+<section>
+ <title>Creating breakpoints</title>
+ <para>You can add/remove rule breakpoints in drl files in two ways, similar to adding
+ breakpoints to Java files:</para>
+ <orderedlist>
+ <listitem>
+ <para>Double-click the ruler of the DRL editor at the line where you want to
+ add a breakpoint. Note that rule breakpoints can only be created in the
+ consequence of a rule. Double-clicking on a line where no breakpoint is allowed
+ will do nothing. A breakpoint can be removed by double-clicking the ruler once more.
+ </para>
+ </listitem>
+ <listitem>
+ <para>If you right-click the ruler, a popup menu will show up, containing the
+ "Toggle breakpoint" action. Note that rule breakpoints can only be created in the
+ consequence of a rule. The action is automatically disabled if no rule
+ breakpoint is allowed at that line. Clicking the action will add a breakpoint at the
+ selected line, or remove it if there was one already.</para>
+ </listitem>
+ </orderedlist>
+ <para>The Debug Perspective contains a Breakpoints view which can be used to see
+ all defined breakpoints, get their properties, enable/disable or remove them, etc.</para>
+</section>
+<section>
+ <title>Debugging rules</title>
+ <para>Drools breakpoints are only enabled if you debug your application as
+ a Drools Application. You can do this like this:</para>
+
+ <figure>
+ <title>Debug as Drools Application</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="debugAsDrools.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <orderedlist>
+ <listitem>
+ <para>Select the main class of your application. Right click it and select the
+ "Debug As >" sub-menu and select Drools Application. Alternatively, you can also select
+ the "Debug ..." menu item to open a
+ new dialog for creating, managing and running debug configurations (see
+ screenshot below)</para>
+ <orderedlist>
+ <listitem>
+ <para>Select the "Drools Application" item in the left tree and click the "New
+ launch configuration" button (leftmost icon in the toolbar above the tree). This
+ will create a new configuration and already fill in some of the properties
+ (like the project and main class) based on main class you selected in the beginning.
+ All properties shown here are the same as any standard Java program.</para>
+ </listitem>
+ <listitem>
+ <para>Change the name of your debug configuration to something meaningful.
+ You can just accept the defaults for all other properties. For more information
+ about these properties, please check the Eclipse jdt documentation.</para>
+ </listitem>
+ <listitem>
+ <para>Click the "Debug" button on the bottom to start debugging your application. You only have to define your debug configuration once. The next time you try to run your Drools application, you don't have to create a new one but select the one you defined previously by selecting it in the tree on the left, as a sub-element of the "Drools Application"
+ tree node, and then click the Debug button. The Eclipse toolbar also contains shortcut
+ buttons to quickly re-execute the one of your previous configurations (at least when the
+ Java, Java Debug, or Drools perspective has been selected).
+ </para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </orderedlist>
+
+ <figure>
+ <title>Debug as Drools Application Configuration</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="debug_rules_configuration.png" format="PNG" role="" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>After clicking the "Debug" button, the application starts executing and will halt if any
+ breakpoint is encountered. This can be a Drools rule breakpoint, or any other standard
+ Java breakpoint. Whenever a Drools rule breakpoint is encountered, the corresponding drl
+ file is opened and the active line is highlighted. The Variables view also contains all rule
+ parameters and their value. You can then use the default Java debug actions
+ to decide what to do next (resume, terminate, step over, etc.). The debug views can also
+ be used to determine the contents of the working memory and agenda at that time as well
+ (you don't have to select a working memory now, the current executing working memory
+ is automatically shown).
+ </para>
+
+ <figure>
+ <title>Debugging</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="debug.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ </section>
+ </section>
+
+
+</chapter>
Deleted: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-IDE/Section-QuickStart.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-IDE/Section-QuickStart.xml 2008-06-14 16:26:55 UTC (rev 20482)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-IDE/Section-QuickStart.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -1,764 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<section>
- <title>Introduction</title>
-
- <para>
- The IDE provides developers (and very technical users) with an environment to edit and test rules in various formats, and integrate it deeply with their applications. In cases where you prefer business rules and web tooling, you will want to look at the BRMS (but using the BRMS and the IDE together is not uncommon).</para>
-
- <para>The Drools IDE is delivered as an Eclipse plug-in, which
- allows you to author and manage rules from within Eclipse, as well as
- integrate rules with your application. This is an optional tool, and not all
- components are required to be used, you can use what components are relevant
- to you. The Drools IDE is also a part of the Red Hat Developer Studio (formerly known as JBoss IDE).</para>
-
- <para>This guide will cover some of the features of JBoss Drools, in as far
- as the IDE touches on them (it is assumed that the reader has some
- familiarity with rule engines, and Drools in particular. It is important to
- note that none of the underlying features of the rule engine are dependent
- on Eclipse, and integrators are free to use their tools of choice, as always
- ! Plenty of people use IntelliJ with rules, for instance.</para>
-
- <para>Note you can get the plug-in either as a zip to download, or from an
- update site (refer to the chapter on installation).</para>
-
- <figure>
- <title>Overview</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="all.jpg" format="JPG" scalefit="1" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <section>
- <title>Features outline</title>
-
- <para>The rules IDE has the following features</para>
-
- <orderedlist>
- <listitem>
- <para>Textual/graphical rule editor</para>
-
- <orderedlist>
- <listitem>
- <para>An editor that is aware of DRL syntax, and provides content
- assistance (including an outline view)</para>
- </listitem>
- <listitem>
- <para>An editor that is aware of DSL (domain specific langauge) extensions, and provides content assistance.</para>
- </listitem>
- </orderedlist>
- </listitem>
-
- <listitem>
- <para>RuleFlow graphical editor</para>
- <para>You can edit visual graphs which represent a process (a rule flow). The RuleFlow can then be applied to your rule package to have imperative control.</para>
- </listitem>
-
- <listitem>
- <para>Wizards to accelerate and ...</para>
-
- <orderedlist>
- <listitem>
- <para>Help you quickly create a new "rules" project</para>
- </listitem>
-
- <listitem>
- <para>Create a new rule resource</para>
- </listitem>
-
- <listitem>
- <para>Create a new Domain Specific language</para>
- </listitem>
-
- <listitem>
- <para>Create a new decision table, guided editor, ruleflow</para>
- </listitem>
-
-
- </orderedlist>
- </listitem>
-
- <listitem>
- <para>A domain specific language editor</para>
-
- <orderedlist>
- <listitem>
- <para>Create and manage mappings from your users language to the
- rule language</para>
- </listitem>
- </orderedlist>
- </listitem>
-
- <listitem>
- <para>Rule validation</para>
-
- <orderedlist>
- <listitem>
- <para>As rules are entered, the rule is "built" in the background
- and errors reported via the problem "view" where possible</para>
- </listitem>
- </orderedlist>
- </listitem>
- </orderedlist>
-
- <para>You can see the above features make use of Eclipse infrastructure
- and features. All of the power of Eclipse is available.</para>
- </section>
-
- <section>
- <title>Creating a Rule project</title>
-
- <para>The aim of the new project wizard is to setup an executable scaffold
- project to start using rules immediately. This will setup a basic
- structure, classpath and sample rules and test case to get you
- started.</para>
-
- <figure>
- <title>New rule project scaffolding</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="new_project1.jpg" format="JPG" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>When you choose to create a new "rule project" - you will get a choice to add some default artifacts to it (like rules, decision tables, ruleflows etc). These can serve as a starting point, and will give you something executable to play with (which you can then modify and mould to your needs). The simplest case (a hello world rule) is shown below. Feel free to experiment with the plug-in at this point.</para>
-
- <figure>
- <title>New rule project result</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="new_project2.png" format="JPG" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The newly created project contains an example rule file (Sample.drl)
- in the src/rules dir and an example Java file (DroolsTest.Java) that can
- be used to execute the rules in a Drools engine in the folder src/Java, in
- the com.sample package. All the others jars that are necessary during
- execution are also added to the classpath in a custom classpath container
- called Drools Library. Rules do not have to be kept in "Java"
- projects at all, this is just a convenience for people who are already
- using Eclipse as their Java IDE.</para>
-
- <para>Important note: The Drools plug-in adds a "Drools Builder"
- capability to your Eclipse instance. This means you can enable a builder
- on any project that will build and validate your rules when resources
- change. This happens automatically with the Rule Project Wizard, but you
- can also enable it manually on any project. One downside of this is if you
- have rule files that have a large number of rules (>500 rules per file)
- it means that the background builder may be doing a lot of work to
- build the rules on each change. An option here is to turn off the builder,
- or put the large rules into .rule files, where you can still use the rule
- editor, but it won't build them in the background - to fully validate the
- rules you will need to run them in a unit test of course.</para>
- </section>
-
- <section>
- <title>Creating a new rule and wizards</title>
-
- <para>You can create a rule simple as an empty text ".drl" file, or use
- the wizard to do so. The wizard menu can be invoked by Control+N, or
- choosing it from the toolbar (there will be a menu with the JBoss Drools
- icon).</para>
-
- <figure>
- <title>The wizard menu</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="wizards.jpg" format="JPG" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The wizard will ask for some basic options for generating a rule
- resource. These are just hints, you can change your mind later !. In terms
- of location, typically you would create a top level /rules directory to
- store your rules if you are creating a rule project, and store it in a
- suitably named subdirectory. The package name is mandatory, and is similar
- to a package name in Java (ie. its a namespace that groups like rules
- together).</para>
-
- <figure>
- <title>New rule wizard</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="new_rule.jpg" format="JPG" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>This result of this wizard is to generate a rule skeleton to work
- from. As with all wizards, they are candy: you don't have to use them if
- you don't want !</para>
- </section>
-
- <section>
- <title>Textual rule editor</title>
-
- <para>The rule editor is where rule managers and developers will be
- spending most of their time. The rule editor follows the pattern of a
- normal text editor in Eclipse, with all the normal features of a text
- editor. On top of this, the rule editor provides pop up content
- assistance. You invoke popup content assistance the "normal" way by
- pressing Control + Space at the same time.</para>
-
- <figure>
- <title>The rule editor in action</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="editor1.jpg" format="JPG" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The rule editor works on files that have a .drl (or .rule)
- extension. Rules are generally grouped together as a "package" of rules
- (like the old ruleset construct). It will also be possible to have rules
- in individual files (grouped by being in the same package "namespace" if
- you like). These DRL files are plain text files.</para>
-
- <para>You can see from the example above that the package is using a
- domain specific language (note the expander keyword, which tells the rule
- compiler to look for a dsl file of that name, to resolve the rule
- language). Even with the domain specific language (DSL) the rules are
- still stored as plain text as you see on screen, which allows simpler
- management of rules and versions (comparing versions of rules for
- instance).</para>
-
- <para>The editor has an outline view that is kept in sync with the
- structure of the rules (updated on save). This provides a quick way of
- navigating around rules by name, in a file which may have hundreds of
- rules. The items are sorted alphabetically by default.</para>
-
- <figure>
- <title>The rule outline view</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="outline.jpg" format="JPG" />
- </imageobject>
- </mediaobject>
- </figure>
- </section>
-
-<section>
- <title>Guided editor (rule GUI)</title>
- <para>
- A new feature of the Drools IDE (since version 4) is the guided editor for rules. This is similar to the web based editor that is available in the BRMS. This allows you to build rules in a GUI driven fashion, based on your object model.
- </para>
-
- <figure>
- <title>The guided editor</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="guidededitor1.png" format="PNG" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>
- To create a rule this way, use the wizard menu. It will create a instance of a .brl file and open an editor. The guided editor works based on a .package file in the same directory as the .brl file. In this "package" file - you have the package name and import statements - just like you would in the top of a normal DRL file. So the first time you create a brl rule - you will need to ppulate the package file with the fact classes you are interested in. Once you have this the guided editor will be able to prompt you with facts/fields and build rules graphically.
- </para>
-
- <para>
- The guided editor works off the model classes (fact classes) that you configure. It then is able to "render" to DRL the rule that you have entered graphically. You can do this visually - and use it as a basis for learning DRL, or you can use it and build rules of the brl directly. To do this, you can either use the drools-ant module (it is an ant task that will build up all the rule assets in a folder as a rule package - so you can then deploy it as a binary file), OR you can use the following snippet of code to convert the brl to a drl rule:
-
- </para>
-
- <programlisting>BRXMLPersitence read = BRXMLPersitence.getInstance();
-BRDRLPersistence write = BRDRLPersistence.getInstance();
-String brl = ... read from the .brl file as needed...
-String outputDRL = write.marshall(read.unmarshal(brl));
-//then pass the outputDRL to the PackageBuilder as normal</programlisting>
-</section>
-
- <section>
- <title>Views</title>
-
- <para>When debugging an application using a Drools engine, these views
- can be used to check the state of the Drools engine itself: the Working
- Memory View, the Agenda View the Global Data View. To be able to use
- these views, create breakpoints in your code invoking the working memory.
- For example, the line where you call workingMemory.fireAllRules() is a
- good candidate. If the debugger halts at that joinpoint, you should select
- the working memory variable in the debug variables view. The following
- rules can then be used to show the details of the selected working
- memory:</para>
-
- <orderedlist>
- <listitem>
- <para>The Working Memory shows all elements in the working memory of
- the Drools working memory.</para>
- </listitem>
-
- <listitem>
- <para>The Agenda View shows all elements on the agenda. For each rule
- on the agenda, the rule name and bound variables are shown.</para>
- </listitem>
-
- <listitem>
- <para>The Global Data View shows all global data currently defined in
- the Drools working memory.</para>
- </listitem>
- </orderedlist>
-
- <para>The Audit view can be used to show audit logs that contain events
- that were logged during the execution of a rules engine in a tree
- view.</para>
-
- <section>
- <title>The Working Memory View</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="workingMemory.png" />
- </imageobject>
- </mediaobject>
-
- <para>The Working Memory shows all elements in the working memory of the
- Drools engine.</para>
-
- <para>An action is added to the right of the view, to customize what is
- shown:</para>
-
- <orderedlist>
- <listitem>
- <para>The Show Logical Structure toggles showing the logical
- structure of the elements in the working memory, or all their
- details. Logical structures allow for example visualizing sets of
- elements in a more obvious way.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>The Agenda View</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="agenda.png" />
- </imageobject>
- </mediaobject>
-
- <para>The Agenda View shows all elements on the agenda. For each rule on
- the agenda, the rule name and bound variables are shown.</para>
-
- <para>An action is added to the right of the view, to customize what is
- shown:</para>
-
- <orderedlist>
- <listitem>
- <para>The Show Logical Structure toggles showing the logical
- structure of the agenda item, or all their details. Logical
- structures allow for example visualizing sets of elements in a more
- obvious way. The logical structure of AgendaItems shows the rule
- that is represented by the AgendaItem, and the values of all the
- parameters used in the rule.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>The Global Data View</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="globals.png" />
- </imageobject>
- </mediaobject>
-
- <para>The Global Data View shows all global data currently defined in
- the Drools engine.</para>
-
- <para>An action is added to the right of the view, to customize what is
- shown:</para>
-
- <orderedlist>
- <listitem>
- <para>The Show Logical Structure toggles showing the logical
- structure of the elements in the working memory, or all their
- details. Logical structures allow for example visualizing sets of
- elements in a more obvious way.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>The Audit View</title>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="audit.jpg" scalefit="1" width="100%" />
- </imageobject>
- </mediaobject>
-
- <para>The audit view can be used to visualize an audit log that can be
- created when executing the rules engine. To create an audit log, use the
- following code:</para>
-
- <programlisting> WorkingMemory workingMemory = ruleBase.newWorkingMemory();
- // create a new Working Memory Logger, that logs to file.
- WorkingMemoryFileLogger logger = new WorkingMemoryFileLogger(workingMemory);
- // an event.log file is created in the log dir (which must exist)
- // in the working directory
- logger.setFileName("log/event");
-
- workingMemory.assertObject( ... );
- workingMemory.fireAllRules();
-
- // stop logging
- logger.writeToDisk();</programlisting>
-
- <para>Open the log by clicking the Open Log action (first action in the
- Audit View) and select the file. The Audit view now shows all events
- that where logged during the executing of the rules. There are different
- types of events (each with a different icon):</para>
-
- <orderedlist>
- <listitem>
- <para>Object inserted (green square)</para>
- </listitem>
-
- <listitem>
- <para>Object updated (yellow square)</para>
- </listitem>
-
- <listitem>
- <para>Object removed (red square)</para>
- </listitem>
-
- <listitem>
- <para>Activation created (arrow to the right)</para>
- </listitem>
-
- <listitem>
- <para>Activation cancelled (arrow to the left)</para>
- </listitem>
-
- <listitem>
- <para>Activation executed (blue diamond)</para>
- </listitem>
-
- <listitem>
- <para>Ruleflow started / ended (process icon)</para>
- </listitem>
-
- <listitem>
- <para>Ruleflow-group activated / deactivated (process icon)</para>
- </listitem>
-
- <listitem>
- <para>Rule package added / removed (Drools icon)</para>
- </listitem>
-
- <listitem>
- <para>Rule added / removed (Drools icon)</para>
- </listitem>
- </orderedlist>
-
- <para>All these events show extra information concerning the event, like
- the id and toString representation of the object in case of working
- memory events (assert, modify and retract), the name of the rule and all
- the variables bound in the activation in case of an activation event
- (created, cancelled or executed). If an event occurs when executing an
- activation, it is shown as a child of the activation executed event. For
- some events, you can retrieve the "cause":</para>
-
- <orderedlist>
- <listitem>
- <para>The cause of an object modified or retracted event is the last
- object event for that object. This is either the object asserted
- event, or the last object modified event for that object.</para>
- </listitem>
-
- <listitem>
- <para>The cause of an activation cancelled or executed event is the
- corresponding activation created event.</para>
- </listitem>
- </orderedlist>
-
- <para>When selecting an event, the cause of that event is shown in green
- in the audit view (if visible of course). You can also right click the
- action and select the "Show Cause" menu item. This will scroll you to
- the cause of the selected event.</para>
- </section>
- </section>
-
- <section>
- <title>Domain Specific Languages</title>
-
- <para>Domain Specific Languages (dsl) allow you to create a language that
- allows your rules to look like, rules ! Most often the domain specific
- language reads like natural language. Typically you would look at how a
- business analyst would describe the rule, in their own words, and then map
- this to your object model via rule constructs. A side benefit of this is
- that it can provide an insulation layer between your domain objects, and
- the rules themselves (as we know you like to refactor !). A domain
- specific language will grow as the rules grow, and works best when there
- are common terms used over an over, with different parameters.</para>
-
- <para>To aid with this, the rule workbench provides an editor for domain
- specific languages (they are stored in a plain text format, so you can
- use any editor of your choice - it uses a slightly enhanced version of the
- "Properties" file format, simply). The editor will be invoked on any files
- with a .dsl extension (there is also a wizard to create a sample
- DSL).</para>
-
- <section>
- <title>Editing languages</title>
-
- <figure>
- <title>The Domain Specific Language editor</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="dsl_editor.jpg" format="JPG" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>The DSL editor provides a table view of Language Expression to
- Rule Expression mapping. The Language expression is what is used in the
- rules. This also feeds the content assistance for the rule editor, so
- that it can suggest Language Expressions from the DSL configuration (the
- rule editor loads up the DSL configuration when the rule resource is
- loaded for editing). The Rule language mapping is the "code" for the
- rules - which the language expression will be compiled to by the rule
- engine compiler. For form of this Rule language depends if it is for a
- condition or action part of a rule (it may be a snippet of Java, for
- instance). The "scope" item indicates where the expression is targeted:
- is it for the "when" part of the rule (LHS)? the "then" part (RHS)? Or
- anywhere?</para>
-
- <para>By selecting a mapping item (a row in the table) you can see the
- expression and mapping in the greyed out fields below. Double clicking
- or pressing the edit button will open the edit dialog. You can remove
- items, and add new ones (you should generally only remove when you know
- that expression is no longer in use).</para>
-
- <figure>
- <title>Language Mapping editor dialog</title>
-
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="mapping_editor.jpg"
- format="JPG" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>How it works: the "Language expression" is used to parse the rule
- language, depending on what the "scope" is set to. When it is found in a
- rule, the values that are market by the curly braces {value} are
- extracted from the rule source. These values are then interpolated with
- the "Rule mapping" expression, based on the names between the curly
- braces. So in the example above, the natural language expression maps
- to 2 constraints on a fact of type Person (ie the person object has the
- age field as less than {age}, and the location value is the string of
- {value}, where {age} and {value} are pulled out of the original rule
- source. The Rule mapping may be a Java expression (such as if the scope
- was "then"). If you did not wish to use a language mapping for a
- particular rule in a drl, prefix the expression with > and the
- compiler will not try to translate it according to the language
- definition. Also note that domain specific languages are optional. When
- the rule is compiled, the .dsl file will also need to be
- available.</para>
- </section>
- </section>
-
- <section>
- <title>The Rete View</title>
-
- <para>The Rete Tree View shows you the current Rete Network for your drl
- file. Just click on the tab "Rete Tree" below on the DRL Editor.
- Afterwards you can generate the current Rete Network visualization. You
- can push and pull the nodes to arrange your optimal network overview. If
- you got hundreds of nodes, select some of them with a frame. Then you can
- pull groups of them. You can zoom in and out, in case not all nodes are
- shown in the current view. For this press the button "+" oder "-".</para>
-
- <para>There is no export function, which creates a gif or jpeg picture, in
- the current release. Please use ctrl + alt + print to create a copy of
- your current Eclipse window and cut it off.</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="thereteview.jpg" />
- </imageobject>
- </mediaobject>
-
- <para>The Rete View is
- an advanced feature which takes full advantage of the Eclipse Graphical Editing Framework (GEF).</para>
-
- <para>The Rete view works only in Drools Rule Projects, where the Drools
- Builder is set in the project´s properties.</para>
-
- <para>If you are using Drools in an other type of project, where you are
- not having a Drools Rule Project with the appropriate Drools Builder, you
- can create a little workaround:</para>
-
- <para>Set up a little Drools Rule Project next to it, putting needed
- libraries into it and the drls you want to inspect with the Rete View.
- Just click on the right tab below in the DRL Editor, followed by a click
- on "Generate Rete View".</para>
- </section>
-
- <section>
- <title>Large drl files</title>
-
- <para>Depending on the JDK you use, it may be necessary to increase the
- permanent generation max size. Both SUN and IBM jdk have a permanent
- generation, whereas BEA JRockit does not.</para>
-
- <para>To increase the permanent generation, start Eclipse with
- -XX:MaxPermSize=###m</para>
-
- <para>Example: c:\Eclipse\Eclipse.exe -XX:MaxPermSize=128m</para>
-
- <para>Rulesets of 4,000 rules or greater should set the permanent
- generation to atleast 128Mb.</para>
-
- <para>(note that this may also apply to compiling large numbers of rules
- in general - as there is generally one or more classes per rule).</para>
-
- <para>As an alternative to the above, you may put rules in a file with the
- ".rule" extension, and the background builder will not try to compile them
- with each change, which may provide performance improvements if your IDE
- becomes sluggish with very large numbers of rules.</para>
- </section>
-
-
- <section>
-
- <title>Debugging rules</title>
-
- <figure>
- <title>Debugging</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="debug-overview.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>You can debug rules during the execution of your Drools application.
- You can add breakpoints in the consequences of your rules, and whenever
- such a breakpoint is uncounted during the execution of the rules, the execution
- is halted. You can then inspect the variables known at that point and use any
- of the default debugging actions to decide what should happen next (step over,
- continue, etc.). You can also use the debug views to inspect the content of the
- working memory and agenda.</para>
-
-<section>
- <title>Creating breakpoints</title>
- <para>You can add/remove rule breakpoints in drl files in two ways, similar to adding
- breakpoints to Java files:</para>
- <orderedlist>
- <listitem>
- <para>Double-click the ruler of the DRL editor at the line where you want to
- add a breakpoint. Note that rule breakpoints can only be created in the
- consequence of a rule. Double-clicking on a line where no breakpoint is allowed
- will do nothing. A breakpoint can be removed by double-clicking the ruler once more.
- </para>
- </listitem>
- <listitem>
- <para>If you right-click the ruler, a popup menu will show up, containing the
- "Toggle breakpoint" action. Note that rule breakpoints can only be created in the
- consequence of a rule. The action is automatically disabled if no rule
- breakpoint is allowed at that line. Clicking the action will add a breakpoint at the
- selected line, or remove it if there was one already.</para>
- </listitem>
- </orderedlist>
- <para>The Debug Perspective contains a Breakpoints view which can be used to see
- all defined breakpoints, get their properties, enable/disable or remove them, etc.</para>
-</section>
-<section>
- <title>Debugging rules</title>
- <para>Drools breakpoints are only enabled if you debug your application as
- a Drools Application. You can do this like this:</para>
-
- <figure>
- <title>Debug as Drools Application</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="debugAsDrools.png" format="PNG" role="" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <orderedlist>
- <listitem>
- <para>Select the main class of your application. Right click it and select the
- "Debug As >" sub-menu and select Drools Application. Alternatively, you can also select
- the "Debug ..." menu item to open a
- new dialog for creating, managing and running debug configurations (see
- screenshot below)</para>
- <orderedlist>
- <listitem>
- <para>Select the "Drools Application" item in the left tree and click the "New
- launch configuration" button (leftmost icon in the toolbar above the tree). This
- will create a new configuration and already fill in some of the properties
- (like the project and main class) based on main class you selected in the beginning.
- All properties shown here are the same as any standard Java program.</para>
- </listitem>
- <listitem>
- <para>Change the name of your debug configuration to something meaningful.
- You can just accept the defaults for all other properties. For more information
- about these properties, please check the Eclipse jdt documentation.</para>
- </listitem>
- <listitem>
- <para>Click the "Debug" button on the bottom to start debugging your application. You only have to define your debug configuration once. The next time you try to run your Drools application, you don't have to create a new one but select the one you defined previously by selecting it in the tree on the left, as a sub-element of the "Drools Application"
- tree node, and then click the Debug button. The Eclipse toolbar also contains shortcut
- buttons to quickly re-execute the one of your previous configurations (at least when the
- Java, Java Debug, or Drools perspective has been selected).
- </para>
- </listitem>
- </orderedlist>
- </listitem>
- </orderedlist>
-
- <figure>
- <title>Debug as Drools Application Configuration</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="debug_rules_configuration.png" format="PNG" role="" />
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>After clicking the "Debug" button, the application starts executing and will halt if any
- breakpoint is encountered. This can be a Drools rule breakpoint, or any other standard
- Java breakpoint. Whenever a Drools rule breakpoint is encountered, the corresponding drl
- file is opened and the active line is highlighted. The Variables view also contains all rule
- parameters and their value. You can then use the default Java debug actions
- to decide what to do next (resume, terminate, step over, etc.). The debug views can also
- be used to determine the contents of the working memory and agenda at that time as well
- (you don't have to select a working memory now, the current executing working memory
- is automatically shown).
- </para>
-
- <figure>
- <title>Debugging</title>
- <mediaobject>
- <imageobject>
- <imagedata align="center" fileref="debug.png" format="PNG"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- </section>
- </section>
-
-
-</section>
Added: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Chapter-JSR94.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Chapter-JSR94.xml (rev 0)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Chapter-JSR94.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns:xi="http://www.w3.org/2001/XInclude" >
+ <title>The Java Rule Engine API</title>
+
+ <xi:include href="Section-Introduction.xml" />
+
+ <!-- Removed till it can be completed -->
+
+ <!-- include href="Chapter-JSR94/Section-Specification.xml" /-->
+
+ <xi:include href="Section-How_To_Use.xml" />
+
+ <xi:include href="Section-References.xml" />
+ </chapter>
\ No newline at end of file
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Section-How_To_Use.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Section-How_To_Use.xml 2008-06-14 16:26:55 UTC (rev 20482)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Section-How_To_Use.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<section>
+ <section xml:base="../">
<title>How To Use</title>
<para>There are two parts to working with JSR94. The first part is the
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Section-Introduction.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Section-Introduction.xml 2008-06-14 16:26:55 UTC (rev 20482)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Section-Introduction.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<section>
+ <section xml:base="../">
<title>Introduction</title>
<para>Drools provides an implementation of the Java Rule Engine API (known
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Section-References.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Section-References.xml 2008-06-14 16:26:55 UTC (rev 20482)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Section-References.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<section>
+ <section xml:base="../">
<title>References</title>
<para>If you need more information on JSR 94, please refer to the following
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Section-Specification.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Section-Specification.xml 2008-06-14 16:26:55 UTC (rev 20482)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-JSR94/Section-Specification.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<section>
+ <section xml:base="../">
<title>Specification</title>
<para>This sections introduces the specification with the included packages
Added: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Chapter-RuleLanguage.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Chapter-RuleLanguage.xml (rev 0)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Chapter-RuleLanguage.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns:xi="http://www.w3.org/2001/XInclude" >
+ <title>The Rule Language</title>
+
+ <xi:include href="Section-Overview.xml" />
+
+ <xi:include href="Section-Comments.xml" />
+
+ <xi:include href="Section-Package.xml" />
+
+ <xi:include href="Section-Function.xml" />
+
+ <xi:include href="Section-Rule.xml" />
+
+ <xi:include href="Section-Query.xml" />
+
+ <xi:include href="Section-DSL.xml" />
+
+ <xi:include href="Section-XML.xml" />
+ </chapter>
\ No newline at end of file
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Comments.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Comments.xml 2008-06-14 16:26:55 UTC (rev 20482)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Comments.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -1,7 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<section>
+ <section xml:base="../">
<title>Comments</title>
<note>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-DSL.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-DSL.xml 2008-06-14 16:26:55 UTC (rev 20482)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-DSL.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -1,7 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<section>
+ <section xml:base="../">
<title>Domain Specific Languages</title>
<para>As mentioned previously, <indexterm>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Function.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Function.xml 2008-06-14 16:26:55 UTC (rev 20482)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Function.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -1,7 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<section>
+ <section xml:base="../">
<title>Function</title>
<note>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Overview.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Overview.xml 2008-06-14 16:26:55 UTC (rev 20482)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Overview.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -1,7 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<section>
+ <section xml:base="../">
<title>Overview</title>
<note>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Package.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Package.xml 2008-06-14 16:26:55 UTC (rev 20482)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Package.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -1,7 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<section>
+ <section xml:base="../">
<title>Package</title>
<note>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Query.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Query.xml 2008-06-14 16:26:55 UTC (rev 20482)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Query.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -1,7 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<section>
+ <section xml:base="../">
<title>Query</title>
<figure>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Rule.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Rule.xml 2008-06-14 16:26:55 UTC (rev 20482)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-Rule.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -1,7 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<section>
+ <section xml:base="../">
<title>Rule</title>
<figure>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-XML.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-XML.xml 2008-06-14 16:26:55 UTC (rev 20482)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/Chapter-Rule_Language/Section-XML.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -1,7 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<section>
+ <section xml:base="../">
<title>XML Rule Language</title>
<para>As an option, Drools also supports a "native" <indexterm>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/master.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/master.xml 2008-06-14 16:26:55 UTC (rev 20482)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/en/master.xml 2008-06-14 17:21:47 UTC (rev 20483)
@@ -58,63 +58,17 @@
</chapter>
- <chapter>
- <title>Decision Tables</title>
+ <xi:include href="Chapter-Decision_Tables/Chapter-Spreadsheet.xml" />
+
+ <xi:include href="Chapter-IDE/Chapter-QuickStart.xml" />
- <xi:include href="Chapter-Decision_Tables/Section-Spreadsheet.xml" />
- </chapter>
+ <xi:include href="Chapter-Deployment/Chapter-DepymentAndTest.xml" />
- <chapter>
- <title>The (Eclipse based) Rule IDE</title>
-
- <xi:include href="Chapter-IDE/Section-QuickStart.xml" />
- </chapter>
-
- <chapter>
- <title>Deployment and Testing</title>
-
- <xi:include href="Chapter-Deployment/Section-Deployment.xml" />
-
- <xi:include href="Chapter-Deployment/Section-Testing.xml" />
- </chapter>
-
- <chapter>
- <title>The Java Rule Engine API</title>
-
- <xi:include href="Chapter-JSR94/Section-Introduction.xml" />
-
- <!-- Removed till it can be completed -->
-
- <!-- include href="Chapter-JSR94/Section-Specification.xml" /-->
-
- <xi:include href="Chapter-JSR94/Section-How_To_Use.xml" />
-
- <xi:include href="Chapter-JSR94/Section-References.xml" />
- </chapter>
-
- <chapter>
- <title>The Rule Language</title>
-
- <xi:include href="Chapter-Rule_Language/Section-Overview.xml" />
-
- <xi:include href="Chapter-Rule_Language/Section-Comments.xml" />
-
- <xi:include href="Chapter-Rule_Language/Section-Package.xml" />
-
- <xi:include href="Chapter-Rule_Language/Section-Function.xml" />
-
- <xi:include href="Chapter-Rule_Language/Section-Rule.xml" />
-
- <xi:include href="Chapter-Rule_Language/Section-Query.xml" />
-
- <xi:include href="Chapter-Rule_Language/Section-DSL.xml" />
-
- <xi:include href="Chapter-Rule_Language/Section-XML.xml" />
- </chapter>
+ <xi:include href="Chapter-JSR94/Chapter-JSR94.xml" />
- <chapter xmlns:xi="http://www.w3.org/2001/XInclude">
- <xi:include href="Chapter-Examples/Section-Examples.xml" />
- </chapter>
+ <xi:include href="Chapter-Rule_Language/Chapter-RuleLanguage.xml" />
+ <xi:include href="Chapter-Examples/Chapter-Examples.xml" />
+
<index/>
</book>
More information about the jboss-svn-commits
mailing list