[jboss-cvs] JBossCache/docs/TreeCache/en/modules ...
Manik Surtani
msurtani at jboss.com
Tue Nov 28 23:02:48 EST 2006
User: msurtani
Date: 06/11/28 23:02:48
Modified: docs/TreeCache/en/modules configuration.xml
replication.xml
Log:
JBCACHE-878
Revision Changes Path
1.12 +31 -1 JBossCache/docs/TreeCache/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/TreeCache/en/modules/configuration.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -b -r1.11 -r1.12
--- configuration.xml 6 Sep 2006 17:57:39 -0000 1.11
+++ configuration.xml 29 Nov 2006 04:02:48 -0000 1.12
@@ -512,6 +512,36 @@
</entry>
</row>
+ <row>
+ <entry>
+ <para>SyncCommitPhase</para>
+ </entry>
+
+ <entry>
+ <para>This option is used to control the behaviour of the commit part of a 2-phase commit protocol, when
+ using REPL_SYNC (does not apply to other cache modes). By default this is set to
+ <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.
+ </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>SyncRollbackPhase</para>
+ </entry>
+
+ <entry>
+ <para>This option is used to control the behaviour of the rollback part of a 2-phase commit protocol, when
+ using REPL_SYNC (does not apply to other cache modes). By default this is set to
+ <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.
+ </para>
+ </entry>
+ </row>
+
</tbody>
</tgroup>
</informaltable>
1.7 +54 -13 JBossCache/docs/TreeCache/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/TreeCache/en/modules/replication.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -b -r1.6 -r1.7
--- replication.xml 10 Jul 2006 14:50:02 -0000 1.6
+++ replication.xml 29 Nov 2006 04:02:48 -0000 1.7
@@ -42,6 +42,47 @@
simply written to a log. Even when using transactions, a transaction may succeed but replication may not succeed on all <literal>TreeCache</literal> instances.</para>
<section>
+ <title>Replicated Caches and Transactions</title>
+ <para>
+ When using transactions, replication only occurs at the transaction boundary - i.e., when a transaction commits.
+ This results in minimising replication traffic since a single modification os broadcast rather than a series of
+ individual modifications, and can be a lot more efficient than not using transactions. Another effect of this
+ is that if a transaction were to roll back, nothing is broadcast across a cluster.
+ </para>
+ <para>
+ Depending on whether you are running your cluster in 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> protocol, respectively.
+ </para>
+ <section>
+ <title>One Phase Commits</title>
+ <para>
+ Used when your cache mode is REPL_ASYNC. All modifications are replicated in a single call, which instructs
+ remote caches to apply the changes to their local in-memory state and commit locally. Remote
+ errors/rollbacks are never fed back to the originator of the transaction since the communication is asynchronous.
+ </para>
+ </section>
+ <section>
+ <title>Two Phase Commits</title>
+ <para>
+ Used when your cache mode is REPL_SYNC. Upon committing your transaction, JBoss Cache broadcasts a prepare call,
+ which carries all modifications relevant to the transaction. Remote caches then acquire local locks on their
+ im-memory state and apply the modifications. Once all remote caches respond to the prepare call, the
+ originator of the transaction broadcasts a commit. This instructs all remote caches to commit their data.
+ If any of the caches fail to respond to the prepare phase, the originator broadcasts a rollback.
+ </para>
+ <para>
+ Note that although the prepare phase is synchronous, the commit and rollback phases are asynchronous. This
+ is because <ulink url="http://java.sun.com/products/jta/">Sun's JTA specification</ulink> does not specify how transactional resources should deal with failures
+ at this stage of a transaction; and other resources participating in the transaction may have indeterminate
+ state anyway. As such, we do away with the overhead of synchronous communication for this phase of the
+ transaction. That said, they can be forced to be synchronous using the <literal>SyncCommitPhase</literal>
+ and <literal>SyncRollbackPhase</literal> configuration options.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
<title>Buddy Replication</title>
<para>
Buddy Replication allows you to suppress replicating your data to all instances in a cluster. Instead,
More information about the jboss-cvs-commits
mailing list