[jbosscache-commits] JBoss Cache SVN: r8318 - enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US.
jbosscache-commits at lists.jboss.org
jbosscache-commits at lists.jboss.org
Thu Dec 10 00:35:53 EST 2009
Author: laubai
Date: 2009-12-10 00:35:51 -0500 (Thu, 10 Dec 2009)
New Revision: 8318
Modified:
enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/architecture.xml
enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/cache_loaders.xml
enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/eviction_policies.xml
enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/replication.xml
enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/transactions.xml
Log:
Added second part of changes for JBPAPP-2964.
Modified: enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/architecture.xml
===================================================================
--- enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/architecture.xml 2009-12-10 04:47:53 UTC (rev 8317)
+++ enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/architecture.xml 2009-12-10 05:35:51 UTC (rev 8318)
@@ -169,7 +169,7 @@
</para>
<para>
In addition to being visitable, commands are also replicable. The JBoss Cache marshallers know how to
- efficiently marshall commands and invoke them on remote cache instances using an internal RPC mechanism
+ efficiently marshal commands and invoke them on remote cache instances using an internal RPC mechanism
based on JGroups.
</para>
</section>
@@ -184,13 +184,11 @@
which sits at the start of the interceptor chain.
</para>
<para>
- <literal>InvocationContext</literal>
- , as its name implies, holds contextual information associated with a single cache
+ <literal>InvocationContext</literal>, as its name implies, holds contextual information associated with a single cache
method invocation. Contextual information includes associated
<literal>javax.transaction.Transaction</literal>
or
- <literal>org.jboss.cache.transaction.GlobalTransaction</literal>
- ,
+ <literal>org.jboss.cache.transaction.GlobalTransaction</literal>,
method invocation origin (
<literal>InvocationContext.isOriginLocal()</literal>
) as well as
@@ -240,13 +238,11 @@
in delegating classes, such as
<literal>SingletonStoreCacheLoader</literal>
or
- <literal>AsyncCacheLoader</literal>
- ,
+ <literal>AsyncCacheLoader</literal>,
or may add the
<literal>CacheLoader</literal>
to a chain using the
- <literal>ChainingCacheLoader</literal>
- .
+ <literal>ChainingCacheLoader</literal>.
</para>
</section>
Modified: enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/cache_loaders.xml
===================================================================
--- enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/cache_loaders.xml 2009-12-10 04:47:53 UTC (rev 8317)
+++ enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/cache_loaders.xml 2009-12-10 05:35:51 UTC (rev 8318)
@@ -141,7 +141,7 @@
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,
non-null element of data. When performing writes, all cache loaders are
- written to (except if the
+ written to, except if the
<literal>ignoreModifications</literal>
element has been set to
<literal>true</literal>
@@ -190,8 +190,7 @@
whereas a database implementation might define the database URL, name
and password to establish a database connection. This configuration is
passed to the cache loader implementation via
- <literal>CacheLoader.setConfig(Properties)</literal>
- . Note that
+ <literal>CacheLoader.setConfig(Properties)</literal>. Note that
backspaces may have to be escaped.
</para>
@@ -243,22 +242,20 @@
<literal>async</literal>
element
defaults to
- <literal>false</literal>
- .
+ <literal>false</literal>.
</para>
- <para>
- <emphasis role="bold">Note on using the
- <literal>async</literal>
- element:
- </emphasis>
- there is always the possibility of dirty reads since
+ <note>
+ <title>Using the <literal>async</literal> element</title>
+ </para>
+ There is always the possibility of dirty reads since
all writes are performed asynchronously, and it is thus impossible to
guarantee when (and even if) a write succeeds. This needs to be kept in
mind when setting the
<literal>async</literal>
element to true.
- </para>
+ </para>
+ </note>
<para>
<literal>ignoreModifications</literal>
@@ -271,10 +268,8 @@
used by all servers in
the network. This feature allows you to write to the 'local' file cache
loader but not the shared
- <literal>JDBCCacheLoader</literal>
- . This property defaults to
- <literal>false</literal>
- , so writes are propagated to all cache loaders
+ <literal>JDBCCacheLoader</literal>. This property defaults to
+ <literal>false</literal>, so writes are propagated to all cache loaders
configured.
</para>
@@ -284,8 +279,7 @@
(if
<literal>ignoreModifications</literal>
is
- <literal>false</literal>
- )
+ <literal>false</literal>)
when the cache loader starts up.
</para>
@@ -346,8 +340,7 @@
Default value for
<literal>enabled</literal>
is
- <literal>false</literal>
- .
+ <literal>false</literal>.
</para>
<para>
@@ -357,10 +350,8 @@
<literal>class</literal>
element that specifies the implementation class that provides the
singleton store functionality. This class must extend
- <literal>org.jboss.cache.loader.AbstractDelegatingCacheLoader</literal>
- , and if absent, it defaults to
- <literal>org.jboss.cache.loader.SingletonStoreCacheLoader</literal>
- .
+ <literal>org.jboss.cache.loader.AbstractDelegatingCacheLoader</literal>, and if absent, it defaults to
+ <literal>org.jboss.cache.loader.SingletonStoreCacheLoader</literal>.
</para>
<para>
@@ -395,8 +386,7 @@
<literal>true</literal>
if each node's cache loader is configured with a different
location. Default value is
- <literal>true</literal>
- .
+ <literal>true</literal>.
</para>
<para>
@@ -412,13 +402,10 @@
if exceeded. Default value is 20000.
</para>
- <para>
- <emphasis role="bold">Note on using the
- <literal>singletonStore</literal>
- element:
- </emphasis>
- setting
- up a cache loader as a singleton and using cache passivation (via
+ <note>
+ <title>Using the <literal>singletonStore</literal> element</title>
+ <para>
+ Setting up a cache loader as a singleton and using cache passivation (via
evictions) can lead to undesired effects. If a node is to be passivated
as a result of an eviction, while the cluster is in the process of
electing a new coordinator, the data will be lost. This is because no
@@ -426,7 +413,8 @@
the cluster will store the passivated node. A new coordinator is elected
in the cluster when either, the coordinator leaves the cluster, the
coordinator crashes or stops responding.
- </para>
+ </para>
+ </note>
</section>
</section>
@@ -447,7 +435,7 @@
configuration element
contains a
<literal>location</literal>
- property, which maps to a directory to be used as a persistent store.
+ property, which maps to a directory to be used as a persistent store
(e.g.,
<literal>location=/tmp/myDataStore</literal>
). Used mainly for testing and not recommended for production use.
@@ -455,8 +443,7 @@
<itemizedlist>
<listitem>
<para>
- <literal>FileCacheLoader</literal>
- , which is a simple filesystem-based implementation. By default, this cache
+ <literal>FileCacheLoader</literal>, which is a simple filesystem-based implementation. By default, this cache
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
@@ -503,19 +490,15 @@
<para>
<literal>BdbjeCacheLoader</literal>
, which is a cache loader implementation based on the Oracle/Sleepycat's
- <ulink url="http://www.oracle.com/database/berkeley-db/index.html">BerkeleyDB Java Edition
- </ulink>
- .
+ <ulink url="http://www.oracle.com/database/berkeley-db/index.html">BerkeleyDB Java Edition</ulink>.
</para>
</listitem>
<listitem>
<para>
- <literal>JdbmCacheLoader</literal>
- , which is a cache loader
+ <literal>JdbmCacheLoader</literal>, which is a cache loader
implementation based on the
- <ulink url="http://jdbm.sourceforge.net/">JDBM engine</ulink>
- , a fast and free alternative to
+ <ulink url="http://jdbm.sourceforge.net/">JDBM engine</ulink>, a fast and free alternative to
BerkeleyDB.
</para>
</listitem>
@@ -524,7 +507,7 @@
<para>Note that the BerkeleyDB implementation is much more efficient than
the filesystem-based implementation, and provides transactional
guarantees, but requires a commercial license if distributed with an
- application (see http://www.oracle.com/database/berkeley-db/index.html for
+ application (see <ulink url="http://www.oracle.com/database/berkeley-db/index.html">http://www.oracle.com/database/berkeley-db/index.html</ulink> for
details).
</para>
@@ -542,16 +525,14 @@
</listitem>
<listitem>
<para>
- <literal>ClusteredCacheLoader</literal>
- , which allows querying
+ <literal>ClusteredCacheLoader</literal>, which allows querying
of other caches in the same cluster for in-memory data via the same
clustering protocols used to replicate data. Writes are
<emphasis>not</emphasis>
'stored' though, as replication would
take care of any updates needed. You need to specify a property
called
- <literal>timeout</literal>
- , a long value telling the cache
+ <literal>timeout</literal>, a long value telling the cache
loader how many milliseconds to wait for responses from the cluster
before assuming a null value. For example,
<literal>timeout = 3000</literal>
@@ -568,8 +549,7 @@
<para>JBossCache is distributed with a JDBC-based cache loader
implementation that stores/loads nodes' state into a relational database.
The implementing class is
- <literal>org.jboss.cache.loader.JDBCCacheLoader</literal>
- .
+ <literal>org.jboss.cache.loader.JDBCCacheLoader</literal>.
</para>
<para>The current implementation uses just one table. Each row in the table
@@ -594,7 +574,10 @@
<para>
<literal>Fqn</literal>s are stored as strings. Node content is stored
as a BLOB.
- <emphasis>WARNING:</emphasis>
+ </para>
+
+ <warning>
+ <para>
JBoss Cache does not impose any
limitations on the types of objects used in
<literal>Fqn</literal>
@@ -602,8 +585,7 @@
cache loader requires
<literal>Fqn</literal>
to contain only objects of type
- <literal>java.lang.String</literal>
- . Another limitation for
+ <literal>java.lang.String</literal>. Another limitation for
<literal>Fqn</literal>
is its
length. Since
@@ -612,7 +594,8 @@
<literal>VARCHAR</literal>
which can store text values up to some
maximum length determined by the database in use.
- </para>
+ </para>
+ </warning>
<para>See
<ulink url="http://www.jboss.org/community/docs/DOC-10864">this wiki page</ulink>
@@ -832,7 +815,7 @@
</loaders>
]]></programlisting>
- <para>Cconfiguration example for a cache loader using c3p0 JDBC connection pooling:</para>
+ <para>Configuration example for a cache loader using c3p0 JDBC connection pooling:</para>
<programlisting role="XML"><![CDATA[
<loaders passivation="false" shared="false">
@@ -982,7 +965,7 @@
<listitem><para>
<literal>cache.s3.secure</literal>
-
- The default is<literal>false</literal>:
+ The default is <literal>false</literal>:
Traffic is sent unencrypted over the public Internet.
Set to
<literal>true</literal>
@@ -996,22 +979,22 @@
Name of the bucket to store data.
For different caches using the same access key, use a different bucket name.
Read the S3 documentation on the definition of a bucket.
- The default value is<literal>jboss-cache</literal>.</para>
+ The default value is <literal>jboss-cache</literal>.</para>
</listitem>
<listitem><para>
<literal>cache.s3.callingFormat</literal>
-
- One of<literal>PATH</literal>,<literal>SUBDOMAIN</literal>, or
+ One of<literal>PATH</literal>, <literal>SUBDOMAIN</literal>, or
<literal>VANITY</literal>.
Read the S3 documentation on the use of calling domains.
- The default value is<literal>SUBDOMAIN</literal>.</para>
+ The default value is <literal>SUBDOMAIN</literal>.</para>
</listitem>
<listitem><para>
<literal>cache.s3.optimize</literal>
-
- The default is<literal>false</literal>.
+ The default is <literal>false</literal>.
If true,
<literal>put(Map)</literal>
operations
@@ -1023,7 +1006,7 @@
<listitem><para>
<literal>cache.s3.parentCache</literal>
-
- The default is<literal>true</literal>.
+ The default is <literal>true</literal>.
Set this value to
<literal>false</literal>
if you are using multiple caches
@@ -1342,11 +1325,11 @@
the FileCacheLoader), or a shared database. Because both nodes access
the same store, they don't necessarily need state transfer on
startup.
- <footnote>
+ <note>
<para>Of course they can enable state transfer, if they want to
have a warm or hot cache after startup.
</para>
- </footnote>
+ </note>
Rather, the
<literal>FetchInMemoryState</literal>
attribute could be set to false, resulting in a 'cold' cache, that
@@ -1427,7 +1410,7 @@
cache are (a) replicated across the cluster and (b) persisted using
the cache loader. This means that all datastores have exactly the same
state. When replicating changes synchronously and in a transaction,
- the two phase commit protocol takes care that all modifications are
+ the two-phase commit protocol takes care that all modifications are
replicated and persisted in each datastore, or none is replicated and
persisted (atomic updates).
</para>
Modified: enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/eviction_policies.xml
===================================================================
--- enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/eviction_policies.xml 2009-12-10 04:47:53 UTC (rev 8317)
+++ enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/eviction_policies.xml 2009-12-10 05:35:51 UTC (rev 8318)
@@ -161,12 +161,14 @@
<literal>/a</literal>
and<literal>/a/b</literal>.
</para>
- <para>
- N.B. when adding attributes to a resident node, e.g.
- <literal>cache.put("/a", "k", "v")</literal>
- in the above example, it would make sense to mark the nodes
- as non-resident again and let them be considered for eviction..
- </para>
+ <note>
+ <para>
+ When adding attributes to a resident node, e.g.
+ <literal>cache.put("/a", "k", "v")</literal>
+ in the above example, it would make sense to mark the nodes
+ as non-resident again and let them be considered for eviction.
+ </para>
+ </note>
</section>
</section>
Modified: enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/replication.xml
===================================================================
--- enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/replication.xml 2009-12-10 04:47:53 UTC (rev 8317)
+++ enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/replication.xml 2009-12-10 05:35:51 UTC (rev 8318)
@@ -75,9 +75,8 @@
asynchronous or synchronous mode, JBoss Cache will use either a single
phase or
<ulink
- url="http://en.wikipedia.org/wiki/Two-phase_commit_protocol">two phase
- commit
- </ulink>
+ url="http://en.wikipedia.org/wiki/Two-phase_commit_protocol">two-phase
+ commit</ulink>
protocol, respectively.
</para>
@@ -179,8 +178,7 @@
which contains the logic used to
select buddies in a network. JBoss Cache currently ships with a
single implementation,
- <literal>NextMemberBuddyLocator</literal>
- ,
+ <literal>NextMemberBuddyLocator</literal>,
which is used as a default if no implementation is provided. The
<literal>NextMemberBuddyLocator</literal>
selects the next member in
@@ -226,8 +224,7 @@
<title>BuddyPools</title>
<para>Also known as
- <emphasis>replication groups</emphasis>
- , a buddy
+ <emphasis>replication groups</emphasis>, a buddy
pool is an optional construct where each instance in a cluster may
be configured with a buddy pool name. Think of this as an 'exclusive
club membership' where when selecting buddies,
@@ -489,8 +486,7 @@
<literal>InactiveOnStartup</literal>
property
is
- <literal>true</literal>
- . This property is used in
+ <literal>true</literal>. This property is used in
conjunction with region-based marshalling.
</para>
</listitem>
@@ -511,8 +507,7 @@
</para>
<para>After registration, the application calls
- <literal>cache.getRegion(fqn, true).activate()</literal>
- ,
+ <literal>cache.getRegion(fqn, true).activate()</literal>,
which initiates a partial state transfer of the relevant subtree's
state. The request is first made to the oldest cache instance in the
cluster. However, if that instance responds with no state, it is then
@@ -523,8 +518,7 @@
<para>Typically when region-based marshalling is used, the cache's
<literal>InactiveOnStartup</literal>
property is set to
- <literal>true</literal>
- . This suppresses initial state transfer,
+ <literal>true</literal>. This suppresses initial state transfer,
which would fail due to the inability to deserialize the transferred
state.
</para>
@@ -547,10 +541,8 @@
the
<literal>InactiveOnStartup</literal>
property is set to
- <literal>false</literal>
- . If it is
- <literal>true</literal>
- , state
+ <literal>false</literal>. If it is
+ <literal>true</literal>, state
transfer amongst the buddies only occurs when the application
activates the region on the various members of the group.
</para>
@@ -586,8 +578,7 @@
<para>"In-memory" state transfer is enabled by setting the cache's
<literal>FetchInMemoryState</literal>
configuration attribute to
- <literal>true</literal>
- .
+ <literal>true</literal>.
</para>
</listitem>
@@ -603,8 +594,7 @@
loader's
<literal>fetchPersistentState</literal>
attribute to
- <literal>true</literal>
- . If multiple cache loaders are configured
+ <literal>true</literal>. If multiple cache loaders are configured
in a chain, only one can have this property set to true; otherwise
you will get an exception at startup.
</para>
@@ -616,8 +606,7 @@
cache loader has
<literal>fetchPersistentState</literal>
set to
- <literal>true</literal>
- .
+ <literal>true</literal>.
</para>
</listitem>
</orderedlist>
Modified: enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/transactions.xml
===================================================================
--- enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/transactions.xml 2009-12-10 04:47:53 UTC (rev 8317)
+++ enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/transactions.xml 2009-12-10 05:35:51 UTC (rev 8318)
@@ -230,7 +230,7 @@
<literal>TransactionManager</literal>.
</para>
- <para>When the transaction commits, we initiate either a one- two-phase commit
+ <para>When the transaction commits, we initiate either a one-phase or two-phase commit
protocol. See <xref linkend="replication.tx" /> for details.
</para>
More information about the jbosscache-commits
mailing list