[jboss-cvs] JBossAS SVN: r99268 - projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US.

jboss-cvs-commits at lists.jboss.org jboss-cvs-commits at lists.jboss.org
Tue Jan 12 02:22:44 EST 2010


Author: laubai
Date: 2010-01-12 02:22:44 -0500 (Tue, 12 Jan 2010)
New Revision: 99268

Modified:
   projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JBoss_Cache.xml
Log:
Corrected Clustering JBoss Cache chapter.

Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JBoss_Cache.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JBoss_Cache.xml	2010-01-12 06:37:32 UTC (rev 99267)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Clustering_Guide_JBoss_Cache.xml	2010-01-12 07:22:44 UTC (rev 99268)
@@ -24,7 +24,7 @@
       <title>Key JBoss Cache Configuration Options</title>
       <para>JBoss Enterprise Web Platform ships with a reasonable set of default JBoss Cache 
       configurations that are suitable for the standard clustered service
-      use cases (e.g. web session replication or JPA/Hibernate caching).  
+      use cases (for example, web session replication or JPA/Hibernate caching).  
       Most applications that involve the standard
       clustered services just work out of the box with the default configurations. 
       You only need to tweak them when you are deploying an application that 
@@ -35,10 +35,12 @@
       documentation available at <ulink url="http://www.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/">http://www.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/</ulink>.</para>
       
       <para>Most JBoss Cache configuration examples in this section use the 
-      JBoss Microcontainer schema for building up an <literal>org.jboss.cache.config.Configuration</literal>
+      JBoss Microcontainer schema for building up an 
+      <classname>org.jboss.cache.config.Configuration</classname>
       object graph from XML.  JBoss Cache has its own custom XML schema, but
-      the standard JBoss Enterprise Web Platform CacheManager service uses the JBoss Microcontainer
-      schema to be consistent with most other internal Enterprise Web Platform services.</para>
+      the standard JBoss Enterprise Web Platform <classname>CacheManager</classname> 
+      service uses the JBoss Microcontainer schema to be consistent with most 
+      other internal Enterprise Web Platform services.</para>
       
       <para>Before getting into the key configuration options, let's have a
       look at the most likely place that a user would encounter them.</para>
@@ -48,22 +50,22 @@
           <para>As discussed in <xref linkend="clustering-blocks-jbc-cachemanager"/>, 
 		  the standard JBoss Enterprise Web Platform clustered services use the CacheManager service 
           as a factory for JBoss Cache instances. So, cache configuration changes 
-          are likely to involve edits to the CacheManager service.</para>
+          are likely to involve edits to the <classname>CacheManager</classname> service.</para>
           
-          <note><para>Users can also use the CacheManager as a factory for
+          <note><para>Users can also use the <classname>CacheManager</classname> as a factory for
           custom caches used by directly by their own applications; see
           <xref linkend="jbosscache-custom-deployment-cachemgr"/>.</para></note>
           
-          <para>The CacheManager is configured via the 
-          <literal>deploy/cluster/jboss-cache-manager.sar/META-INF/jboss-cache-manager-jboss-beans.xml</literal> 
-          file. The element most likely to be edited is the "CacheConfigurationRegistry" 
+          <para>The <classname>CacheManager</classname> is configured via the 
+          <filename>deploy/cluster/jboss-cache-manager.sar/META-INF/jboss-cache-manager-jboss-beans.xml</filename> 
+          file. The element most likely to be edited is the <classname>CacheConfigurationRegistry</classname> 
           bean, which maintains a registry of all the named JBC configurations 
-          the CacheManager knows about. Most edits to this file would 
+          the <classname>CacheManager</classname> knows about. Most edits to this file would 
           involve adding a new JBoss Cache configuration or changing a 
           property of an existing one.</para>
           
-          <para>The following is a redacted version of the "CacheConfigurationRegistry" 
-          bean configuration:</para>
+          <para>The following is a redacted version of the 
+          <classname>CacheConfigurationRegistry</classname> bean configuration:</para>
                 
                 <programlisting><![CDATA[
 <bean name="CacheConfigurationRegistry" 
@@ -130,20 +132,20 @@
             JBoss Microcontainer's schema rather than one of the standard JBoss 
             Cache configuration formats. When JBoss Cache parses one of its 
             standard configuration formats, it creates a Java Bean of type 
-            <literal>org.jboss.cache.config.Configuration</literal> with a tree 
+            <classname>org.jboss.cache.config.Configuration</classname> with a tree 
             of child Java Beans for some of the more complex sub-configurations 
-            (i.e. cache loading, eviction, buddy replication). Rather than 
-            delegating this task of XML parsing/Java Bean creation to JBC, we 
+            (for example, cache loading, eviction, buddy replication). Rather than 
+            delegating this task of XML parsing and Java Bean creation to JBC, we 
 	    let the Enterprise Web Platform's microcontainer do it directly. This has the advantage 
             of making the microcontainer aware of the configuration beans, which 
-	    in later Enterprise Web Platform 5.x releases will be helpful in allowing external 
+	    in later Enterprise Web Platform releases will be helpful in allowing external 
             management tools to manage the JBC configurations.</para>
             
             <para>The configuration format should be fairly self-explanatory if 
 		    you look at the standard configurations the Enterprise Web Platform ships; they include 
-            all the major elements. The types and properties of the various java 
-            beans that make up a JBoss Cache configuration can be seen in the 
-            JBoss Cache javadocs.  Here is a fairly complete example:</para>
+            all the major elements. The types and properties of the various Java 
+            Beans that make up a JBoss Cache configuration can be seen in the 
+            JBoss Cache Javadocs. Here is a fairly complete example:</para>
             
             <programlisting><![CDATA[
 <bean name="StandardSFSBCacheConfig" class="org.jboss.cache.config.Configuration">
@@ -262,11 +264,11 @@
 </bean>]]></programlisting>
 
         <para>Basically, the XML specifies the creation of an 
-        <literal>org.jboss.cache.config.Configuration</literal> java bean and
+        <classname>org.jboss.cache.config.Configuration</classname> Java Bean and
         the setting of a number of properties on that bean. Most of the
         properties are of simple types, but some, such as 
-        <literal>buddyReplicationConfig</literal> and <literal>cacheLoaderConfig</literal>
-        take various types java beans as their values.</para>
+        <varname>buddyReplicationConfig</varname> and <varname>cacheLoaderConfig</varname>
+        take various types of Java Bean as their values.</para>
         
         <para>Next we'll look at some of the key configuration options.</para>
         
@@ -274,104 +276,124 @@
       <section id="jbosscache-configuration-cachemode">
          <title>Cache Mode</title>
          
-         <para>JBoss Cache's <literal>cacheMode</literal> configuration attribute 
+         <para>JBoss Cache's <varname>cacheMode</varname> configuration attribute 
          combines into a single property two related aspects:</para>
          
          <para><emphasis role="bold">Handling of Cluster Updates</emphasis></para>
          <para>This controls how a cache instance on one node should notify
          the rest of the cluster when it makes changes in its local state.
-         There are three options:
-         <itemizedlist>
-            <listitem><para><emphasis role="bold">Synchronous</emphasis> means 
-            the cache instance sends a message to its peers notifying them of the
-            change(s) and before returning waits for them to acknowledge that 
-            they have applied the same changes. If the changes are made as part
-            of a JTA transaction, this is done as part of a 2 phase-commit 
-            process during transaction commit.  Any locks are held until this
-            acknowledgment is received. Waiting for acknowledgement from
-            all nodes adds delays, but it ensures consistency around the cluster.
-            Synchronous mode is needed when all the nodes in the cluster may
-            access the cached data resulting in a high need for consistency.
-            </para></listitem>
-            <listitem><para><emphasis role="bold">Asynchronous</emphasis> means 
-            the cache instance sends a message to its peers notifying them of the
-            change(s) and then immediately returns, without any acknowledgement 
-            that they have applied the same changes. It <emphasis>does not</emphasis>
-            mean sending the message is handled by some other thread besides the 
-            one that changed the cache content; the thread that makes the change
-            still spends some time dealing with sending messages to the cluster,
-            just not as much as with synchronous communication. Asynchronous
-            mode is most useful for cases like session replication, where the
-            cache doing the sending expects to be the only one that accesses the
-            data and the cluster messages are used to provide backup copies in
-            case of failure of the sending node. Asynchronous messaging adds a
-            small risk that a later user request that fails over to another node may
-            see out-of-date state, but for many session-type applications this
-            risk is acceptable given the major performance benefits asynchronous
-            mode has over synchronous mode. 
-            </para></listitem>
-            <listitem><para><emphasis role="bold">Local</emphasis> means 
-            the cache instance doesn't send a message at all.  A JGroups channel
-            isn't even used by the cache. JBoss Cache has
-            many useful features besides its clustering capabilities and is a
-            very useful caching library even when not used in a cluster. Also,
-            even in a cluster, some cached data does not need to be kept consistent
-            around the cluster, in which case Local mode will improve performance.
-            Caching of JPA/Hibernate query result sets is an example of this;
-            Hibernate's second level caching logic uses a separate mechanism to
-            invalidate stale query result sets from the second level cache, so
-            JBoss Cache doesn't need to send messages around the cluster for
-            a query result set cache.
-            </para></listitem>
-         </itemizedlist>
-         </para>
+         There are three options:</para>
+        <variablelist>
+          <varlistentry>
+            <term><literal>Synchronous</literal></term>
+            <listitem>
+              <para>
+                When a change is made, the cache sends a message to notify its peers of changes
+                and waits for acknowledgement that its peers have applied those changes
+                before returning. If the changes are made as part of a JTA
+                transaction, this is done as part of a two-phase commit process.
+                Any locks are held until acknowledgement is received. Waiting for this
+                acknowledgement to be received from all nodes adds delays, but ensures
+                consistency around the cluster. Synchronous mode is
+                required when there is a high need for consistency, such as when all
+                nodes can access cached data.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><literal>Asynchronous</literal></term>
+            <listitem>
+              <para>
+                When a change is made, the cache sends a message to notify its peers of changes
+                and returns immediately <emphasis>without</emphasis> any acknowledgement that 
+                the changes have been applied. Asynchronous mode is most
+                useful in session replication, where only the cache that sends the messages 
+                accesses data, and cluster messages are used to provide backup copies in the case 
+                of a failure on the sending node. Asynchronous messaging
+                has minor consistency risks, in that a later user request that fails over to
+                another node may see out-of-date state. However, this is usually considered an
+                acceptable risk for session-type applications because of the major performance
+                benefits associated with asynchronous messaging.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><literal>Local</literal></term>
+            <listitem>
+              <para>
+                No message is sent, and no JGroups channel is used by the cache.
+                Local messaging will provide improved performance when 
+                cached data need not be kept consistent around the cluster. One example
+                of this is caching JPA/Hibernate query result sets: Hibernate's second
+                level cache logic uses a separate mechanism to invalidate stale query result
+                sets from the second level cache, so JBoss Cache does not need to send messages
+                around the cluster for a query result set cache.
+              </para>
+            </listitem>
+          </varlistentry>
+        </variablelist>
          
          <para><emphasis role="bold">Replication vs. Invalidation</emphasis></para>
+ 
+          <para>
+            Nodes in a cluster can reflect changes from the sending node in
+            two ways:
+          </para>
+        <variablelist>
+          <varlistentry>
+            <term><literal>Replication</literal></term>
+            <listitem>
+              <para>
+                Other nodes update their state to reflect the new state on the
+                sending node. This means that the sending node must include the
+                changed state, increasing the resource cost of the message.
+                Replication is required if there is no other way for other nodes to
+                obtain the changed state.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term><literal>Invalidation</literal></term>
+            <listitem>
+              <para>
+                Other nodes remove the changed state from their local state.
+                Invalidation mode reduces the resource cost of
+                cluster update messages, since only the cache key of the state
+                changed needs to be transmitted. However, this is only an option
+                if the removed state can be retrieved from another source. It is
+                an excellent option for a clustered JPA/Hibernate entity cache,
+                since in this case cached state can be reread from the database.
+              </para>
+            </varlistentry>
+          </variablelist>
          
-         <para>This aspect deals with the content of messages sent around the cluster
-         when a cache changes its local state, i.e. what should the other caches
-         in the cluster do to reflect the change:
-         <itemizedlist>
-         <listitem>
-           <para><emphasis role="bold">Replication</emphasis> means the other nodes
-           should update their state to reflect the new state on the sending
-           node.  This means the sending node needs to include the changed state, 
-           increasing the cost of the message. Replication is necessary if
-           the other nodes have no other way to obtain the state.</para>
-         </listitem>
-         <listitem>
-           <para><emphasis role="bold">Invalidation</emphasis> means the other
-           nodes should remove the changed state from their local state. 
-           Invalidation reduces the cost of the cluster update messages, since
-           only the cache key of the changed state needs to be transmitted, not the
-           state itself.  However, it is only an option if the removed state can be
-           retrieved from another source. It is an excellent option for a 
-           clustered JPA/Hibernate entity cache, since the cached state can
-           be re-read from the database.</para>
-         </listitem>
-         </itemizedlist>
-         </para>
-         
-         <para>These two aspects combine to form 5 valid values for the
-         <literal>cacheMode</literal> configuration attribute:
-         <itemizedlist>
-           <listitem><para><emphasis role="bold">LOCAL</emphasis> means no
-           cluster messages are needed.
-           </para></listitem>
-           <listitem><para><emphasis role="bold">REPL_SYNC</emphasis> means 
-           synchronous replication messages are sent.
-           </para></listitem>
-           <listitem><para><emphasis role="bold">REPL_ASYNC</emphasis> means 
-           asynchronous replication messages are sent.
-           </para></listitem>
-           <listitem><para><emphasis role="bold">INVALIDATION_SYNC</emphasis> means 
-           synchronous invalidation messages are sent.
-           </para></listitem>
-           <listitem><para><emphasis role="bold">INVALIDATION_ASYNC</emphasis> means 
-           asynchronous invalidation messages are sent.
-           </para></listitem>
-         </itemizedlist>
-         </para>
+          <para>
+            The <varname>cacheMode</varname> configuration attribute has five
+            possible values, which form various combinations of the aforementioned
+            aspects:
+          </para>
+          <variablelist>
+            <varlistentry>
+              <term><literal>LOCAL</literal></term>
+              <listitem><para>No cluster messages are required.</para></listitem>
+            </varlistentry>
+            <varlistentry>
+              <term><literal>REPL_SYNC</literal></term>
+              <listitem><para>Synchronous replication messages are sent.</para></listitem>
+            </varlistentry>
+            <varlistentry>
+              <term><literal>REPL_ASYNC</literal></term>
+              <listitem><para>Asynchronous replication messages are sent.</para></listitem>
+            </varlistentry>
+            <varlistentry>
+              <term><literal>INVALIDATION_SYNC</literal></term>
+              <listitem><para>Synchronous invalidation messages are sent.</para></listitem>
+            </varlistentry>
+            <varlistentry>
+              <term><literal>INVALIDATION_ASYNC</literal></term>
+              <listitem><para>Asynchronous invalidation messages are sent.</para></listitem>
+            </varlistentry>
+          </variablelist>
       </section>
       
       <section id="jbosscache-configuration-transactions">
@@ -386,143 +408,158 @@
          part of transaction commit (reducing chattiness).</para>
          
          <para>Integration with a transaction manager is accomplished by
-         setting the <literal>transactionManagerLookupClass</literal> configuration
+         setting the <varname>transactionManagerLookupClass</varname> configuration
          attribute; this specifies the fully qualified class name of a class JBoss Cache
-	 can use to find the local transaction manager. Inside JBoss Enterprise Web Platform, this
+      	 can use to find the local transaction manager. Inside JBoss Enterprise Web Platform, this
          attribute would have one of two values:</para>
          
-         <itemizedlist>
-           <listitem>
-             <para><emphasis role="bold">org.jboss.cache.transaction.JBossTransactionManagerLookup</emphasis></para>
-             <para>This finds the standard transaction manager running in the application server.
-             Use this for any custom caches you deploy where you want caching
-             to participate in any JTA transactions.</para>
-           </listitem>
-           <listitem>
-             <para><emphasis role="bold">org.jboss.cache.transaction.BatchModeTransactionManagerLookup</emphasis></para>
-             <para>This is used in the cache configurations used for web session
-             and EJB SFSB caching.  It specifies a simple mock <literal>TransactionManager</literal> 
-             that ships with JBoss Cache called the <literal>BatchModeTransactionManager</literal>.
-             This transaction manager is not a true JTA transaction manager and
-             should not be used for anything other than JBoss Cache. Its usage
-	     in JBoss Enterprise Web Platform is to get most of the benefits of JBoss Cache's transactional
-             behavior for the session replication use cases, but without getting
-             tangled up with end user transactions that may run during a request.
-             </para>
-           </listitem>
-         </itemizedlist>
-         
+
+         <variablelist>
+           <varlistentry>
+              <term><literal>org.jboss.cache.transaction.JBossTransactionManagerLookup</literal></term>
+              <listitem>
+                <para>
+                  The standard transaction manager running in the application server.
+                  Use this for any custom caches you deploy where you want caching
+                  to participate in any JTA transactions.
+                </para>
+              </listitem>
+            </varlistentry>
+           <varlistentry>
+              <term><literal>org.jboss.cache.transaction.BatchModeTransactionManagerLookup</literal></term>
+              <listitem>
+                <para>
+                  Used in the cache configurations for web session caching. Specifies 
+                  the <classname>BatchModeTransactionManager</classname>, a mock 
+                  <classname>TransactionManager</classname> shipped with JBoss Cache.
+                  Since this is not a true JTA transaction manager, it should not be used
+                  with anything other than JBoss Cache. In JBoss Enterprise Web Platform,
+                  it benefits from JBoss Cache's transactional behavior in session
+                  replication, without participating in end-user transactions that may
+                  run during a request.
+                </para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+
          <note>
-           <para>For caches used for JPA/Hibernate caching, the 
-           <literal>transactionManagerLookupClass</literal> should not be
-           configured.  Hibernate internally configures the cache to use
-           the same transaction manager it is using for database access.</para>
-         </note>
+           <para>The <classname>transactionManagerLookupClass</classname> should not be
+            configured for caches that are used for JPA/Hibernate caching. Hibernate 
+            internally configures the cache to use the same transaction manager that
+            Hibernate uses for database access.</para>
+        </note>
       </section>
       
       <section id="jbosscache-configuration-concurrency">
          <title>Concurrent Access</title>
          <para>JBoss Cache is a thread safe caching API, and uses its own efficient 
          mechanisms of controlling concurrent access. Concurrency is configured
-         via the <literal>nodeLockingScheme</literal> and <literal>isolationLevel</literal>
+         via the <varname>nodeLockingScheme</varname> and <varname>isolationLevel</varname>
          configuration attributes.
          </para>
          
-         <para>There are three choices for <literal>nodeLockingScheme</literal>:
-         <itemizedlist>
-         <listitem>
-         <para><emphasis role="bold">MVCC</emphasis> or multi-versioned concurrency 
-         control, is a locking scheme commonly used by modern database implementations 
-         to control fast, safe concurrent access to shared data. JBoss Cache 3.x uses 
-         an innovative implementation of MVCC as the default locking scheme. MVCC 
-         is designed to provide the following features for concurrent access:
-         <itemizedlist>
-         <listitem><para>Readers that don't block writers</para></listitem>
-         <listitem><para>Writers that fail fast</para></listitem>
-         </itemizedlist>
-         It achieves this by using data versioning and copying for concurrent 
-         writers. The theory is that readers continue reading shared state, 
-         while writers copy the shared state, increment a version id, and write 
-         that shared state back after verifying that the version is still valid 
-         (i.e., another concurrent writer has not changed this state first).</para>
-         <para>MVCC is the recommended choice for JPA/Hibernate entity caching.</para>
-         </listitem>
-         <listitem>
-            <para><emphasis role="bold">PESSIMISTIC</emphasis> locking involves
-            threads/transactions acquiring either exclusive or non-exclusive
-            locks on nodes before reading or writing. Which is acquired
-            depends on the <literal>isolationLevel</literal> (see below) but
-            in most cases a non-exclusive lock is acquired for a read and an
-            exclusive lock is acquired for a write. Pessimistic locking
-            requires considerably more overhead than MVCC and allows lesser concurrency,
-            since reader threads must block until a write has completed and 
-            released its exclusive lock (potentially a long time if the write 
-            is part of a transaction). A write will also be delayed due to ongoing
-            reads.</para>
-            <para>Generally MVCC is a better choice than PESSIMISTIC, which is
-            deprecated as of JBoss Cache 3.0. But, for the session caching usage 
-	    in JBoss Enterprise Web Platform 5.0.0, PESSIMISTIC is still the default. This is largely 
-            because for the session use case there are generally not concurrent 
-            threads accessing the same cache location, so the benefits of MVCC 
-	    are not as great. <!--, and 2) the Enterprise Web Platform development team wanted to continue 
-            to evaluate MVCC in the session use case before moving to it as the default.--></para>
-         </listitem>
-         <listitem>
-            <para><emphasis role="bold">OPTIMISTIC</emphasis> locking seeks to
-            improve upon the concurrency available with PESSIMISTIC by creating
-            a "workspace" for each request/transaction that accesses the cache. 
-            Data accessed by the request/transaction (even reads) is <emphasis>copied</emphasis> 
-            into the workspace, which is adds overhead. All data is versioned;
-            on completion of non-transactional requests or commits of transactions
-            the version of data in the workspace is compared to the main cache,
-            and an exception is raised if there are are inconsistencies. Otherwise
-            changes to the workspace are applied to the main cache.</para>
-            <para>OPTIMISTIC locking is deprecated but is still provided to
-            support backward compatibility. Users are encouraged to use MVCC 
-            instead, which provides the same benefits at lower cost.</para>
-         </listitem>
-         </itemizedlist>
-         </para>
+         <para>There are three possible values for <varname>nodeLockingScheme</varname>:</para>
+
+          <variablelist>
+            <varlistentry>
+              <term><literal>MVCC</literal> (Multi-Versioned Concurrency Control)</term>
+              <listitem>
+                <para>
+                  A locking scheme commonly used by modern database implementations to
+                  control fast, safe concurrent access to shared data. JBoss Cache 3.x
+                  uses an innovative implementation of MVCC as the default locking scheme.
+                  MVCC is designed to provide the following features for concurrent access:
+                </para>
+                <itemizedlist>
+                  <listitem><para>readers that do not block writers</para></listitem>
+                  <listitem><para>writers that fail fast</para></listitem>
+                </itemizedlist>
+                <para>
+                  It achieves this by using data versioning and copying for concurrent writers.
+                  In theory, readers continue reading shared state, while writers copy the
+                  shared state, increment the version ID, and write that shared state back
+                  after verifying that the version is still valid (that is, thata another
+                  convurrent writer has not altered the state first).
+                </para>
+                <para>
+                  MVCC is recommended for JPA/Hibernate entity caching.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term><literal>PESSIMISTIC</literal></term>
+              <listitem>
+                <para>
+                  Threads or transactions acquire either exclusive or non-exclusive locks
+                  on nodes before reading or writing. The lock type acquired depends on
+                  the <varname>isolationLevel</varname>, but in most cases a non-exclusive
+                  lock is acquired for a read, and an exclusive lock is aquired for a write.
+                  Pessimistic locking requires more resources than MVCC, and allows less
+                  concurrency, since reader threads must block until a write has completed
+                  and released its exclusive lock. This can be a long time if the write is
+                  part of a transaction. A write will also be delayed due to ongoing reads.
+                </para>
+                <para>
+                  Pessimistic locking is deprecated as of JBoss Cache 3.0. For session caching
+                  use in JBoss Enterprise Web Platform, <literal>PESSIMISTIC</literal> is 
+                  the default value, since concurrent threads usually do not access the same
+                  cache location in session caching and the benefits of MVCC are not as great.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term><literal>OPTIMISTIC</literal></term>
+              <listitem>
+                <para>
+                  Improves the concurrency available with pessimistic locking by creating
+                  a "workspace" for each request or transaction that accesses the cache.
+                  Data accessed by requests (including reads) is <emphasis>copied</emphasis>
+                  into the workspace, which increases resource usage. All data is versioned,
+                  so when non-transactional requests or transaction commits are completed,
+                  the version of data in the workspace is compared to the primary cache.
+                  If there are inconsistencies, an exception is raised. Otherwise, changes to
+                  the workspace are applied to the main cache.
+                </para>
+                <para>
+                  Optimistic locking is deprecated, but is provided to support backwards
+                  compatibility. Users are encouraged to use <literal>MVCC</literal> instead,
+                  which provides the same benefits at a lower cost to resources.
+                </para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
          
-         <para>The <literal>isolationLevel</literal> attribute has two possible
-         values <emphasis role="bold">READ_COMMITTED</emphasis> and 
-         <emphasis role="bold">REPEATABLE_READ</emphasis> which correspond in 
-         semantic to database-style isolation levels. Previous versions of JBoss 
-         Cache supported all 5 database isolation levels, and if an unsupported 
-         isolation level is configured, it is either upgraded or downgraded to 
-         the closest supported level. 
-         </para>
-         
-         <para>REPEATABLE_READ is the default isolation level, to maintain 
-         compatibility with previous versions of JBoss Cache. READ_COMMITTED, 
-         while providing a slightly weaker isolation, has a significant performance 
-         benefit over REPEATABLE_READ.</para>
+          <para>The <varname>isolationLevel</varname> attribute has two possible
+          values, <literal>READ_COMMITTED</literal> and <literal>REPEATABLE_READ</literal>,
+          which correspond to database style isolation levels. The default isolation level
+          is <literal>REPEATABLE_READ</literal>, which maintains backwards compatibility
+          with previous versions of JBoss Cache. <literal>READ_COMMITTED</literal> provides
+          slightly weaker isolation, but has significant performance benefits.</para>
       </section>
       
       <section id="jbosscache-configuration-jgroups">
          <title>JGroups Integration</title>
          
-         <para>Each JBoss Cache instance internally uses a JGroups <literal>Channel</literal>
-		 to handle group communications. Inside JBoss Enterprise Web Platform, we strongly recommend 
-		 that you use the Enterprise Web Platform's JGroups Channel Factory service <!--(see 
-         <xref linkend="clustering-blocks-jgroups-channelfactory"/>)--> as the 
-         source for your cache's <literal>Channel</literal>. In this section
-         we discuss how to configure your cache to get it's channel from
-         the Channel Factory; if you wish to configure the channel in some
-         other way see the JBoss Cache documentation.</para>
+         <para>Each JBoss Cache instance internally uses a JGroups <classname>Channel</classname>
+    		 to handle group communications. Inside JBoss Enterprise Web Platform, we strongly recommend 
+		     that you use the Enterprise Web Platform's JGroups Channel Factory service <!--(see 
+         <xref linkend="clustering-blocks-jgroups-channelfactory"/>)--> as the source for your 
+          cache's <classname>Channel</classname>. In this section we discuss how to configure your 
+          cache to get its channel from the Channel Factory; if you wish to configure the channel 
+          in some other way, see the JBoss Cache documentation.</para>
          
          <para><emphasis role="bold">Caches obtained from the CacheManager Service</emphasis></para>
          
-         <para>This is the simplest approach. The CacheManager service already has
-         a reference to the Channel Factory service, so the only configuration
+         <para>This is the simplest approach. The <classname>CacheManager</classname> service 
+         already contains a reference to the Channel Factory service, so the only configuration
          task is to configure the name of the JGroups protocol stack configuration
          to use.</para>
          
          <para>If you are configuring your cache via the CacheManager service's
-         <literal>jboss-cache-manager-jboss-beans.xml</literal> 
+         <filename>jboss-cache-manager-jboss-beans.xml</filename> 
          file (see <xref linkend="jbosscache-custom-deployment-cachemgr"/>), 
-         add the following to your cache configuration, where the value is the 
-         name of the protocol stack configuration.:</para>
+         add the following to your cache configuration, where the value 
+          is the name of the protocol stack configuration (here <literal>udp</literal>):</para>
          
          <programlisting><![CDATA[<property name="multiplexerStack">udp</property>]]></programlisting>
          
@@ -535,11 +572,11 @@
          <programlisting><![CDATA[<jgroupsConfig multiplexerStack="udp"/>]]></programlisting>
          -->
          
-         <para><emphasis role="bold">Caches Deployed via a <literal>-jboss-beans.xml</literal> File</emphasis></para>
+         <para><emphasis role="bold">Caches Deployed via a <filename>-jboss-beans.xml</filename> File</emphasis></para>
          
          <para>If you are deploying a cache via a JBoss Microcontainer 
-         <literal>-jboss-beans.xml</literal> file (see 
-         <xref linkend="jbosscache-custom-deployment-beans.xml"/>), you need
+         <filename>-jboss-beans.xml</filename> file (see 
+         <xref linkend="jbosscache-custom-deployment-beans.xml"/>), you need to
          inject a reference to the Channel Factory service as well as specifying
          the protocol stack configuration:</para>
          
@@ -551,14 +588,14 @@
 </property>
 <property name="multiplexerStack">udp</property>]]></programlisting>
          
-         <para><emphasis role="bold">Caches Deployed via a <literal>-service.xml</literal> File</emphasis></para>
+         <para><emphasis role="bold">Caches Deployed via a <filename>-service.xml</filename> File</emphasis></para>
          
          <para>If you are deploying a cache MBean via <literal>-service.xml</literal> 
          file (see <xref linkend="jbosscache-custom-deployment-service.xml"/>),
-         <literal>CacheJmxWrapper</literal> is the class of your MBean; that 
-         class exposes a <literal>MuxChannelFactory</literal> MBean attribute. 
+         <classname>CacheJmxWrapper</classname> is the class of your MBean; that 
+         class exposes a <classname>MuxChannelFactory</classname> MBean attribute. 
          You dependency inject the Channel Factory service into
-         this attribute, and set the protocol stack name via the <literal>MultiplexerStack</literal>
+         this attribute, and set the protocol stack name via the <varname>MultiplexerStack</varname>
          attribute:</para>
          
          <programlisting><![CDATA[
@@ -577,7 +614,7 @@
          as a Hibernate Second Level Cache" guide at 
          <ulink url="http://www.jboss.org/jbossclustering/docs/hibernate-jbosscache-guide-3.pdf">http://www.jboss.org/jbossclustering/docs/hibernate-jbosscache-guide-3.pdf</ulink>.
          For web session caches, eviction should not be configured; the
-         distributable session manager handles eviction itself. For EJB 3
+         distributable session manager handles eviction itself. For EJB3
 	 SFSB caches, stick with the eviction configuration in the Enterprise Web Platform's standard
          <literal>sfsb-cache</literal> configuration (see 
          <xref linkend="clustering-blocks-jbc-cachemanager"/>). The EJB container
@@ -592,10 +629,10 @@
          <para>Cache loading allows JBoss Cache to store data in a persistent
          store in addition to what it keeps in memory. This data can either be
          an overflow, where the data in the persistent store is not reflected
-         in memory. Or it can be a superset of what is in memory, where everything
+         in memory, or it can be a superset of what is in memory, where everything
          in memory is also reflected in the persistent store, along with items
          that have been evicted from memory. Which of these two modes is used
-         depends on the setting of the <literal>passivation</literal> flag in 
+         depends on the setting of the <varname>passivation</varname> flag in 
          the JBoss Cache cache loader configuration section. A <literal>true</literal>
          value means the persistent store acts as an overflow area written to when
          data is evicted from the in-memory cache.</para>
@@ -603,7 +640,7 @@
          <para>If you wish to configure cache loading for a custom cache, see 
          the JBoss Cache documentation for all of the available options. Do not
          configure cache loading for a JPA/Hibernate cache, as the database
-         itself serves as a persistent store; adding a cache loader is just
+         itself serves as a persistent store; adding a cache loader is
          redundant.</para>
          
          <para>The caches used for web session and EJB3 SFSB caching use
@@ -625,7 +662,7 @@
            change from the defaults.</para>
            
            <para>The Cache Loader configuration for the 
-           <literal>standard-session-cache</literal> config serves as a good
+           <varname>standard-session-cache</varname> configuration serves as a good
            example:</para>
            
            <programlisting><![CDATA[
@@ -652,50 +689,56 @@
    </bean>
 </property>]]></programlisting>
 
-         <para>Some explanation:</para>
-         
-         <itemizedlist>
-         <listitem><para><emphasis role="bold">passivation</emphasis> property
-         MUST be <literal>true</literal></para></listitem>
-         <listitem><para><emphasis role="bold">shared</emphasis> property MUST be 
-         <literal>false</literal>. Do not passivate sessions to a shared persistent 
-         store, otherwise if another node activates the session, it will be gone 
-         from the persistent store and also gone from memory on other nodes that 
-         have passivated it. Backup copies will be lost.</para></listitem>
-         <listitem><para><emphasis role="bold">individualCacheLoaderConfigs</emphasis> 
-         property accepts a list of Cache Loader configurations. JBC allows you 
-         to chain cache loaders; see the JBoss Cache docs. For the session passivation 
-         use case a single cache loader is sufficient.</para></listitem>
-         <listitem><para><emphasis role="bold">class</emphasis> attribute on a 
-         cache loader config bean must refer to the configuration class for a 
-         cache loader implementation (e.g. <literal>org.jboss.cache.loader.FileCacheLoaderConfig</literal> 
-         or <literal>org.jboss.cache.loader.JDBCCacheLoaderConfig</literal>). See 
-         the JBoss Cache documentation for more on the available CacheLoader 
-         implementations. If you wish to use JDBCCacheLoader (to persist to a 
-         database rather than the filesystem used by FileCacheLoader) note the 
-         comment above about the <literal>shared</literal> property.  Don't use 
-         a shared database, or at least not a shared table in the database.  Each 
-         node in the cluster must have its own storage location.</para></listitem>
-         <listitem><para><emphasis role="bold">location</emphasis> property for 
-         FileCacheLoaderConfig defines the root node of the filesystem tree where 
-         passivated sessions should be stored. The default is to store them in 
-	 your JBoss Enterprise Web Platform configuration's <literal>data</literal> directory.</para></listitem>
-         <listitem><para><emphasis role="bold">async</emphasis> MUST be 
-         <literal>false</literal> to ensure passivated sessions are promptly 
-         written to the persistent store.</para></listitem>
-         <listitem><para><emphasis role="bold">fetchPersistentState</emphasis> 
-         property MUST be <literal>true</literal> to ensure passivated sessions 
-         are included in the set of session backup copies transferred over from 
-         other nodes when the cache starts.</para></listitem>
-         <listitem><para><emphasis role="bold">purgeOnStartup</emphasis> should 
-         be <literal>true</literal> to ensure out-of-date session data left over 
-         from a previous shutdown of a server doesn't pollute the current data 
-         set.</para></listitem>
-         <listitem><para><emphasis role="bold">ignoreModifications</emphasis> 
-         should be <literal>false</literal></para></listitem>
-         <listitem><para><emphasis role="bold">checkCharacterPortability</emphasis> 
-         should be <literal>false</literal> as a minor performance optimization.</para>
-         </listitem>
+        <itemizedlist>
+          <listitem>
+            <para><varname>passivation</varname> must be set to <literal>true</literal>.</para>
+          </listitem>
+          <listitem>
+            <para><varname>shared</varname> must be set to <literal>false</literal>. Do
+            not passivate sessions to a shared persistent store, or if another node activates
+            the session, the session will be removed from the persistent store and from the 
+            memory on other nodes that have passivated it. Backup copies will be lost.</para>
+          </listitem>
+          <listitem>
+            <para><varname>individualCacheLoaderConfigs</varname> accepts a list of
+            cache loader configurations. You can also chain cache loaders (see the
+            JBoss Cache documentation for details). For session passivation, a single
+            cache loader is sufficient.</para>
+          </listitem>
+          <listitem>
+            <para><varname>class</varname> must refer to the configuration class for a
+            cache loader implementation, for example, 
+            <classname>org.jboss.cache.loader.FileCacheLoaderConfig</classname>  or 
+            <classname>org.jboss.cache.loader.JDBCCacheLoaderConfig</classname>. See 
+            the JBoss Cache documentation for more information about the available
+            <classname>CacheLoader</classname> implementations. If you want to use
+            <classname>JDBCCacheLoader</classname> (to persist to a database rather than
+            the filesystem used by <classname>FileCacheLoader</classname>), take note of
+            the comments about the <varname>shared</varname> property. Do not use a shared
+            database. Each node in the cluster must have its own storage location.</para>
+          </listitem>
+          <listitem>
+            <para><literal>FileCacheLoaderConfig</literal>'s <varname>location</varname>
+            property defines the root node of the filesystem tree where passivated sessions
+            should be stored. The default is to store them in your JBoss Enterprise Web Platform
+            configuration's <filename>data</filename> directory.</para>
+          </listitem>
+           <listitem><para><varname>async</varname> must be 
+           <literal>false</literal> to ensure passivated sessions are promptly 
+           written to the persistent store.</para></listitem>
+           <listitem><para><varname>fetchPersistentState</varname> 
+           property must be <literal>true</literal> to ensure passivated sessions 
+           are included in the set of session backup copies transferred over from 
+           other nodes when the cache starts.</para></listitem>
+           <listitem><para><varname>purgeOnStartup</varname> should 
+           be <literal>true</literal> to ensure out-of-date session data left over 
+           from a previous shutdown of a server doesn't pollute the current data 
+           set.</para></listitem>
+           <listitem><para><varname>ignoreModifications</varname> 
+           should be <literal>false</literal></para></listitem>
+           <listitem><para><varname>checkCharacterPortability</varname> 
+           should be <literal>false</literal> for a minor performance improvement.</para>
+           </listitem>
          </itemizedlist>
          </section>
          
@@ -705,35 +748,35 @@
          <title>Buddy Replication</title>
          <para>Buddy Replication is a JBoss Cache feature that allows you to 
          suppress replicating your data to all instances in a cluster. Instead, 
-         each instance picks one or more 'buddies' in the cluster, and only 
-         replicates to those specific buddies. This greatly helps scalability 
+         each instance picks one or more <emphasis>buddies</emphasis> in the cluster, and only 
+         replicates to those specific buddies. This greatly helps scalability, 
          as there is no longer a memory and network traffic impact every time 
          another instance is added to a cluster.</para> 
          
          <para>If the cache on another node needs data that it doesn't have 
          locally, it can ask the other nodes in the cluster to provide it; 
          nodes that have a copy will provide it as part of a process called 
-         "data gravitation". The new node will become the owner of the data, 
+         <emphasis>data gravitation</emphasis>. The new node will become the owner of the data, 
          placing a backup copy of the data on its buddies. The ability to 
          gravitate data means there is no need for all requests for data to 
          occur on a node that has a copy of it; any node
-         can handle a request for any data.  However, data gravitation is 
+         can handle a request for any data. However, data gravitation is 
          expensive and should not be a frequent occurence; ideally it should 
          only occur if the node that is using some data fails or is shut down,
          forcing interested clients to fail over to a different node. This
          makes buddy replication primarily useful for session-type applications
-         with session affinity (a.k.a. "sticky sessions") where all requests
+         with session affinity (also known as <emphasis>sticky sessions</emphasis>) where all requests
          for a particular session are normally handled by a single server.</para>
          
          <para>Buddy replication can be enabled for the web session and
          EJB3 SFSB caches. Do not add buddy replication to the cache configurations
-         used for other standard clustering services (e.g. JPA/Hibernate
+         used for other standard clustering services (for example, JPA/Hibernate
          caching).  Services not specifically engineered for buddy replication
          are highly unlikely to work correctly if it is introduced.</para>
          
          <para>Configuring buddy replication is fairly straightforward. As
          an example we'll look at the buddy replication configuration section
-         from the CacheManager service's <literal>standard-session-cache</literal>
+         from the <classname>CacheManager</classname> service's <literal>standard-session-cache</literal>
          config:</para>
          <programlisting><![CDATA[
 <property name="buddyReplicationConfig">
@@ -770,28 +813,28 @@
          <para>The main things you would be likely to configure are:</para>
          
          <itemizedlist>
-         <listitem><para><emphasis role="bold">buddyReplicationEnabled</emphasis> 
-         &#8212; <literal>true</literal> if you want buddy replication; <literal>false</literal>
-         if data should be replicated to all nodes in the cluster, in which case
-         none of the other buddy replication configurations matter.</para>
-         </listitem>
-         <listitem><para><emphasis role="bold">numBuddies</emphasis> 
-         &#8212; to how many backup nodes should each node replicate its state.</para>
-         </listitem>
-         <listitem><para><emphasis role="bold">buddyPoolName</emphasis> 
-         &#8212; allows logical subgrouping of nodes within the cluster; if possible, 
-         buddies will be chosen from nodes in the same buddy pool.</para>
-         </listitem>
+           <listitem><para><varname>buddyReplicationEnabled</varname> 
+           &#8212; <literal>true</literal> if you want buddy replication; <literal>false</literal>
+           if data should be replicated to all nodes in the cluster, in which case
+           none of the other buddy replication configurations matter.</para>
+           </listitem>
+           <listitem><para><varname>numBuddies</varname> 
+           &#8212; to how many backup nodes should each node replicate its state.</para>
+           </listitem>
+           <listitem><para><varname>buddyPoolName</varname> 
+           &#8212; allows logical subgrouping of nodes within the cluster; if possible, 
+           buddies will be chosen from nodes in the same buddy pool.</para>
+           </listitem>
          </itemizedlist>
          
-         <para>The <literal>ignoreColocatedBuddies</literal> switch means that 
-         when the cache is trying to find a buddy, it will if possible not choose 
+         <para>The <varname>ignoreColocatedBuddies</varname> switch means that 
+         when the cache is trying to find a buddy, where possible it will not choose 
          a buddy on the same physical host as itself. If the only server it can 
          find is running on its own machine, it will use that server as a buddy.</para>
          
-         <para>Do not change the settings for <literal>autoDataGravitation</literal>, 
-         <literal>dataGravitationRemoveOnFind</literal> and 
-         <literal>dataGravitationSearchBackupTrees</literal>.  Session replication 
+         <para>Do not change the settings for <varname>autoDataGravitation</varname>, 
+         <varname>dataGravitationRemoveOnFind</varname> or 
+         <varname>dataGravitationSearchBackupTrees</varname>. Session replication 
          will not work properly if these are changed.</para>
       </section>
       
@@ -808,15 +851,16 @@
      <section id="jbosscache-custom-deployment-cachemgr">
        <title>Deployment Via the CacheManager Service</title>
        
-       <para>The standard JBoss clustered services that use JBoss Cache
-	       obtain a reference to their cache from the Enterprise Web Platform's CacheManager service
-       (see <xref linkend="clustering-blocks-jbc-cachemanager"/>). End
-       user applications can do the same thing; here's how.</para>
+       <para>The standard JBoss clustered services that use JBoss Cache obtain a reference 
+        to their cache from the Enterprise Web Platform's <classname>CacheManager</classname> 
+        service (see <xref linkend="clustering-blocks-jbc-cachemanager"/>). End
+       user applications can do the same thing.</para>
        
        <para><xref linkend="jbosscache-configuration-cachemanager"/> shows
-       the configuration of the CacheManager's "CacheConfigurationRegistry" bean.
+       the configuration of the CacheManager's <classname>CacheConfigurationRegistry</classname> bean.
        To add a new configuration, you would add an additional element inside 
-       that bean's <literal>newConfigurations</literal> &lt;map&gt;:</para>
+       that bean's <literal>newConfigurations</literal> 
+        <varname><![CDATA[<map>]]></varname>:</para>
        
        <programlisting><![CDATA[
 <bean name="CacheConfigurationRegistry" 
@@ -845,14 +889,14 @@
        
        <section>
           <title>Accessing the CacheManager</title>
-          <para>Once you've added your cache configuration to the CacheManager,
-          the next step is to provide a reference to the CacheManager to your
-          application.  There are three ways to do this:</para>
-          
+          <para>Once you've added your cache configuration to the <classname>CacheManager</classname>,
+          the next step is to provide a reference to your application to the CacheManager. 
+          There are three ways to do this:</para>
+
           <itemizedlist>
              <listitem><para><emphasis role="bold">Dependency Injection</emphasis></para>
              <para>If your application uses the JBoss Microcontainer for configuration,
-             the simplest mechanism is to have it inject the CacheManager into
+             the simplest mechanism is to have it inject the <classname>CacheManager</classname> into
              your service.</para>
              
              <programlisting><![CDATA[
@@ -861,7 +905,7 @@
 </bean>]]></programlisting>
              </listitem>
              <listitem><para><emphasis role="bold">JNDI Lookup</emphasis></para>
-             <para>Alternatively, you can find look up the CacheManger is
+             <para>Alternatively, you can look up the <classname>CacheManager</classname> in
              JNDI. It is bound under <literal>java:CacheManager</literal>.</para>
              
              <programlisting><![CDATA[
@@ -878,7 +922,7 @@
              </listitem>
              <listitem><para><emphasis role="bold">CacheManagerLocator</emphasis></para>
 		     <para>JBoss Enterprise Web Platform also provides a service locator object that can 
-             be used to access the CacheManager.</para>
+             be used to access the <classname>CacheManager</classname>.</para>
              
              <programlisting><![CDATA[
 import org.jboss.ha.cachemanager.CacheManager;
@@ -897,13 +941,13 @@
              </listitem>
           </itemizedlist>
           
-          <para>Once a reference to the CacheManager is obtained; usage is simple.
-          Access a cache by passing in the name of the desired configuration.
-          The CacheManager will not start the cache; this is the responsibility
+          <para>Once a reference to the <classname>CacheManager</classname> is obtained; 
+          usage is simple. Access a cache by passing in the name of the desired configuration.
+          The <classname>CacheManager</classname> will not start the cache; this is the responsibility
           of the application. The cache may, however, have been started by
           another application running in the cache server; the cache may be
           shared.  When the application is done using the cache, it should not 
-          stop.  Just inform the CacheManager that the cache is no longer being 
+          stop.  Just inform the <classname>CacheManager</classname> that the cache is no longer being 
           used; the manager will stop the cache when all callers that have asked
           for the cache have released it.</para>
              
@@ -932,7 +976,7 @@
    }
 }]]></programlisting>
           
-          <para>The CacheManager can also be used to access instances of
+          <para>The <classname>CacheManager</classname> can also be used to access instances of
           POJO Cache.</para>
              
              <programlisting><![CDATA[
@@ -964,15 +1008,13 @@
      </section>
      
      <section id="jbosscache-custom-deployment-service.xml">
-       <title>Deployment Via a <literal>-service.xml</literal> File</title>
+       <title>Deployment Via a <filename>-service.xml</filename> File</title>
        
-       <para>As in JBoss 4.x, you can also deploy a JBoss Cache instance as
-       an MBean service via a <literal>-service.xml</literal> file.
-       The primary difference from JBoss 4.x is the value of the <literal>code</literal>
-       attribute in the <literal>mbean</literal> element. In JBoss 4.x, this
-       was <literal>org.jboss.cache.TreeCache</literal>; in JBoss 5.x it is
-       <literal>org.jboss.cache.jmx.CacheJmxWrapper</literal>. Here's an
-       example:</para>
+       <para>You can also deploy a JBoss Cache instance as
+       an MBean service via a <filename>-service.xml</filename> file.
+       This is done through the <varname>code</varname> attribute in the <literal>mbean</literal>
+        element, and the <classname>org.jboss.cache.jmx.CacheJmxWrapper</classname>,
+        like so:</para>
        
        <programlisting><![CDATA[
 <?xml version="1.0" encoding="UTF-8"?>
@@ -999,24 +1041,24 @@
   </mbean>
 </server>]]></programlisting>
        
-       <para>The <literal>CacheJmxWrapper</literal> is not the cache itself (i.e.
+       <para>The <classname>CacheJmxWrapper</classname> is not the cache itself (that is,
        you can't store stuff in it). Rather, as it's name implies, it's
-       a wrapper around an <literal>org.jboss.cache.Cache</literal> that 
-       handles integration with JMX. <literal>CacheJmxWrapper</literal> exposes
-       the <literal>org.jboss.cache.Cache</literal> via its <literal>CacheJmxWrapperMBean</literal>
-       MBean interfaces <literal>Cache</literal> attribute; services that need 
-       the cache can obtain a reference to it via that attribute.</para>       
+       a wrapper around an <classname>org.jboss.cache.Cache</classname> that 
+       handles integration with JMX. <classname>CacheJmxWrapper</classname> exposes
+       the <classname>org.jboss.cache.Cache</classname> via its 
+      <classname>CacheJmxWrapperMBean</classname> MBean interfaces <literal>Cache</literal>   
+      attribute; services that need the cache can obtain a reference to it via that attribute.</para>       
      </section>
      
      <section id="jbosscache-custom-deployment-beans.xml">
-       <title>Deployment Via a <literal>-jboss-beans.xml</literal> File</title>
+       <title>Deployment Via a <filename>-jboss-beans.xml</filename> File</title>
        
        <para>Much like it can deploy MBean services described with a
-	       <literal>-service.xml</literal>, JBoss Enterprise Web Platform 5 can also deploy services
+	       <filename>-service.xml</filename>, JBoss Enterprise Web Platform can also deploy services
        that consist of Plain Old Java Objects (POJOs) if the POJOs are described
-       using the JBoss Microcontainer schema in a <literal>-jboss-beans.xml</literal>
+       using the JBoss Microcontainer schema in a <filename>-jboss-beans.xml</filename>
        file. You create such a file and deploy it, either directly in the
-       <literal>deploy</literal> dir, or packaged in an ear or sar. Following
+       <filename>deploy</filename> directory, or packaged in an EAR or SAR. Following
        is an example:</para>
        
        <programlisting><![CDATA[
@@ -1071,12 +1113,13 @@
 </deployment>]]></programlisting>
 
        <para>The bulk of the above is the creation of a JBoss Cache 
-       <literal>Configuration</literal> object; this is the same as what we
-       saw in the configuration of the CacheManager service 
+       <classname>Configuration</classname> object; this is the same as what we
+       saw in the configuration of the <classname>CacheManager</classname> service 
        (see <xref linkend="jbosscache-configuration-cachemanager"/>). In this
-       case we're not using the CacheManager service as a cache factory, so
+       case we're not using the <classname>CacheManager</classname> service as a cache factory, so
        instead we create our own factory bean and then use it to create
-       the cache (the "ExampleCache" bean).  The "ExampleCache" is then
+       the cache (the <classname>ExampleCache</classname> bean).  The 
+        <classname>ExampleCache</classname> is then
        injected into a (fictitious) service that needs it.</para>
        
        <para>An interesting thing to note in the above example is the use of the 
@@ -1087,7 +1130,7 @@
        other deployment descriptor in the Enterprise Web Platform, the referenced beans have already 
        been described.</para>
        
-       <para>Using the configuration above, the "ExampleCache" cache will not
+       <para>Using the configuration above, the <classname>ExampleCache</classname> cache will not
        be visible in JMX. Here's an alternate approach that results in
        the cache being bound into JMX:</para>
        
@@ -1122,18 +1165,18 @@
 
 </deployment>]]></programlisting>
      
-     <para>Here the "ExampleCacheJmxWrapper" bean handles the task of creating
-     the cache from the configuration. <literal>CacheJmxWrapper</literal> is
+     <para>Here the <classname>ExampleCacheJmxWrapper</classname> bean handles the task of creating
+     the cache from the configuration. <classname>CacheJmxWrapper</classname> is
      a JBoss Cache class that provides an MBean interface for a cache.
-     Adding an &lt;annotation&gt; element binds the JBoss Microcontainer
+     Adding an <varname><![CDATA[<annotation>]]></varname> element binds the JBoss Microcontainer
      <literal>@JMX</literal> annotation to the bean; that in turn results
-     in JBoss Enterprise Web Platform registering the bean in JXM as part of the deployment process.
+     in JBoss Enterprise Web Platform registering the bean in JMX as part of the deployment process.
      </para>
      
-     <para>The actual underlying <literal>org.jboss.cache.Cache</literal> instance
-     is available from the <literal>CacheJmxWrapper</literal> via its
-     <literal>cache</literal> property; the example shows how this
-     can be used to inject the cache into the "ExampleService".</para>
+     <para>The actual underlying <classname>org.jboss.cache.Cache</classname> instance
+     is available from the <classname>CacheJmxWrapper</classname> via its
+     <varname>cache</literal> varname; the example shows how this
+     can be used to inject the cache into the <classname>ExampleService</classname>.</para>
      </section>
      
     </section>




More information about the jboss-cvs-commits mailing list