[jboss-svn-commits] JBL Code SVN: r25356 - labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-SessionClock.

[jboss-svn-commits at lists.jboss.org]

Author: tirelli
Date: 2009-02-19 21:36:25 -0500 (Thu, 19 Feb 2009)
New Revision: 25356

Modified:
   labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-SessionClock/Section-SessionClock.xml
Log:
adding docs

Modified: labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-SessionClock/Section-SessionClock.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-SessionClock/Section-SessionClock.xml	2009-02-20 02:11:35 UTC (rev 25355)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-SessionClock/Section-SessionClock.xml	2009-02-20 02:36:25 UTC (rev 25356)
@@ -1,16 +1,57 @@
 <?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">
-	<title>Session Clock</title>	
-	
-	<xi:include href="Section-SessionClock_AvailableClockImplementations.xml" />
-	
-	<xi:include href="Section-SessionClock_HowToImplementNewClocks.xml" />
-	
-		
+         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>Session Clock</title>
+
+  <para>Reasoning over time requires a reference clock. Just to mention one
+  example, if a rule reasons over the average price of a given stock over the
+  last 60 minutes, how the engine knows what stock price changes happened over
+  the last 60 minutes in order to calculate the average? The obvious response
+  is: by comparing the timestamp of the events with the "current time". How
+  the engine knows what <emphasis role="bold">time is now</emphasis>? Again,
+  obviously, by querying the Session Clock.</para>
+
+  <para>The session clock implements a strategy pattern, allowing different
+  types of clocks to be plugged and used by the engine. This is very important
+  because the engine may be running in an array of different scenarios that
+  may require different clock implementations. Just to mention a few:</para>
+
+  <itemizedlist>
+    <listitem>
+      <para><emphasis role="bold">Rules testing:</emphasis> testing always
+      requires a controled environment, and when the tests include rules with
+      temporal constraints, it is necessary to not only control the input
+      rules and facts, but also the flow of time.</para>
+    </listitem>
+
+    <listitem>
+      <para><emphasis role="bold">Regular execution:</emphasis> usually, when
+      running rules in production, the application will require a real time
+      clock that allows the rules engine to react immediately to the time
+      progression.</para>
+    </listitem>
+
+    <listitem>
+      <para><emphasis role="bold">Special environments:</emphasis> specific
+      environments may have specific requirements on time control. Cluster
+      environments may require clock synchronization through heart beats, or
+      JEE environments may require the use of an AppServer provided clock,
+      etc.</para>
+    </listitem>
+
+    <listitem>
+      <para><emphasis role="bold">Rules replay or simulation: </emphasis>to
+      replay scenarios or simulate scenarios it is necessary that the
+      application also controls the flow of time.</para>
+    </listitem>
+  </itemizedlist>
+
+  <xi:include href="Section-SessionClock_AvailableClockImplementations.xml" />
+
+  <xi:include href="Section-SessionClock_HowToImplementNewClocks.xml" />
 </section>