[jboss-svn-commits] JBL Code SVN: r25963 - in labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook: en-US/Chapter-BAM and 4 other directories.

jboss-svn-commits at lists.jboss.org jboss-svn-commits at lists.jboss.org
Sun Apr 5 19:17:53 EDT 2009 

Author: KrisVerlaenen
Date: 2009-04-05 19:17:52 -0400 (Sun, 05 Apr 2009)
New Revision: 25963

Added:
   labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-BAM/
   labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-BAM/Chapter-BAM.xml
   labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-BAM/
   labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-BAM/EventingReport.png
   labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-BAM/EventingReportEdit.png
Modified:
   labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Flow/Chapter-RuleFlow.xml
   labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Persistence/Chapter-Persistence.xml
   labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/master.xml
Log:
 - updated transaction docs
 - added section on Drools4 processes
 - added chapter on BAM

Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-BAM/Chapter-BAM.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-BAM/Chapter-BAM.xml	                        (rev 0)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-BAM/Chapter-BAM.xml	2009-04-05 23:17:52 UTC (rev 25963)
@@ -0,0 +1,113 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter 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="./">
+
+  <title>Business Activity Monitoring</title>
+
+  <para>You need to actively monitor your processes to make sure you can detect any anomalies and react to unexpected events
+  as soon as possible.  Business Activity Monitoring (BAM) is related to the real-time monitoring your processes and the
+  possibility to intervene directly (possibly even automatically), based on the analysis of these events.</para>
+
+  <para>Drools Flow allows users to define reports based on the events generated by the process engine, and possibly direct
+  intervention in specific situations using Complex Event Processing rules (Drools Fusion), as described in the next two
+  sections.  Support for the entire Business Activity Monitoring requirements (including a web-based application that can
+  be used to more easily interact with a running process engine, inspect its state, generate reports, etc.) will be included
+  in future releases of the Drools platform.</para>
+
+  <section>
+    <title>Reporting</title>
+
+    <para>By adding a history logger to the process engine, all relevent events are stored in the database.  This history
+    log can be used to monitor and analyze the execution of your processes.  We are using Eclipse BIRT (Business Intelligence
+    Reporting Tool) to create reports that show the key performance indicators.  It's easy to define your own reports yourself,
+    using the predefined data sets containing all process history information, and any other data sources you might want to
+    add yourself.</para>
+
+    <para>The Eclipse BIRT framework allows you to define data sets, create reports, include charts, preview your reports,
+    export them on web pages, etc.  We refer to the Eclipse BIRT documentation on how to define your own reports.  The following
+    screen shot shows a sample on how to create such a chart.</para>
+
+    <figure>
+      <title>Creating a report using Eclipse BIRT</title>
+      <mediaobject>
+        <imageobject>
+          <imagedata align="center" fileref="images/Chapter-BAM/EventingReportEdit.png" format="PNG" role="" />
+        </imageobject>
+      </mediaobject>
+    </figure>
+
+    <para>The next figure shows a simple report based on some history data, showing the number of requests every hour, and the
+    average completion time of the request in that hour.  These charts could be used to check for an unexpected drop or rise
+    of requests, an increase in the average processing time, etc.  These charts could signal possible problems before the
+    situation really gets out of hand.</para>
+
+    <figure>
+      <title>The eventing report</title>
+      <mediaobject>
+        <imageobject>
+	  <imagedata align="center" fileref="images/Chapter-BAM/EventingReport.png" format="PNG" role="" />
+        </imageobject>
+      </mediaobject>
+    </figure>
+
+  </section>
+
+  <section>
+    <title>Direct intervention</title>
+
+    <para>Reports can be used to visualize an overview of the current state of your processes, they do however rely on
+    a human actor to take action based on the information in these charts.  We do however allow users to define how to 
+    respond automatically to specific circumstances.</para>
+
+    <para>Drools Fusion provides numerous features that make it easy to process large sets of events.  This can be used
+    to monitor the process engine itself.  This can be achieved by adding a listener to the engine that forwards all
+    related process events (whenever a process instance is started / completed or when a specific node is triggered during
+    the execution of your process instances) to a session responsible for processing these events (this could be the same
+    session as the one executing the processes or it could be an independent session as well).  Complex Event Processing
+    (CEP) rules could then be used to specify how to process these events.  For example, these rules could generate higher-
+    level business events based on (a specific occurrence of) low-level process events.  The rules could also specify
+    how to respond to specific situations.</para>
+
+    <para>The next section shows a sample rule that accumulates all start process events for one specific order process
+    over the last hour (using the sliding windows support).  This rule prints out an error message if more than 1000 process
+    instances were started in the last hour (e.g. to detect possible overload of the server).  Note that, in a realistic
+    setting, this would probably be replaced by sending an email or other form of notification to the responsible instead
+    of the simple logging.</para>
+
+    <programlisting>
+declare ProcessStartedEvent
+    @role( event )
+end
+
+dialect "mvel"
+
+rule "Number of process instances above threshold"
+  when
+    Number( nbProcesses : intValue > 1000 )
+      from accumulate(
+        e: ProcessStartedEvent( processInstance.processId == "com.sample.order.OrderProcess" )
+    	  over window:size(1h),
+        count(e) )
+  then
+    System.err.println(
+      "WARNING: Number of order processes in the last hour above 1000: " + nbProcesses );
+end</programlisting>
+
+    <para>These rules could even be used to automatically alter the behaviour of a process at runtime based on the
+    events generated by the engine.  For example, whenever a specific situation is detected, additional rules could
+    be added to the knowledge base to dynamically modify the behaviour of the process.  For example, whenever 
+    a large amount of user requests within a specific time frame are detected, additional validation could be added
+    to the process (for example automatically add an additional step to the process to have the end user fill in a
+    captcha to prevent scripting attacks, but only if the number of requests on the process engine is above a specific
+    treshold).  Or additional logging rules could be deployed whenever problems are detected to log additional
+    information (and this only when errors are detected, not during normal operation).  These rules could then be
+    removed from the knowledge base again, once they are no longer needed.</para>
+
+  </section>
+
+</chapter>


Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-BAM/Chapter-BAM.xml
___________________________________________________________________
Name: svn:executable
   + *

Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Flow/Chapter-RuleFlow.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Flow/Chapter-RuleFlow.xml	2009-04-05 22:40:52 UTC (rev 25962)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Flow/Chapter-RuleFlow.xml	2009-04-05 23:17:52 UTC (rev 25963)
@@ -1027,6 +1027,38 @@
     in the working memory (eg. in the above example, it is checking for claims
     with a value of less than 250). Should this condition be true, then the
     path specified by it will be followed.</para>
+  </section>
+
+  <section>
+    <title>Using old Drools 4.x RuleFlow processes</title>
+
+    <para>The XML format that was used in Drools4 to store RuleFlow processes
+    was an automatically generated XML file generated by XStream.  As a result,
+    it was hard to read by human actors and hard to maintain and extend.  The
+    new Drools Flow XML format has been created to simplify this.  This however
+    means that, by default, old RuleFlow processes cannot simply be executed on
+    the Drools5 engine.</para>
+
+    <para>We do however provide a RuleFlowMigrator that allows you to transform
+    your old .rf file to the new format.  It uses an XSLT transformation to 
+    generate the new XML based on the old content.  You can use this class to
+    manually transform your old processes to the new format once when upgrading
+    from Drools4.x to Drools5.x.  You can however also let the KnowledgeBuilder
+    to automatically upgrade your processes when to the new format when they are
+    loaded into the knowledge base.  While this requires a conversion every time
+    the process is loaded into the knowledge base, it does however support a more
+    seamless upgrade.  To support this automatic upgrade, you need to set the 
+    "drools.ruleflow.port" system property to "true", for example by adding
+    -Ddrools.ruleflow.port=true when starting your application or by calling
+    System.setProperty("drools.ruleflow.port", "true");</para>
+
+    <para>The Drools Eclipse plugin also automatically detects if an old RuleFlow
+    file is opened.  At that point, it will automatically perform the conversion
+    and show the result in the graphical editor.  You then need to save this result
+    (either in a new file or by overriding the old one) to persist the old process
+    in the new format.  Note that the plugin does not support editing and saving
+    processes in the old Drools4.x format.</para>
   </section>
+  
 
 </chapter>

Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Persistence/Chapter-Persistence.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Persistence/Chapter-Persistence.xml	2009-04-05 22:40:52 UTC (rev 25962)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/Chapter-Persistence/Chapter-Persistence.xml	2009-04-05 23:17:52 UTC (rev 25963)
@@ -221,10 +221,20 @@
     will automatically execute each method invocation on the engine in a separate transaction.
     If this is acceptable behaviour, you don't need to do anything else.  You can however
     also specify the transaction boundaries yourself.  This allows you for example to combine
-    multiple commands into one transaction.  We use the Java Transaction API (JTA) to specify
-    transaction boundaries, as shown below:
+    multiple commands into one transaction.  You need to register a transaction manager at
+    the environment before using user-defined transactions.  For example, the following sample
+    uses the Bitronix transaction manager.  Next, we use the Java Transaction API (JTA)
+    to specify transaction boundaries, as shown below:
 
     <programlisting>
+// create the entity manager factory and register it in the environment
+EntityManagerFactory emf =
+    Persistence.createEntityManagerFactory( "org.drools.persistence.jpa" );
+Environment env = KnowledgeBaseFactory.newEnvironment();
+env.set( EnvironmentName.ENTITY_MANAGER_FACTORY, emf );
+env.set( EnvironmentName.TRANSACTION_MANAGER,
+         TransactionManagerServices.getTransactionManager() );
+
 // create a new knowledge session that uses JPA to store the runtime state
 StatefulKnowledgeSession ksession =
     JPAKnowledgeService.newStatefulKnowledgeSession( kbase, null, env );

Modified: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/master.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/master.xml	2009-04-05 22:40:52 UTC (rev 25962)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/en-US/master.xml	2009-04-05 23:17:52 UTC (rev 25963)
@@ -60,6 +60,7 @@
   <xi:include href="Chapter-HumanTasks/Chapter-HumanTasks.xml" />
   <xi:include href="Chapter-Debugging/Chapter-Debugging.xml" />
   <xi:include href="Chapter-Eclipse/Chapter-Eclipse.xml" />
+  <xi:include href="Chapter-BAM/Chapter-BAM.xml" />
     
   <index/>
 </book>

Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-BAM/EventingReport.png
===================================================================
(Binary files differ)


Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-BAM/EventingReport.png
___________________________________________________________________
Name: svn:mime-type
   + application/octet-stream

Added: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-BAM/EventingReportEdit.png
===================================================================
(Binary files differ)


Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-flow/src/main/docbook/images/Chapter-BAM/EventingReportEdit.png
___________________________________________________________________
Name: svn:mime-type
   + application/octet-stream

More information about the jboss-svn-commits mailing list