[jboss-cvs] JBossCache/docs/JBossCache-UserGuide/en/modules ...
Manik Surtani
msurtani at jboss.com
Mon Jan 29 12:40:35 EST 2007
User: msurtani
Date: 07/01/29 12:40:35
Modified: docs/JBossCache-UserGuide/en/modules preface.xml
configuration.xml eviction_policies.xml
cache_loaders.xml basic_api.xml architecture.xml
deployment.xml replication.xml
configuration_reference.xml introduction.xml
transactions.xml
Log:
Doc improvements
Revision Changes Path
1.6 +3 -3 JBossCache/docs/JBossCache-UserGuide/en/modules/preface.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: preface.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/preface.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- preface.xml 26 Jan 2007 04:04:31 -0000 1.5
+++ preface.xml 29 Jan 2007 17:40:35 -0000 1.6
@@ -9,12 +9,12 @@
When used, JBoss Cache refers to JBoss Cache Core, a tree-structured clustered, transactional cache.
Pojo Cache, also a part of the JBoss Cache distribution, is documented separately. (Pojo Cache is a cache that
deals with Plain Old Java Objects, complete with object relationships, with the ability to cluster such pojos
- while maintaining their relationships. Please see the Pojo Cache documentation for more information around this.)
+ while maintaining their relationships. Please see the Pojo Cache documentation for more information about this.)
</para>
<para>
- This book is targeted at both developers wishing to use the JBoss Cache as a clustering and caching library in
- their codebase, as well as people who wish to "OEM" JBoss Cache by building on and extending it's features. As
+ This book is targeted at both developers wishing to use JBoss Cache as a clustering and caching library in
+ their codebase, as well as people who wish to "OEM" JBoss Cache by building on and extending its features. As
such,
this book is split into two major sections - one detailing the "User" API and the other going much deeper into
specialist topics and the JBoss Cache architecture.
1.6 +10 -0 JBossCache/docs/JBossCache-UserGuide/en/modules/configuration.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: configuration.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/configuration.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- configuration.xml 23 Jan 2007 19:20:32 -0000 1.5
+++ configuration.xml 29 Jan 2007 17:40:35 -0000 1.6
@@ -75,6 +75,16 @@
before invoking your method on the cache.
</para>
<para>
+ E.g.:
+ <programlisting>
+
+ MyCustomDataVersion v = new MyCustomDataVersion();
+ cache.getInvocationContext().getOptionOverrides().setDataVersion(v);
+ Node ch = cache.getRoot().addChild(Fqn.fromString("/a/b/c"));
+
+ </programlisting>
+ </para>
+ <para>
See the javadocs on the
<literal>Option</literal>
class for details on the options available.
1.6 +1 -1 JBossCache/docs/JBossCache-UserGuide/en/modules/eviction_policies.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: eviction_policies.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/eviction_policies.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- eviction_policies.xml 24 Jan 2007 17:17:44 -0000 1.5
+++ eviction_policies.xml 29 Jan 2007 17:40:35 -0000 1.6
@@ -53,7 +53,7 @@
<itemizedlist>
<listitem><literal>wakeUpIntervalSeconds</literal> - this required parameter defines how often the eviction thread runs</listitem>
<listitem><literal>eventQueueSize</literal> - this optional parameter defines how large a queue of items to evict to create. If your eviction thread does not run often enough, you may need to increase this.</listitem>
- <listitem><literal>policyClass</literal> - this required, unless you set individual policyClass attributes on each and every region. This defines the eviction policy to use if one os not defined for a region.</listitem>
+ <listitem><literal>policyClass</literal> - this is required, unless you set individual policyClass attributes on each and every region. This defines the eviction policy to use if one is not defined for a region.</listitem>
</itemizedlist>
</para>
1.7 +14 -7 JBossCache/docs/JBossCache-UserGuide/en/modules/cache_loaders.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: cache_loaders.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/cache_loaders.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- cache_loaders.xml 24 Jan 2007 01:53:00 -0000 1.6
+++ cache_loaders.xml 29 Jan 2007 17:40:35 -0000 1.7
@@ -60,7 +60,7 @@
<literal>setCache()</literal>
are called. The latter can be used to
store a reference to the cache, the former is used to configure this
- instance of the CacheLoader. For example, here a database CacheLoader
+ instance of the <literal>CacheLoader</literal>. For example, here a database cache loader
could establish a connection to the database.
</para>
@@ -135,7 +135,7 @@
<section>
<title>Configuration</title>
- <para>The CacheLoader is configured as follows in the JBossCache XML
+ <para>Cache loaders are configured as follows in the JBoss Cache XML
file. Note that you can define several cache loaders, in
a chain. The impact is that the cache will look at all of the cache
loaders in the order they've been configured, until it finds a valid,
@@ -363,6 +363,13 @@
coordinator crashes or stops responding.
</para>
+ <para>
+ <literal>shared</literal>
+ indicates that the cache loader is shared among different cache instances, for example where all instances in a
+ cluster use the same JDBC settings t talk to the same remote, shared database. Setting this to <literal>true</literal>
+ prevents repeated and unnecessary writes of the same data to the cache loader by different cache instances. Default value is <literal>false</literal>.
+ </para>
+
</section>
@@ -388,7 +395,7 @@
loader checks for any potential character portability issues in the
location or tree node names, for example invalid characters, producing
warning messages. These checks can be disabled adding
- <literal>check.character.portability</literal> property and setting it to <literal>false</literal>
+ <literal>check.character.portability</literal> property to the <literal><![CDATA[<properties>]]></literal> element and setting it to <literal>false</literal>
(e.g., <literal>check.character.portability=false</literal>).
</para>
</listitem>
@@ -809,7 +816,7 @@
<literal>myRemoteServer:7500</literal>.
</para>
- <para>A typical use case could be multiple replicated instance of
+ <para>A typical use case could be multiple replicated instances of
JBoss Cache in the same cluster, all delegating to the same
TcpCacheServer instance. The TcpCacheServer might itself delegate to a
database via JDBCCacheLoader, but the point here is that - if we have
@@ -963,7 +970,7 @@
</section>
<section>
- <title>Replicated Caches With Each Cache Having It's Own Store</title>
+ <title>Replicated Caches With Each Cache Having Its Own Store</title>
<figure>
<title>2 nodes each having its own backend store</title>
@@ -985,8 +992,8 @@
</para>
<para>Note that JBoss Cache is <emphasis>not</emphasis> an
- XAResource, that means it doesn't implement recovery. When used with a
- transactionm anager that supports recovery, this functionality is not
+ XA Resource, that means it doesn't implement recovery. When used with a
+ transaction manager that supports recovery, this functionality is not
available.
</para>
1.5 +2 -2 JBossCache/docs/JBossCache-UserGuide/en/modules/basic_api.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: basic_api.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/basic_api.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- basic_api.xml 23 Jan 2007 15:23:23 -0000 1.4
+++ basic_api.xml 29 Jan 2007 17:40:35 -0000 1.5
@@ -41,7 +41,7 @@
// The factory method used creates a cache with default settings, and starts it.
// There are many overloaded factory methods; see CacheFactory javadocs for details.
- Cache cache = factory.createCache();
+ Cache cache = factory.createCache("/cache-configuration.xml");
// All nodes in the tree structure are identified by Fqn objects.
Fqn peterGriffinFqn = Fqn.fromString("/griffin/peter");
@@ -171,7 +171,7 @@
</listitem>
<listitem>
<literal>org.jboss.cache.loader.JDBCCacheLoader</literal>
- - uses a JDBC connection to store data. Connections could be created and maintained in an internal pool,
+ - uses a JDBC connection to store data. Connections could be created and maintained in an internal pool (uses the c3p0 pooling library)
or from a configured DataSource. The database this CacheLoader connects to could be local or remotely
located.
</listitem>
1.5 +3 -3 JBossCache/docs/JBossCache-UserGuide/en/modules/architecture.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: architecture.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/architecture.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- architecture.xml 23 Jan 2007 23:40:15 -0000 1.4
+++ architecture.xml 29 Jan 2007 17:40:35 -0000 1.5
@@ -31,7 +31,7 @@
underlying group communication between networked nodes is done using <ulink url="http://www.jgroups.org">JGroups</ulink>.
</para>
- <para>Any modification (see <link linkend="api">API chapter</link>) in one cache instance will be replicated to
+ <para>Any modifications (see <link linkend="api">API chapter</link>) in one cache instance will be replicated to
the other cache. Naturally, you can have more than 2 caches in a cluster.
Depending on the transactional settings, this replication will occur either after each modification or at the
end of a transaction, at commit time. When a new cache is created, it can optionally acquire the contents
@@ -190,7 +190,7 @@
<title>CacheLoaderManager</title>
<para>
Sets up and configures cache loaders. This class wraps individual <literal>CacheLoader</literal> instances
- in delegating classes, such as <literal>SingletonCacheLoader</literal> or <literal>AsyncCacheLoader</literal>,
+ in delegating classes, such as <literal>SingletonStoreCacheLoader</literal> or <literal>AsyncCacheLoader</literal>,
or may add the <literal>CacheLoader</literal> to a chain using the <literal>ChainingCacheLoader</literal>.
</para>
</section>
@@ -268,7 +268,7 @@
Types that the marshaller does not know or care about are serialized using the highly efficient
<ulink url="http://labs.jboss.com/portal/serialization">JBoss Serialization</ulink> library. This adds
<literal>jboss-serialization.jar</literal> as a dependency, but can be disabled by adding the following
- JVM argument <literal>-Dserialization.jboss=false</literal>. In this case serialization of unknown types
+ JVM argument <literal>-Djboss.serialization=false</literal>. In this case serialization of unknown types
will fall back to standard Java serialization.
</para>
</section>
1.4 +4 -4 JBossCache/docs/JBossCache-UserGuide/en/modules/deployment.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: deployment.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/deployment.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- deployment.xml 24 Jan 2007 01:53:00 -0000 1.3
+++ deployment.xml 29 Jan 2007 17:40:35 -0000 1.4
@@ -21,7 +21,7 @@
<para>First, the
<literal>jboss-cache.jar</literal> and all it's dependent jars
- have to be copied to the /lib
+ have to be copied to the server's <literal>/lib</literal>
directory and JBoss AS has to be restarted. Then a regular JBoss Cache
configuration file in XML format has to be copied to the /deploy
directory. The XML file format is the same as discussed in
@@ -35,8 +35,8 @@
<programlisting>
<![CDATA[
MBeanServer server=MBeanServerLocator.locateJBoss();
- CacheJmxWrapperMBean cacheWrapper;
- cacheWrapper = (CacheJmxWrapperMBean) MBeanProxyExt.create(CacheJmxWrapperMBean.class, "jboss.cache:service=Cache", server);
+ org.jboss.cache.jmx.CacheJmxWrapperMBean cacheWrapper;
+ cacheWrapper = (org.jboss.cache.jmx.CacheJmxWrapperMBean) MBeanProxyExt.create(CacheJmxWrapperMBean.class, "jboss.cache:service=Cache", server);
Cache cache = cacheWrapper.getCache();
cache.getRoot(); // etc etc
]]>
@@ -262,7 +262,7 @@
to access MBeans running in a server's MBean container.
</para>
<para>
- In additio, though, JBoss Cache MBeans are also accessible when running in a non-server environment if the
+ In addition, though, JBoss Cache MBeans are also accessible when running in a non-server environment if the
JVM is JDK 5.0 or later. When running a standalone cache in a JDK 5.0 environment, you can access the
cache's MBeans as follows.
</para>
1.7 +4 -4 JBossCache/docs/JBossCache-UserGuide/en/modules/replication.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: replication.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/replication.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- replication.xml 25 Jan 2007 16:57:30 -0000 1.6
+++ replication.xml 29 Jan 2007 17:40:35 -0000 1.7
@@ -26,7 +26,7 @@
<section>
<title>Replicated Caches</title>
- <para>Replicated caches replicate all changes to the other cache
+ <para>Replicated caches replicate all changes to some or all of the other cache
instances in the cluster. Replication can either happen after each
modification (no transactions), or at the end of a transaction (commit
time).</para>
@@ -46,7 +46,7 @@
cluster that they received and applied the modification successfully
(round-trip time). However, when a synchronous replication returns
successfully, the caller knows for sure that all modifications have been
- applied at all nodes, whereas this is not be the case with asynchronous
+ applied to all cache instances, whereas this is not be the case with asynchronous
replication. With asynchronous replication, errors are simply written to
a log. Even when using transactions, a transaction may succeed but
replication may not succeed on all cache instances.</para>
@@ -266,7 +266,7 @@
<literal>autoDataGravitation</literal>
- - Whether data gravitation occurs for every cache miss. My default this is set to
+ - Whether data gravitation occurs for every cache miss. By default this is set to
<literal>false</literal>
@@ -561,7 +561,7 @@
correct state. In-memory state can be transferred as well if the
desire is to have a "hot" cache -- one that has all relevant data in
memory when the cache begins providing service. (Note that the
- "CacheLoaderPreload" configuration parameter can be used as well to
+ <literal><![CDATA[<cacheloader><preload>]]></literal> element in the <literal>CacheLoaderConfig</literal>configuration parameter can be used as well to
provide a "warm" or "hot" cache without requiring an in-memory state
transfer. This approach somewhat reduces the burden on the cache
instance providing state, but increases the load on the persistent
1.5 +1 -1 JBossCache/docs/JBossCache-UserGuide/en/modules/configuration_reference.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: configuration_reference.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/configuration_reference.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- configuration_reference.xml 24 Jan 2007 18:05:25 -0000 1.4
+++ configuration_reference.xml 29 Jan 2007 17:40:35 -0000 1.5
@@ -463,7 +463,7 @@
<entry>
<para>For synchronous replication: time in milliseconds to wait
until replication acks have been received from all nodes in the
- cluster.
+ cluster. It is usually best that this is greater than the LockAcquisitionTimeout.
</para>
</entry>
</row>
1.5 +12 -13 JBossCache/docs/JBossCache-UserGuide/en/modules/introduction.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: introduction.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/introduction.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- introduction.xml 23 Jan 2007 03:11:44 -0000 1.4
+++ introduction.xml 29 Jan 2007 17:40:35 -0000 1.5
@@ -6,8 +6,8 @@
<title>What is JBoss Cache?</title>
<para>
- JBoss Cache is a tree-structured, clustered, transactional cache from JBoss Cache. It is
- is the backbone for many fundamental JBoss Application Server clustering services, including - in certain
+ JBoss Cache is a tree-structured, clustered, transactional cache. It is
+ the backbone for many fundamental JBoss Application Server clustering services, including - in certain
versions - clustering JNDI, HTTP and EJB sessions.
</para>
<para>
@@ -42,22 +42,21 @@
JBoss Cache offers a simple and straightforward API, where data (simple Java objects) can be placed in the
cache and, based on configuration options selected, this data may be one or all of:
<itemizedlist>
- <listitem>replicated to some or all cache instances in a cluster</listitem>
- <listitem>persisted to disk and/or a remote cluster ("far-cache")</listitem>
- <listitem>garbage collected from memory when memory runs low, and passivated to disk so state isn't lost
+ <listitem>replicated to some or all cache instances in a cluster.</listitem>
+ <listitem>persisted to disk and/or a remote cluster ("far-cache").</listitem>
+ <listitem>garbage collected from memory when memory runs low, and passivated to disk so state isn't lost.
</listitem>
</itemizedlist>
In addition, JBoss Cache offers a rich set of enterprise-class features:
<itemizedlist>
- <listitem>being able to participate in JTA transactions (works with Java EE compliant TransactionManagers)
+ <listitem>being able to participate in JTA transactions (works with Java EE compliant TransactionManagers).
</listitem>
- <listitem>attach to JMX servers and provide runtime statistics on the state of the cache</listitem>
- <listitem>allow client code to attach listeners and receive notifications on cache events</listitem>
+ <listitem>attach to JMX servers and provide runtime statistics on the state of the cache.</listitem>
+ <listitem>allow client code to attach listeners and receive notifications on cache events.</listitem>
</itemizedlist>
</para>
- <para>A
- The cache is organised as a tree, with a single root. Each node in the tree essentially contains a Map,
+ <para>A cache is organised as a tree, with a single root. Each node in the tree essentially contains a Map,
which acts as a store for key/value pairs. The only requirement placed on objects that are cached is that
they implement
<literal>java.io.Serializable</literal>
@@ -67,7 +66,7 @@
<para>JBoss Cache
can be either local or replicated. Local trees exist
only inside the JVM in which they are created, whereas replicated trees
- propagate any changes to all other replicated trees in the same cluster. A
+ propagate any changes to some or all other trees in the same cluster. A
cluster may span different hosts on a network or just different JVMs
on a single host.
</para>
@@ -99,7 +98,7 @@
default, with an optimistic locking scheme as a configurable option. With pessimistic locking, the degree
of concurrency can be tuned using a number of isolation levels, corresponding to database-style
transaction isolation levels, i.e., SERIALIZABLE, REPEATABLE_READ, READ_COMMITTED, READ_UNCOMMITTED and NONE.
- More on concurrency, locking and isolation levels will be discussed later.
+ More on concurrency, locking and isolation levels later.
</para>
</section>
@@ -115,7 +114,7 @@
to retroweave the Java 5.0 binaries.
</para>
<para>
- In addition, JBoss Cache has dependencies on
+ In addition, at a minimum, JBoss Cache has dependencies on
<ulink url="http://www.jgroups.org">JGroups</ulink>
, Apache's
<ulink
1.4 +3 -3 JBossCache/docs/JBossCache-UserGuide/en/modules/transactions.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: transactions.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/transactions.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- transactions.xml 24 Jan 2007 00:18:39 -0000 1.3
+++ transactions.xml 29 Jan 2007 17:40:35 -0000 1.4
@@ -3,7 +3,7 @@
<section>
<title>Concurrent Access</title>
- <para>JBoss Cache is a thread safe caching API, and uses it's own efficient mechanisms of controlling concurrent
+ <para>JBoss Cache is a thread safe caching API, and uses its own efficient mechanisms of controlling concurrent
access. It uses a pessimistic locking scheme by default for this purpose. Optimistic locking may alternatively
be used, and is discussed later.
</para>
@@ -165,7 +165,7 @@
<para>For example, if a transaction calls <literal>cache.getRoot().getChild( Fqn.fromString("/a/b/c") )</literal>,
nodes a, b and c are copied from the main data tree
and into the workspace. The data is versioned and all calls in the transaction work on the copy of the
- data rather than the actual data. When the transaction commits, it's workspace is merged back into the
+ data rather than the actual data. When the transaction commits, its workspace is merged back into the
underlying tree by matching versions. If there is a version mismatch - such as when the actual data tree
has a higher version than the workspace, perhaps if another transaction were to access the same data,
change it and commit before the first transaction can finish - the transaction throws a
@@ -193,7 +193,7 @@
<para>
Optimistic locking makes use of the <literal>DataVersion</literal> interface (and an internal and default
<literal>DefaultDataVersion</literal> implementation to keep a track of node versioning. In certain cases,
- where cached data is an in-memory reporesentation of data from an external source such as a database,
+ where cached data is an in-memory representation of data from an external source such as a database,
it makes sense to aling the versions used in JBoss Cache with the versions used externally. As such,
using the <link linkend="configuration.options">options API</link>, it is possible to set the <literal>DataVersion</literal>
you wish to use on a per-invocation basis, allowing you to implement the <literal>DataVersion</literal>
More information about the jboss-cvs-commits
mailing list