[jboss-svn-commits] JBL Code SVN: r18877 - in labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en: Chapter-BRMS and 2 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Wed Mar 12 02:24:48 EDT 2008
Author: irooskov at redhat.com
Date: 2008-03-12 02:24:48 -0400 (Wed, 12 Mar 2008)
New Revision: 18877
Modified:
labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-AdminGuide.xml
labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-Introduction.xml
labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-Deployment/Section-Deployment.xml
labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-Deployment/Section-Testing.xml
labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-IDE/Section-QuickStart.xml
labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/master.xml
Log:
continued re-wording the user guide. Now onto final sections of the BRMS chapter.
Modified: labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-AdminGuide.xml
===================================================================
--- labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-AdminGuide.xml 2008-03-12 06:10:20 UTC (rev 18876)
+++ labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-AdminGuide.xml 2008-03-12 06:24:48 UTC (rev 18877)
@@ -5,76 +5,57 @@
<title>Administration guide</title>
<para>This chapter covers installation and administration issues of the
- BRMS.</para>
+ BRMS. From the initial setup to import/export functions are covered in this section.</para>
- <para>The BRMS is a web application that can run in multiple environments,
- and be configured to suit most situations. There is also some initial setup
- of data, and export/import functions covered.</para>
-
<section>
<title>Installation</title>
<para>Installation for most people is very simple. The BRMS application is
deployed as a .war file, which can be deployed in application servers or
- servlet containers with little or no configuration if you are happy with
- the defaults.</para>
+ servlet containers with little or no configuration if the defaults are satisfactory.</para>
- <para>When you have downloaded the BRMS distribution (which you can get
- from http://labs.jboss.com/jbossrules/downloads), you will find the
- drools-jbrms.war file in the zip file. Copy the WAR file into the
- deployment directory of you app server, and then start your app server. If
- you need to customize some settings, you can first "explode" (unzip) the
- war file, and change any configuration settings, and then either zip it
- up, or deploy it "exploded".</para>
+ <para>After the BRMS distribution has been downloaded (which you can get
+ from <ulink url="http://labs.jboss.com/jbossrules/downloads.html"> Drools downloads</ulink>), the
+ drools-jbrms.war file can be found in the zip file. Copy the WAR file into the
+ deployment directory of an application server, and then start the server. To customize settings, first unzip the WAR file, change the configuration settings and re-zip the archive or deploy it as it is.</para>
<para>Once the drools-jbrms.war has been placed in the deployment
- directory, and the application server started, you should navigate to
- http://localhost/drools-jbrms and check that the BRMS appears. (Obviously
- substitute the URL for what your application server is configured
- to).</para>
+ directory, and the application server started, navigate to the application server localhost address, such as
+ <address>http://localhost/drools-jbrms</address> and check that the BRMS appears.</para>
- <para>Once that shows up, you are deployed and ready to go !</para>
+ <para>When the BRMS appears, then deployment has been completed and it is ready for use.</para>
<section>
<title>Supported and recommended platforms</title>
- <para>The BRMS is capable of running in any application server that
- supports Java SE5 (JEE 5 is not required) - this includes servlet
+ <para>The BRMS is actively tested on JBoss platforms, and while these are reccommended, it is capable of running in any application server that
+ supports Java SE5 (JEE 5 is not required); this includes servlet
containers like tomcat.</para>
- <para>It is actively tested on JBoss platforms, and these are
- recommended if you are able to use them, or don't have any existing
- infrastructure. However, it is possible to use any container/app server,
- in some cases with minor configuration tweaks (consult the wiki for
- specific tips).</para>
-
<para>The following are a list of recommended platforms (all freely
- available), in all cases, you can substitute newer versions of the same
- and it should work (as time may have passed since this was
- written):</para>
+ available), in all cases, you can substitute newer versions of the platforms should remain com patable:</para>
<itemizedlist>
<listitem>
<para>JBoss Application Server 4.0.5</para>
<para>This is recommended as a general application server solution,
- if you need to run other applications alongside the BRMS.</para>
+ if other applications are needed to be run alongside the BRMS.</para>
</listitem>
<listitem>
<para>JBoss Web 1.0.1</para>
- <para>This is an ideal solution if you need a "lighter" server to
- run just the BRMS (perhaps stand alone).</para>
+ <para>This is an ideal solution if (for instance) the server is to run only the BRMS (perhaps stand alone).</para>
</listitem>
</itemizedlist>
- <para>You can of course download these from www.jboss.com for every
- operating system.</para>
+ <para>You can of course download these from <ulink url="www.jboss.com">JBoss.com (Enterprise releases)</ulink> or <ulink url="www.jboss.org">JBoss.org</ulink> (Community projects), for most popular
+ operating systems.</para>
- <para>Deployment into JBoss platforms: If you are installing a new JBoss
+ <para>If you are installing a new JBoss
platform, the WAR can be copied to [app server
- directory]/server/default/deploy. You then start up the server by
+ directory]/server/default/deploy. Then start the server by
running run.sh or run.bat in the [app server directory/bin]
directory.</para>
</section>
@@ -83,51 +64,44 @@
<section>
<title>Database configuration</title>
- <para>The BRMS uses the JCR standard for storing assets (such as rules).
- The default implementation is Apache Jackrabbit
- (http://jackrabbit.apache.org/). This includes an out of the box storage
- engine/database, which you can use as is, or configure to use an existing
- RDBMS if needed.</para>
+ <para>The BRMS uses the Java Content Repository (JCR) standard for storing assets (such as rules).
+ The default implementation is <ulink url="http://jackrabbit.apache.org/">Apache Jackrabbit</ulink>, which includes an out of the box storage
+ engine/database. This can be configured to use an existing Relational Database Management System (RDBMS) or work as it is.</para>
<section>
<title>Changing the location of the data store</title>
- <para>When you run the BRMS for the first time (starting up the app
+ <para>When running the BRMS for the first time (starting up the app
server), it will create a database in the [app server directory]/bin/
- directory (assuming you used on of the JBoss platforms). There is a
+ directory (assuming use of the JBoss platforms). There is a
repository.xml file, and a repository directory that are automatically
created.</para>
<para>The location of the data store should be a secure location, that
is backed up. The default location may not be suitable for this, so the
easiest way is to set a more suitable location. If you want to change
- this, please make sure you have stopped the BRMS (ie stopped the app
+ this, please make sure you have stopped the BRMS (that is, stopped the application
server or undeployed the application).</para>
<para>To change the location, unzip the WAR file, and locate the
- components.xml file in the WEB-INF directory. This is a JBoss Seam
+ <filename>components.xml</filename> file in the WEB-INF directory. This is a JBoss Seam
configuration file (Seam is the framework used) which allows various
- parts of the system to be customized. When you have located the
- components.xml file, you should see something like the following:</para>
- <programlisting><component name="repositoryConfiguration">
- <!--
- *** This is for configuring the "home" directory for the repository storage. the directory must exist. ***
- <property name="homeDirectory">/home/michael/RulesRepository_001</property>
- -->
-
+ parts of the system to be customized. When the <filename>components.xml</filename> file has been located, output similar to the following should appear:</para>
+<screen><component name="repositoryConfiguration">
+<!--
+*** This is for configuring the "home" directory for the repository storage. the directory must exist. ***
+<property name="homeDirectory">/home/michael/RulesRepository_001</property>
+-->
...
</component>
-</programlisting>
+</screen>
- <para>Find the component with a name of "repositoryConfiguration" and
- the property with the name of "homeDirectory".</para>
+<para>Find the component with the name <emphasis>repositoryConfiguration</emphasis> and
+ the property with the name of <property>homeDirectory</property>.</para>
- <para>If you un comment this (as in the example above it is commented
- out), you can set whatever path you need for the repository data to be
- stored in. You can also use this to move the repository around. In that
- case, when you have set the location in the components.xml you can
- simply move the repository.xml AND the repository directory to the new
- location that you set in the components.xml.</para>
+ <para>If this property is uncomment (in the example above it is commented
+ out), any path for the repository data can be set. If changing the location of the repository data, set the location in the components.xml and move the repository.xml and repository directory to the new
+ location.</para>
<para>If there is no repository at the location specified (or in the
default location) then the BRMS will create a new empty one.</para>
@@ -140,19 +114,22 @@
<section>
<title>Configuring the BRMS to use an external RDBMS</title>
- <para>In some cases it may be a requirement that you use an external
- RDBMS, such as Oracle, MySQL, or Microsoft SQL Server as the data store
- - this is permitted. In this case, the easiest thing to do is to start
+ <para>In some cases it may be a requirement that an external
+ RDBMS, such as Oracle, MySQL or alike is used. In this case, the easiest thing to do is to start
up the RDBMS with defaults (or with a suitable home directory as
specified above) to let it generate the default repository.xml
scaffolding.</para>
- <para>Locate the repository.xml file that was generated, and open it -
- it will be annotated with comments describing many of the different
- options. From here on, you will need to know a little about Jackrabbit
- Persistence managers:
- http://jackrabbit.apache.org/doc/config.html</para>
+ <para>Locate and open the <filename>repository.xml</filename> file that was generated, it will be annotated with comments describing many of the different
+ options. </para>
+<important>
+ <para>
+Knowledge about Jackrabbit
+ Persistence Managers will be necessary from this point onwards. The required information can be found at:
+ <ulink url="http://jackrabbit.apache.org">Apache Jackrabbit</ulink>
+ </para>
+</important>
<para>There are a few persistence managers, some are database specific
(eg Oracle). There is a SimpleDBPersistenceManager which works with any
database that supports JDBC - you also specify the database type, so it
Modified: labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-Introduction.xml
===================================================================
--- labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-Introduction.xml 2008-03-12 06:10:20 UTC (rev 18876)
+++ labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-Introduction.xml 2008-03-12 06:24:48 UTC (rev 18877)
@@ -4,8 +4,7 @@
<section>
<title>Introduction</title>
- <para>This section introduces the BRMS. See the other relevant sections for
- installation, usage and administration.</para>
+ <para>Introducing the BRMS, this chapter will explore the installation, administration and usage of the system. For advanced topics concerning the BRMS, refer to the Drools Reference Guide.</para>
<figure>
<title>The BRMS in action</title>
@@ -23,10 +22,9 @@
<para>BRMS stands for Business Rules Management System.</para>
- <para>This is the component of JBoss Rules which covers rule management,
+ <para>This is the component of Drools which covers rule management,
storage, editing and deployment. A Web based user interface is provided so
- this tool can be used by people who don't work in IDEs or text editors,
- but it is intended for a wide audience.</para>
+ this tool can be used by people who don't work in IDEs or text editors, while also containing information that may be of interest to the aforementioned audiences.</para>
<para>A BRMS allows people to manage rules in a multi user environment, it
is a single point of truth for your business rules, allowing change in a
@@ -35,19 +33,35 @@
<section>
<title>When to use a BRMS</title>
- <para>You should consider a BRMS if any of the following apply to you:
- You need to manage versions/deployment of rules, you need to let
- multiple users of different skill levels access and edit rules, you
- don't have any existing infrastructure to manage rules, you have lots of
- "business" rules (as opposed to technical rules as part of an
- application). </para>
+ <para>A BRMS should be considerd if any of the following apply:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Management of versions/deployment of rules is required
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Multiple users of different skill levels require access and the ability to edit rules.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ There is no existing infrastructure to manage rules
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The organization has many
+ operations, definitions or constrants which impact the ability to achieve goals (as opposed to technical rules as part of an
+ application)
+ </para>
+ </listitem>
+ </itemizedlist>
- <para>A BRMS can be used on its own, or with the IDE tooling (often both
- together). </para>
+ <para>The BRMS can be used on its own or with the Eclipse IDE (often both
+ together). The management system can also become apart of an application or function as a central rule repository. </para>
- <para>A BRMS can be "branded" and made part of your application, or it
- can be a central rule repository.</para>
-
<section>
<title>When to not use a BRMS</title>
@@ -55,11 +69,11 @@
the rules in a database (for instance as part of an existing application),
and no new application is needed to manage the rules. </para>
- <para>Otherwise, perhaps an existing rule management system and user interface
- already exists (and is tailored to your environment already) - in this
+ <para>It may be that an existing rule management system and user interface
+ already exists (and is tailored to the environment already). In this
case migrating to the BRMS may not be necessary.</para>
- <para>If you are using rules to solve complex algorithmic problems,
+ <para>If rules are being used to solve complex algorithmic problems,
and the rules are essentially an integral part of the application (and
don't need to be managed separately to the code).</para>
</section>
@@ -68,12 +82,32 @@
<section>
<title>Who uses a BRMS</title>
- <para>The main roles of people who would use a BRMS are: Business
- Analyst, Rule expert, Developer, Administrators (rule administrators etc).
- </para>
+ <para>The main roles of people who would use a BRMS are: </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Business Analyst
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Rule Expert
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Developer
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Rule Administrators
+ </para>
+ </listitem>
+ </itemizedlist>
- <para>The BRMS is designed in such a way as these different roles can be
- accommodated, it can be controlled how much is exposed to different users in a safe fashion.</para>
+ <para>The BRMS is designed for control over how much of the system is visible to different users. This means that there is accommodation for a vast array of individuals of different roles to use the BRMS in a safe and secure fashion.</para>
</section>
</section>
Modified: labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-Deployment/Section-Deployment.xml
===================================================================
--- labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-Deployment/Section-Deployment.xml 2008-03-12 06:10:20 UTC (rev 18876)
+++ labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-Deployment/Section-Deployment.xml 2008-03-12 06:24:48 UTC (rev 18877)
@@ -104,64 +104,60 @@
use it until they are finished, in which case it will eventually be
garbage collected).</para>
- <para>There are many more sophisticated approaches to the above - Drools
- rule engine is very dynamic, meaning pretty much all the components can be
- swapped out on the fly (rules, packages) even when there are *existing*
+ <para>There are many more sophisticated approaches, the Drools
+ rule engine is very dynamic, meaning nearly all components can be
+ swapped out on the fly (rules, packages), even when there are <emphasis>existing</emphasis>
working memories in use. For instance rules can be retracted from a
rulebase which has many in-use working memories - the RETE network will
then be adjusted to remove that rule without having to assert all the
facts again. Long running working memories are useful for complex
applications where the rule engine builds up knowledge over time to assist
- with decision making for instance - it is in these cases that the
- dynamic-ness of the engine can really shine.</para>
+ with decision making. In these cases the dynamic nature of the Drools engine can really be showcased.</para>
<section>
<title>DRL and PackageDescr</title>
- <para>One option is to deploy the rules in source form. This leaves the
+ <para>An option when deploying rules is to do so in source form. This leaves the
runtime engine (which must include the compiler components) to compile
the rules, and build the rule base. A similar approach is to deploy the
"PackageDescr" object, which means that the rules are pre-parsed (for
- syntactic errors) but not compiled into the binary form. Use the
- PackageBuilder class to achieve this. You can of course use the XML form
- for the rules if needed.</para>
+ syntactic errors) but not compiled into binary form. The
+ <classname>PackageBuilder</classname> class can be used to achieve this. The XML form for the rules can also be used if needed.</para>
- <programlisting>PackageDescr, PackageBuilder, RuleBaseLoader</programlisting>
+ <screen>PackageDescr, PackageBuilder, RuleBaseLoader</screen>
</section>
<section>
<title>Package</title>
- <para>This option is the most flexible. In this case, Packages are built
+ <para>The Package option is the most flexible. In this case, Packages are built
from DRL source using PackageBuilder - but it is the binary Package
- objects that are actually deployed. Packages can be merged together.
- That means a package containing perhaps a single new rule, or a change
+ objects that are actually deployed. Packages can be merged together, meaning a package containing a single new rule, or a change
to an existing rule, can be built on its own, and then merged in with an
existing package in an existing RuleBase. The rulebase can then notify
existing working memories that a new rule exists (as the RuleBase keeps
- "weak" links back to the Working Memory instances that it spawned). The
- rulebase keeps a list of Packages, and to merge into a package, you will
- need to know which package you need to merge into (as obviously, only
+ <emphasis>weak</emphasis> links back to the Working Memory instances that it spawned). The
+ rulebase keeps a list of Packages, and to merge into a package, the package to merge with needs to be known (only
rules from the same package name can be merged together).</para>
<para>Package objects themselves are serializable, hence they can be
sent over a network, or bound to JNDI, Session etc.</para>
- <programlisting>PackageBuilder, RuleBase, org.drools.rule.Package</programlisting>
+ <screen>PackageBuilder, RuleBase, org.drools.rule.Package</screen>
</section>
<section>
<title>RuleBase</title>
- <para>Compiled Packages are added to the rulebases. RuleBases are
- serializable, so they can be a binary deployment unit themselves. This
- can be a useful option for when rulebases are updated as a whole - for
+ <para>. RuleBases are
+ serializable, so they can be a binary deployment unit themselves, with compiled Packages being added to the rulebases. This
+ can be a useful option for when rulebases are updated as a whole; for
short lived working memories. If existing working memories need to have
rules changed on the fly, then it is best to deploy Package objects.
- Also beware that rulebases take more processing effort to serialize (may
+ Also beware that rulebases take more processing effort to serialize (might
be an issue for some large rulebases).</para>
- <programlisting>RuleBase, RuleBaseLoader</programlisting>
+ <screen>RuleBase, RuleBaseLoader</screen>
</section>
<section>
@@ -170,14 +166,16 @@
<para>Practically all of the rulebase related objects in Drools are
serializable. For a working memory to be serializable, all of your
objects must of course be serializable. So it is always possible to
- deploy remotely, and "bind" rule assets to JNDI as a means of using them
+ deploy remotely, and <emphasis>bind</emphasis> rule assets to JNDI (Java Naming and Directory Interface) as a means of using them
in a container environment.</para>
</section>
- <para>Please note that when using package builder, you may want to check
- the hasError() flag before continuing deploying your rules (if there are
- errors, you can get them from the package builder - rather then letting it
- fail later on when you try to deploy).</para>
+ <note>
+ <para>When using package builder, check
+ the <methodname>hasError()</methodname> flag before continuing with the deployment of the rules (if there are
+ errors, they will be found now from the package builder, rather then letting it
+ fail later on when deploying).</para>
+ </note>
</section>
<section>
@@ -187,7 +185,7 @@
<title>In process rule building</title>
<para>In this case, rules are provided to the runtime system in source
- form. The runtime system contains the drools-compiler component to build
+ form. The runtime system contains the <classname>drools-compiler</classname> component to build
the rules. This is the simplest approach.</para>
</section>
@@ -201,20 +199,19 @@
any errors to do with compiling are well contained and and known before
deployment to the running system is attempted.</para>
- <para>Use the PackageBuilder class out of process, and then use
- getPackage() to get the Package object. You can then (for example)
+<para>Use the <classname>PackageBuilder</classname> class out of process, and then use
+ <methodname>getPackage()</methodname> to get the Package object. You can then (for example)
serialize the Package object to a file (using standard java
serialization). The runtime system, which only needs drools-core, can
then load the file using
- RuleBaseFactory.newRuleBase().addPackage(deserialized package
- object).</para>
+ <command>RuleBaseFactory.newRuleBase().addPackage(deserialized package
+ object)</command>.</para>
</section>
<section>
<title>Some deployment scenarios</title>
- <para>This section contains some suggested deployment scenarios, of
- course you can use a variety of technologies as alternatives to the ones
+ <para>This section contains some suggested deployment scenarios, however there are a variety of technologies which can be used as alternatives to the ones
in the diagram.</para>
<section>
@@ -242,9 +239,9 @@
<title>Push style</title>
<para>In this scenario, the rule deployment process/repository
- "pushes" rules into the runtime system (either in source or binary
+ <emphasis>pushes</emphasis> rules into the runtime system (either in source or binary
form, as described above). This gives more control as to when the new
- rules take effect.</para>
+ rules will take effect.</para>
</section>
<screenshot>
@@ -262,9 +259,9 @@
<para>A possible deployment pattern for rules are to expose the rules as a
web service. There a many ways to achieve this, but possibly the simplest
- way at present do achieve it is to use an interface-first process: Define
- the "facts" classes/templates that the rules will use in terms of XML
- Schema - and then use binding technologies to generate binding objects for
+ way at present is to use an interface-first process. Define
+ the <emphasis>facts</emphasis> classes/templates that the rules will use in terms of XML
+ Schema and then use binding technologies to generate binding objects for
the rules to actually operate against. A reverse possibility is to use a
XSD/WSDL generator to generate XML bindings for classes that are hand
built (which the rules work against). It is expected in a future version
Modified: labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-Deployment/Section-Testing.xml
===================================================================
--- labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-Deployment/Section-Testing.xml 2008-03-12 06:10:20 UTC (rev 18876)
+++ labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-Deployment/Section-Testing.xml 2008-03-12 06:24:48 UTC (rev 18877)
@@ -7,24 +7,23 @@
bring to software development has been realized. In a sense, rules are code
(although at a high level), and a lot of the same principles apply.</para>
- <para>You can provide tests as a means to specify rule behavior before
+ <para>Tests can be provided as a means to specify rule behavior before
rules are even written. Further to this, tests are even more important in
environments where rules change frequently. Tests can provide a baseline of
confidence that the rule changes are consistent with what is specified in
the tests. Of course, the rules may change in such a way as the tests are
now wrong (or perhaps new tests need to be written to cover the new rule
- behavior). As in TDD practices, tests should be run often, and in a rule
+ behavior). As in TDD (Test-Driven Development) practices, tests should be run often, and in a rule
driven environment, this means that they should be run every time the rules
change (even though the software may be static).</para>
<section>
<title>Testing frameworks</title>
- <para>For developers, clearly JUnit (or TestNG) are popular tools for
+ <para>For developers, JUnit (or TestNG) are popular tools for
testing code, and these can also apply to rules. Keep in mind that rule
- changes may happen out of sync with code changes, so you should be
- prepared to keep these unit tests up to date with rules (may not be
- possible in all environments). Also, the best idea is to target testing
+ changes may happen out of sync with code changes, so unit tests should be kept up to date with rules (though this may not be
+ possible in all environments). The best idea is to target testing of
some core features of the rule sets that are not as likely to change over
time.</para>
@@ -75,10 +74,10 @@
<para>Using Fit for rules, you capture test data, pass it to the rule
engine and then verify the results (with documentation woven in with the
- test). It is expected that in future, the Drools Server tools will provide
- a similar integrated framework for testing (green means good ! red means a
- failure - with the expected values placed in the cell). Refer to
- http://fit.c2.com for more information on the FIT framework itself.</para>
+ test). It is expected that in the future, Drools Server tools will provide
+ a similar integrated framework for testing (green means good, red means a
+ failure; with the expected values placed in the cell). Refer to
+ <ulink url="http://fit.c2.com">FIT</ulink> for more information on the FIT framework itself.</para>
<screenshot>
<mediaobject>
Modified: labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-IDE/Section-QuickStart.xml
===================================================================
--- labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-IDE/Section-QuickStart.xml 2008-03-12 06:10:20 UTC (rev 18876)
+++ labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-IDE/Section-QuickStart.xml 2008-03-12 06:24:48 UTC (rev 18877)
@@ -5,24 +5,21 @@
<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>
+ 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. Where business rules and web tooling is prefered, the BRMS would be better suited over the IDE(but using the BRMS and the IDE together is not uncommon).</para>
<para>The Drools IDE is delivered as an eclipse plugin, 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>
+ allows the authoring and management of rules from within Eclipse, as well as
+ integrating rules with the application. This is an optional tool, and only those components relevant to the application need be in use. 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 is 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>
+<note>
+<para>None of the underlying features of the rule engine are dependent
+ on Eclipse, and integrators are free to use their tools of choice.For example the IDE IntelliJ could be used with Drools.</para>
+</note>
+<!--
<para>Note you can get the plugin either as a zip to download, or from an
update site (refer to the chapter on installation).</para>
-
+-->
<figure>
<title>Overview</title>
@@ -55,7 +52,7 @@
<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>
+ <para>Visual graph editing which represents a process (a rule flow). The RuleFlow can then be applied to the rule package to have imperative control.</para>
</listitem>
<listitem>
@@ -63,7 +60,7 @@
<orderedlist>
<listitem>
- <para>Help you quickly create a new "rules" project</para>
+ <para>Helps quickly create a new "rules" project</para>
</listitem>
<listitem>
@@ -87,7 +84,7 @@
<orderedlist>
<listitem>
- <para>Create and manage mappings from your users language to the
+ <para>Create and manage mappings from the users language to the
rule language</para>
</listitem>
</orderedlist>
@@ -98,15 +95,15 @@
<orderedlist>
<listitem>
- <para>As rules are entered, the rule is "built" in the background
- and errors reported via the problem "view" where possible</para>
+ <para>As rules are entered, the rule is <emphasis>built</emphasis> in the background
+ and errors reported via the problem <emphasis>view</emphasis> 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>
+ and features. All of the power of Eclipse is available.</para>
</section>
<section>
@@ -114,8 +111,7 @@
<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>
+ structure, classpath, sample rules and test case.</para>
<figure>
<title>New rule project scaffolding</title>
@@ -126,7 +122,7 @@
</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 plugin at this point.</para>
+ <para>When choosing to create a new <emphasis>rule project</emphasis>, there will be a choice to add a selection of default artifacts to the projet (rules, decision tables, ruleflows etc). These can serve as a starting point (which can then be modified and moulded to specific needs). The simplest case (a hello world rule) is shown below. Feel free to experiment with the plugin at this point.</para>
<figure>
<title>New rule project result</title>
@@ -141,33 +137,30 @@
<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
+ 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"
+ 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>
<note>
-<para>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
+<para>The Drools plugin adds a <emphasis>Drools Builder</emphasis>
+ capability to your eclipse instance. This means a builder can be enabled
+ on any project that will build and validate the rules when resources
+ change. This happens automatically with the Rule Project Wizard, but
+ can also be manually enabled on any project. One downside of this is if there are a large number of rule files (>500 rules per file), as this would mean 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>
+ or put the large rules into <filename>.rule</filename> files, where the rule editor can still be used, but it won't build them in the background. To fully validate the
+ rules they will need to be run in a unit test.</para>
</note>
</section>
<section>
<title>Creating a new rule and wizards</title>
- <para>You can create a rule simply 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
+ <para>A rule can be created simply as an empty text <filename>.drl</filename> file, or via the use of
+ the wizard. The wizard menu can be invoked by <command>Control (Ctrl) + N</command>, or
+ selecting it from the toolbar (there will be a menu with the JBoss Drools
icon).</para>
<figure>
@@ -181,11 +174,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
+ resource, which can be altered at a later date. In terms
+ of location, typically a top level /rules directory would be created to
+ store the rules when creating a rule project with
+ suitably named subdirectorys. The package name is mandatory, and is similar
+ to a package name in java (ie. its a namespace that groups similar rules
together).</para>
<figure>
@@ -207,10 +200,10 @@
<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
+ 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>
+ assistance. Popup content assistance is invoked by
+ pressing Control (Ctrl) and the Spacebar at the same time.</para>
<figure>
<title>The rule editor in action</title>
@@ -223,16 +216,16 @@
</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
+ extension. Rules are generally grouped together as a <emphasis>package</emphasis> 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
+ in individual files (grouped by being in the same package <emphasis>namespace</emphasis> 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
+ <para>From the example above it can been seen 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
+ still stored as plain text, which allows simpler
management of rules and versions (comparing versions of rules for
instance).</para>
@@ -269,19 +262,19 @@
</figure>
<para>
- To create a rule this way, use the wizard menu. It will create an 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 populate the package file with the fact classes you are interested in. Once this has been done, the guided editor will be able to prompt you with facts/fields and build rules graphically.
+ To create a rule this way, use the wizard menu. It will create an instance of a .brl file and open an editor. The guided editor works based on a <filename>.package</filename> file in the same directory as the <filename>.brl</filename> file. In this <emphasis>package</emphasis> file are the package name and import statements, the same as would appear at the top of a normal DRL file. The first time a brl rule is created, the package file will need to be populated with the fact classes of interest. Once this has been done, the guided editor will be able to prompt 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:
+ The guided editor works off the configured model classes (fact classes). It then is able to <emphasis>render</emphasis> to DRL the rule that has been entered graphically. Done visually, this can be used as a basis for learning DRL, or it can be used to build rules of the brl directly. The drools-ant module (it is an ant task that will build up all the rule assets in a folder as a rule package, which can then be deployed as a binary file) can be used to accomplish this, or the following snippet of code can be used to convert the brl to a drl rule:
</para>
- <programlisting>BRXMLPersitence read = BRXMLPersitence.getInstance();
+ <screen>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>
+//then pass the outputDRL to the PackageBuilder as normal</screen>
</section>
<section>
@@ -290,8 +283,8 @@
<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 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
+ these views, create breakpoints in the code that invokes the working memory.
+ For example, the line where you call <methodname>workingMemory.fireAllRules()</methodname> 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
@@ -337,7 +330,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. As an example, logical structures allow for the visualization sets of
elements in a more obvious way.</para>
</listitem>
</orderedlist>
@@ -405,23 +398,22 @@
</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>
+ created when executing the rules engine. Here is an example of how to creatre an audit log:</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");
+<screen> 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();
+workingMemory.assertObject( ... );
+workingMemory.fireAllRules();
- // stop logging
- logger.writeToDisk();</programlisting>
+// stop logging
+logger.writeToDisk();</screen>
- <para>Open the log by clicking the Open Log action (first action in the
+ <para>Open the log by clicking the <action>Open Log</action> action (first action in the
Audit View) and select the file. The Audit view now shows all events
that where logged during the execution of the rules. There are different
types of events (each with a different icon):</para>
@@ -468,19 +460,19 @@
</listitem>
</orderedlist>
- <para>All these events show extra information concerning the event, like
+ <para>All these advents show extra information concerning the event, such as
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>
+ activation, it is shown as a child of the activation. For
+ some events, you can retrieve the <emphasis>cause</emphasis>:</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>
+ event, or the last object modified event.</para>
</listitem>
<listitem>
@@ -499,21 +491,18 @@
<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
+ <para>Domain Specific Languages (DSL) give the ability for you to create a language that
+ allows your rules to look like rules. Most often the DSL reads like natural language. Typically you would look at how a
+ business analyst would describe the rule, 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
+ the rules themselves. 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>
+ are common terms used repeatedly, 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
+ <para>To aid with this, the rule workbench provides an editor for DSLs (they are stored in a plain text format, so they can
+ be used with any editor. The editor will be invoked on any files
+ with a <filename>.dsl</filename> extension (there is also a wizard to create a sample
DSL).</para>
<section>
@@ -530,23 +519,21 @@
</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
+ 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
+ loaded for editing). The Rule language mapping is the <emphasis>code</emphasis> for the
+ rules, which the language expression will be compiled to by the rule
+ engine compiler. The 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
+ instance). The <emphasis>scope</emphasis> item indicates where the expression is targeted:
+ is it for the <emphasis>when</emphasis> part of the rule (LHS), the <emphasis>then</emphasis> 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>
+ <para>By selecting a mapping item (a row in the table) the
+ expression and mapping can be seen in the greyed out fields below. Double clicking
+ or pressing the edit button will open the edit dialog. Items can be removed, and new ones added (an item should only be removed when it is known that the expression is no longer in use).</para>
<figure>
<title>Language Mapping editor dialog</title>
@@ -559,38 +546,36 @@
</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
+ <para>How it works: the <emphasis>Language expression</emphasis> is used to parse the rule
+ language, depending on what the <emphasis>scope</emphasis> is set to. When it is found in a
+ rule, the values that are marked by the curly braces <emphasis>{value}</emphasis> are
extracted from the rule source. These values are then interpolated with
- the "Rule mapping" expression, based on the names between the curly
+ the <emphasis>Rule mapping</emphasis> 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
+ to 2 constraints on a fact of type Person (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
+ was <emphasis>then</emphasis>). If a language mapping is not wished to be used 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. </para>
+<note>
+<para>Domain Specific Languages (DSLs) are optional. When
the rule is compiled, the .dsl file will also need to be
available.</para>
+</note>
</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>The Rete Tree View shows the current Rete Network for your drl
+ file. Click the tab <emphasis>Rete Tree </emphasis>below on the DRL Editor, enabling the generation of the current Rete Network visualization. From here nodes can be pushed an pulled in order to arrange an optimal network overview. If
+ there are hundreds of nodes, select some of them with a frame, grouping the nodes. In some cases, not all nodes will be viewable in the current view, use the buttons "+" and "-" to zoom in and out respectively.</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
+ <para>In the current release there is no export function, which to export an image of the Please use ctrl + alt + print to create a copy of
your current eclipse window and cut it off.</para>
<mediaobject>
@@ -605,38 +590,36 @@
<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>If you are using Drools in an other type of project, where there is not a Drools Rule Project with the appropriate Drools Builder, there is a 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>
+ <para>Set up a little Drools Rule Project next to it, placing needed
+ libraries into it and the drls needed to inspect with the Rete View.
+ Click on the right tab below in the DRL Editor, followed by a click
+ on <emphasis>Generate Rete View</emphasis>.</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
+ 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>To increase the permanent generation, start eclipse with:</para>
+ <screen>-XX:MaxPermSize=###m</screen>
- <para>Example: c:\eclipse\eclipse.exe -XX:MaxPermSize=128m</para>
+ <example>Example: c:\eclipse\eclipse.exe -XX:MaxPermSize=128m</example>
<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>
+ <note><para>This may also apply to compiling large numbers of rules
+ in general, as there is generally one or more classes per rule).</para></note>
<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>
+ <filename>.rule</filename> extension, and the background builder will not try to compile them
+ with each change. This may provide performance improvements if your IDE
+ becomes slow with very large numbers of rules.</para>
</section>
@@ -653,12 +636,12 @@
</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
+ <para>Rules can be debugged during the execution of the Drools application and
+ breakpoints can be added in the consequences of your rules. Whenever
+ such a breakpoint is encounted during the execution of the rules, the execution
+ is halted. Known variables can then be inspected 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
+ continue as examples). The debug views can also be used to inspect the content of the
working memory and agenda.</para>
<section>
@@ -668,17 +651,25 @@
<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.
+ add a breakpoint. Double-clicking on a line where there is no breakpoint will yeild no results. A breakpoint can be removed by double-clicking the ruler once more.
</para>
+ <note>
+ <para>
+ Rule breakpoints can only be created in the consequence of a rule.
+ </para>
+ </note>
</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
+ <para>If you right-click the ruler, a popup menu will appear, containing the
+ <emphasis>Toggle breakpoint</emphasis> action. 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>
+ <note>
+ <para>
+ Rule breakpoints can only be created in the
+ consequence of a rule
+ </para>
+ </note>
</listitem>
</orderedlist>
<para>The Debug Perspective contains a Breakpoints view which can be used to see
@@ -686,8 +677,8 @@
</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>
+ <para>Drools breakpoints are only enabled if the application is debugged as
+ a Drools Application. This is shown below:</para>
<figure>
<title>Debug as Drools Application</title>
@@ -700,27 +691,25 @@
<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
+ <para>Select the main class of the application. Right click it and select the
+ <emphasis>Debug As ></emphasis> sub-menu and select Drools Application. Alternatively, you can also select
+ the <emphasis>Debug ..."</emphasis> 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
+ <para>Select the <emphasis>Drools Application</emphasis> item in the left tree and click the <emphasis>New Launch Configuration</emphasis> 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.
+ (similar to 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>
+ <para>Change the name of your debug configuration to something meaningful and 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
+ <para>Click the <emphasis>Debug</emphasis> button on the bottom to start debugging the application; the debug configuration only has to be declared once. The next time the Drools application is run, select the debug configuration previously created, by selecting it in the tree on the left, as a sub-element of the <emphasis>Drools Application</emphasis>
+ tree node; 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>
@@ -738,14 +727,13 @@
</mediaobject>
</figure>
- <para>After clicking the "Debug" button, the application starts executing and will halt if any
+ <para>After clicking the <emphasis>Debug</emphasis> 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
+ parameters and their value. Then the default Java debug actions can be used to decide what to do next (resume, terminate, step over and so forth). 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
+ (a working memory dos not ahve to be selected, the current executing working memory
is automatically shown).
</para>
Modified: labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/master.xml
===================================================================
--- labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/master.xml 2008-03-12 06:10:20 UTC (rev 18876)
+++ labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/master.xml 2008-03-12 06:24:48 UTC (rev 18877)
@@ -137,7 +137,7 @@
</chapter>
<chapter>
- <title>The BRMS (Business Rule Management System)</title>
+ <title>The Business Rule Management System (BRMS)</title>
<xi:include href="Chapter-BRMS/Section-Introduction.xml" />
More information about the jboss-svn-commits
mailing list