[jboss-svn-commits] JBL Code SVN: r25178 - in labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US: Chapter-Features/Chapter-Events and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Mon Feb 9 18:37:16 EST 2009
Author: tirelli
Date: 2009-02-09 18:37:15 -0500 (Mon, 09 Feb 2009)
New Revision: 25178
Added:
labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_EventsMetadata.xml
Removed:
labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_TimestampAndDuration.xml
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events.xml
labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_Declaration.xml
labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_Semantics.xml
labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/master.xml
Log:
working on docs
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events.xml 2009-02-09 22:43:14 UTC (rev 25177)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events.xml 2009-02-09 23:37:15 UTC (rev 25178)
@@ -1,13 +1,21 @@
<?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>Events</title>
-
- <xi:include href="Section-Events_TimestampAndDuration.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>Events</title>
+
+ <para>Events, from a Drools perspective are just a special type of fact. In
+ this way, we can say that all events are facts, but not all facts are
+ events. In the next few sections the specific differences that characterize
+ an event are presented.</para>
+
+ <xi:include href="Section-Events_Semantics.xml" />
+
+ <xi:include href="Section-Events_Declaration.xml" />
+
+ <xi:include href="Section-Events_EventsMetadata.xml" />
</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_Declaration.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_Declaration.xml 2009-02-09 22:43:14 UTC (rev 25177)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_Declaration.xml 2009-02-09 23:37:15 UTC (rev 25178)
@@ -1,11 +1,60 @@
<?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>Event Declaration</title>
-
+ 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>Event Declaration</title>
+
+ <para>To declare a fact type as an event, all it is required is to assign
+ the @role metadata tag to the fact type. The @role metadata tag accepts two
+ possible values:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>fact : this is the default, declares that the type is to be
+ handled as a regular fact.</para>
+ </listitem>
+
+ <listitem>
+ <para>event : declares that the type is to be handled as an
+ event.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>For instance, the example bellow is declaring that the fact type
+ StockTick in a stock broker application shall be handled as an event.</para>
+
+ <para><example>
+ <title>declaring a fact type as an event</title>
+
+ <programlisting><emphasis role="bold">import</emphasis> some.package.StockTick
+
+<emphasis role="bold">declare</emphasis> StockTick
+ <emphasis>@role</emphasis>( event )
+<emphasis role="bold">end</emphasis>
+</programlisting>
+ </example></para>
+
+ <para>The same applies to facts declared inline. So, if StockTick was a fact
+ type declared in the DRL itself, instead of a previously existing class, the
+ code would be:</para>
+
+ <para><example>
+ <title>declaring a fact type and assiging it the event role</title>
+
+ <programlisting><emphasis role="bold">declare</emphasis> StockTick
+ <emphasis>@role</emphasis>( event )
+
+ datetime : java.util.Date
+ symbol : String
+ price : double
+<emphasis role="bold">end</emphasis>
+</programlisting>
+ </example>For more information on type declarations, please check the Rule
+ Language section of the Drools Expert documentation.</para>
+
+ <para></para>
</section>
Copied: labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_EventsMetadata.xml (from rev 25119, labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_TimestampAndDuration.xml)
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_EventsMetadata.xml (rev 0)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_EventsMetadata.xml 2009-02-09 23:37:15 UTC (rev 25178)
@@ -0,0 +1,159 @@
+<?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>Event Metadata</title>
+
+ <para>All events have a set of metadata associated to them. Most of the
+ metadata values have defaults that are automatically assigned to each event
+ when they are inserted into the working memory, but it is possible to change
+ the default on an event type basis, using the metadata tags listed
+ bellow.</para>
+
+ <para>For the examples, lets assume the user has the following class in the
+ application domain model:</para>
+
+ <example>
+ <title>the VoiceCall fact class</title>
+
+ <programlisting><emphasis>/**
+ * A class that represents a voice call in
+ * a Telecom domain model
+ */</emphasis>
+<emphasis role="bold">public class</emphasis> VoiceCall {
+ <emphasis role="bold">private</emphasis> String originNumber;
+ <emphasis role="bold">private</emphasis> String destinationNumber;
+ <emphasis role="bold">private</emphasis> Date callDateTime;
+ <emphasis role="bold">private</emphasis> long callDuration; // in milliseconds
+
+ // constructors, getters and setters
+}
+</programlisting>
+ </example>
+
+ <section>
+ <title>@role</title>
+
+ <para>The @role meta data was already discussed in the previous section
+ and is presented here for completeness:</para>
+
+ <programlisting><emphasis>@role</emphasis>( <fact|event> )
+</programlisting>
+
+ <para>It annotates a given fact type as either a regular fact or event. It
+ accepts either "fact" or "event" as a parameter. Default is "fact".</para>
+
+ <example>
+ <title>declaring VoiceCall as an event type</title>
+
+ <programlisting><emphasis role="bold">declare</emphasis> VoiceCall
+ <emphasis>@role</emphasis>( event )
+<emphasis role="bold">end</emphasis>
+</programlisting>
+ </example>
+
+ <para></para>
+ </section>
+
+ <section>
+ <title>@timestamp</title>
+
+ <para>Every event has an associated timestamp assigned to it. By default,
+ the timestamp for a given event is read from the Session Clock and
+ assigned to the event at the time the event is inserted into the working
+ memory. Although, sometimes, the event has the timestamp as one of it's
+ own attributes. In this case, the user may tell the engine to use the
+ timestamp from the event's attribute instead of reading it from the
+ Session Clock.</para>
+
+ <programlisting><emphasis>@timestamp</emphasis>( <attributeName> )</programlisting>
+
+ <para>To tell the engine what attribute to use as the source of the
+ event's timestamp, just list the attribute name as a parameter to the
+ @timestamp tag.</para>
+
+ <example>
+ <title>declaring the VoiceCall timestamp attribute</title>
+
+ <programlisting><emphasis role="bold">declare</emphasis> VoiceCall
+ <emphasis>@role</emphasis>( event )
+ <emphasis>@timestamp</emphasis>( callDateTime )
+<emphasis role="bold">end</emphasis>
+</programlisting>
+ </example>
+ </section>
+
+ <section>
+ <title>@duration</title>
+
+ <para>Drools supports both event semantics: point-in-time events and
+ interval-based events. A point-in-time event is represented as an
+ interval-based event whose duration is zero. By default, all events have
+ duration zero. The user may attribute a different duration for an event by
+ declaring which attribute in the event type contains the duration of the
+ event.</para>
+
+ <programlisting><emphasis>@duration</emphasis>( <attributeName> )</programlisting>
+
+ <para>So, for our VoiceCall fact type, the declaration would be:</para>
+
+ <example>
+ <title>declaring the VoiceCall duration attribute</title>
+
+ <programlisting><emphasis role="bold">declare</emphasis> VoiceCall
+ <emphasis>@role</emphasis>( event )
+ <emphasis>@timestamp</emphasis>( callDateTime )
+ <emphasis>@duration</emphasis>( callDuration )
+<emphasis role="bold">end</emphasis></programlisting>
+ </example>
+ </section>
+
+ <section>
+ <title>@expires</title>
+
+ <important>
+ <para>This tag is only considered when running the engine in STREAM
+ mode. Also, additional discussion on the effects of using this tag is
+ made on the Memory Management section. It is included here for
+ completeness.</para>
+ </important>
+
+ <para>Events may be automatically expired after some time in the working
+ memory. Typically this happens when, based on the existing rules in the
+ knowledge base, the event can no longer match and activate any rules.
+ Although, it is possible to explicitly define when an event should
+ expire.</para>
+
+ <programlisting><emphasis>@expires</emphasis>( <timeOffset> )</programlisting>
+
+ <para>The value of <emphasis>timeOffset</emphasis> is a temporal interval
+ in the form:</para>
+
+ <programlisting>[#d][#h][#m][#s][#[ms]]</programlisting>
+
+ <para>Where <emphasis>[ ]</emphasis> means an optional parameter and
+ <emphasis>#</emphasis> means a numeric value.</para>
+
+ <para>So, to declare that the VoiceCall facts should be expired after 1
+ hour and 35 minutes after they are inserted into the working memory, the
+ user would write:</para>
+
+ <para><example>
+ <title>declaring the expiration offset for the VoiceCall
+ events</title>
+
+ <programlisting><emphasis role="bold">declare</emphasis> VoiceCall
+ <emphasis>@role</emphasis>( event )
+ <emphasis>@timestamp</emphasis>( callDateTime )
+ <emphasis>@duration</emphasis>( callDuration )
+ <emphasis>@expires</emphasis>( 1h35m )
+<emphasis role="bold">end</emphasis></programlisting>
+ </example></para>
+
+ <para></para>
+ </section>
+</section>
Property changes on: labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_EventsMetadata.xml
___________________________________________________________________
Name: svn:mergeinfo
+
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_Semantics.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_Semantics.xml 2009-02-09 22:43:14 UTC (rev 25177)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_Semantics.xml 2009-02-09 23:37:15 UTC (rev 25178)
@@ -1,11 +1,71 @@
<?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>Event Semantics</title>
-
+ 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>Event Semantics</title>
+
+ <para>An <emphasis>event</emphasis> is a fact that present a few
+ distinguishing characteristics:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">Usually immutables:</emphasis> since, by the
+ previously discussed definition, events are a record of a state change
+ in the application domain, i.e., a record of something that already
+ happened, and the past can not be "changed", events are immutables. This
+ constraint is an important requirement for the development of several
+ optimizations and for the specification of the event lifecycle. This
+ does not mean that the java object representing the object must be
+ immutable. Quite the contrary, the engine does not enforce immutability
+ of the object model, because one of the most common usecases for rules
+ is event data enrichment.</para>
+
+ <tip>
+ <para>As a best practice, the application is allowed to populate
+ un-populated event attributes (to enrich the event with infered data),
+ but already populated attributes should never be changed.</para>
+ </tip>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Strong temporal constraints:</emphasis>
+ rules involving events usually require the correlation of multiple
+ events, specially temporal correlations where events are said to happen
+ at some point in time relative to other events.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Managed lifecycle:</emphasis> due to their
+ immutable nature and the temporal constraints, events usually will only
+ match other events and facts during a limited window of time, making it
+ possible for the engine to manage the lifecycle of the events
+ automatically. In other words, one an event is inserted into the working
+ memory, it is possible for the engine to find out when an event can no
+ longer match other facts and automatically retract it, releasing its
+ associated resources.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Use of sliding windows:</emphasis> since all
+ events have timestamps associated to them, it is possible to define and
+ use sliding windows over them, allowing the creation of rules on
+ aggregations of values over a period of time. Example: average of an
+ event value over 60 minutes.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Drools supports the declaration and usage of events with both
+ semantics: <emphasis role="bold">point-in-time</emphasis> events and
+ <emphasis role="bold">interval-based</emphasis> events. </para>
+
+ <tip>
+ <para>A simplistic way to understand the unitification of the semantics is
+ to consider a <emphasis>point-in-time</emphasis> event as an
+ <emphasis>interval-based</emphasis> event whose <emphasis>duration is
+ zero</emphasis>.</para>
+ </tip>
</section>
Deleted: labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_TimestampAndDuration.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_TimestampAndDuration.xml 2009-02-09 22:43:14 UTC (rev 25177)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-Events/Section-Events_TimestampAndDuration.xml 2009-02-09 23:37:15 UTC (rev 25178)
@@ -1,11 +0,0 @@
-<?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>Timestamps and Duration</title>
-
-</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/master.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/master.xml 2009-02-09 22:43:14 UTC (rev 25177)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/master.xml 2009-02-09 23:37:15 UTC (rev 25178)
@@ -1,13 +1,13 @@
<?xml version="1.0" encoding="UTF-8"?>
-
-<book 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">
-
+
+<book 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">
+
<info>
<title>Drools Fusion User Guide</title>
@@ -28,6 +28,11 @@
<surname>Tirelli</surname>
</author>
+ <author>
+ <firstname>Kris</firstname>
+ <surname>Verlaenen</surname>
+ </author>
+
</info>
<!--
@@ -43,13 +48,13 @@
<para />
</preface>
-->
-<title>Drools Fusion</title>
-
- <xi:include href="Chapter-Introduction/Chapter-Introduction.xml" />
-
- <xi:include href="Chapter-Features/Chapter-Features.xml" />
-
- <xi:include href="Chapter-References/Section-References.xml" />
-
+<title>Drools Fusion</title>
+
+ <xi:include href="Chapter-Introduction/Chapter-Introduction.xml" />
+
+ <xi:include href="Chapter-Features/Chapter-Features.xml" />
+
+ <xi:include href="Chapter-References/Section-References.xml" />
+
<index/>
-</book>
+</book>
More information about the jboss-svn-commits
mailing list