[jboss-svn-commits] JBL Code SVN: r26191 - in labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook: images/Chapter-IDE and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Apr 21 12:06:50 EDT 2009
Author: laune
Date: 2009-04-21 12:06:50 -0400 (Tue, 21 Apr 2009)
New Revision: 26191
Added:
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/activity.gif
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/arrowleft.GIF
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/arrowright.GIF
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/bluediamond.GIF
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/drools.gif
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/greensquare.GIF
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/process.gif
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/redsquare.GIF
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/yellowsquare.GIF
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-IDE/Chapter-QuickStart.xml
Log:
improvements
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-IDE/Chapter-QuickStart.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-IDE/Chapter-QuickStart.xml 2009-04-21 16:03:09 UTC (rev 26190)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-IDE/Chapter-QuickStart.xml 2009-04-21 16:06:50 UTC (rev 26191)
@@ -3,16 +3,21 @@
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg" xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook">
- <title>The (Eclipse based) Rule IDE</title>
+ <title>The Rule IDE (Eclipse)</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>
+ The Eclipse based 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>
+ 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
@@ -21,8 +26,8 @@
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>
+ <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>
@@ -35,7 +40,7 @@
</figure>
<section xml:base="../">
- <title>Features outline</title>
+ <title>Features Outline</title>
<para>The rules IDE has the following features</para>
@@ -60,24 +65,27 @@
</listitem>
<listitem>
- <para>Wizards to accelerate and ...</para>
+ <para>Wizards for fast creation of</para>
<orderedlist>
<listitem>
- <para>Help you quickly create a new "rules" project</para>
+ <para>a "rules" project</para>
</listitem>
<listitem>
- <para>Create a new rule resource</para>
+ <para>a rule resource, either as a DRL file or a "guided rule editor" file (.brl)</para>
</listitem>
<listitem>
- <para>Create a new Domain Specific language</para>
+ <para>a Domain Specific language</para>
</listitem>
<listitem>
- <para>Create a new decision table, guided editor, ruleflow</para>
+ <para>a decision table</para>
</listitem>
+ <listitem>
+ <para>a ruleflow</para>
+ </listitem>
</orderedlist>
@@ -88,7 +96,7 @@
<orderedlist>
<listitem>
- <para>Create and manage mappings from your users language to the
+ <para>Create and manage mappings from your user's language to the
rule language</para>
</listitem>
</orderedlist>
@@ -100,22 +108,22 @@
<orderedlist>
<listitem>
<para>As rules are entered, the rule is "built" in the background
- and errors reported via the problem "view" where possible</para>
+ 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>
+ <para>The above features make use of Eclipse infrastructure
+ and features, with all of the power of Eclipse being available.</para>
</section>
<section xml:base="../">
- <title>Creating a Rule project</title>
+ <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
+ <para>The aim of the new project wizard is to set up an executable scaffold
+ project to start using rules immediately. This will set up a basic
+ structure, the classpath, sample rules and a test case to get you
started.</para>
<figure>
@@ -127,7 +135,12 @@
</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>
+ <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
+ almost immediately, 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>
@@ -140,9 +153,10 @@
</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
+ in the src/rules directory and an example Java file (DroolsTest.java) that can
+ be used to execute the rules in a Drools engine. You'll find this in the
+ folder src/java, in the com.sample package. All the other 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
@@ -152,22 +166,22 @@
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
+ can also enable it manually on any project. One downside of this is that
+ if you have rule files with a large number of rules (more than 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
+ 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 xml:base="../">
- <title>Creating a new rule and wizards</title>
+ <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>
+ the wizard to do so. The wizard menu can be invoked with Control+N, or by
+ choosing it from the toolbar, where there is a menu with the JBoss Drools
+ icon.</para>
<figure>
<title>The wizard menu</title>
@@ -180,12 +194,11 @@
</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>
+ resource. These are just hints - you can change your mind later. For
+ storing rule files you would typically create a directory src/rules and
+ create suitably named subdirectories. The package name is mandatory, and
+ is similar to a package name in Java; i.e., it establishes a namespace for
+ grouping related rules.</para>
<figure>
<title>New rule wizard</title>
@@ -197,20 +210,20 @@
</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>
+ <para>The result of this wizard is a rule skeleton, for you to expand.
+ As with all wizards, they are an optional help - you don't have to use
+ them if you don't want to.</para>
</section>
<section xml:base="../">
- <title>Textual rule editor</title>
+ <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>
+ normal text editor in Eclipse, with all the customary features of a text
+ editor. On top of this, the rule editor provides pop-up content
+ assistance. You invoke pop-up content assistance the "normal" way by
+ pressing Control+Space.</para>
<figure>
<title>The rule editor in action</title>
@@ -223,22 +236,21 @@
</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>
+ extension. Usually these contain related rules, but it would also be
+ possible to have rules in individual files, grouped by being in the
+ same package "namespace", if you so prefer. 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
+ <para>You can see from the example above that the rule group 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>
+ language. Even with the domain specific language (DSL) the rules are
+ still stored as plain text as you see it onscreen, which allows simpler
+ management of rules and versions, e.g., comparing versions of rules.</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
+ structure of the rules; it is updated on save. This provides a quick way of
+ navigating around rules by name, even in a file which may have hundreds of
rules. The items are sorted alphabetically by default.</para>
<figure>
@@ -253,10 +265,12 @@
</section>
<section xml:base="../">
- <title>Guided editor (rule GUI)</title>
+ <title>The 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>
+ 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. It
+ allows you to build rules in a GUI-driven fashion, based on your object
+ model.</para>
<figure>
<title>The guided editor</title>
@@ -269,38 +283,50 @@
</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>
+ To create a rule this way, use the wizard menu. It will create an instance
+ of a .brl file and open it in the guided editor. This 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 at the top of a normal DRL file. First time you create
+ a brl rule you will need to populate 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 and their fields so that you can
+ 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:
+ The guided editor works off the model classes (or 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.
+ One way to do this is by using the drools-ant module, which is an ant task
+ that creates all the rule assets in a folder, as a rule package, so that
+ you can then deploy it as a binary file. Alternatively, you can use the
+ following snippet of code to convert the brl to a drl rule.</para>
- </para>
-
<programlisting>BRXMLPersitence read = BRXMLPersitence.getInstance();
BRDRLPersistence write = BRDRLPersistence.getInstance();
-String brl = ... read from the .brl file as needed...
+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>
+// Pass the outputDRL to the PackageBuilder, as usual</programlisting>
</section>
<section xml:base="../">
- <title>Views</title>
+ <title>Drools 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
+ Memory View, the Agenda View, and 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
+ the working memory variable in the debug variables view. The available
+ views 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>
+ <para>The Working Memory View shows all elements of the Drools
+ working memory.</para>
</listitem>
<listitem>
@@ -314,9 +340,8 @@
</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>
+ <para>The Audit view can be used to display audit logs containing events
+ that were logged during the execution of a rules engine, in tree form.</para>
<section>
<title>The Working Memory View</title>
@@ -327,7 +352,7 @@
</imageobject>
</mediaobject>
- <para>The Working Memory shows all elements in the working memory of the
+ <para>The Working Memory View 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
@@ -337,7 +362,7 @@
<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
+ details. Logical structures allow for visualizing sets of
elements in a more obvious way.</para>
</listitem>
</orderedlist>
@@ -404,76 +429,76 @@
</imageobject>
</mediaobject>
- <para>The audit view can be used to visualize an audit log that can be
+ <para>The audit view visualizes an audit log, that is optionally
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");
+ <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 subdirectory log (which must exist)
+// of the working directory.
+logger.setFileName( "log/event" );
- workingMemory.assertObject( ... );
- workingMemory.fireAllRules();
+workingMemory.assertObject(...);
+workingMemory.fireAllRules();
- // stop logging
- logger.writeToDisk();</programlisting>
+// 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
+ <para>Open the log by clicking the Open Log action, the first icon 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>
+ types of events, each with a different icon:</para>
<orderedlist>
<listitem>
- <para>Object inserted (green square)</para>
+ <para>Object inserted, a green square: <inlinemediaobject><imageobject><imagedata fileref="images/Chapter-IDE/greensquare.GIF"/></imageobject></inlinemediaobject></para>
</listitem>
<listitem>
- <para>Object updated (yellow square)</para>
+ <para>Object updated, a yellow square: <inlinemediaobject><imageobject><imagedata fileref="images/Chapter-IDE/yellowsquare.GIF"/></imageobject></inlinemediaobject></para>
</listitem>
<listitem>
- <para>Object removed (red square)</para>
+ <para>Object removed, a red square: <inlinemediaobject><imageobject><imagedata fileref="images/Chapter-IDE/redsquare.GIF"/></imageobject></inlinemediaobject></para>
</listitem>
<listitem>
- <para>Activation created (arrow to the right)</para>
+ <para>Activation created, a right arrow: <inlinemediaobject><imageobject><imagedata fileref="images/Chapter-IDE/arrowright.GIF"/></imageobject></inlinemediaobject></para>
</listitem>
<listitem>
- <para>Activation cancelled (arrow to the left)</para>
+ <para>Activation cancelled, a left arrow: <inlinemediaobject><imageobject><imagedata fileref="images/Chapter-IDE/arrowleft.GIF"/></imageobject></inlinemediaobject></para>
</listitem>
<listitem>
- <para>Activation executed (blue diamond)</para>
+ <para>Activation executed, a blue diamond: <inlinemediaobject><imageobject><imagedata fileref="images/Chapter-IDE/bluediamond.GIF"/></imageobject></inlinemediaobject></para>
</listitem>
<listitem>
- <para>Ruleflow started / ended (process icon)</para>
+ <para>Ruleflow start or end, the "process" icon: <inlinemediaobject><imageobject><imagedata fileref="images/Chapter-IDE/process.gif"/></imageobject></inlinemediaobject></para>
</listitem>
<listitem>
- <para>Ruleflow-group activated / deactivated (process icon)</para>
+ <para>Ruleflow-group activation or deactivation, the "activity" icon: <inlinemediaobject><imageobject><imagedata fileref="images/Chapter-IDE/activity.gif"/></imageobject></inlinemediaobject></para>
</listitem>
<listitem>
- <para>Rule package added / removed (Drools icon)</para>
+ <para>Rule package addition or removal, the Drools icon: <inlinemediaobject><imageobject><imagedata fileref="images/Chapter-IDE/drools.gif"/></imageobject></inlinemediaobject></para>
</listitem>
<listitem>
- <para>Rule added / removed (Drools icon)</para>
+ <para>Rule addition or removal, the Drools icon: <inlinemediaobject><imageobject><imagedata fileref="images/Chapter-IDE/drools.gif"/></imageobject></inlinemediaobject></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
+ memory events (insert, 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
+ activation, it is shown as a child of the activation's execution event. For
some events, you can retrieve the "cause":</para>
<orderedlist>
@@ -499,22 +524,22 @@
<section xml:base="../">
<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
+ <para>Domain Specific Languages (DSL) enable 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
+ 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>
+ <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; this format is simply a slightly enhanced
+ version of the "Properties" file format. 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>
@@ -529,24 +554,25 @@
</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
+ <para>The DSL editor provides a tabular view of the mapping of
+ Language to Rule Expressions. 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>
+ that it can suggest Language Expressions from the DSL configuration. (The
+ rule editor loads the DSL configuration when the rule resource is
+ loaded for editing.) The Rule language mapping defines the "code" for the
+ rules into which the language expression will be compiled by the rule
+ engine compiler. The form of this Rule language expression depends on it
+ being intended for the condition or the action part of a rule. (For the
+ RHS it may be a snippet of Java, for instance). The "scope" item indicates
+ where the expression belongs, "when" indicating the LHS, "then" the RHS,
+ and "*" meaning anywhere. It's also possible to create aliases for
+ keywords.</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>
+ expression and mapping in the text fields below the table. Double clicking
+ or pressing the edit button will open the edit dialog. Other buttons let you
+ remove and add mappings. Don't remove mappings while they are still in
+ use.</para>
<figure>
<title>Language Mapping editor dialog</title>
@@ -559,20 +585,21 @@
</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
+ <para>Here is a short description of the DSL translation process.
+ The parser reads the rule text in a DSL, line by line, and tries to
+ match some "Language Expression", depending on the scope. After a
+ match, the values that correspond to a placeholder between curly
+ braces (e.g., {age}) are extracted from the rule source. The
+ placeholders in the corresponding "Rule Expression" are replaced by
+ their corresponding value. In the example above, the natural
+ language expression maps to two constraints on a fact of type
+ Person, based on the fields age and location, and the {age} and {location}
+ values are extracted from the original rule text.</para>
+
+ <para>If you do 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
+ 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>
@@ -581,17 +608,17 @@
<section xml:base="../">
<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>The Rete Tree View shows you the current Rete Network for your DRL
+ file. You display it by clicking on the tab "Rete Tree" at the bottom
+ of the DRL Editor window. With the Rete Network visualization being open,
+ you can use drag-and-drop on individual nodes to arrange optimal network
+ overview. You may also select multiple nodes by dragging a rectangle
+ over them; then the entire group can be moved around. The Eclips toolbar
+ icons for zooming in and out can be used in the customary manner.</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>
+ <para>In the current release there is no export function to creates a gif
+ or jpeg file. Meanwhile, please use ctrl + alt + print to create a copy of
+ your current Eclipse window, and cut it off.</para>
<mediaobject>
<imageobject>
@@ -599,27 +626,26 @@
</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 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
+ <para>If you are using Drools in another 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.
+ can use a workaround: 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 xml:base="../">
- <title>Large drl files</title>
+ <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
+ permanent generation max size. Both the SUN and the IBM JDK have a permanent
generation, whereas BEA JRockit does not.</para>
<para>To increase the permanent generation, start Eclipse with
@@ -628,10 +654,10 @@
<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>
+ generation to at least 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>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
@@ -642,7 +668,7 @@
<section xml:base="../">
- <title>Debugging rules</title>
+ <title>Debugging Rules</title>
<figure>
<title>Debugging</title>
@@ -655,16 +681,17 @@
<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>
+ such a breakpoint is encountered during the execution of the rules,
+ 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 the 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>
+ <title>Creating Breakpoints</title>
+ <para>You can add and 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
@@ -685,7 +712,7 @@
all defined breakpoints, get their properties, enable/disable or remove them, etc.</para>
</section>
<section>
- <title>Debugging rules</title>
+ <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>
@@ -700,33 +727,39 @@
<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>
+ <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 the
+ screenshot below).</para>
+
+ <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 with some of
+ the properties (like project and main class)already filled in,
+ based on the main class you selected in the beginning. All properties
+ shown here are the same as for 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 run your Drools application, you don't have
+ to create a new one but select the previously defined one
+ 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 one of your
+ previous configurations (at least when one of the Java, Java Debug,
+ or Drools perspectives has been selected).</para>
+ </listitem>
</orderedlist>
<figure>
@@ -738,16 +771,16 @@
</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
+ <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>
+ to decide what to do next: resume, terminate, step over, etc. The debug
+ view can also be used to inspect the contents of the Working Memory and the
+ Agenda at that time as well. You don't have to select a Working Memory now,
+ as the current executing working memory is automatically shown.</para>
<figure>
<title>Debugging</title>
Added: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/activity.gif
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/activity.gif
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/arrowleft.GIF
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/arrowleft.GIF
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/arrowright.GIF
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/arrowright.GIF
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/bluediamond.GIF
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/bluediamond.GIF
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/drools.gif
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/drools.gif
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/greensquare.GIF
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/greensquare.GIF
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/process.gif
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/process.gif
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/redsquare.GIF
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/redsquare.GIF
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/yellowsquare.GIF
===================================================================
(Binary files differ)
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/images/Chapter-IDE/yellowsquare.GIF
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
More information about the jboss-svn-commits
mailing list