Bug 1043574 - Admin Guide issues - parts 1 - 5
Summary: Admin Guide issues - parts 1 - 5
Keywords:
Status: CLOSED CURRENTRELEASE
Alias: None
Product: JBoss Data Grid 6
Classification: JBoss
Component: Documentation
Version: 6.2.0
Hardware: Unspecified
OS: Unspecified
unspecified
high
Target Milestone: GA
: 6.2.0
Assignee: Rakesh
QA Contact:
URL:
Whiteboard:
Depends On:
Blocks:
TreeView+ depends on / blocked
 
Reported: 2013-12-16 16:42 UTC by Jiri Holusa
Modified: 2014-01-16 00:01 UTC (History)
4 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Environment:
Last Closed: 2014-01-16 00:01:45 UTC
Type: Bug


Attachments (Terms of Use)

Description Jiri Holusa 2013-12-16 16:42:05 UTC
Here are my notes to parts 1 - 5 of ADmin Guide (http://file.bne.redhat.com/~mhusnain/Admin_Guide/)

#1 Section 1.7. Red Hat JBoss Data Grid Cache Architecture 
(http://file.bne.redhat.com/~mhusnain/Admin_Guide/#JBoss_Data_Grid_Cache_Architecture)

First item of the list after picture (starting with "Elements that a user cannot directly interact with (depicted within a dark box)". This paragraph is not correct, it doesn't match the diagram nor the reality and the new paragraph says pretty much the opposite of this (e.g. that we cannot interact with Cache but few lines later we can). I suggest replacing it with (or something similiar):

Elements that a user cannot directly interact with (depicted within a dark box). In Remote Client-Server mode, this consists of Persistent Store, Cache, Cache Manager, L1 Cache and Server Module. In Library mode, user cannot directly interact with Persistent Store and L1 Cache.


#2 Section 1.7. Red Hat JBoss Data Grid Cache Architecture, subsection Library and Remote Client-Server Mode Architecture
(http://file.bne.redhat.com/~mhusnain/Admin_Guide/#JBoss_Data_Grid_Cache_Architecture)

In second paragraph (last paragraph of section 1.7) in the second sentence, there's a typo, the sentence should start with capital A. ("additionally, the Application usually resides in a different JVM,...") 

I'm not a native speaker, so maybe I'm wrong, but few sentences further, there is "..o.er the network using one of the supported protocols such as Memcached, Hot Rod, or REST." Is the comma between "Hotrod, or REST" correct or is it typo? Seriously don't know, just looks strange to me :-)


#3 Section 1.9.1. The Asynchronous API
(http://file.bne.redhat.com/~mhusnain/Admin_Guide/#About_the_Asynchronous_API)

In the last paragraph, there's 

For example, in a cache parameterized as Cache(String, String), Cache.put(String key, String value) returns a String, while Cache.putAsync(String key, String value) returns a Future(String). 

Since this is talking about parametrization, this is actually a Java code, I would suggest to change it into a correct code manner like this:

For example, in a cache parameterized as Cache<String, String>, Cache.put(String key, String value) returns a String, while Cache.putAsync(String key, String value) returns a Future<String>. 

#4 Section 3.2.1. Create a New RemoteCacheManager
(http://file.bne.redhat.com/~mhusnain/Admin_Guide/#Create_a_New_RemoteCacheManager)

First code snippet, please add following imports at the beginning of the snippet since it's little confusing, because another classes with the same name exists in other packages.

import org.infinispan.client.hotrod.configuration.Configuration;
import org.infinispan.client.hotrod.configuration.ConfigurationBuilder;

#5 Section 6.5.1. Sample XML Configuration for the Root Logger
(http://file.bne.redhat.com/~mhusnain/Admin_Guide/#Sample_XML_Configuration_for_the_Root_Logger)

Since there's not a feature like this in the server (or it doesn't behave as expected, see: https://bugzilla.redhat.com/show_bug.cgi?id=1040961), please remove the item 2 (Define the filter-spec Property) and also the code snippet. Also remove the line with <filter-spec> element from the third snippet in this section (List handlers)

#6 Section 6.5.3. Sample XML Configuration for a Console Log Handler, item 5 (Define the filter-spec Property)
In the code snippet there probably happend HTML entity substituion but that's incorrect. On the line with <filter-spec> element, instean of
<filter-spec value="not(match(&amp;quot;JBAS.*&amp;quot;))"/>

must be
<filter-spec value="not(match(&quot;JBAS.*&quot;))"/>

The same thing also in the following code snippet in item 6 Specify the formatter.

#7 Section 6.4. Logging Attributes
In second paragraph, second sentence at the end, there is "(ordered by lowest to highest)", please add "(ordered by lowest to highest severity)". 

In third paragraph, I suggest a clarification. Third sentece of this paragraph:
Log categories and handlers are assigned a log level and they only process log messages of that level or higher.

Please change this to:
Log categories and handlers are assigned a log level and they only process log messages of that numeric value or higher.

#8 Section 6.4.3. About Log Categories

Second paragraph, currently this:
The log messages to capture are defined by their Java package of origin and log level. Messages from classes in that package and of that log level or lower are captured by the log category and sent to the specified log handlers. As an example, the DEBUG log level results in log values of 300, 400 and 500 are captured. 

should be corrected to:
The log messages to capture are defined by their Java package of origin and log level. Messages from classes in that package and of that log level or higher (with greater or equal numeric value) are captured by the log category and sent to the specified log handlers. As an example, the WARNING log level results in log values of 900, 1000 and 1100 are captured. 

#9 Section 7.2. Local Mode
Third paragraph, there's a typo "read-biased", should be "read-based".

#10 8.6. Configure Distribution Mode (Library Mode)
Item 2: Specify the Remote Call Timeout - please insert that the time is in milliseconds.

Exactly the same in:
9.4. Configure Replication Mode (Library Mode)
10.3. Configure Invalidation Mode (Library Mode)

#11 Section 8.8.1. Distributed GET and PUT Operation Resource Usage
This paragraph:
Disable the Flag.SKIP_REMOTE_LOOKUP flag for ...

rephrase that as:
Use the Flag.SKIP_REMOTE_LOOKUP flag for ...

#12 Section 10.2. Configure Invalidation Mode (Remote Client-Server Mode)
First paragraph, second sentence, instead of "Replication mode" should be "Invalidation mode"

That's all what I have found in parts 1 - 5. 
Thank you :-)

Comment 2 gsheldon 2013-12-17 07:13:08 UTC
Assigning this to Bobb.

Comment 3 Rakesh 2013-12-18 07:11:06 UTC
JBoss Data Grid introductory chapter removed from all the guides except the GSG as per Divya's need. So the introductory chapter edits will be performed only in the GSG guide. 

Due to the intro chapter removal, chapter numbers and topic numbers in Admin guide is different from what is mentioned above. The correct numbers will be added in this bug subsequently.

Comment 6 Rakesh 2013-12-18 14:10:58 UTC
Jiri, the changes are made. Please have a look.

Comment 10 Jiri Holusa 2013-12-19 09:18:24 UTC
All right, I haven't found any more issues. You can set it ON_QA now :-)

Thanks you!

Comment 11 Rakesh 2013-12-23 09:42:35 UTC
Awaiting docstage to be up and running to verify.

Comment 12 Misha H. Ali 2014-01-07 23:35:18 UTC
Jiri, if you have already verified all the required changes on the docbuilder links, please set this bug to VERIFIED. If there is still some action you need us to take, please let us know and set it back to ASSIGNED.

Comment 13 Tomas Sykora 2014-01-08 16:38:42 UTC
Excellent work both Jirka and Rakesh!!

Comment 14 Misha H. Ali 2014-01-16 00:01:45 UTC
The fix for this bug is now generally released and available here:

https://access.redhat.com/site/documentation/en-US/Red_Hat_JBoss_Data_Grid/6.2/index.html


Note You need to log in before you can comment on or make changes to this bug.