[jboss-svn-commits] JBL Code SVN: r28980 - in labs/jbossrules/trunk/drools-docs: drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start and 1 other directories.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Wed Aug 19 01:58:17 EDT 2009
Author: michael.neale at jboss.com
Date: 2009-08-19 01:58:17 -0400 (Wed, 19 Aug 2009)
New Revision: 28980
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Deployment/Section-Deployment.xml
labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Section-More_On_Building_And_Deploying.xml
labs/jbossrules/trunk/drools-docs/drools-docs-guvnor/src/main/docbook/en-US/Chapter-Guvnor/Section-UserGuide.xml
Log:
Documentation updates... for knowledge agent
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Deployment/Section-Deployment.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Deployment/Section-Deployment.xml 2009-08-19 05:35:03 UTC (rev 28979)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Deployment/Section-Deployment.xml 2009-08-19 05:58:17 UTC (rev 28980)
@@ -1,11 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
-<section version="5.0" xmlns="http://docbook.org/ns/docbook"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xmlns:xi="http://www.w3.org/2001/XInclude"
- xmlns:svg="http://www.w3.org/2000/svg"
- xmlns:m="http://www.w3.org/1998/Math/MathML"
- xmlns:html="http://www.w3.org/1999/xhtml"
- xmlns:db="http://docbook.org/ns/docbook" xml:base="../../">
+<section version="5.0" xml:base="../../" xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns:m="http://www.w3.org/1998/Math/MathML"
+ xmlns:html="http://www.w3.org/1999/xhtml"
+ xmlns:db="http://docbook.org/ns/docbook">
<title>Deployment options</title>
<para>Once you have rules integrated in your application (or ideally before)
@@ -17,9 +17,10 @@
<para>The recommended way of deploying depends on how you are managing your
rules. If you are using the BRMS, you should use the RuleAgent (the detailed
- documentation for this is in the chapter on the BRMS). You can still use the
- RuleAgent even without the BRMS, in which case you will need to use ant (the drools-ant task or
- something custom) to create serialized "Package" objects of your rules.</para>
+ documentation for this is in the chapter on the BRMS/Guvnor). You can still
+ use the RuleAgent even without the BRMS, in which case you will need to use
+ ant (the drools-ant task or something custom) to create serialized "Package"
+ objects of your rules.</para>
<para>As every organization is subtly different, and different deployment
patterns will be needed. Many organizations have (or should have)
@@ -33,52 +34,10 @@
should be able to deploy either as the agent, or in the classpath.</para>
<section>
- <title>Deployment using the RuleAgent</title>
+ <title>Deployment using the KnowledgeAgent</title>
<para>The easiest and most automated way to deploy rules is to use the
- RuleAgent. This is described in detail in the BRMS user guide. In short,
- the rule agent requires that you build binary packages of rules outside of
- "your" application (ie the application that is using rules).</para>
-
- <para>The upside of this is that your application only needs to include
- drools-core.jar - no other dependencies (of course you need the classes
- that form the model that the rules use as well !). It also means the agent
- can be configured to automatically monitor for rule changes - directly to
- the BRMS, or from a file/directory.</para>
-
- <para>To use the rule agent in your application use the following
- code:</para>
-
- <programlisting>RuleAgent agent = RuleAgent.newRuleAgent("/MyRules.properties");
-RuleBase rb = agent.getRuleBase();
-rb.newStatefulSession....
-//now assert your facts into the session and away you go !
-</programlisting>
-
- <para>The MyRules.properties is a configuration file which (in the above
- case) should be on the root of your classpath:</para>
-
- <programlisting>##
-## RuleAgent configuration file example
-##
-
-
-
-dir=/my/dir
-url=http://some.url/here http://some.url/here
-localCacheDir=/foo/bar/cache
-poll=30
-
-
-name=MyConfig</programlisting>
-
- <para>In the above config, the agent will look for binary package files in
- /my/dir, and also at the specified URLs. It will pick up any changes for
- these packages and apply them to the rulebase.</para>
-
- <para>If you are using the BRMS, you can use the url feature. You can use
- "file" or "dir" if the packages need to be manually migrated to your
- production servers.</para>
+ Knowlegde Agent as described in the quick start guide. This can access rules from the file system, classpath, web server, the Guvnor server (which is really a web server) and more. Rules can be in DRL, XLS, compiled binary form and more.</para>
</section>
<section>
@@ -293,5 +252,4 @@
<para>A future release of Drools will contain a rule repository (server)
component that will directly support the above patterns, and more.</para>
</section>
-
</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Section-More_On_Building_And_Deploying.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Section-More_On_Building_And_Deploying.xml 2009-08-19 05:35:03 UTC (rev 28979)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Quick_Start/Section-More_On_Building_And_Deploying.xml 2009-08-19 05:58:17 UTC (rev 28980)
@@ -103,7 +103,14 @@
change set, the entire contents of that directory will be scanned for
changes.</para>
- <para>A not on remote HTTP Url Resources: if your knowledge agent is
+ <para>For polling to occur, the polling and notifier services must be started:
+<programlisting>ResourceFactory.getResourceChangeNotifierService().start();
+ResourceFactory.getResourceChangeScannerService().start();</programlisting>
+ </para>
+
+ <section>
+ <title>Remote HTTP resource caching</title>
+ <para>A note on remote HTTP Url Resources: if your knowledge agent is
"pulling" resources from a http(s) URL, then you might rightly be
concerned if that resource (remote web server) suddenly disappears. To
survive a restart when a resource is no longer available remotely (eg the
@@ -118,5 +125,7 @@
agent to use should it be restarted (when a remote resource becomes
available, and is updated, it will automatically update the local cache
copy). </para>
+
+ </section>
</section>
</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-guvnor/src/main/docbook/en-US/Chapter-Guvnor/Section-UserGuide.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-guvnor/src/main/docbook/en-US/Chapter-Guvnor/Section-UserGuide.xml 2009-08-19 05:35:03 UTC (rev 28979)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-guvnor/src/main/docbook/en-US/Chapter-Guvnor/Section-UserGuide.xml 2009-08-19 05:58:17 UTC (rev 28980)
@@ -771,10 +771,11 @@
altogether, just use "when" and "then" to mark the condition and
action sections respectively). Normally you would use the IDE to edit
raw DRL files, since it has all the advanced tooling and content
- assistance and debugging. However, there are times when a rule may have
- to deal with something fairly technical in a package in Guvnor. In any typical package of
- rules, you generally have a need for some "technical rules" - you can
- mix and match all the rule types together of course.</para>
+ assistance and debugging. However, there are times when a rule may
+ have to deal with something fairly technical in a package in Guvnor.
+ In any typical package of rules, you generally have a need for some
+ "technical rules" - you can mix and match all the rule types together
+ of course.</para>
<figure>
<title>DRL technical rule</title>
@@ -1172,8 +1173,8 @@
<para>Snapshots, URLS and binary packages:</para>
<para>URLs are central to how built packages are provided. The BRMS
- provides packages via URLs (for download and use by the Knowledge Agent).
- These URLs take the form of:
+ provides packages via URLs (for download and use by the Knowledge
+ Agent). These URLs take the form of:
http://<server>/drools-guvnor/org.drools.guvnor.Guvnor/package/<packageName>/<packageVersion></para>
<para><packageName> is the name you gave the package.
@@ -1182,9 +1183,9 @@
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>
- <para>Refer to the section on the Knowledge Agent 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>
+ <para>Refer to the section on the Knowledge Agent 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>
<figure>
<title>Deployment snapshots</title>
@@ -1397,17 +1398,17 @@
<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
- KnowledgeAgent deployment component that automates most of this for you.</para>
+ KnowledgeAgent deployment component that automates most of this for
+ you.</para>
<section>
<title>The Knowledge Agent</title>
- <para>The knowledge agent is a component which is embedded in the Drools API.
- To use this, you don't need any extra
- components. In fact, if you are using Guvnor, your application should
- only need to include the drools-api and drools-core dependencies in its classpath
- (drools and mvel jars only), and no other rules specific
- dependencies.</para>
+ <para>The knowledge agent is a component which is embedded in the Drools
+ API. To use this, you don't need any extra components. In fact, if you
+ are using Guvnor, your application should only need to include the
+ drools-api and 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
@@ -1418,7 +1419,12 @@
the ant task), you are ready to use the agent in your target
application.</para>
-<para>The Following example constructs an agent that will build a new KnowledgeBase from the files specified in the path String. It will poll those files every 60 seconds, which is the default, to see if they are updated. If new files are found it will construct a new KnowledgeBase. If the change set specifies a resource that is a directory it's contents will be scanned for changes too.</para>
+ <para>The Following example constructs an agent that will build a new
+ KnowledgeBase from the files specified in the path String. It will poll
+ those files every 60 seconds, which is the default, to see if they are
+ updated. If new files are found it will construct a new KnowledgeBase.
+ If the change set specifies a resource that is a directory it's contents
+ will be scanned for changes too.</para>
<programlisting>
KnowledgeAgent kagent = KnowledgeAgentFactory.newKnowledgeAgent( "MyAgent" );
@@ -1426,9 +1432,12 @@
KnowledgeBase kbase = kagent.getKnowledgeBase();
</programlisting>
-<para>The KnowledgeAgent can accept a configuration that allows for some of the defaults to be changed. An example property is "drools.agent.scanDirectories", by default any specified directories are scanned for new additions, it is possible to disable this.</para>
+ <para>The KnowledgeAgent can accept a configuration that allows for some
+ of the defaults to be changed. An example property is
+ "drools.agent.scanDirectories", by default any specified directories are
+ scanned for new additions, it is possible to disable this.</para>
- <programlisting>KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
+ <programlisting>KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
KnowledgeAgentConfiguration kaconf = KnowledgeAgentFactory.newKnowledgeAgentConfiguration();
kaconf.setProperty( "drools.agent.scanDirectories",
@@ -1437,21 +1446,22 @@
KnowledgeAgent kagent = KnowledgeAgentFactory.newKnowledgeAgent( "test agent", // the name of the agent
kaconf );
kagent.applyChangeSet( ResourceFactory.newUrlResource( url ) ); // resource to the change-set xml for the resources to add</programlisting>
-
- <para>An example of the change-set.xml.</para>
+ <para>An example of the change-set.xml.</para>
- <programlisting><![CDATA[<change-set xmlns='http://drools.org/drools-5.0/change-set'";
+ <programlisting><change-set xmlns='http://drools.org/drools-5.0/change-set'";
xmlns:xs='http://www.w3.org/2001/XMLSchema-instance'
- xs:schemaLocation='http://drools.org/drools-5.0/change-set drools-change-set-5.0.xsd' >
- <add>
- <resource source='http://localhost:9000/TEST.pkg' type='PKG' />
- </add>
-</change-set>]]></programlisting>
+ xs:schemaLocation='http://drools.org/drools-5.0/change-set drools-change-set-5.0.xsd' >
+ <add>
+ <resource source='http://localhost:9000/TEST.pkg' type='PKG' />
+ </add>
+</change-set></programlisting>
- <para>Resource scanning is not on by default, it's a service and must be started, the same is for notification. This can be done via the ResourceFactory.</para>
+ <para>Resource scanning is not on by default, it's a service and must be
+ started, the same is for notification. This can be done via the
+ ResourceFactory.</para>
- <programlisting>ResourceFactory.getResourceChangeNotifierService().start();
+ <programlisting>ResourceFactory.getResourceChangeNotifierService().start();
ResourceFactory.getResourceChangeScannerService().start();</programlisting>
<para>Following shows the deployment screen of Guvnor, which provides
@@ -1485,9 +1495,11 @@
<section>
<title>Drools execution server</title>
- <para>
- IMPORTANT NOTE: the exact message formats described here are likely to slightly change post drools 5 (as support for processes and stateful sessions is added). The following will be preserved for compatability, but may be deprecated in favour of more flexible formats that are in the pipelines.
- </para>
+ <para>IMPORTANT NOTE: the exact message formats described here are
+ likely change post drools 5 (as support for processes and stateful
+ sessions is added). The following will be preserved for compatability,
+ but may be deprecated in favour of more flexible formats that are in the
+ pipelines (ie consider the following to be DEPRECATED).</para>
<para>The drools execution server (drools-server) module is a war which
you can deploy to execute knowledgebases (rulebases) remotely for any
@@ -1527,8 +1539,8 @@
<para>To configure a "knowledgebase" - you create a properties file
with a knowledge agent configuration in it (see the section above for
- details on the options in the knowledge agent configuration). The name of
- this properties file will be the name in the URL that you use to
+ details on the options in the knowledge agent configuration). The name
+ of this properties file will be the name in the URL that you use to
access this servive. So lets take the example of
teamallocation.properties: an agent configuration for a service that
will allocated some piece of work to a team. teamallocation.properties
@@ -1715,14 +1727,14 @@
<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 knowledge
- agent.</para>
+ deployment into their own mechanism. Normally you should use the
+ knowledge agent.</para>
<para>For those who do not wish to use the automatic deployment of the
KnowledgeAgent, "rolling your own" is quite simple. The binary packages
emitted by Guvnor are serialized Package objects. You can deserialize
- them and add them into any knowledgebase - essentially that is all you need
- to do.</para>
+ them and add them into any knowledgebase - essentially that is all you
+ need to do.</para>
<para>From Guvnor, binary packages are provided either from the latest
version of a package (once you have successfully validated and built a
More information about the jboss-svn-commits
mailing list