Bug 778577 (SOA-1049)

chapter 3 removed

image cleanup will have to be done in a future version

Assigning to QE for review

I first raised this comment in: https://jira.jboss.org/jira/browse/SOA-970

In reviewing this book, I think that apart from any small changes (such as those listed above), my real concern is its overall organization. Chapters 2-3 are interesting descriptions of rules engines and decision tables, but the book lacks a chapter that introduces the reader to Drools/Rules and defines/explains constructs such as

JBoss Rules Terms
  Fact ( application data )
  Working Memory ( stateful collection of facts )
  Production Memory ( the rules )
  Inference Engine ( JBoss Rules & RETE )
  Agenda ( conflict resolution )
  Salience ( priority )
From: http://www.cooug.org/brsig/event_details/presentations/2006_June_20_DRules.pdf

For 4.2, 4.3 , I'm not recommending a redesign of the book. I'm guessing that we'll have a completely new book to use for Drools 5? 

Other comments:

1.2.1.1. Working Memory creation

Drools 3.0.x had only one working memory type that worked like a stateful working memory. Drools
4.0.x introduces separate APIs for Stateful and Stateless working memories that are called now Rule
Sessions.

------> "now called"

1.2.1.2. Working Memory Actions
Drools 4.0.x now supports pluggable dialects and has built-in support for Java and MVEL scripting
language. In order to avoid keyword conflicts, the working memory actions were renamed as showed
bellow:

------> "below"

1.2.2. Rule Language Changes
The DRL Rule Language also has some backward incompatible changes as detailed bellow.

------> "below"

1.2.2.1. Working Memory Actions
The Working Memory actions in rule consequences were also changed in a similar way to the change
made in the API. The following table summarizes the change:

------> The following table summarizes the changes: 

1.2.2.2. Primitive support and unboxing
Drools 3.0.x did not had native support for primitive types and consequently, it auto-boxed all
primitives in it's respective wrapper classes. That way, any use of a boxed variable binding required a
manual unbox.
Drools 4.0.x has full support for primitive types and does not wrap values anymore. So, all previous
unwrap method calls must be removed from the DRL.

------> Drools 3.0.x did not had native support for primitive types, Consequently, it auto-boxed all
primitives in their respective wrapper classes. Any use of a boxed variable binding required a
manual unbox.
Drools 4.0.x has full support for primitive types and does not wrap values. All previous
unwrap method calls must be removed from the DRL. 

2.1.1. Introduction and Background

Drools is a Rule Engine that uses the Rule Based approached to implement an Expert System and is more
correctly classified as a Production Rule System.

------> Drools is a Rule Engine that uses the Rule Based approach to implement an Expert System and is more
correctly classified as a Production Rule System.

While a Production Rule System is a kind of Rule Engine and also an Expert System, the validation and expression evaluation
Rule Engines mention previously are not Expert Systems.

comment ------> While a Production Rule System is a kind of Rule Engine and also an Expert System, the validation and expression evaluation
Rule Engines mentioned previously are not Expert Systems.

A Production Rule System is turing complete with a focus on knowledge representation to express
propositional and first order logic in a concise, non ambiguous and declarative manner.

comment ------> "a turing machine?"

The Agenda manages the execution order of these conflicuting rules using a Conflict Resolution strategy.

comment ------> The Agenda manages the execution order of these conflicting rules using a Conflict Resolution strategy. 

2.3.1 First Order Logic

On Page 16

In Java we can say that a simple proposition is of the form "variable operator value", where we often
refer to 'value' as being a literal value, a proposition can be thought as a field constraint. Further to this
propositions can be combined with conjunctive and disjunctive connectives, which is the logic theorists
way of saying 'AND' and 'OR' (&& and ||).

Suggested rewording: ------>

In Java we can say that a simple proposition is of the form "variable operator value, " where we often
refer to 'value' as being a literal value, and a proposition can be thought as a field constraint. These
propositions can be combined with conjunctive and disjunctive connectives, which is the logic theorists'
way of saying 'AND' and 'OR' (&& and ||). 

2.5.4.2. Insertion

When an Object is insert it returns a FactHandle.

------> Comment "inserted"

New instance assertions will only return a new FactHandle if a not equal classes have been asserted.

------> Comment "if a not equal classes condition"

2.5.4.3. Retraction

Note that it is possible to have rules that depend on the "non existence" of a fact, in which case retracting a fact may cause a rule to activate (see the 'not' and 'exist' keywords). 

------> Comment "(see the 'not' - section 5.2.2.5 and 'exist' - section 5.2.2.6 - keywords)

2.5.4.6. Shadow Facts

There's generally two ways to guarantee truthfulness.

------> Comment "There are two ways to guarantee truthfulness."

2.5.4.8. Initial Fact

To support conditional elements like "not" (which will be covered later on),

------> Comment "(which will be covered later on in chapter 5)"

2.5.6. Stateless Session

The execute method iterates the objects inserting each and calling fireAllRules() at the end; session finished.

------> Comment "and calling fireAllRules() at the end when the session is finished."

"StatelessSessions also support sequential mode, which is a special optimized mode that uses less memory and executes faster; please see the Sequential section for more details."

------> Comment "please see the Sequential section (section 2.5.10) for more details."

ReferenceOriginalGlobalExporter just passes a reference to the original Global Resolver; the latter should be used with care as identifier instances can be changed at any time by the StatelessSession and the GlobalResolver may not be
serializable freindly.

------> Comment - just drop the misspelled word "freindly"

2.5.7.2. Agenda Groups
Agenda groups are a way to partition rules (activations, actually) on the agenda. At any one time, only one group has "focus" which means that the activations for rules in that group will only take effect -
you can also have rules "auto focus" which means the focus for its agenda group is taken when that rules conditions are true.

------> Comment "when those rules' conditions are true"

Agenda groups are a handy way to create a "flow" between grouped rules.

------> Comment: The previous paragraph indicated that a flow between rules cannot be relied on. Are we saying that the flow between groups is a way around that limitation?

2.5.10. Sequential Mode

1. Order the Rules by salience and position in the ruleset (just sets a sequence attribute on the rule terminal node). 4

------> Comment: Delete the "4"

3.1.4.1. Syntax of templates

The "$param" place holder is used in templates to indicate where data form the cell will be interpolated

------> Comment "from"

For consequences: How snippets are rendered also depends on if there is anything in the row immediately above it. If there is nothing there, the output is simple the interpolated snippets

------> Comment: Change "simple" to "simply"

4.1. Introduction

------> This section refers to "Red Hat Developer Studio." Is this name being used at all? We only refer to it as JBDS.

Note you can get the plug in either as a zip to download, or from an update site (refer to the chapter on installation).

------> There is no "installation" chapter in this book.

Figures 4.3, 4.4 - these include a very old Rules icon - probably from Rules 3 in 2006 (figure 4.6 shows a date of 2006) - when can we get these updated? If not in 4.2 CP03 then in 4.3 FP01?

5.5.2.1. Pattern

The subsections in this^ section are numbered:

5.5.2.1.1. Field Constraints
5.5.2.1.1.1. JavaBeans as facts
5.5.2.1.1.3.1. Operators

It's hard to read and reference chapter sections with 7-level-deep section numbers - why not move section 5.5.2.1 "Pattern" to the same level as 5.5 "Rule" - 4-levels is about as deep as most people can follow.

incorporating changes

6.1. Deployment options

If you are using the BRMS, you should use the RuleAgent (the detailed documentation for this is in the chapter on the BRMS).

------> comment: There is no chapter on the BRMS in this doc.

6.1.1. Deployment using the RuleAgent

The easiest and most automated way to deploy rules is to use the RuleAgent. This is described in detail in the BRMS user guide.

------> comment: Do we have a BRMS user guide?

Index

BeanShell, 12
------> Comment: The only reference to BeanShell is a question on page 12.

C
Collection, 108, 108
------> Comment: The term is used on pages 1, 17, 42, etc. But not ever really defined in the context of Rules

Domain Specific Languages, 128
------> Comment: It's on pages 79 and 128

DSL, 129
------> Comment: It's used on pages 128-133

I think we need to remove/replace the entire index. It's very short and includes multiple errors. 

feedback incorporated with the following exceptions:
JBoss Rules Terms - I'll work on this for FP01, see what comes out of the newer docs & port it back in a future CP

2.5.4.2. Insertion
New instance assertions will only return a new FactHandle if a not equal classes have been asserted.
------> Comment "if a not equal classes condition"
Neither form makes grammatical sense 

2.5.7.2. Agenda Groups
Agenda groups are a handy way to create a "flow" between grouped rules.
------> Comment: The previous paragraph indicated that a flow between rules cannot be relied on. Are we saying that the flow between groups is a way around that limitation?
Need clarfication on intent of content, specifically the meaning of the term 'flow' in this context

Actually fixed the "Insertions" section, just the agenda groups 'flow" item.  Will create a FP01 JIRA for it.

Assigning to QE for verification and closure.

Nothing major so far - did the doc pick up all the changes from 4.3 CP03?

Index
   Remove the index - it's very incomplete and includes some errors

Section 5.5.2. Left Hand Side (when) Conditional Elements
   below misspelled as bellow


Comments from:  https://jira.jboss.org/jira/browse/SOA-1049?focusedCommentId=12444597#action_12444597

These are still in the doc

2.5.4.2. Insertion

When an Object is insert it returns a FactHandle.

------> Comment "inserted"

New instance assertions will only return a new FactHandle if a not equal classes have been asserted.

------> Comment "if a not equal classes condition"

2.5.4.3. Retraction

Note that it is possible to have rules that depend on the "non existence" of a fact, in which case retracting a fact may cause a rule to activate (see the 'not' and 'exist' keywords).

------> Comment "(see the 'not' - section 5.2.2.5 and 'exist' - section 5.2.2.6 - keywords)

2.5.4.6. Shadow Facts

There's generally two ways to guarantee truthfulness.

------> Comment "There are two ways to guarantee truthfulness."

2.5.4.8. Initial Fact

To support conditional elements like "not" (which will be covered later on),

------> Comment "(which will be covered later on in chapter 5)"

2.5.6. Stateless Session

The execute method iterates the objects inserting each and calling fireAllRules() at the end; session finished.

------> Comment "and calling fireAllRules() at the end when the session is finished."

"StatelessSessions also support sequential mode, which is a special optimized mode that uses less memory and executes faster; please see the Sequential section for more details."

------> Comment "please see the Sequential section (section 2.5.10) for more details."

ReferenceOriginalGlobalExporter just passes a reference to the original Global Resolver; the latter should be used with care as identifier instances can be changed at any time by the StatelessSession and the GlobalResolver may not be
serializable freindly.

------> Comment - just drop the misspelled word "freindly"

2.5.7.2. Agenda Groups
Agenda groups are a way to partition rules (activations, actually) on the agenda. At any one time, only one group has "focus" which means that the activations for rules in that group will only take effect -
you can also have rules "auto focus" which means the focus for its agenda group is taken when that rules conditions are true.

------> Comment "when those rules' conditions are true"

Agenda groups are a handy way to create a "flow" between grouped rules.

------> Comment: The previous paragraph indicated that a flow between rules cannot be relied on. Are we saying that the flow between groups is a way around that limitation?

2.5.10. Sequential Mode

1. Order the Rules by salience and position in the ruleset (just sets a sequence attribute on the rule terminal node). 4

------> Comment: Delete the "4"

3.1.4.1. Syntax of templates

The "$param" place holder is used in templates to indicate where data form the cell will be interpolated

------> Comment "from"

For consequences: How snippets are rendered also depends on if there is anything in the row immediately above it. If there is nothing there, the output is simple the interpolated snippets

------> Comment: Change "simple" to "simply"

4.1. Introduction

------> This section refers to "Red Hat Developer Studio." Is this name being used at all? We only refer to it as JBDS.

I think the last comment should have attach attached to SOA-1171

Re-opened in error - closing.