[jboss-cvs] JBossCache/docs/JBossCache-UserGuide/en/modules ...
Manik Surtani
msurtani at jboss.com
Tue Jan 23 19:18:39 EST 2007
User: msurtani
Date: 07/01/23 19:18:39
Modified: docs/JBossCache-UserGuide/en/modules replication.xml
transactions.xml
Removed: docs/JBossCache-UserGuide/en/modules
treecache_marshaller.xml
Log:
Chapter 10
Revision Changes Path
1.4 +1 -1 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.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- replication.xml 23 Jan 2007 23:46:52 -0000 1.3
+++ replication.xml 24 Jan 2007 00:18:39 -0000 1.4
@@ -49,7 +49,7 @@
succeed but replication may not succeed on all cache instances.
</para>
- <section>
+ <section id="replication.tx">
<title>Replicated Caches and Transactions</title>
<para>
When using transactions, replication only occurs at the transaction boundary - i.e., when a transaction
1.3 +65 -166 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.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- transactions.xml 22 Jan 2007 22:50:09 -0000 1.2
+++ transactions.xml 24 Jan 2007 00:18:39 -0000 1.3
@@ -3,8 +3,9 @@
<section>
<title>Concurrent Access</title>
- <para>JBoss Cache uses a pessimistic locking scheme by default to prevent concurrent
- access to the same data. Optimistic locking may alternatively be used, and is discussed later.
+ <para>JBoss Cache is a thread safe caching API, and uses it's 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>
<section>
@@ -20,12 +21,11 @@
Regardless, a transaction or a thread is internally transformed into
an instance of
<literal>GlobalTransaction</literal>
- , which is used as a globally unique ID
+ , which is used as a globally unique identifier
for modifications across a cluster. E.g. when we run a two-phase commit
- protocol (see below) across the cluster, the
+ protocol across the cluster, the
<literal>GlobalTransaction</literal>
- uniquely
- identifies the unit of work across a cluster.
+ uniquely identifies a unit of work across a cluster.
</para>
<para>Locks can be read or write locks. Write locks serialize read and
@@ -49,7 +49,6 @@
</para>
</section>
-
<section>
<title>Pessimistic locking</title>
<para>By default, JBoss Cache uses pessimistic locking. Locking is not exposed directly to user. Instead, a
@@ -77,14 +76,14 @@
before Tx1 commits. In other words, if you have the following
sequence,
<programlisting>
- <![CDATA[
+<![CDATA[
Tx1 Tx2
W
R
- ]]>
+]]>
</programlisting>
- using this isolation level will not Tx2 read operation.
+ using this isolation level will not prevent Tx2 read operation.
Implementations typically use an exclusive lock for writes while reads
don't need to acquire a lock.
</para>
@@ -97,12 +96,12 @@
can produce different results. For example, if you have the following
sequence,
<programlisting>
- <![CDATA[
+<![CDATA[
Tx1 Tx2
R
W
R
- ]]>
+]]>
</programlisting>
</para>
@@ -144,7 +143,7 @@
</section>
<section>
- <title>Optimistic locking</title>
+ <title>Optimistic Locking</title>
<para>The motivation for optimistic locking is to improve concurrency. When a lot of threads have a lot of
contention for access to the data tree, it can be inefficient to lock portions of the tree - for reading or
writing - for the entire duration of a transaction as we do in pessimistic locking. Optimistic locking
@@ -160,10 +159,11 @@
</para>
</footnote>
. Even if you do not invoke a call within the scope of an ongoing transaction, JBoss Cache creates an
- implicit transaction 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 get("/a/b/c"), nodes a, b and c are copied from the main data tree
+ <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
underlying tree by matching versions. If there is a version mismatch - such as when the actual data tree
@@ -184,10 +184,28 @@
</para>
</section>
<section>
+ <title>Data Versioning</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/DataVersions.png" format="PNG"/>
+ </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,
+ where cached data is an in-memory reporesentation 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>
+ interface to hold the versioning information obtained externally before putting your data into the
+ cache.
+ </para>
+ </section>
+ <section>
<title>Configuration</title>
Optimistic locking is enabled by using the NodeLockingScheme XML attribute, and setting it to "OPTIMISTIC":
<programlisting>
- <![CDATA[
+<![CDATA[
...
<!--
Node locking scheme:
@@ -206,8 +224,7 @@
<section>
<title>Transactional Support</title>
- <para>JBoss Cache can be configured to use transactions to bundle units of
- work, which can then be replicated as one unit. Alternatively, if
+ <para>JBoss Cache can be configured to use and participate in JTA compliant transactions. Alternatively, if
transaction support is disabled, it is equivalent to setting AutoCommit to
on where modifications are potentially
<footnote>
@@ -217,13 +234,13 @@
enabled).
</para>
- <para>What JBoss Cache does on every incoming call (e.g. put()) is:</para>
+ <para>What JBoss Cache does on every incoming call is:</para>
<orderedlist>
<listitem>
- <para>get the transaction associated with the thread</para>
+ <para>Retrieve the current <literal>javax.transaction.Transaction</literal> associated with the thread</para>
</listitem>
<listitem>
- <para>register (if not already done) 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>
@@ -238,13 +255,19 @@
.
</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/TransactionLookup.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+
<para>JBoss Cache ships with
<literal>JBossTransactionManagerLookup</literal>
and
<literal>GenericTransactionManagerLookup</literal>
. The
<literal>JBossTransactionManagerLookup</literal>
- is able to bind to a running JBoss Application Server and retrieve a
+ is able to bind to a running JBoss AS instance and retrieve a
<literal>TransactionManager</literal>
while the
<literal>GenericTransactionManagerLookup</literal>
@@ -255,135 +278,11 @@
Java EE Application Server. Being a dummy, however, this is just for demo and testing purposes and is not
recommended for production use.
</para>
- <para>The implementation of the
- <literal>JBossTransactionManagerLookup</literal>
- is as follows:
- </para>
-
- <programlisting>
- <![CDATA[
- public class JBossTransactionManagerLookup implements TransactionManagerLookup {
-
- public JBossTransactionManagerLookup() {}
-
- public TransactionManager getTransactionManager() throws Exception {
- Object tmp=new InitialContext().lookup("java:/TransactionManager");
- return (TransactionManager)tmp;
- }
- }
- ]]>
- </programlisting>
-
- <para>The implementation looks up the JBoss Transaction Manager from
- JNDI and returns it.
- </para>
-
- <para>When a call comes in, the
- <literal>TreeCache</literal>
- gets the current transaction and
- records the modification under the transaction as key. (If there is no
- transaction, the modification is applied immediately and possibly
- replicated). So over the lifetime of the transaction all modifications
- will be recorded and associated with the transaction. Also, the
- <literal>TreeCache</literal>
- registers with the transaction to be notified of transaction committed or
- aborted when it first encounters the transaction.
- </para>
-
- <para>When a transaction rolls back, we undo the changes in the cache and
- release all locks.
- </para>
- <para>When the transaction commits, we initiate a two-phase commit
- protocol
- <footnote>
- <para>Only with synchronous replication or invalidation.</para>
- </footnote>
- : in the first phase, a PREPARE containing all modifications
- for the current transaction is sent to all nodes in the cluster. Each node
- acquires all necessary locks and applies the changes, and then sends back
- a success message. If a node in a cluster cannot acquire all locks, or
- fails otherwise, it sends back a failure message.
- </para>
-
- <para>The coordinator of the two-phase commit protocol waits for all
- responses (or a timeout, whichever occurs first). If one of the nodes in
- the cluster responds with FAIL (or we hit the timeout), then a rollback
- phase is initiated: a ROLLBACK message is sent to all nodes in the
- cluster. On reception of the ROLLBACK message, every node undoes the
- changes for the given transaction, and releases all locks held for the
- transaction.
- </para>
-
- <para>If all responses are OK, a COMMIT message is sent to all nodes in
- the cluster. On reception of a COMMIT message, each node applies the
- changes for the given transaction and releases all locks associated with
- the transaction.
- </para>
-
- <para>When we referred to 'transaction', we actually mean a global
- representation of a local transaction, which uniquely identifies a
- transaction across a cluster.
- </para>
-
- <section>
- <title>Example</title>
-
- <para>Let's look at an example of how to use JBoss Cache in a standalone (i.e.
- outside an application server) fashion with dummy transactions:
- </para>
-
- <programlisting>
- <![CDATA[
- Properties prop = new Properties();
- prop.put(Context.INITIAL_CONTEXT_FACTORY, "org.jboss.cache.transaction.DummyContextFactory");
- User Transaction tx=(UserTransaction)new InitialContext(prop).lookup("UserTransaction");
- TreeCache tree = new TreeCache();
- PropertyConfigurator config = new PropertyConfigurator();
- config.configure(tree, "META-INF/replSync-service.xml");
- tree.createService(); // not necessary
- tree.startService(); // kick start tree cache
-
- try {
- tx.begin();
- tree.put("/classes/cs-101", "description", "the basics");
- tree.put("/classes/cs-101", "teacher", "Ben");
- tx.commit();
- }
- catch(Throwable ex) {
- try { tx.rollback(); } catch(Throwable t) {}
- }
- ]]>
- </programlisting>
-
- <para>The first lines obtain a user transaction using the 'JEE way' via
- JNDI. Note that we could also say
+ <para>When the transaction commits, we initiate either a one- two-phase commit
+ protocol. See <link linkend="replication.tx">replicated caches and transactions</link>
+ for details.
</para>
- <para>
- <programlisting>
- <![CDATA[
- UserTransaction tx = new DummyUserTransaction(DummyTransactionManager.getInstance());
- ]]>
- </programlisting>
- </para>
-
- <para>Then we create a new TreeCache and configure it using a
- PropertyConfigurator class and a configuration XML file (see below for a
- list of all configuration options).
- </para>
-
- <para>Next we start the cache. Then, we start a transaction (and
- associate it with the current thread internally). Any methods invoked on
- the cache will now be collected and only applied when the transaction is
- committed. In the above case, we create a node "/classes/cs-101" and add
- 2 elements to its map. Assuming that the cache is configured to use
- synchronous replication, on transaction commit the modifications are
- replicated. If there is an exception in the methods (e.g. lock
- acquisition failed), or in the two-phase commit protocol applying the
- modifications to all nodes in the cluster, the transaction is rolled
- back.
- </para>
- </section>
</section>
</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list