[jboss-svn-commits] JBL Code SVN: r19133 - labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Thu Mar 20 00:53:42 EDT 2008
Author: irooskov at redhat.com
Date: 2008-03-20 00:53:41 -0400 (Thu, 20 Mar 2008)
New Revision: 19133
Modified:
labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-UserGuide.xml
Log:
completed re-writting of the new Drools User Guide
Modified: labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-UserGuide.xml
===================================================================
--- labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-UserGuide.xml 2008-03-20 04:45:25 UTC (rev 19132)
+++ labs/jbossrules/branches/irooskov_docs/drools-docs/drools-docs-userguide/en/Chapter-BRMS/Section-UserGuide.xml 2008-03-20 04:53:41 UTC (rev 19133)
@@ -551,10 +551,10 @@
<para>In the above diagram, <emphasis>MM</emphasis> indicates a value that will be used in the rule, yet <emphasis>Mini Mal</emphasis> will be displayed in the GUI.</para>
- <para>Getting data lists from external data sources: It is possible to have the BRMS call a piece of code which will load a list of Strings. To do this, a bit of code that returns a <property>java.util.List</property> (of String's) to be on the classpath of the BRMS will be needed. Instead of specifying a list of values in the BRMS itself - the code can return the list of Strings (you can use the "=" inside the strings if you want to use a different display value to the rule value, as normal). For example, in the 'Person.age' line above, you could change it to:</para>
+ <para> When retrieving data lists from external data sources it is possible by having code on the classpath of the BRMS, to have it call a piece of code which will load a list of Strings (<property>java.util.List</property>). Instead of specifying a list of values in the BRMS itself, the code can return the list of Strings (use the "=" inside the strings if a different display value is wished to be returned to the rule value, as normal). For example, in the <emphasis>Person.age</emphasis> line above, you could change it to:</para>
<screen> 'Person.age' : (new com.yourco.DataHelper()).getListOfAges()</screen>
<para>
-This assumes you have a class called "DataHelper" which has a method "getListOfAges()" which returns a List of strings (and is on the classpath). You can of course mix these "dynamic" enumerations with fixed lists. You could for example load from a database using JDBC. The data enumerations are loaded the first time you use the guided editor in a session. If you have any guided editor sessions open - you will need to close and then open the rule to see the change. To check the enumeration is loaded - if you go to the Package configuration screen, you can "save and validate" the package - this will check it and provide any error feedback.</para>
+This assumes there is a class called <classname>DataHelper</classname> which has a method <methodname>getListOfAges()</methodname> that returns a List of strings (and is on the classpath). These <emphasis>dynamic</emphasis> enumerations can be mixed with fixed lists; for example, it is possible to load from a database using JDBC. The data enumerations are loaded the first time the guided editor is used in a session. If any guided editor sessions are open, these will need to close and then the rule will have to be reopened in order to see the change. To check the enumeration is loaded go to the Package configuration screen and <emphasis>save and validate</emphasis> the package; this will check it and provide any error feedback.</para>
</section>
@@ -562,28 +562,28 @@
<section>
<title>Advanced enumaration concepts</title>
- <para>There are a few other advanced things you can do with data enumerations.</para>
+ <para>There are a few advanced operations that can be achieved with data enumerations. Firsty Drop down lists that depends on field values will be discussed. </para>
- <para>Drop down lists that depend on field values: Lets imagine a simple fact model, we have a class called Vehicle, which has 2 fields: "engineType" and "fuelType". We want to have a choice for the "engineType" of "Petrol" or "Diesel". Now, obviously the choice type for fuel must be dependent on the engine type (so for Petrol we have ULP and PULP, and for Diesel we have BIO and NORMAL). We can express this dependency in an enumerattion as:</para>
+ <para>Taking a simple fact model, there is a class called Vehicle, which has 2 fields: <emphasis>engineType</emphasis> and <emphasis>fuelType</emphasis>. Choice is necessary for the <emphasis>engineType</emphasis> of <emphasis>Petrol</emphasis> or <emphasis>Diesel</emphasis>. The choice of fuel type is dependent on the engine type. For Petrol there is ULP and PULP, and for Diesel there is BIO and NORMAL. This dependency can be expressed in an enumerattion as:</para>
- <programlisting>
- 'Vehicle.engineType' : ['Petrol', 'Diesel']
- 'Vehicle.fuelType[engineType=Petrol]' : ['ULP', 'PULP' ]
- 'Vehicle.fuelType[engineType=Diesel]' : ['BIO', 'NORMAL' ]
-</programlisting>
+<screen>
+'Vehicle.engineType' : ['Petrol', 'Diesel']
+'Vehicle.fuelType[engineType=Petrol]' : ['ULP', 'PULP' ]
+'Vehicle.fuelType[engineType=Diesel]' : ['BIO', 'NORMAL' ]
+</screen>
- <para>This shows how it is possible to make the choices dependent on
- other field values. Note that once you pick the engineType, the choice
- list for the fuelType will be determined.</para>
+ <para>Once the engineType has been chosen, the choice
+ list for the fuelType will be determined, demonstrating how it is possible to make the choices dependent on
+ other field values</para>
- <para>Loading enums programmatically: In some cases, people may want
- to load their enumeration data entirely from external data source
- (such as a relational database). To do this, you can implement a class
- that returns a Map. The key of the map is a string (which is the
- Fact.field name as shown above), and the value is a java.util.List of
+ <para>In some cases, it may be desirable
+ to load enumeration data entirely from an external data source
+ (such as a relational database). To do this, implementation of a class
+ that returns a Map that's key is a string (which is the
+ <emphasis>Fact.field</emphasis> name as shown above), and the value is a <emphasis>java.util.List</emphasis> of
Strings.</para>
- <programlisting>
+<screen>
public class SampleDataSource2 {
public Map<String>, List<String>> loadData() {
@@ -598,39 +598,38 @@
}
}
-</programlisting>
+</screen>
- <para>And in the enumeration in the brms, you put:</para>
+ <para>In the enumeration in the BRMS, write:</para>
- <programlisting>=(new SampleDataSource2()).loadData()
-</programlisting>
+<screen>
+=(new SampleDataSource2()).loadData()
+</screen>
- <para>The "=" tells it to load the data by executing your code.</para>
+ <para>The "=" tells it to load the data by executing the custom code.</para>
</section>
</section>
<section>
<title>Templates of assets/rules</title>
-
- <para>Tip: As you may have many similar rules, you can create rule
- templates, which are simply rules which are kept in an inactive package
- - you can then categories templates accordingly, and copy them as needed
+<tip>
+ <para>As there may be similar rules, creation of rule
+ templates can be useful and store the rules in an inactive package.
+ Templates can be categorized accordingly, and copyed as needed
(choosing a live package as the target package).</para>
+</tip>
</section>
<section>
<title>Status management</title>
- <para>Each asset (and also package) in the BRMS has a status flag set.
- The values of the status flag are set in the Administration section of
- the BRMS. (you can add your own status names). Similar to Categories,
+ <para>Each asset (and also package) in the BRMS has a status flag set with
+ the values of the status flag being set in the Administration section. Similar to Categories.
Statuses do NOT effect the execution in any way, and are purely
- informational. Unlike categories, assets only have one status AT A
- TIME.</para>
+ informational. Unlike categories, assets only have one status at any one time.</para>
- <para>Using statuses is completely optional. You can use it to manage
- the lifecycle of assets (which you can alternatively do with categories
- if you like).</para>
+ <para>Using statuses is completely optional but can be used for such things as managing
+ the lifecycle of assets (which can also be achieved with categories).</para>
<figure>
<title>Asset status</title>
@@ -643,9 +642,8 @@
</mediaobject>
</figure>
- <para>You can change the status of an individual asset (like in the
- diagram above). Its change takes effect immediately, no separate save is
- needed.</para>
+ <para>The status of an individual asset can be changed without a seperate save, as in the
+ diagram above.</para>
<figure>
<title>Asset status</title>
@@ -658,26 +656,24 @@
</mediaobject>
</figure>
- <para>You can change the status of a whole package - this sets the
- status flag on the package itself, but it ALSO changes the statuses on
- ALL the assets that belong to this package in one hit (to be the same as
- what you set the package to).</para>
+ <para>The status of a whole package can be changed with its status flag, but it also changes the statuses on
+ all the assets that belong to this package at the same time.</para>
</section>
<section>
<title>Package management</title>
<para>Configuring packages is generally something that is done once, and
- by someone with some experience with rules/models. Generally speaking,
- very few people will need to configure packages, and once they are
+ by someone with some experience with rules or models.
+ Very few people should ever need to configure packages, and once they are
setup, they can be copied over and over if needed. Package configuration
- is most definitely a technical task that requires the appropriate
+ is a technical task that requires the appropriate
expertise.</para>
- <para>All assets live in "packages" in the BRMS - a package is like a
- folder (it also serves as a "namespace"). A home folder for rule assets
- to live in. Rules in particular need to know what the fact model is,
- what the namespace is etc.</para>
+ <para>All assets live in <emphasis>packages</emphasis> in the BRMS. A package is similar to a
+ folder (it also serves as a <emphasis>namespace</emphasis>). A home folder for rule assets
+ to live in. Rules in particular need to know what the fact model is and
+ what the namespace is amoungst other facts.</para>
<para><figure>
<title>The package explorer</title>
@@ -690,18 +686,17 @@
</mediaobject>
</figure>The above picture shows the package explorer. Clicking on an
asset type will show a list of matches (for packages with thousands of
- rules, showing the list may take several seconds - hence the importance
- of using categories to help you find your way around).</para>
+ rules, showing the list may take several seconds, demonstating the importance
+ of using categories for organisation).</para>
- <para>So whilst rules (and assets in general) can appear in any number
- of categories, they only live in one package. If you think of the BRMS
+ <para>Whilst rules (and assets in general) can appear in any number
+ of categories, they only live in one package. Think of the BRMS
as a file system, then each package is a folder, and the assets live in
- that folder - as one big happy list of files. When you create a
- deployment snapshot of a package, you are effectively copying all the
- assets in that "folder" into another special "folder".</para>
+ that folder. When a
+ deployment snapshot of a package is created, effectively what is occurring is that all the assest in that <emphasis>folder</emphasis> are being copyed into another special <emphasis>folder</emphasis>.</para>
- <para>The package management feature allows you to see a list of
- packages, and then "expand" them, to show lists of each "type" of asset
+ <para>The package management feature allows the user to view a list of
+ packages, and then <emphasis>expand</emphasis> them, to show lists of each <emphasis>type</emphasis> of asset
(there are many assets, so some of them are grouped together):</para>
<para>The asset types: <itemizedlist>
@@ -729,7 +724,7 @@
</listitem>
<listitem>
- <para>Model: A package requires at least one model - for the
+ <para>Model: A package requires at least one model, for the
rules.</para>
</listitem>
</itemizedlist></para>
@@ -743,11 +738,8 @@
format="PNG" scalefit="1" />
</imageobject>
</mediaobject>
- </figure> From the package explorer you can create new rules, or new
- assets. Some assets you can only create from the package explorer. The
- above picture shows the icons which launch wizards for this purpose. If
- you hover the mouse over them, a tooltip will tell you what they
- do.</para>
+ </figure> From the package explorer new rules and assets can be created. Some assets can only be created from the package explorer and the
+ above picture shows the icons which launch wizards for this purpose. Hovering the mouse over each icon will present a tooltip explaining what each does.</para>
<para><figure>
<title>Package configuration</title>
@@ -758,13 +750,10 @@
format="PNG" scalefit="1" />
</imageobject>
</mediaobject>
- </figure>One of the most critical things you need to do is configure
+ </figure>One of the most critical things to do is configure
packages. This is mostly importing the classes used by the rules, and
- globals variables. Once you make a change, you need to save it, and that
- package is then configured and ready to be built. For example, you may
- add a model which has a class called "com.something.Hello", you would
- then add "import com.something.Hello" in your package configuration and
- save the change.</para>
+ globals variables. Once a change is made, it needs to be saved and that
+ package is then configured and ready to be built. For example, adding a model which has a class called <classname>com.something.Hello</classname>, <emphasis>import com.something.Hello</emphasis> would then be added to the package configuration and the changes saved.</para>
<para><figure>
<title>Package building</title>
@@ -775,40 +764,40 @@
format="PNG" scalefit="1" />
</imageobject>
</mediaobject>
- </figure>Finally you would "build" a package. Any errors caught are
- then shown at this point. If the build was successful, then you will
- have the option to create a snapshot for deployment. You can also view
- the "drl" that this package results in. WARNING: in cases of large
- numbers of rules, all these operations can take some time.</para>
+ </figure>Finally the package would be built. Any errors caught are
+ then shown at this point. If the build was successful, an option to create a snapshot for deployment will be shown; the DRL the package results in can be viewed.</para>
+<note>
+<para>In circumstances with large numbers of rules, all these operations can take some time.</para>
+</note>
- <para>It is optional at this stage to enter the name of a "selector" -
+ <para>It is optional at this stage to enter the name of a <emphasis>selector</emphasis>;
see the admin section for details on how to configure custom selectors
- for your system (if you need them - selecters allow you to filter down
- what you build into a package - if you don't know what they are for, you
- probably don't need to use them).</para>
+ for the system. Selecters allow for filtration down through a package contents.</para>
<section>
- <title>Importing drl packages</title>
+ <title>Importing DRL packages</title>
<para>It is also possible to create a package by importing an existing
- "drl" file. When you choose to create a new package, you can choose an
- option to upload a .drl file. The BRMS will then attempt to understand
- that drl, break create a package for you. The rules in it will be
- stored as individual assets (but still as drl text content). Note that
- to actually build the package, you will need to upload an appropriate
- model (as a jar) to validate against, as a separate step.</para>
+ DRL file. When choosing to create a new package, you have an option to upload a <filename>.drl</filename> file. The BRMS will then attempt to understand
+ that drl and create a package. The rules in it will be
+ stored as individual assets (but still as drl text content).</para>
+<important>
+ <para>
+ In order to build the package, an appropriate model (as a .jar) will need to be uploaded to validate against, as a separate step.
+ </para>
+</important>
</section>
</section>
<section>
<title>Version management</title>
- <para>Both assets and whole packages of assets are "versioned" in the
+ <para>Both assets and whole packages of assets are <emphasis>versioned</emphasis> in the
BRMS, but the mechanism is slightly different. Individual assets are
saved a bit like a version of a file in a source control system.
- However, packages of assets are versioned "on demand" by taking a
- snapshot (typically which is used for deployment). The next section
- talks about deployment management and snapshots.</para>
+ However, packages of assets are versioned <emphasis>on demand</emphasis> by taking a
+ snapshot (typically used for deployment). The next section
+ talks about <link linkend="Deployment_Management">deployment management and snapshots</link>.</para>
<figure>
<title>Asset versions</title>
@@ -821,13 +810,12 @@
</mediaobject>
</figure>
- <para>Each time you make a change to an asset, it creates a new item in
- the version history. This is a bit like having an unlimited undo. You
- can look back through the history of an individual asset like the list
+ <para>Each time a change to an asset is made, it creates a new item in
+ the version history. This is a bit like having an unlimited undo. The history can be traversed for an individual asset like the list
above, and view it (and restore it) from that point in time.</para>
</section>
- <section>
+ <section id="Deployment_Management">
<title>Deployment management</title>
<para>Snapshots, URLS and binary packages:</para>
@@ -837,13 +825,13 @@
These URLs take the form of:
http://<server>/drools-jbrms/org.drools.brms.JBRMS/package/<packageName>/<packageVersion></para>
- <para><packageName> is the name you gave the package.
+ <para><packageName> is the custom name given to the package.
<packageVersion> is either the name of a snapshot, or "LATEST" (if
its LATEST, then it will be the latest built version from the main
- package, not a snapshot). You can use these in the agent, or you can
- paste them into your browser and it will download them as a file.</para>
+ package, not a snapshot). These can be used in the agent, or
+ pasted into a browser and it will download them as a file.</para>
- <para>Refer to the section on the Rule Agent for details on how you can
+<para>Refer to the section on the <link linkend="Chapter-BRMS-Section-UserGuide-The_Rule_Agent"> Rule Agent</link> for details on how you can
use these URLs (and binary downloads) in your application, and how rules
can be updated on the fly.</para>
@@ -858,10 +846,10 @@
</mediaobject>
</figure>
- <para>The above shows deployment snapshots view. On the left there is a
- list of packages. Clicking on a specific package will show you a list of
- snapshots for that package (if any). From there you can copy, remove or
- view an asset snapshot. Each snapshot is available for download or
+ <para>The above shows the deployment snapshots view. On the left there is a
+ list of packages. Clicking on a specific package will show a list of
+ snapshots for that package (if any). From there an asset snapshot can be copyed, removed or
+ viewed. Each snapshot is available for download or
access via a URL for deployment.</para>
</section>
@@ -872,8 +860,8 @@
user-driven Categorization (tagging) as outlined above, and the package
explorer view.</para>
- <para>The category view provides a way to navigate your rules in a way
- that makes sense to your organization.</para>
+ <para>The category view provides a way to navigate the rules in a way
+ that makes sense to the organization.</para>
<figure>
<title>Category view</title>
@@ -887,13 +875,13 @@
</figure>
<para>The above diagram shows categories in action. Generally under each
- category you should have no more then a few dozen rules, if
+ category there should be no more then a few dozen rules, if
possible.</para>
<para>The alternative and more technical view is to use the package
explorer. This shows the rules (assets) closer to how they are actually
stored in the database, and also separates rules into packages (name
- spaces) and their type (format, as rules can be in many different
+ spaces) and their type (as rules can be in many different
formats).</para>
<figure>
@@ -907,7 +895,7 @@
</mediaobject>
</figure>
- <para>The above shows the alternate way of exploring - using
+ <para>The above shows the alternate way of exploring: using
packages.</para>
</section>
</section>
@@ -915,82 +903,74 @@
<section>
<title>The business user perspective</title>
- <para>You can see from this manual, that some expertise and practice is
- required to use the BRMS. In fact any software system in some sense
- requires that people be "technical" even if it has a nice looking GUI.
- Having said that, in the right hands the BRMS can be setup to provide a
+ <para>Some expertise and practice is
+ required to use the BRMS, however once setup it can be configured to provide a
suitable environment for non technical users.</para>
<para>The most appropriate rule formats for this use are using the Guided
- editor, Decision tables and DSL rules. You can use some DSL expressions
- also in the guided editor (so it provides "forms" for people to enter
- values).</para>
+ editor, Decision tables and DSL rules. DSL expressions
+ can also be used in the guided editor to provide an easy <emphasis>form</emphasis> interface for users.</para>
- <para>You can use categories to isolate rules and assets from non
- technical users. Only assets which have a category assigned will appear in
- the "rules" feature.</para>
+ <para>Categories can be used to isolate rules and assets from non-technical users. Only assets which have a category assigned will appear in
+ the <emphasis>rules</emphasis> feature.</para>
<para>The initial setup of the BRMS will need to be done by a
developer/technical person who will set the foundations for all the rules.
- They may also create "templates" which are rules which may be copied (they
- would typically live in a "dummy" package, and have a category of
- "template" - this can also help ease the way).</para>
+ They may also create <emphasis>templates</emphasis> which are rules which may be copied (they
+ would typically live in a <emphasis>dummy</emphasis> package, and have a category of
+ <emphasis>template</emphasis>, this can also help ease the way).</para>
- <para>Deployment should also not be done by non technical users (as
- mentioned previously this happens from the "Package" feature).</para>
+ <para>Deployment should not be done by non-technical users (as
+ mentioned previously this happens from the <emphasis>Package</emphasis> feature).</para>
</section>
<section>
- <title>Deployment: Integrating rules with your applications</title>
+ <title>Deployment: Integrating rules with the applications</title>
- <para>Its all very interesting to manage rules, but how to you use or
- "consume" them in your application? This section covers the usage of the
- RuleAgent deployment component that automates most of this for you.</para>
+ <para>This section covers the usage of the
+ RuleAgent deployment component that automates the interweaving of rules into an application.</para>
<section id="Chapter-BRMS-Section-UserGuide-The_Rule_Agent">
<title>The Rule Agent</title>
<para>The rule agent is a component which is embedded in the core
- runtime of the rules engine. To use this, you don't need any extra
- components. In fact, if you are using the BRMS, your application should
+ runtime of the rules engine. To use this, no extra components are necessary and if the BRMS is in use, the application should
only need to include the drools-core dependencies in its classpath
(drools and mvel jars only), and no other rules specific
dependencies.</para>
- <para>Note that there is also a drools-ant ant task, so you can build
- rules as part of an ant script (for example in cases where the rules are
- edited in the IDE) without using the BRMS at all - the drools-ant task
+ <para>Note that there is also a drools-ant task, so ruels can be built as part of an ant script (for example, in cases where the rules are
+ edited in the IDE) without using the BRMS at all. The drools-ant task
will generate .pkg files the same as the BRMS.</para>
- <para>Once you have "built" your rules in a package in the BRMS (or from
- the ant task), you are ready to use the agent in your target
- application.</para>
+ <para>Once the rules have been built in a package in the BRMS (or from
+ the ant task), instigating the agent in your target
+ application is the next step.</para>
<para>To use the rule agent, you will use a call in your applications
- code like:</para>
+ code similar to:</para>
- <programlisting>RuleAgent agent = RuleAgent.newRuleAgent("/MyRules.properties");
+<screen>RuleAgent agent = RuleAgent.newRuleAgent("/MyRules.properties");
RuleBase rb = agent.getRuleBase();
rb.newStatefulSession....
//now assert your facts into the session and away you go !
-</programlisting>
+</screen>
- <para>IMPORTANT: You should only have one instance of the RuleAgent per
- rulebase you are using. This means you should (for example) keep the
- agent in a singleton, JNDI (or similar). In practice most people are
- using frameworks like Seam or Spring - in which case they will take care
- of managing this for you (in fact in Seam - it is already integrated -
- you can inject rulebases into Seam components). Note that the RuleBase
- can be used multiple times by multiple threads if needed (no need to
- have multiple copies of it).</para>
+<important>
+ <para>There should only be one instance of the RuleAgent per
+ rulebase you are using. This means (for example) the agent should be kept in a singleton, JNDI (or similar). In practice most people are
+ using frameworks like Seam or Spring, in which case these programs will look after the management of this (in fact in Seamit is already integrated). Further, the RuleBase
+ can be used multiple times by multiple threads if needed (forgoing the need for multiple copies).</para>
+</important>
<para>This assumes that there is a MyRules.properties in the root of
- your classpath. You can also pass in a Properties object with the
+ the classpath. A Properties object can also be passed in with the
parameters set up (the parameters are discussed next).</para>
- <para>The following shows the content of MyRules.properties:</para>
+ <para>The following shows the content of <filename>MyRules.properties</filename>:</para>
- <programlisting>##
+<screen>
+##
## RuleAgent configuration file example
##
@@ -1002,27 +982,26 @@
poll=30
-name=MyConfig</programlisting>
+name=MyConfig
+</screen>
- <para>You can only have one type of key in each configuration (eg only
- one "file", "dir" etc - even though you can specify multiple items by
- space separating them). Note also, instead of a discrete properties
- file, you can construct a java.utils.Properties object, and pass it in
+ <para>There can only be one type of key in each configuration (for example, only
+ one "file", "dir" even though multiple items can be specified by separating them with a space). Further, instead of a discrete properties
+ file, a java.utils.Properties object can be constructed, and passed in
to the RuleBase methods.</para>
- <para>Referring to the above example, the "keys" in the properties
+ <para>Referring to the above example, the <emphasis>keys</emphasis> in the properties
are:</para>
<itemizedlist>
<listitem>
<para>newInstance</para>
- <para>Setting this to "true" means that the RuleBase instance will
- be created fresh each time there is a change. this means you need to
- do agent.getRuleBase() to get the new updated rulebase (any existing
+ <para>Setting this to true means that the RuleBase instance will
+ be created fresh each time there is a change. Meaning <methodname>agent.getRuleBase()</methodname> needs to be executed in order to get the new updated rulebase (any existing
ones in use will be untouched). The default is false, which means
- rulebases are updated "in place" - ie you don't need to keep calling
- getRuleBase() to make sure you have the latest rules (also any
+ rulebases are updated "in place"; for instance
+ <methodname>getRuleBase()</methodname> does not need to be continually called to make sure the latest rules are in use (also any
StatefulSessions will be updated automatically with rule
changes).</para>
</listitem>
@@ -1030,34 +1009,37 @@
<listitem>
<para>file</para>
- <para>This is a space-separated list of files - each file is a
- binary package as exported by the BRMS. You can have one or many.
- The name of the file is not important. Each package must be in its
+ <para>This is a space-separated list of files where each file is a
+ binary package as exported by the BRMS. There can be one or many with
+ the name of the file is not important. Each package must be in its
own file.</para>
- <para>NOTE: it is also possible to specify .drl files - and it will
- compile it into the package. However, note that for this to work,
- you will need the drools-compiler dependencies in your applications
+ <note>
+ <para>It is also possible to specify .drl files and it will
+ compile it into the package. However, for this to work
+ the drools-compiler dependencies will be needed in the applications
classpath (as opposed to just the runtime dependencies).</para>
- <para>Please note that if the path has a space in it, you will need
- to put double quotes around it (as the space is used to separate
+ <para>If the path has a space in it, there will need
+ to be double quotes around it (as the space is used to separate
different items, and it will not work otherwise). Generally spaces
in a path name are best to avoid.</para>
+</note>
</listitem>
<listitem>
<para>dir</para>
<para>This is similar to file, except that instead of specifying a
- list of files you specify a directory, and it will pick up all the
+ list of files a directory is specified and it will pick up all the
files in there (each one is a package) and add them to the rulebase.
Each package must be in its own file.</para>
-
- <para>Please note that if the path has a space in it, you will need
- to put double quotes around it (as the space is used to separate
- different items, and it will not work otherwise). Generally spaces
- in a path name are best to avoid.</para>
+<note>
+ <para>If the path has a space in it, there will need
+ to be double quotes around it (as the space is used to separate
+ different items, and it will not work otherwise). Generally spaces
+ in a path name are best to avoid.</para>
+</note>
</listitem>
<listitem>
@@ -1072,7 +1054,7 @@
<para>This is used in conjunction with the url above, so that if the
BRMS is down (the url is not accessible) then if the runtime has to
- start up, it can start up with the last known "good" versions of the
+ start up, it can start up with the last known working versions of the
packages.</para>
</listitem>
@@ -1106,37 +1088,31 @@
</mediaobject>
</figure>
- <para>You can see the "Package URI" - this is the URL that you would
- copy and paste into the agent .properties file to specify that you want
- this package. It specifies an exact version (in this case to a snapshot)
- - each snapshot has its own URL. If you want the "latest" - then replace
- "NewSnapshot" with "LATEST".</para>
+ <para>The <emphasis>Package URI</emphasis> is the URL that would be
+ copy and pasted into the agents <filename>.properties</filename> file to specify that the package is wanted. It specifies an exact version. In this case to a snapshot, with each snapshot having its own URL. If you want the latest, then replace
+ <emphasis>NewSnapshot</emphasis> with <emphasis>LATEST</emphasis>.</para>
- <para>You can also download a .pkg file from here, which you can drop in
+ <para>A .pkg file can also be downloaded from here, which can be droped in
a directory and use the "file" or "dir" feature of the RuleAgent if
- needed (in some cases people will not want to have the runtime
- automatically contact the BRMS for updates - but that is generally the
- easiest way for many people).</para>
+ needed (in some cases it may not be viable to have the runtime
+ automatically contact the BRMS for updates, but that is generally the
+ easiest).</para>
</section>
<section>
<title>Manual deployment</title>
<para>This section is only needed for advanced users who are integrating
- deployment into their own mechanism. Normally you should use the rule
- agent.</para>
+ deployment into their own mechanism. In normal circumstances the rule agent should be used.</para>
<para>For those who do not wish to use the automatic deployment of the
- RuleAgent, "rolling your own" is quite simple. The binary packages
- emitted by the BRMS are serialized Package objects. You can deserialize
- them and add them into any rulebase - essentially that is all you need
- to do.</para>
+ RuleAgent, the rules can be deployed independant of this. The binary packages
+ emitted by the BRMS are serialized Package objects, which means they can be deserialized
+ and add into any rulebase.</para>
<para>From the BRMS, binary packages are provided either from the latest
- version of a package (once you have successfully validated and built a
- package) or from the deployment snapshots. The URLs that the BRMS web
- application exposes provide the binary package via http. You can also
- issue a "HEAD" command to get the last time a package was
+ version of a package (once successfully validated and the package built) or from the deployment snapshots. The URLs that the BRMS web
+ application exposes provide the binary package via http. The <emphasis>HEAD</emphasis> command can also be issued to get the last time a package was
updated.</para>
</section>
</section>
More information about the jboss-svn-commits
mailing list