Chapters 1,2 and 8

Attachment: Added: JBoss_Rules_5_Reference_Guide_chapters_1_2_8.pdf

added chapter 3

Attachment: Added: JBoss_Rules_5_Reference_Guide_chapter_1 _2_3_8.pdf

Attachment: Removed: JBoss_Rules_5_Reference_Guide_chapter_1 _2_3_8.pdf 

Attachment: Removed: JBoss_Rules_5_Reference_Guide_chapters_1_2_8.pdf 

Ready for QE

Brand new sections & sections with revisions highlighted, specially, chapters 2, 3, 4.4 and 8

Attachment: Added: JBoss_Rules_5_Reference_Guide.pdf

Jarek - can you take the first look at this? Thanks!

Docs are/will be here:
   https://svn.devel.redhat.com/repos/jboss-soa/trunk/build-tools/docs/BRMS

Hey Darrin, this is what I have so far (chapter 2):

======== PAGE 10 ========

1. the fact being matched against must be of type Applicant
2. the value of age must be less than 18, and

The "and" at the end of the second bullet should be at the end of the first bullet:
1. the fact being matched against must be of type Applicant, and
2. the value of age must be less than 18

---------
System.err.println( builder.getErrors().toString() );
it's kbuilder, not builder:
System.err.println( kbuilder.getErrors().toString() );

--------
kbase.addKnowledgePackages( builder.getKnowledgePackages() );
it's kbuilder, not builder:
kbase.addKnowledgePackages( kbuilder.getKnowledgePackages() );

--------
Moreover this example won't run successfully, since the "valid" field is not set to true by default. So I would change:
Applicant applicant = new Applicant( "Mr John Smith", 16 );
to
Applicant applicant = new Applicant( "Mr John Smith", 16, tue );

and add a constructor to Applicant.java that looks like this:
public Applicant(String name, int age, boolean valid){
    	this.name = name;
    	this.age = age;
    	this.valid = valid;
}

--------

======== PAGE 11 ========

Because Java arrays do not implement the Iterable interface, so we have to use the Array method
asList().
The word "so" is not needed I think and it should be "Arrays", not "Array".

--------
This example also won't run successfully, since the Application's "valid" field is set to false by default. A constructor would help:

public Application(boolean valid){
		this.valid = valid;
}

and this line sholud be modified:
Application application = new Application();
to:
Application application = new Application(true);

Morevoer these two lines are wrong:
assertTrue( application() );
assertFalse( application() );

should be:

assertTrue( application.isValid() );
assertFalse( application.isValid() );
-------

ksession.execute(
   CommandFactory.newInsertIterable( new Object[] {application,applicant} )
);

should be:

ksession.execute(
   CommandFactory.newInsertElements(Arrays.asList(new Object[] {application,applicant}))
);

-------

cmds.add( CommandFactory.newInsert(new Person("Mr John Smith"), "mrSmith");
cmds.add( CommandFactory.newInsert( new Person( "Mr John Doe" ), "mrDoe" );
BatchExecutionResults results = ksession.execute( CommandFactory.newBatchExecution( cmds ) );

should be:

cmds.add( CommandFactory.newInsertObject(new Person("Mr John Smith"), "mrSmith"));
cmds.add( CommandFactory.newInsertObject( new Person( "Mr John Doe" ), "mrDoe" ));
ExecutionResults results = ksession.execute( CommandFactory.newBatchExecution( cmds ) );

-------

======== PAGE 14 ========

not Sprinkler( on === true )
one equlas sign to much:
not Sprinkler( on == true )

----------

kbuilder.add( ResourceFactory.newClasspathResource( "fireAlarm.drl", getClass() ), ResourceType.DRL );
newClasspathResource should have upper case "P":
kbuilder.add( ResourceFactory.newClassPathResource( "fireAlarm.drl", getClass() ), ResourceType.DRL );

---------
System.err.println( builder.getErrors().toString() );
should be kbuilder:
System.err.println( kbuilder.getErrors().toString() );
---------

StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();
should have these two line before:

KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
kbase.addKnowledgePackages( kbuilder.getKnowledgePackages() );
StatefulKnowledgeSession ksession = kbase.newStatefulKnowledgeSession();


======== PAGE 15 ========

Turn on the sprinkler for room office
Turn on the sprinkler for room kitchen
should be off instead of on:
Turn off the sprinkler for room office
Turn off the sprinkler for room kitchen

======== PAGE 16 ========

then
     System.out.println( "Hello Chuck" );
     end

There shouldn't be any white chars before "end"

======== PAGE 18 ========
last code sample has red characters, isthis intended?

======== PAGE 19 ========
date >= ap.start && <= ap.end,
should be:
date >= ap.start && <= ap.end,

-------------
acc.balance += $amount;
and
acc.balance -= $amount;
try to access private fields; should be:
acc.setBalance(acc.getBalance() + $amount);
and
acc.setBalance(acc.getBalance() - $amount);

Or you can mark the balance field in Account.java as public.

======== PAGE 20 ========

Same as above, accountNo and balance are not public but private, hence cannot be accessed without an accessor:
System.out.println( acc.accountNo + " : " + acc.balance );
should be:
System.out.println( acc.getAccountNo() + " : " + acc.getBalance() );

======== PAGE 21 ========
versions will add support for <remove>and <modify>.
missing space after <remove>:
versions will add support for <remove> and <modify>.

======== PAGE 22 ========
System.err.println( builder.getErrors().toString() );
kbuilder, not builder:
System.err.println( kbuilder.getErrors().toString() );

page iii
3.2.1. KnowledgePackage and Knowledge Definitions
KnowledgePackage is in bold, but shouldn't be.

======== PAGE 25 ========
This allows the behavior of the KnowledgeBuilder to modified. 

strange wording, maybe this sounds better:

This allows the behavior of the KnowledgeBuilder to *be* modified.
or:
This allows to modify the KnowledgeBuilder's behavior.

--------------
strange wording:
The first parameter is for Properties and is optional and may be left null for the default options will be used.

---------------
======== PAGE 26 ========

First 6 lines of example 3.6 should be reomoved:
KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
if( kbuilder.hasErrors() )
{
  System.out.println( kbuilder.getErrors() );
  return;
}


======== PAGE 29 ========
KnowledgePackages - the "s" at the end is bold, but shouldn't be

======== PAGE 30 ========
KnowledgeBaseFactory.createKnowledgeBaseConfiguration( null, cl );
should be:
KnowledgeBaseFactory.newKnowledgeBaseConfiguration( null, cl );

======== PAGE 31 ========
sample 3.15:
the ">" and "<" chars have been replaced with &lt; and &gt;
Also @SuppressWarnings is missing and it wouldn't compile anyway - KnowledgePackage and not KnowledgePackages and missing a cast

Collection&lt;KnowledgePackages&gt; kpkgs = in.readObject( );

should be:

@SuppressWarnings( "unchecked" )
Collection<KnowledgePackage> kpkgs = (Collection<KnowledgePackage>)in.readObject(  );

======== PAGE 32 ========
The KnowlegeBuilder is created using the KnowledgeBuilderFactory.
should be:
The KnowlegeAgent is created using the KnowledgeAgentFactory.

======== PAGE 33 ========
remove one "for"
This is also true for for notification.

======== PAGE 34 ========
KnowledgeBaseFactory.createKnowledgeBaseConfiguration( null, cl );
should be:
KnowledgeBaseFactory.newKnowledgeBaseConfiguration( null, cl );

KnowledgeBase kbase KnowledgeBaseFactory.newKnowledgeBase( kbaseConf );
should be:
KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase( kbaseConf );

Example 3.21. ChangeSet XML which adds a directories contents
I think this should be:
Example 3.21. ChangeSet XML which adds a directorie's contents


======== PAGE 35 ========
KnowledgeAgentConfiguration kaconf = KnowledgeAgentFactory.newKnowledgeAgentConfiguation();
typo in newKnowledgeAgentConfiguation, missing "r", should be:
KnowledgeAgentConfiguration kaconf = KnowledgeAgentFactory.newKnowledgeAgentConfiguration();


Example 3.23. Creating a new KnowledgeBuilder
should be:
Example 3.23. Creating a new KnowledgeBase


======== PAGE 36 ========
Example 3.24. Add KnowledgePackages to a KnowledgeBase
should be:
Example 3.24. Creating a new StatefulKnowledgeSession

this provides a unified API to work with process and rules. 
should be process*es*:
this provides a unified API to work with processes and rules. 

======== PAGE 37 ========
It is common to hear the two terms used interchangably; so expect to hear the two used interchangeably.
I would remove the second part ;) and fix the typo in interchangably (should be interchangeably)

---------
As mentioned in the KnowledgeBase section a WorkingMemory may operate in one of two assertion modes: equality or identity.
That hasn't been mentioned before, so I would change it to:
A WorkingMemory may operate in one of two assertion modes: equality or identity.

======== PAGE 38 ========

The Rule Engine must be notified of modified Facts, so that they can be reprocessed.
should be lower case "f" in Facts:
The Rule Engine must be notified of modified facts, so that they can be reprocessed.

---------

Within a rule the modify keyword is supported and provides block setters.
I would rephrase it:
Within a rule the modify statement is supported and provides calls to objects' setters.

--------

The WorkingMemory provides access to the Agenda, query executions as well getting access to named EntryPoints.
I would reword it:
The WorkingMemory provides access to the Agenda, query execution results as well as named EntryPoints.


======== PAGE 40 ========
The KnowledgeRuntime provides further methods that are applicableto both rules and processes.
"applicableto" - missing space


======== PAGE 43 ========
when calling FireAllRules().
lowercase "f", should be:
when calling fireAllRules().

======== PAGE 50 ========
kbuilder.add( ResourceFactory.newFileSystemResource( fileName ), ResourceType.DRL );
should be:
kbuilder.add( ResourceFactory.newFileResource( fileName ), ResourceType.DRL );

======== PAGE 51 ========
Eaxample 3.32 should be removed, it's a duplicate of 3.31

Eaxample 3.33:
cmds.add( CommandFactory.newInsert( new Person( "jon", 102 ), "person" ) ); - wrong method name
cmds.add( CommandFactory.newQuery( "Get People" "getPeople" ) - missing ","

should be:
cmds.add( CommandFactory.newInsertObject( new Person( "jon", 102 ), "person" ) );
cmds.add( CommandFactory.newQuery( "Get People", "getPeople" )


======== PAGE 54 ========
The second part of the first sentence sounds strange to me and it doesn't really fit with the second sentence IMHO:
Pipeline is not meant as a replacement for products like the more powerful Camel, but is aimed as a complimentary framework that ultimately can be integrated into more powerful pipeline frameworks. Instead it is a simple framework aimed at the specific JBoss Rules use cases.

-----
Two types of Pipelines are provided, both requiring a different PipelineContexts. - I think there should be no "s" at the end of "PipelineContexts"


======== PAGE 60 ========
StatefulSession didn't have this method and insert used the more traditional insert(...) method.
First "insert" should be removed:
StatefulSession didn't have this method and used the more traditional insert(...) method.

======== PAGE 62 ========
The CommandFactory allows for commands to be executed on those sessions, only only difference being the StatelessKnowledgeSession...
Remove one "only" and add "that" before "the StatelessKnowledgeSession"

----

CommandFactory.newInsert( new Cheese( "stilton" ), "stilton_id" ) );
should be:
CommandFactory.newInsertObject( new Cheese( "stilton" ), "stilton_id" ) );

-------

Stilton stilton = bresults.getValue( "stilton_id" );
should be:
Object stilton = bresults.getValue( "stilton_id" );

--------
Example 3.48. Insert Command
should be:
Example 3.48. InsertObject Command

----------

Eaxample 3.49:
Command cmd = CommandFactory.newInsertElements(Arrays.asList( Object[] {new Cheese("stilton"), new Cheese("brie"), new Cheese("cheddar"),});
added "new" and ")" and removed ",", should be:
Command cmd = CommandFactory.newInsertElements(Arrays.asList(new Object[] {new Cheese("stilton"), new Cheese("brie"), new Cheese("cheddar")}));

--------

Sorry, don't understand this sentence:
What you say, the method only allows for a single command?

--------

That's Where the BatchExecution
"Where" should be lower case:
That's where the BatchExecution

======== PAGE 63 ========

cmds.add( CommandFactory.newQuery("cheeses"));
should be:
cmds.add( CommandFactory.newQuery("cheeses", "queryName"));

---------------

So in the above example you saw how multiple commands where executed two of which populate the ExecutionResults.
IMHO the original text below sounds better, anyway "where" needs to be replaced with "were":
In the example above, multiple commands are executed, two of which populate the ExecutionResults.

---------
Please make sure the statement below is (still) true, IMHO it's not, there's no newQuery("id") method, you need to provide also a name for the query, hence there's no default value:
The query command defaults to use the same identifier as the query name, but it can also be mapped to a different identifier.

Chapter 8, Page 179, section:  8.1. Hello World

The table at the top of the page reads:

Name:       Banking Tutorial
Main class: org.drools.tutorials.banking
Type:       java application
Objective:  Tutorial that builds up knowledge of pattern matching, basic sorting and calculation
            rules.

But, the example program described is actually:

Name:       HelloWorldExample
Main class: org.drools.examples.HelloWorldExample
Type:       java application
Objective:  Tutorial that demonstrates simple Rules usage.

LOW priority edits to make if time permits:


page 49, Example 3.28. FileLogger

Comment - we should add a note explaining to users that the KnowledgeRuntimeLoggerFactory.newFileLogger() method appends a file extension of .log to the log file created. For example, this statement:

   KnowledgeRuntimeLoggerFactory.newFileLogger(ksession, "logdir/mylogfile");

   Creates a file named: logdir/mylogfile.log

-----------------------------------

page 179, 8.1. Hello World

Text (4th paragraph)

   Once we know the builder is error, we can do the following: get the Package collection; instantiate a KnowledgeBase from the KnowledgeBaseFactory; and add the package collection.

Comment - replace the text with:

   Once we know the builder is error free, we can do the following: get the Package collection; instantiate a KnowledgeBase from the KnowledgeBaseFactory; and add the package collection.

-----------------------------------

Page 183 - 1st line on the page

Text:

   1. Open the class org.drools.examples.FibonacciExample in your Eclipse IDE.

Comment:

   This should read:  org.drools.examples.HelloWorldExample

-----------------------------------

feedback incorporated & PDF checked in

A few issues left:

======== PAGE 10 ========
kbase.addKnowledgePackages( builder.getKnowledgePackages() );
it's kbuilder, not builder:
kbase.addKnowledgePackages( kbuilder.getKnowledgePackages() ); 

======== PAGE 11 ========

we have to use the Arraysmethod
no space after Arrays

======== PAGE 12 ========

assertFalse( application().isValid );
parenthesis in wrong place
assertFalse( application.isValid() );

======== PAGE 15 ========
System.err.println( builder.getErrors().toString() );
it's kbuilder, not builder:
System.err.println( kbuilder.getErrors().toString() );


======== PAGE 16/17 ========

then
     System.out.println( "Hello Chuck" );
     end

There shouldn't be any white chars before "end" 


======== PAGE 22 ========
versions will add support for <remove>and <modify>.
missing space after <remove>:
versions will add support for <remove> and <modify>.

======== PAGE 32 ========
KnowledgeBaseFactory.createKnowledgeBaseConfiguration( null, cl );
should be:
KnowledgeBaseFactory.newKnowledgeBaseConfiguration( null, cl ); 

======== PAGE 38 ========
Example 3.24. AddCreating a new StatefulKnowledgeSession
should be:
Example 3.24. Creating a new StatefulKnowledgeSession

======== PAGE 52 ========
kbuilder.add( ResourceFactory.newFilemResource( fileName ), ResourceType.DRL );
typo: newFilemResource, should be newFileResource:
kbuilder.add( ResourceFactory.newFileResource( fileName ), ResourceType.DRL );

======== PAGE 64 ========
The only only difference is that StatelessKnowledgeSession executes
remove one "only"

This doc has shipped for 5.0 GA so I'll set this JIRA back to Fixed in GA & create a new JIRA for CP01 with the last set of comments.

last comments moved to BRMS-129