[jboss-svn-commits] JBL Code SVN: r34487 - in labs/jbossesb/trunk/product/docs/Services_Guide/en-US: extras/rule_service and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Tue Aug 3 14:05:07 EDT 2010
Author: dward
Date: 2010-08-03 14:05:07 -0400 (Tue, 03 Aug 2010)
New Revision: 34487
Added:
labs/jbossesb/trunk/product/docs/Services_Guide/en-US/extras/rule_service/channels.xmlt
labs/jbossesb/trunk/product/docs/Services_Guide/en-US/extras/rule_service/channels1.xmlt
labs/jbossesb/trunk/product/docs/Services_Guide/en-US/extras/rule_service/channels2.xmlt
labs/jbossesb/trunk/product/docs/Services_Guide/en-US/extras/rule_service/drl3.xmlt
Modified:
labs/jbossesb/trunk/product/docs/Services_Guide/en-US/Content_Based_Routing_Using_Drools.xml
labs/jbossesb/trunk/product/docs/Services_Guide/en-US/Rule_Services_Using_Drools.xml
labs/jbossesb/trunk/product/docs/Services_Guide/en-US/What_is_a_Rule_Service.xml
Log:
Added documentation per JBESB-3408 ( https://jira.jboss.org/browse/JBESB-3408 ).
Modified: labs/jbossesb/trunk/product/docs/Services_Guide/en-US/Content_Based_Routing_Using_Drools.xml
===================================================================
--- labs/jbossesb/trunk/product/docs/Services_Guide/en-US/Content_Based_Routing_Using_Drools.xml 2010-08-03 18:04:02 UTC (rev 34486)
+++ labs/jbossesb/trunk/product/docs/Services_Guide/en-US/Content_Based_Routing_Using_Drools.xml 2010-08-03 18:05:07 UTC (rev 34487)
@@ -6,7 +6,7 @@
]>
<section>
- <title>Content-Based Routing Using JBoss Rules</title>
+ <title>Content-Based Routing Using Drools</title>
<section>
@@ -16,7 +16,7 @@
<para>
The Content Based Router (CBR) in the JBossESB uses
- JBossRules/Drools as its default rule provider engine. JBossESB
+ Drools as its default rule provider engine. JBossESB
integrates with Drools through three different routing action
classes,
</para>
@@ -127,8 +127,8 @@
</title>
<para>
- A rule set can be created using the JBossIDE or Red Hat
- Developer Studio which includes a plug-in for JBossRules.
+ A rule set can be created using the JBoss
+ Developer Studio which includes a plug-in for Drools.
Below is a screen shot of the plug-in. For a detailed
discussion on rule creation and the Drools language itself
please see the Drools documention. To turn a regular ruleSet
@@ -361,7 +361,7 @@
<tbody>
<row>
- <entry>ruleSet</entry>
+ <entry><property>ruleSet</property></entry>
<entry>
Name of the filename containing the Drools ruleSet. The
set of rules that is used to evaluate the content. Only
@@ -370,7 +370,7 @@
</row>
<row>
- <entry>ruleLanguage</entry>
+ <entry><property>ruleLanguage</property></entry>
<entry>
Optional reference to a file containing the definition
of a Domain Specific Language to be used for evaluating
@@ -379,19 +379,19 @@
</row>
<row>
- <entry>ruleAgentProperties</entry>
+ <entry><property>ruleAgentProperties</property></entry>
<entry>
This property points to a rule agent properties file
located on the classpath. The properties file can
contain a property that points to precompiled rules
packages on the file system, in a directory, or
identified by an URL for integration with the BRMS. See
- the “RuleAgent” section below for more information.
+ the “KnowledgeAgent” section below for more information.
</entry>
</row>
<row>
- <entry>ruleReload</entry>
+ <entry><property>ruleReload</property></entry>
<entry>
Optional property which can be to true to enable 'hot'
redeployment of rule sets. Note that this feature will
@@ -402,7 +402,7 @@
</row>
<row>
- <entry>stateful</entry>
+ <entry><property>stateful</property></entry>
<entry>
Optional property which tells the RuleService to use a
stateful session where facts will be remembered between
@@ -412,7 +412,7 @@
</row>
<row>
- <entry>destinations</entry>
+ <entry><property>destinations</property></entry>
<entry>
A set of route-to properties each containing the
logical name of the destination along with the Service
@@ -423,12 +423,39 @@
</row>
<row>
- <entry>object-paths</entry>
+ <entry><property>object-paths</property></entry>
<entry>
Optional property to pass Message objects into Drools
WorkingMemory.
</entry>
</row>
+
+ <row>
+ <entry><property>ruleAuditType</property></entry>
+ <entry>Optional property to have Drools perform audit
+ logging. The log can be read into the Drools Eclipse
+ plugin and inspected. Valid values are CONSOLE, FILE and
+ THREADED_FILE. The default is that no audit logging will
+ be performed.</entry>
+ </row>
+
+ <row>
+ <entry><property>ruleAuditFile</property></entry>
+ <entry>Optional property to define the filepath for audit
+ logging. Only applies to FILE or THREADED_FILE
+ ruleAuditType. The default is "event". Note that JBoss
+ Drools will append ".log" for you. The default location
+ for this file is "." - the current working directory
+ (which for JBoss is in its bin/ directory).</entry>
+ </row>
+
+ <row>
+ <entry><property>ruleAuditInterval</property></entry>
+ <entry>Optional property to define how often to flush audit
+ events to the audit log. Only applies to the THREADED_FILE
+ ruleAuditType. The default is 1000 (milliseconds).</entry>
+ </row>
+
</tbody>
</tgroup>
</table>
@@ -610,16 +637,16 @@
<section>
<title>
- RuleAgent
+ KnowledgeAgent
</title>
<para>
- By using the rule agent property you can use precompiled rules
+ By using the ruleAgentProperty property, you can use precompiled rules
packages that can be located on the local file system, in a
local directory, or point to an URL. For information about the
configuration options that exist for the properties file please
- refer to The Rule Agent section of the Drools manual.
+ refer to the KnowledgeAgent section of the Drools manual.
</para>
<note>
@@ -640,16 +667,16 @@
<section>
<title>
- RuleAgent and Business Rule Management System
+ KnowledgeAgent and Business Rule Management System
</title>
<para>
- By using the rule agent property you can effectively integrate
+ By using the ruleAgentProperties property, you can effectively integrate
your service with a Business Rule Management System (BRMS).
This can be accomplished by specifying a URL in the rule agent
properties file. For information about the how to configure the
- URL and the other properties please refer to section 9.4.4.1.
- The Rule Agent of the Drools manual.
+ URL and the other properties please refer to the KnowledgeAgent
+ section of the Drools manual.
</para>
<note>
@@ -662,7 +689,7 @@
<note>
<para>
For information about the how to install and configure the BRMS
- please refer to the chapter Chapter 9 of the Drools manual.
+ please refer to the Drools manual.
</para>
</note>
Modified: labs/jbossesb/trunk/product/docs/Services_Guide/en-US/Rule_Services_Using_Drools.xml
===================================================================
--- labs/jbossesb/trunk/product/docs/Services_Guide/en-US/Rule_Services_Using_Drools.xml 2010-08-03 18:04:02 UTC (rev 34486)
+++ labs/jbossesb/trunk/product/docs/Services_Guide/en-US/Rule_Services_Using_Drools.xml 2010-08-03 18:05:07 UTC (rev 34487)
@@ -17,7 +17,7 @@
</title>
<para>
- The Rule Service support in the JBossESB uses JBossRules/Drools
+ The Rule Service support in the JBossESB uses Drools
as its rule engine. JBossESB integrates with Drools through
</para>
@@ -60,8 +60,8 @@
<para>
- A rule set can be created using the Red Hat Developer Studio which
- includes a plug-in for JBoss Drools, or with Eclispe 3.3 and the
+ A rule set can be created using the JBoss Developer Studio which
+ includes a plug-in for Drools, or with Eclispe 3.5 and the
plugin installed (see Drools download site for the plugin). Since
the message is added as a global, you need to add
jbossesb-rosetta.jar to your Drools project.
@@ -94,7 +94,7 @@
<listitem>
<para>
All rules deployed as a rule service must define the
- ESBMessage as a global, i.e.,
+ ESB Message as a global, i.e.,
</para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/rule_service/declareglobals.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -118,13 +118,6 @@
globals (other than the ESB Message) need to be set, they
can be done in higher salience rule. E.g.,
</para>
-
- <para>
- Note that the <classname>BusinessRulesProcessor</classname> and
- <classname>DroolsRuleService</classname> do not currently provide any means
- to set globals in the <filename>jboss-esb.xml</filename> file.
- However, this functionality may be added in the future.
- </para>
<programlisting language="Java" role="JAVA"><xi:include href="extras/rule_service/declareglobalssalience.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
@@ -337,6 +330,41 @@
<programlisting language="XML" role="XML"><xi:include href="extras/rule_service/drl2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
</listitem>
+<listitem>
+
+<para>
+ Rules are in a drl, execution is stateful, audit logging is enabled,
+ and the Drools clockType, eventProcessingType and channels are set
+ to aid in Complex Event Processing (CEP).
+ </para>
+
+ <para>
+ In this scenario, a service may want to perform Drools audit logging
+ so that the Drools Eclipse editor can parse the audit file for
+ debugging. It also wants to specify a specific clock type or event
+ processing type for CEP. Last it wants to specify Drools “Channels”
+ to send Objects to (“Channels” used to be known as “ExitPoints”).
+ </para>
+
+
+<note>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ A CEP scenario is a stateful scenario, and thus
+ is shared across all concurrent executions of a
+ Stateful Session deployment, just like in the
+ Example above.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+</note>
+
+<programlisting language="XML" role="XML"><xi:include href="extras/rule_service/drl3.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
+</listitem>
<listitem>
<para>
@@ -405,7 +433,7 @@
<segtitle>Description</segtitle>
<seglistitem>
- <seg><systemitem>ruleSet</systemitem></seg>
+ <seg><property>ruleSet</property></seg>
<seg>Optional reference to a file containing the Drools
ruleSet. The set of rules that is used to evaluate the
@@ -415,7 +443,7 @@
</seglistitem>
<seglistitem>
- <seg><systemitem>ruleLanguage</systemitem></seg>
+ <seg><property>ruleLanguage</property></seg>
<seg>Optional reference to a file containing the definition
of a Domain Specific Language to be used for evaluating the
@@ -425,7 +453,7 @@
</seglistitem>
<seglistitem>
- <seg><systemitem>ruleReload</systemitem></seg>
+ <seg><property>ruleReload</property></seg>
<seg>Optional property which can be to true to enable 'hot'
redeployment of rule sets. Note that this feature will
@@ -436,7 +464,7 @@
</seglistitem>
<seglistitem>
- <seg><systemitem>decisionTable</systemitem></seg>
+ <seg><property>decisionTable</property></seg>
<seg>This is an optional reference to a file containing the
definition of a rule-specification spreadsheet. </seg>
@@ -444,13 +472,13 @@
</seglistitem>
<seglistitem>
- <seg><systemitem>ruleAgentProperties</systemitem></seg>
+ <seg><property>ruleAgentProperties</property></seg>
<seg>Optional reference to a properties file containing the
location (URL or file path) to the compiled rule
package(s). Note there is no need to specify ruleReload
- with a ruleAgent, since this is controlled through the
- properties file.</seg>
+ with a KnowledgeAgent, since this is controlled through the
+ Drools resource scanning/notification system.</seg>
</seglistitem>
<seglistitem>
@@ -472,6 +500,76 @@
WorkingMemory.</seg>
</seglistitem>
+ <seglistitem>
+
+ <seg><property>ruleFireMethod</property></seg>
+
+ <seg>Optional property to define the stateful rule execution
+ method. Valid values are FIRE_ALL_RULES (the default) and
+ FIRE_UNTIL_HALT (which will kick off it's own Thread -
+ useful for Complex Event Processing "CEP")</seg>
+
+ </seglistitem>
+ <seglistitem>
+
+ <seg><property>ruleAuditType</property></seg>
+
+ <seg>Optional property to have Drools perform audit
+ logging. The log can be read into the Drools Eclipse
+ plugin and inspected. Valid values are CONSOLE, FILE and
+ THREADED_FILE. The default is that no audit logging will
+ be performed.</seg>
+
+ </seglistitem>
+ <seglistitem>
+
+ <seg><property>ruleAuditFile</property></seg>
+
+ <seg>Optional property to define the filepath for audit
+ logging. Only applies to FILE or THREADED_FILE
+ ruleAuditType. The default is "event". Note that JBoss
+ Drools will append ".log" for you. The default location
+ for this file is "." - the current working directory
+ (which for JBoss is in its bin/ directory).</seg>
+
+ </seglistitem>
+ <seglistitem>
+
+ <seg><property>ruleAuditInterval</property></seg>
+
+ <seg>Optional property to define how often to flush audit
+ events to the audit log. Only applies to the THREADED_FILE
+ ruleAuditType. The default is 1000 (milliseconds).</seg>
+
+ </seglistitem>
+ <seglistitem>
+
+ <seg><property>ruleClockType</property></seg>
+
+ <seg>Optional property to define the clock used by JBoss
+ Drools. Valid values are REALTIME and PSEUDO. The
+ default is REALTIME.</seg>
+
+ </seglistitem>
+ <seglistitem>
+
+ <seg><property>ruleEventProcessingType</property></seg>
+
+ <seg>Optional property to define the event processing
+ option used by Drools. The valid values are CLOUD
+ or STREAM (useful for CEP). The default is CLOUD.</seg>
+
+ </seglistitem>
+ <seglistitem>
+
+ <seg><property>channels</property></seg>
+
+ <seg>Optional property to define any Channels a rule can
+ send Objects to. The Channel concept used to be known
+ as an ExitPoint. Please refer to the "Channels" section
+ below.</seg>
+
+ </seglistitem>
</segmentedlist>
</section>
@@ -585,6 +683,70 @@
</section>
+<section>
+
+ <title>
+ Channels
+ </title>
+
+ <para>
+ To send an Object to a Drools Channel in DRL, the syntax is
+ very simple and goes on the RHS (Right Hand Side) of the rule
+ definition:
+ </para>
+
+<programlisting language="Java" role="JAVA"><xi:include href="extras/rule_service/channels.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+
+ <para>
+ For this DRL to be functional, the "mychannel" channel needs
+ to be registered to do this you add a "channels" property
+ section to the jboss-esb.xml configuration. You can define
+ as many Channels as you want, for the same or for different
+ Channel names. (For a particular Channel name, the Channels
+ will be executed in the same order as they appear in the
+ configuration.) The types of Channels supported are:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ The ServiceChannel, which is provided out-of-the-box. All
+ you have to do, as attributes to the send-to element, is
+ specify the channel-name, service-category and service-name.
+ There are also the optional async, timeout and set-payload-location
+ (where the Object sent to that channel will be placed in a
+ new ESB Message) attributes as described above. Under the
+ covers, the ServiceInvoker is used to send the newly created
+ ESB message to the target Service.
+ </para>
+<programlisting language="XML" role="XML"><xi:include href="extras/rule_service/channels1.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ <important>
+ <para>
+ Make sure you have invmScope="GLOBAL" defined on the target Service.
+ </para>
+ </important>
+ </listitem>
+
+ <listitem>
+ <para>
+ Custom Channels. you can specify your own
+ <classname>org.drools.runtime.Channel</classname>
+ implementation class. The send-to attribute for this is
+ channel-class. Your implementation requires a public no-arg
+ constructor. If you want your implementation to be configurable,
+ also implement the
+ <classname>org.jboss.soa.esb.Configurable</classname>
+ interface, and your setConfiguration(ConfigTree) method will be
+ called, passing in the attributes and (sub) property elements
+ to your custom Channel.
+ </para>
+<programlisting language="XML" role="XML"><xi:include href="extras/rule_service/channels2.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
<section>
<title>
Deploying and Packaging
Modified: labs/jbossesb/trunk/product/docs/Services_Guide/en-US/What_is_a_Rule_Service.xml
===================================================================
--- labs/jbossesb/trunk/product/docs/Services_Guide/en-US/What_is_a_Rule_Service.xml 2010-08-03 18:04:02 UTC (rev 34486)
+++ labs/jbossesb/trunk/product/docs/Services_Guide/en-US/What_is_a_Rule_Service.xml 2010-08-03 18:05:07 UTC (rev 34487)
@@ -16,31 +16,31 @@
</title>
<para>
- The JBoss ESB Rule Service allows you to deploy rules created in
- JBoss Drools as services on the ESB. This is beneficial, because it
+ The JBossESB Rule Service allows you to deploy rules created in
+ Drools as services on the ESB. This is beneficial, because it
means you don't have to develop as much client code to integrate
rules into your application environment, and rules can be accessed
as part of an action chain or orchestrated business process. To
understand these types of services, you should first learn about
- JBoss Drools.
+ Drools.
</para>
<para>
Rule Services are supported by the BusinessRulesProcessor
action class and the DroolsRuleService, which implement the
RuleService interface. While it is possible to use rule engines
- other than JBoss Drools, only JBoss Drools is supported out the
+ other than Drools, only Drools is supported out the
the box. The BusinessRulesProcessor supports rules loaded from
the classpath that are defined in .drl files, .dsl files
(domain specific language support), and .xls (decision table
support) files. These are primarily for testing, prototypes,
and very simple rule services. There is no way to specify
multiple rule files in the jboss-esb.xml file, so complex rule
- services need to use the Drools RuleAgent.
+ services need to use the Drools KnowledgeAgent.
</para>
<para>
- The RuleService uses the RuleAgent to access rule packages from
+ The RuleService uses the KnowledgeAgent to access rule packages from
the Drools BRMS or local file system. These rule packages can
contain thousands of rules, the source of which can be:
</para>
@@ -73,7 +73,7 @@
<important>
<para>
- Use of the Drools RuleAgent is the recommended approach for
+ Use of the Drools KnowledgeAgent is the recommended approach for
production systems.
</para>
</important>
@@ -96,6 +96,21 @@
identify a stateful conversation over the ESB.
</para>
-
+ <note>
+ <para>
+ In ESB 4.8 and prior releases, the Drools Rule* API was used.
+ In ESB 4.9, which uses Drools 5.1.0, the Drools Knowledge* API
+ is used. The biggest change here is how the KnowledgeAgent is
+ configured/run differently than the RuleAgent. Polling
+ configuration for DRL changes is no longer done at the RuleAgent
+ level (in the ruleAgentProperties file's "poll" property). It
+ is now done globally, and can be configured by the property
+ "org.jboss.soa.esb.services.rules.resource.scanner.interval",
+ found within jbossesb-properties.xml. The default is 60. This
+ means every 60 seconds, check for resource changes - across ALL
+ KnowledgeAgents.
+ </para>
+ </note>
+
</section>
</section>
Added: labs/jbossesb/trunk/product/docs/Services_Guide/en-US/extras/rule_service/channels.xmlt
===================================================================
--- labs/jbossesb/trunk/product/docs/Services_Guide/en-US/extras/rule_service/channels.xmlt (rev 0)
+++ labs/jbossesb/trunk/product/docs/Services_Guide/en-US/extras/rule_service/channels.xmlt 2010-08-03 18:05:07 UTC (rev 34487)
@@ -0,0 +1 @@
+channels["mychannel"].send(myobject);
Added: labs/jbossesb/trunk/product/docs/Services_Guide/en-US/extras/rule_service/channels1.xmlt
===================================================================
--- labs/jbossesb/trunk/product/docs/Services_Guide/en-US/extras/rule_service/channels1.xmlt (rev 0)
+++ labs/jbossesb/trunk/product/docs/Services_Guide/en-US/extras/rule_service/channels1.xmlt 2010-08-03 18:05:07 UTC (rev 34487)
@@ -0,0 +1,4 @@
+<property name="channels">
+ <send-to channel-name="mychannel"
+ service-category="cat1" service-name="svc1" />
+</property>
Added: labs/jbossesb/trunk/product/docs/Services_Guide/en-US/extras/rule_service/channels2.xmlt
===================================================================
--- labs/jbossesb/trunk/product/docs/Services_Guide/en-US/extras/rule_service/channels2.xmlt (rev 0)
+++ labs/jbossesb/trunk/product/docs/Services_Guide/en-US/extras/rule_service/channels2.xmlt 2010-08-03 18:05:07 UTC (rev 34487)
@@ -0,0 +1,4 @@
+<property name="channels">
+ <send-to channel-name="mychannel"
+ channel-class="com.example.MyChannel" />
+</property>
Added: labs/jbossesb/trunk/product/docs/Services_Guide/en-US/extras/rule_service/drl3.xmlt
===================================================================
--- labs/jbossesb/trunk/product/docs/Services_Guide/en-US/extras/rule_service/drl3.xmlt (rev 0)
+++ labs/jbossesb/trunk/product/docs/Services_Guide/en-US/extras/rule_service/drl3.xmlt 2010-08-03 18:05:07 UTC (rev 34487)
@@ -0,0 +1,32 @@
+<action class="org.jboss.soa.esb.actions.BusinessRulesProcessor"
+ name="OrderEventsRuleServiceStateful">
+ <property name="ruleSet" value="drl/OrderEvents.drl" />
+ <property name="ruleReload" value="false" />
+ <property name="stateful" value="true" >
+ <property name="ruleFireMethod" value="FIRE_UNTIL_HALT" />
+ <property name="ruleAuditType" value="THREADED_FILE" />
+ <property name="ruleAuditFile" value="myaudit" />
+ <property name="ruleAuditInterval" value="1000" />
+ <property name="ruleClockType" value="REALTIME" />
+ <property name="ruleEventProcessingType" value="STREAM" />
+ <property name="object-paths">
+ <object-path esb="body.OrderStatus"
+ entry-point="OrderStatusStream" />
+ <object-path esb="body.OrderInfo"
+ entry-point="OrderInfoStream" />
+ </property>
+ <property name="channels">
+ <!-- chan1 and chan2 are equivalent
+ (but timeout only applies if async is false) -->
+ <send-to channel-name="chan1"
+ service-category="cat1" service-name="svc1" />
+ <send-to channel-name="chan2"
+ service-category="cat1" service-name="svc1"
+ channel-class="org.jboss.soa.esb.services.rules.ServiceChannel"
+ async="true" timeout="30000"
+ set-payload-location="org.jboss.soa.esb.message.defaultEntry" />
+ <!-- chan3 is a custom channel -->
+ <send-to channel-name="chan3"
+ channel-class="com.example.MyChannel" />
+ </property>
+</action>
More information about the jboss-svn-commits
mailing list