[jboss-cvs] JBossCache/docs/JBossCache-UserGuide/en/modules ...
Manik Surtani
manik at jboss.org
Wed May 30 07:56:45 EDT 2007
User: msurtani
Date: 07/05/30 07:56:45
Modified: docs/JBossCache-UserGuide/en/modules
configuration_reference.xml transactions.xml
Log:
JBCACHE-1033
Revision Changes Path
1.15 +91 -33 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.14
retrieving revision 1.15
diff -u -b -r1.14 -r1.15
--- configuration_reference.xml 30 May 2007 03:06:46 -0000 1.14
+++ configuration_reference.xml 30 May 2007 11:56:45 -0000 1.15
@@ -8,7 +8,7 @@
shipped with the JBoss Cache distribution and tweak according to your needs rather than write one from scratch.
</para>
<programlisting>
-<![CDATA[
+ <![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!-- ===================================================================== -->
@@ -163,8 +163,11 @@
Reference table of XML attributes
</title>
<para>A list of definitions of each of the XML attributes used above. If the
- description of an attribute states that it is <emphasis>dynamic</emphasis>,
- that means it can be changed after the cache is created and started.</para>
+ description of an attribute states that it is
+ <emphasis>dynamic</emphasis>
+ ,
+ that means it can be changed after the cache is created and started.
+ </para>
<informaltable frame="all">
<tgroup cols="2">
@@ -185,7 +188,9 @@
<entry>
<para>An XML element that contains detailed buddy replication
- configuration. See <link linkend="br">section on Buddy Replication</link> for details.
+ configuration. See
+ <link linkend="br">section on Buddy Replication</link>
+ for details.
</para>
</entry>
</row>
@@ -197,7 +202,9 @@
<entry>
<para>An XML element that contains detailed cache loader
- configuration. See <link linkend="cache_loaders">chapter on Cache Loaders</link> for details.
+ configuration. See
+ <link linkend="cache_loaders">chapter on Cache Loaders</link>
+ for details.
</para>
</entry>
</row>
@@ -208,7 +215,11 @@
</entry>
<entry>
- <para><emphasis>Deprecated</emphasis>. Use <literal>CacheLoaderConfig</literal>.
+ <para>
+ <emphasis>Deprecated</emphasis>
+ . Use
+ <literal>CacheLoaderConfig</literal>
+ .
</para>
</entry>
</row>
@@ -267,7 +278,11 @@
<entry>
<para>Configuration parameter for the specified eviction policy.
- See <link linkend="eviction_policies">chapter on eviction policies</link> for details. This property is <emphasis>dynamic</emphasis>.
+ See
+ <link linkend="eviction_policies">chapter on eviction policies</link>
+ for details. This property is
+ <emphasis>dynamic</emphasis>
+ .
</para>
</entry>
</row>
@@ -297,8 +312,15 @@
<entry>
<para>Whether or not to acquire the initial in-memory state from
existing members. Allows for hot caches when enabled. Also
- see the <literal>fetchPersistentState</literal> element in
- <literal>CacheLoaderConfig</literal>. Defaults to <literal>true</literal>. This property is <emphasis>dynamic</emphasis>.
+ see the
+ <literal>fetchPersistentState</literal>
+ element in
+ <literal>CacheLoaderConfig</literal>
+ . Defaults to
+ <literal>true</literal>
+ . This property is
+ <emphasis>dynamic</emphasis>
+ .
</para>
</entry>
</row>
@@ -363,7 +385,9 @@
<entry>
<para>Time in milliseconds to wait for a lock to be acquired. If
- a lock cannot be acquired an exception will be thrown. This property is <emphasis>dynamic</emphasis>.
+ a lock cannot be acquired an exception will be thrown. This property is
+ <emphasis>dynamic</emphasis>
+ .
</para>
</entry>
</row>
@@ -377,7 +401,9 @@
<para>Controls whether inserting or removing a node requires a write
lock on the node's parent (when pessimistic locking is used) or whether
it results in an update of the parent node's version (when optimistic
- locking is used). The default value is <code>false</code>.
+ locking is used). The default value is
+ <code>false</code>
+ .
</para>
</entry>
</row>
@@ -388,8 +414,12 @@
</entry>
<entry>
- <para>An instance of <literal>org.jboss.cache.marshall.Marshaller</literal> used to serialize data to byte streams.
- Defaults to <literal>org.jboss.cache.marshall.VersionAwareMarshaller</literal> if not specified.
+ <para>An instance of
+ <literal>org.jboss.cache.marshall.Marshaller</literal>
+ used to serialize data to byte streams.
+ Defaults to
+ <literal>org.jboss.cache.marshall.VersionAwareMarshaller</literal>
+ if not specified.
</para>
</entry>
</row>
@@ -403,15 +433,21 @@
<para>The JMX object name of the service that defines the JGroups multiplexer.
In JBoss AS 5.0 this service is normally defined in the jgroups-multiplexer.sar.
This XML attribute can only be handled by the JBoss AS MBean deployment services;
- if it is included in a file passed to a <literal>CacheFactory</literal> the
+ if it is included in a file passed to a
+ <literal>CacheFactory</literal>
+ the
factory's creation of the cache will fail. Inside JBoss AS, the attribute should
be specified using the "depends optional-attribute-name" syntax shown in
the example above. Inside the AS if this attribute
- is defined, an instance of <literal>org.jgroups.jmx.JChannelFactoryMBean</literal>
- will be injected into the <literal>CacheJmxWrapper</literal> which will use
+ is defined, an instance of
+ <literal>org.jgroups.jmx.JChannelFactoryMBean</literal>
+ will be injected into the
+ <literal>CacheJmxWrapper</literal>
+ which will use
it to obtain a multiplexed JGroups channel. The configuration
of the channel will be that associated with
- <literal>MultiplexerStack</literal>.
+ <literal>MultiplexerStack</literal>
+ .
The
<literal>ClusterConfig</literal>
attribute will be ignored.
@@ -477,7 +513,11 @@
<entry>
<para>Time in milliseconds for elements from the replication
- queue to be replicated. Only used if <literal>UseReplQueue</literal> is enabled. This property is <emphasis>dynamic</emphasis>.
+ queue to be replicated. Only used if
+ <literal>UseReplQueue</literal>
+ is enabled. This property is
+ <emphasis>dynamic</emphasis>
+ .
</para>
</entry>
</row>
@@ -489,7 +529,11 @@
<entry>
<para>Max number of elements in the replication queue until
- replication kicks in. Only used if <literal>UseReplQueue</literal> is enabled. This property is <emphasis>dynamic</emphasis>.
+ replication kicks in. Only used if
+ <literal>UseReplQueue</literal>
+ is enabled. This property is
+ <emphasis>dynamic</emphasis>
+ .
</para>
</entry>
</row>
@@ -506,7 +550,9 @@
<literal>false</literal>
. There is a performance penalty to enabling this, especially when running
in a large cluster, but the upsides are greater cluster-wide data integrity. See the chapter on
- clustered caches for more information on this. This property is <emphasis>dynamic</emphasis>.
+ clustered caches for more information on this. This property is
+ <emphasis>dynamic</emphasis>
+ .
</para>
</entry>
</row>
@@ -519,8 +565,12 @@
<entry>
<para>For synchronous replication: time in milliseconds to wait
until replication acks have been received from all nodes in the
- cluster. It is usually best that this is greater than <literal>LockAcquisitionTimeout</literal>.
- This property is <emphasis>dynamic</emphasis>.
+ cluster. It is usually best that this is greater than
+ <literal>LockAcquisitionTimeout</literal>
+ .
+ This property is
+ <emphasis>dynamic</emphasis>
+ .
</para>
</entry>
</row>
@@ -537,7 +587,9 @@
<literal>false</literal>
. There is a performance penalty to enabling this, especially when running
in a large cluster, but the upsides are greater cluster-wide data integrity. See the chapter on
- clustered caches for more information on this. This property is <emphasis>dynamic</emphasis>.
+ clustered caches for more information on this. This property is
+ <emphasis>dynamic</emphasis>
+ .
</para>
</entry>
</row>
@@ -551,7 +603,7 @@
<para>The fully qualified name of a class implementing
TransactionManagerLookup. Default is
JBossTransactionManagerLookup. There is also an option of
- DummyTransactionManagerLookup for example.
+ GenericTransactionManagerLookup for example.
</para>
</entry>
</row>
@@ -562,7 +614,11 @@
</entry>
<entry>
- <para><emphasis>Deprecated</emphasis>. Use <literal>ExposeManagementStatistics</literal>.
+ <para>
+ <emphasis>Deprecated</emphasis>
+ . Use
+ <literal>ExposeManagementStatistics</literal>
+ .
</para>
</entry>
</row>
@@ -588,7 +644,9 @@
<entry>
<para>For asynchronous replication: whether or not to use a
- replication queue. Defaults to <literal>false</literal>.
+ replication queue. Defaults to
+ <literal>false</literal>
+ .
</para>
</entry>
</row>
1.9 +62 -41 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.8
retrieving revision 1.9
diff -u -b -r1.8 -r1.9
--- transactions.xml 12 Feb 2007 15:50:06 -0000 1.8
+++ transactions.xml 30 May 2007 11:56:45 -0000 1.9
@@ -76,7 +76,7 @@
before Tx1 commits. In other words, if you have the following
sequence,
<programlisting>
-<![CDATA[
+ <![CDATA[
Tx1 Tx2
W
R
@@ -96,7 +96,7 @@
can produce different results. For example, if you have the following
sequence,
<programlisting>
-<![CDATA[
+ <![CDATA[
Tx1 Tx2
R
W
@@ -150,9 +150,15 @@
This approach does not treat child nodes as an integral part of a parent node's state.
This approach allows greater concurrency if nodes are frequently added or removed, but
at a cost of lesser correctness. For use cases where greater correctness is necessary, JBoss
- Cache provides a configuration option <literal>LockParentForChildInsertRemove</literal>.
- If this is set to <literal>true</literal>, insertions and removals of child nodes
- require the acquisition of a <emphasis>write lock</emphasis> on the parent node.
+ Cache provides a configuration option
+ <literal>LockParentForChildInsertRemove</literal>
+ .
+ If this is set to
+ <literal>true</literal>
+ , insertions and removals of child nodes
+ require the acquisition of a
+ <emphasis>write lock</emphasis>
+ on the parent node.
</para>
</section>
</section>
@@ -174,10 +180,13 @@
</para>
</footnote>
. Even if you do not invoke a call within the scope of an ongoing transaction, JBoss Cache creates an
- <emphasis>implicit transaction</emphasis> and commits this transaction when the invocation completes. Each transaction
+ <emphasis>implicit transaction</emphasis>
+ and commits this transaction when the invocation completes. Each transaction
maintains a transaction workspace, which contains a copy of the data used within the transaction.
</para>
- <para>For example, if a transaction calls <literal>cache.getRoot().getChild( Fqn.fromString("/a/b/c") )</literal>,
+ <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, its workspace is merged back into the
@@ -206,12 +215,19 @@
</imageobject>
</mediaobject>
<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,
+ 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 representation of data from an external source such as a database,
it makes sense to align 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>
+ 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>
interface to hold the versioning information obtained externally before putting your data into the
cache.
</para>
@@ -220,7 +236,7 @@
<title>Configuration</title>
Optimistic locking is enabled by using the NodeLockingScheme XML attribute, and setting it to "OPTIMISTIC":
<programlisting>
-<![CDATA[
+ <![CDATA[
...
<!--
Node locking scheme:
@@ -252,10 +268,15 @@
<para>What JBoss Cache does on every incoming call is:</para>
<orderedlist>
<listitem>
- <para>Retrieve the current <literal>javax.transaction.Transaction</literal> associated with the thread</para>
+ <para>Retrieve the current
+ <literal>javax.transaction.Transaction</literal>
+ associated with the thread
+ </para>
</listitem>
<listitem>
- <para>If not already done, register a <literal>javax.transaction.Synchronization</literal> with the transaction manager to be notified when a transaction commits
+ <para>If not already done, register a
+ <literal>javax.transaction.Synchronization</literal>
+ with the transaction manager to be notified when a transaction commits
or is rolled back.
</para>
</listitem>
@@ -289,13 +310,13 @@
is able to bind to most popular Java EE application servers and provide the same functionality. A dummy
implementation -
<literal>DummyTransactionManagerLookup</literal>
- - is also provided, which may be used for standalone JBoss Cache applications and unit tests running outside a
- Java EE Application Server. Being a dummy, however, this is just for demo and testing purposes and is not
- recommended for production use.
+ - is also provided, primarily for unit tests. Being a dummy, this is just for demo and testing purposes and is
+ not recommended for production use.
</para>
<para>When the transaction commits, we initiate either a one- two-phase commit
- protocol. See <link linkend="replication.tx">replicated caches and transactions</link>
+ protocol. See
+ <link linkend="replication.tx">replicated caches and transactions</link>
for details.
</para>
More information about the jboss-cvs-commits
mailing list