[jbosscache-dev] Documentation feedback

[Vladimir Blagojevic]

Here is my feedback. Cheers.


Preface:

Rather than "Along with it's accompanying" it should be "Along with its
accompanying". 
"an FAQ". Even I know that this is a wrong preposition!
"When used." Use capital.
"A tree-structured, clustered". Missing comma.


Chapter 1:
1.1

"JBoss Cache is a tree-structured, clustered, transactional cache from
JBoss Cache." This sentence is confusing.

1.1.1 

"maintaining object references even affter replication or persistence".
Too many rrrss.
"More on concurrency, locking and isolation levels will be discussed
later". I would rather say 
"Concurrency, locking and isolation levels will be discussed later".

1.2 

"A The cache is organised as a tree, with a single root." Obvious
preposition problem.

In this section writer goes on to describe what "we" do in such and such
case. Maybe this can be rewritten 
not to say what we do but rather what Jboss cache does. Just a matter of
style. For example: "When a change 
is made to an object in the cache and that change is done in the context
of a transaction, then we defer the 
replication of changes until the transaction commits successfully"
becomes "When a change is made to an object 
in the cache and that change is done in the context of a transaction,
replication of changes is deferred until 
the transaction commits successfully."

2.2 

"and an instance is is created"

3.1

I would put introduction parameter *before* API image.

3.4 

I would put introduction parameter *before* API image. Should we explain
a bit more what pre boolean parameter 
is about as well as isLocal parameter.

3.5

Instead of term "CacheLoader(s)" use "cache loader(s)" when not
referring to a specific cache loader?

Mention not to use FileCacheLoader in production :)

4.2 

When we already mention that jboss cache is deployed as jboss-cache.jar
rather than the service archive 
the question immediately pops up - why? 


5.0 

Link to compatibility page?


6.1

"How your data is organised" ?? Ugh. Maybe something else... 

6.3

How Calls Are Invoked On The Data Structure -> "Node invocations"

6.3.3 

"This context is one that holds intermediate state for the duration..."
-> "IvocationContext holds intermediate state for the duration..." 

I would rewrite this section like this:

InvocationContext holds intermediate state for the duration of a single
cache method invocation, and is 
set up and destroyed by the InvocationContextInterceptor which sits at
the start of the chain. 

InvocationContext, as its name implies, holds contextual information
associated with a single cache method 
invocation. Contextual information includes associated
javax.transaction.Transaction or 
org.jboss.cache.transaction.GlobalTransaction, method invocation node
origin (InvocationContext.isOriginLocal()) 
as well as Option overrides (link ref).

InvocationContext can be obtained .blah blah blah... 


7.1.2.1

"single modification os broadcast rather" -> "single modification is
broadcast rather"



8.1 

loadEntireState and storeEntireState are outdated. They refer to the old
implementation.

I would replace these with some description similar to current javadocs.

http://labs.jboss.com/file-access/default/members/jbosscache/freezone/do
cs/2.0.0/api/org/jboss/cache/loader/CacheLoader.html


8.2

Shared is not explained in the same bullet point list as other elements
of configuration.


8.5 Strategies

Strategies of what? This section needs an introduction!

I would also add a use case for using several cacheloaders in a chain.
To be honest I never really 
understood the advantage of it. Increased fault tolerance?


8.5.4 "Replicated Caches With Each Cache Having It's Own Store" ->
"Replicated Caches With Each Cache Having Its Own Store"

"When used with a transactionm anager". Typo.

What is the advantage of each cacheloader having its own store? This
should be explained.

8.5 Should explain tradeoffs of various strategies!

This is a very interesting JBC feature and a topic in general to be left
in such non elaborated state. 



9.1.2 

"eventQueueSize - this optional parameter defines how large a queue of
items to evict to create". Huh???

policyClass explanation has several typos.



9.2.1 timeToLiveSeconds . I do not understand this parameter. Does it
mean that the node is swept away 
only if it has not be accessed in certain period of time? Idle is not
defined.


10.1.2.1

Isolation level explanation is a bit fuzzy. I like how isolation levels
are explained in clustering course material 
but I am not sure if we should include it here.


10.1.3.2

"it makes sense to aling the versions". Align spelling problem.

"in-memory reporesentation". Spelling.


11.2

Mention that ReplQueueInterval and ReplQueueMaxElements values are
considered only if UseReplQueue is true.

Mention that SyncReplTimeout should be bigger than
LockAcquisitionTimeout.