[jboss-svn-commits] JBL Code SVN: r25775 - labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-StreamsSupport.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Sun Mar 22 11:04:21 EDT 2009
Author: tirelli
Date: 2009-03-22 11:04:21 -0400 (Sun, 22 Mar 2009)
New Revision: 25775
Modified:
labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-StreamsSupport/Section-StreamsSupport.xml
labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-StreamsSupport/Section-StreamsSupport_DeclaringAndUsingStreams.xml
Log:
Adding docs
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-StreamsSupport/Section-StreamsSupport.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-StreamsSupport/Section-StreamsSupport.xml 2009-03-20 20:05:02 UTC (rev 25774)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-StreamsSupport/Section-StreamsSupport.xml 2009-03-22 15:04:21 UTC (rev 25775)
@@ -1,16 +1,53 @@
<?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>Streams Support</title>
-
- <xi:include href="Section-StreamsSupport_StreamsOfEvents.xml" />
-
- <xi:include href="Section-StreamsSupport_DeclaringAndUsingStreams.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>Streams Support</title>
+
+ <para>Most CEP use cases have to deal with streams of events. The streams
+ can be provided to the application in various forms, from JMS queues to flat
+ text files, from database tables to raw sockets or even through web service
+ calls. In any case, the streams share a common set of
+ characteristics:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>events in the stream are ordered by a timestamp. The timestamp may
+ have different semantics for different streams but they are always
+ ordered internally.</para>
+ </listitem>
+
+ <listitem>
+ <para>volumes of events are usually high.</para>
+ </listitem>
+
+ <listitem>
+ <para>atomic events are rarely useful by themselves. Usually meaning is
+ extracted from the correlation between multiple events from the stream
+ and also from other sources.</para>
+ </listitem>
+
+ <listitem>
+ <para>streams may be homogeneous, i.e. contain a single type of events,
+ or heterogeneous, i.e. contain multiple types of events.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Drools generalized the concept of a stream as an "entry point" into
+ the engine. An entry point is for drools a gate from which facts come. The
+ facts may be regular facts or special facts like events.</para>
+
+ <para>In Drools, facts from one entry point (stream) may join with facts
+ from any other entry point or event with facts from the working memory.
+ Although, they never mix, i.e., they never lose the reference to the entry
+ point through which they entered the engine. This is important because one
+ may have the same type of facts coming into the engine through several entry
+ points, but one fact that is inserted into the engine through entry point A
+ will never match a pattern from a entry point B, for example.</para>
+
+ <xi:include href="Section-StreamsSupport_DeclaringAndUsingStreams.xml" />
</section>
Modified: labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-StreamsSupport/Section-StreamsSupport_DeclaringAndUsingStreams.xml
===================================================================
--- labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-StreamsSupport/Section-StreamsSupport_DeclaringAndUsingStreams.xml 2009-03-20 20:05:02 UTC (rev 25774)
+++ labs/jbossrules/trunk/drools-docs/drools-docs-fusion/src/main/docbook/en-US/Chapter-Features/Chapter-StreamsSupport/Section-StreamsSupport_DeclaringAndUsingStreams.xml 2009-03-22 15:04:21 UTC (rev 25775)
@@ -1,11 +1,90 @@
<?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>Declaring and Using Streams</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>Declaring and Using Entry Points</title>
+
+ <para>Entry points are declared implicitly in Drools by directly making use
+ of them in rules. I.e. referencing an entry point in a rule will make the
+ engine, at compile time, to identify and create the proper internal
+ structures to suppor that entry point. </para>
+
+ <para>So, for instance, lets imagine a banking application, where
+ transactions are fed into the system coming from streams. One of the streams
+ contains all the transactions executed in ATM machines. So, if one of the
+ rules says: a withdraw is authorized if and only if the account balance is
+ over the requested withdraw amount, the rule would look like:</para>
+
+ <para><example>
+ <title>Example of Stream Usage</title>
+
+ <programlisting>rule "authorize withdraw"
+when
+ WithdrawRequest( $ai : accountId, $am : amount ) from entry-point "ATM Stream"
+ CheckingAccount( accountId == $ai, balance > $am )
+then
+ // authorize withdraw
+end
+</programlisting>
+ </example>In the previous example, the engine compiler will identify that
+ the pattern is tied to the entry point "ATM Stream" and will both create all
+ the necessary structures for the rulebase to support the "ATM Stream" and
+ will only match WithdrawRequests coming from the "ATM Stream". In the
+ previous example, the rule is also joining the event from the stream with a
+ fact from the main working memory (CheckingAccount).</para>
+
+ <para>Now, lets imagine a second rule that states that a fee of $2 must be
+ applied to any account for which a withdraw request is placed at a bank
+ branch:</para>
+
+ <para><example>
+ <title>Using a different Stream</title>
+
+ <programlisting>rule "apply fee on withdraws on branches"
+when
+ WithdrawRequest( $ai : accountId, processed == true ) from entry-point "Branch Stream"
+ CheckingAccount( accountId == $ai )
+then
+ // apply a $2 fee on the account
+end
+</programlisting>
+ </example>The previous rule will match events of the exact same type as
+ the first rule (WithdrawRequest), but from two different streams, so an
+ event inserted into "ATM Stream" will never be evaluated against the pattern
+ on the second rule, because the rule states that it is only interested in
+ patterns coming from the "Branch Stream".</para>
+
+ <para>So, entry points, besides being a proper abstraction for streams, are
+ also a way to scope facts in the working memory, and a valuable tool for
+ reducing cross products explosions. But that is a subject for another
+ time.</para>
+
+ <para>Inserting events into an entry point is equally simple. Instead of
+ inserting events directly into the working memory, insert them into the
+ entry point as shown in the example bellow:</para>
+
+ <para><example>
+ <title>Inserting facts into an entry point</title>
+
+ <programlisting>// create your rulebase and your session as usual
+StatefulKnowledgeSession session = ...
+
+// get a reference to the entry point
+WorkingMemoryEntryPoint atmStream = session.getWorkingMemoryEntryPoint( "ATM Stream" );
+
+// and start inserting your facts into the entry point
+atmStream.insert( aWithdrawRequest );
+</programlisting>
+ </example></para>
+
+ <para>The previous example shows how to manually insert facts into a given
+ entry point. Although, usually, the application will use one of the many
+ adapters to plug a stream end point, like a JMS queue, directly into the
+ engine entry point, without coding the inserts manually. The Drools pipeline
+ API has several adapters and helpers to do that as well as examples on how
+ to do it.</para>
</section>
More information about the jboss-svn-commits
mailing list