[jboss-jira] [JBoss JIRA] Commented: (JBRULES-1908) updated Drools docs content from SOA 4.2.CP03 Rules Guide

[Geoffrey De Smet (JIRA)]

    [ https://issues.jboss.org/browse/JBRULES-1908?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12603189#comment-12603189 ] 

Geoffrey De Smet commented on JBRULES-1908:
-------------------------------------------

Hi Darrin,
These changes are very welcome, but because that file has been changed 11 times since than and the Insertion content is changed on about every line: 
  https://github.com/droolsjbpm/drools/tree/master/drools-docs/drools-expert-docs/src/main/docbook/en-US/Obsolete-Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml
So these changes are stale :(
Would it be possible to create a pull request with the not-stale changes (or even apply them directly as you're the documentation lead)?
Poke me if you decide the pull request way: we don't want this to go stale again.

> updated Drools docs content from SOA 4.2.CP03 Rules Guide
> ---------------------------------------------------------
>
>                 Key: JBRULES-1908
>                 URL: https://issues.jboss.org/browse/JBRULES-1908
>             Project: Drools
>          Issue Type: Task
>      Security Level: Public(Everyone can see) 
>          Components: drools-docs-expert
>            Reporter: Darrin Mison
>            Assignee: Geoffrey De Smet
>             Fix For: 5.3.0.M1
>
>
> I revised the language of the "Insertion" section while fixing a couple of reported grammatical errors for the 4.2.CP03 SOA Rules Guide.  
> The original language is the same in: http://anonsvn.jboss.org/repos/labs/labs/jbossrules/soa_tags/4.3.0.FP01_BRMS_5.0.EA/drools-docs/drools-docs-expert/src/main/docbook/en-US/Chapter-Rule_Engine/Section-The_Drools_Rule_Engine.xml , so these changes would also apply to the most recent docs.
> Updated content below, the section ids are different but you get the idea ;-)
> <section id="sect-JBoss_Rules_Reference_Manual-WorkingMemory_and_StatefulStateless_Sessions-Insertion">
>     <title>Insertion</title>
>     <para>
>     <firstterm>Insertion</firstterm> is the act of telling the WorkingMemory about the facts.
>     </para>
>     <important>
>         <para>
>         In many Expert Systems the term used for this concept is
>         <firstterm>assert</firstterm> or <firstterm>assertion</firstterm>.
>         However as the keyword <methodname>assert</methodname> is already used
>         in many languages, Drools uses the keyword &amp; term <methodname>insert</methodname>.
>         You will often encounter these terms used interchangably in discussion of
>         Rules Engines.
>         </para>
>     </important>
>     <para>
>     When inserted, the rule is examined for matches against the rules.  The work
>     of determining what rules to fire is done during insertion, but no rules are
>     executed at this time.  The rules are executed when
>     <methodname>fireAllRules()</methodname> is called, and it should only be called
>     after you have inserted all your facts.
>     </para>
>     <para>
>     It is a common misconception that rule matching occurs when
>     <methodname>fireAllRules()</methodname> is called.
>     </para>
>     <para>
>     When an Object is inserted it returns a FactHandle. This FactHandle is the
>     token used to represent your inserted Object inside the WorkingMemory, it is
>     also how you will interact with the Working Memory when you wish to retract
>     or modify an object.
>     </para>
>     <programlisting language="java">Cheese stilton = new Cheese("stilton");
> FactHandle stiltonHandle = session.insert( stilton );</programlisting>
>     <para>
>     As mentioned in
>     <xref linkend="sect-JBoss_Rules_Reference_Manual-The_Drools_Rule_Engine-RuleBase" />
>     a Working Memory can operate in two assertions modes: <firstterm>equality</firstterm>
>     and <firstterm>identity</firstterm>.  Identity is the default mode.  The assertion
>     mode determines how the Working Memory stores the facts and how it compares the
>     newly inserted fact to previously inserted ones.  If the Working Memory
>     determines the fact to "be the same" as an already inserted one it will ignore 
>     the new fact and return the FactHandle for the previously inserted one.
>     </para>
>     <variablelist>
>         <varlistentry>
>             <term>Identity</term>
>             <listitem>
>             <para>
>             Identity Mode uses an <classname>IdentityHashMap</classname>to store all
>             asserted Objects. New facts being inserted are compared to existing facts
>             "by reference".  A new FactHandle will be returned if the object being
>             inserted is not a reference to an object that has been inserted previously.
>             </para>
>             </listitem>
>         </varlistentry>
>         <varlistentry>
>             <term>Equality</term>
>             <listitem>
>             <para>
>             Equality Mode uses a <classname>HashMap</classname> to store all asserted
>             Objects. New facts being inserted are compared to existing facts "by value".
>             A new FactHandle will be returned if the content of the object is not
>             identical to that of a previously inserted object.
>             </para>
>             </listitem>
>         </varlistentry>
>     </variablelist>
> </section>

--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira