<commit_before><?xml version="1.0" encoding="UTF-8"?>
<section version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd"
         xml:base="../../" xmlns="http://docbook.org/ns/docbook" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:ns="http://docbook.org/ns/docbook">
  <title>Stream Mode</title>

  <para>The STREAM processing mode is the mode of choice when the application
  needs to process streams of events. It adds a few common requirements to the
  regular processing, but enables a whole lot of features that make stream
  event processing a lot simpler.</para>

  <para>The main requirements to use STREAM mode are:</para>

  <itemizedlist>
    <listitem>
      <para>Events in each stream must be time-ordered. I.e., inside a given
      stream, events that happened first must be inserted first into the
      engine.</para>
    </listitem>

    <listitem>
      <para>The engine will force synchronization between streams through the
      use of the session clock, so, although the application does not need to
      enforce time ordering between streams, the use of non-time-synchronized
      streams may result in some unexpected results.</para>
    </listitem>
  </itemizedlist>

  <para>Given that the above requirements are met, the application may enable
  the STREAM mode using the following API:</para>

  <programlisting language="java">KnowledgeBaseConfiguration config = KnowledgeBaseFactory.newKnowledgeBaseConfiguration();
config.setOption( EventProcessingOption.STREAM );</programlisting>

  <para>Or, the equivalent property: </para>

  <programlisting>drools.eventProcessingMode = stream</programlisting>

  <para>When using the STREAM, the engine knows the concept of flow of time
  and the concept of "now", i.e., the engine understands how old events are
  based on the current timestamp read from the Session Clock. This
  characteristic allows the engine to provide the following additional
  features to the application:</para>

  <itemizedlist>
    <listitem>
      <para>Sliding Window support</para>
    </listitem>

    <listitem>
      <para>Automatic Event Lifecycle Management</para>
    </listitem>

    <listitem>
      <para>Automatic Rule Delaying when using Negative Patterns</para>
    </listitem>
  </itemizedlist>

  <para>All these features are explained in the following sections.</para>

  <section>
    <title>Role of Session Clock in Stream mode</title>

    <para>When running the engine in CLOUD mode, the session clock is used
    only to time stamp the arriving events that don't have a previously
    defined timestamp attribute. Although, in STREAM mode, the Session Clock
    assumes an even more important role.</para>

    <para>In STREAM mode, the session clock is responsible for keeping the
    current timestamp, and based on it, the engine does all the temporal
    calculations on event's aging, synchronizes streams from multiple sources,
    schedules future tasks and so on.</para>

    <para>Check the documentation on the Session Clock section to know how to
    configure and use different session clock implementations.</para>
  </section>

  <section>
    <title>Negative Patterns in Stream Mode</title>

    <para>Negative patterns behave different in STREAM mode when compared to
    CLOUD mode. In CLOUD mode, the engine assumes that all facts and events
    are known in advance (there is no concept of flow of time) and so,
    negative patterns are evaluated immediately.</para>

    <para>When running in STREAM mode, negative patterns with temporal
    constraints may require the engine to wait for a time period before
    activating a rule. The time period is automatically calculated by the
    engine in a way that the user does not need to use any tricks to achieve
    the desired result.</para>

    <para>For instance:</para>

    <example>
        <title>a rule that activates immediately upon matching</title>

        <programlisting>rule "Sound the alarm"
when
    $f : FireDetected( )
    not( SprinklerActivated( ) )
then
    // sound the alarm
end
</programlisting>
      </example>
    <para>The above rule has no temporal constraints that would require
    delaying the rule, and so, the rule activates immediately. The following
    rule on the other hand, must wait for 10 seconds before activating, since
    it may take up to 10 seconds for the sprinklers to activate:</para>

    <example>
        <title>a rule that automatically delays activation due to temporal
        constraints</title>

        <programlisting>rule "Sound the alarm"
when
    $f : FireDetected( )
    not( SprinklerActivated( this after[0s,10s] $f ) )
then
    // sound the alarm
end</programlisting>
      </example>
    <para>This behaviour allows the engine to keep consistency when
    dealing with negative patterns and temporal constraints at the same time.
    The above would be the same as writing the rule as below, but does not
    burden the user to calculate and explicitly write the appropriate duration
    parameter:</para>
    <example>
        <title>same rule with explicit duration parameter</title>

        <programlisting>rule "Sound the alarm"
    duration( 10s )
when
    $f : FireDetected( )
    not( SprinklerActivated( this after[0s,10s] $f ) )
then
    // sound the alarm
end</programlisting>
      </example>
  </section>
</section>
<commit_msg>=Updated the documentation about negative patterns in stream mode<commit_after><?xml version="1.0" encoding="UTF-8"?>
<section version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd"
         xml:base="../../" xmlns="http://docbook.org/ns/docbook" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:ns="http://docbook.org/ns/docbook">
  <title>Stream Mode</title>

  <para>The STREAM processing mode is the mode of choice when the application
  needs to process streams of events. It adds a few common requirements to the
  regular processing, but enables a whole lot of features that make stream
  event processing a lot simpler.</para>

  <para>The main requirements to use STREAM mode are:</para>

  <itemizedlist>
    <listitem>
      <para>Events in each stream must be time-ordered. I.e., inside a given
      stream, events that happened first must be inserted first into the
      engine.</para>
    </listitem>

    <listitem>
      <para>The engine will force synchronization between streams through the
      use of the session clock, so, although the application does not need to
      enforce time ordering between streams, the use of non-time-synchronized
      streams may result in some unexpected results.</para>
    </listitem>
  </itemizedlist>

  <para>Given that the above requirements are met, the application may enable
  the STREAM mode using the following API:</para>

  <programlisting language="java">KnowledgeBaseConfiguration config = KnowledgeBaseFactory.newKnowledgeBaseConfiguration();
config.setOption( EventProcessingOption.STREAM );</programlisting>

  <para>Or, the equivalent property: </para>

  <programlisting>drools.eventProcessingMode = stream</programlisting>

  <para>When using the STREAM, the engine knows the concept of flow of time
  and the concept of "now", i.e., the engine understands how old events are
  based on the current timestamp read from the Session Clock. This
  characteristic allows the engine to provide the following additional
  features to the application:</para>

  <itemizedlist>
    <listitem>
      <para>Sliding Window support</para>
    </listitem>

    <listitem>
      <para>Automatic Event Lifecycle Management</para>
    </listitem>

    <listitem>
      <para>Automatic Rule Delaying when using Negative Patterns</para>
    </listitem>
  </itemizedlist>

  <para>All these features are explained in the following sections.</para>

  <section>
    <title>Role of Session Clock in Stream mode</title>

    <para>When running the engine in CLOUD mode, the session clock is used
    only to time stamp the arriving events that don't have a previously
    defined timestamp attribute. Although, in STREAM mode, the Session Clock
    assumes an even more important role.</para>

    <para>In STREAM mode, the session clock is responsible for keeping the
    current timestamp, and based on it, the engine does all the temporal
    calculations on event's aging, synchronizes streams from multiple sources,
    schedules future tasks and so on.</para>

    <para>Check the documentation on the Session Clock section to know how to
    configure and use different session clock implementations.</para>
  </section>

  <section>
    <title>Negative Patterns in Stream Mode</title>

    <para>Negative patterns behave different in STREAM mode when compared to
    CLOUD mode. In CLOUD mode, the engine assumes that all facts and events
    are known in advance (there is no concept of flow of time) and so,
    negative patterns are evaluated immediately.</para>

    <para>When running in STREAM mode, negative patterns with temporal
    constraints may require the engine to wait for a time period before
    activating a rule. The time period is automatically calculated by the
    engine in a way that the user does not need to use any tricks to achieve
    the desired result.</para>

    <para>For instance:</para>

    <example>
        <title>a rule that activates immediately upon matching</title>

        <programlisting>rule "Sound the alarm"
when
    $f : FireDetected( )
    not( SprinklerActivated( ) )
then
    // sound the alarm
end
</programlisting>
      </example>
    <para>The above rule has no temporal constraints that would require
    delaying the rule, and so, the rule activates immediately. The following
    rule on the other hand, must wait for 10 seconds before activating, since
    it may take up to 10 seconds for the sprinklers to activate:</para>

    <example>
        <title>a rule that automatically delays activation due to temporal
        constraints</title>

        <programlisting>rule "Sound the alarm"
when
    $f : FireDetected( )
    not( SprinklerActivated( this after[0s,10s] $f ) )
then
    // sound the alarm
end</programlisting>
      </example>
    <para>This behaviour allows the engine to keep consistency when
    dealing with negative patterns and temporal constraints at the same time.
    The above would be the same as writing the rule as below, but does not
    burden the user to calculate and explicitly write the appropriate duration
    parameter:</para>
    <example>
        <title>same rule with explicit duration parameter</title>

        <programlisting>rule "Sound the alarm"
    duration( 10s )
when
    $f : FireDetected( )
    not( SprinklerActivated( this after[0s,10s] $f ) )
then
    // sound the alarm
end</programlisting>
      </example>
	  
	  <para>The following rule expects every 10 seconds at least one
	  “Heartbeat” event, if not the rule fires. The special case in this rule
	  is that we use the same type of the object in the first pattern and in
	  the negative pattern. The negative pattern has the temporal constraint to
	  wait between 0 to 10 seconds before firing and it excludes the Heartbeat
	  bound to $h. Excluding the bound Heartbeat is important since the
	  temporal constraint [0s, ...] does not exclude by itself the bound event
	  $h from being matched again, thus preventing the rule to fire.</para>
	  <example>
        <title>excluding bound events in negativ patterns</title>

        <programlisting>rule "Sound the alarm"
when
    $h: Heartbeat( ) from entry-point "MonitoringStream"
    not( Heartbeat( this != $h, this after[0s,10s] $h ) from entry-point "MonitoringStream" )
then
    // Sound the alarm
end</programlisting>
      </example>
  </section>
</section>

{'fraction_non_alphanumeric': 0.08181005768137135, 'fraction_numerical': 0.008205378178568527, 'mean_word_length': 3.474736459469284, 'pattern_counts': {'":': 0, '<': 185, '<?xml version=': 2, '>': 185, 'https://': 0, 'lorem ipsum': 0, 'www.': 14, 'xml': 20}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4946724', 'n_tokens_mistral': 3430, 'n_tokens_neox': 3244, 'n_words': 1399}