Hide Forgot
Affects: Documentation (Ref Guide, User Guide, etc.) Date of First Response: 2008-12-16 11:35:33 project_key: SOA remove chapter 3 : installation not required 44 screenshot that need trimming/resizing etc
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.