[jboss-cvs] JBossAS SVN: r82790 - projects/docs/community/5/Clustering_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Jan 12 22:45:37 EST 2009
Author: bstansberry at jboss.com
Date: 2009-01-12 22:45:37 -0500 (Mon, 12 Jan 2009)
New Revision: 82790
Modified:
projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Introduction.xml
Log:
[JBAS-6358] Add CacheManager section
Modified: projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Introduction.xml
===================================================================
--- projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Introduction.xml 2009-01-12 23:12:15 UTC (rev 82789)
+++ projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Introduction.xml 2009-01-13 03:45:37 UTC (rev 82790)
@@ -849,20 +849,241 @@
<para>Users can also create their own JBoss Cache and POJO Cache
instances for custom use by their applications, see
<xref linkend="jbosscache.chapt"/> for more on this.</para>
-
- <para>JBoss AS ships with a reasonable set of default JBoss Cache
- configurations that are suitable for standard clustered service
- use cases listed above. 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
- has special network or performance requirements.</para>
<section id="clustering-blocks-jbc-cachemanager">
<title>The JBoss AS CacheManager Service</title>
- <para></para>
+ <para>Many of the standard clustered services in JBoss AS use JBoss
+ Cache to maintain consistent state across the cluster. Different
+ services (e.g. web session clustering or second level caching of
+ JPA/Hibernate entities) use different JBoss Cache instances, with
+ each cache configured to meet the needs of the service that uses it.
+ In AS 4, each of these caches was independently deployed in the
+ <literal>deploy/</literal> directory, which had a number of disadvantages:
+ <itemizedlist>
+ <listitem><para>Caches that end user applications
+ didn't need were deployed anyway, with each creating an expensive
+ JGroups channel. For example, even if there were no clustered EJB3
+ SFSBs, a cache to store them was started.</para></listitem>
+ <listitem><para>Caches are internal details of the services that
+ use them. They shouldn't be first-class deployments.</para></listitem>
+ <listitem><para>Services would find their cache via JMX lookups.
+ Using JMX for purposes other exposing management interfaces is just
+ not the JBoss 5 way.</para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>In JBoss 5, the scattered cache deployments have been replaced
+ with a new <emphasis role="bold">CacheManager</emphasis> service,
+ deployed via the <literal>JBOSS_HOME/server/all/deploy/cluster/jboss-cache-manager.sar</literal>.
+ The CacheManager is a factory and registry for JBoss Cache instances.
+ It is configured with a set of named JBoss Cache configurations.
+ Services that need a cache ask the cache manager for the cache by
+ name; the cache manager creates the cache (if not already created)
+ and returns it. The cache manager keeps a reference to each cache
+ it has created, so all services that request the same cache name
+ will share the same cache. When a service is done with the cache,
+ it releases it to the cache manager. The cache manager keeps track
+ of how many services are using each cache, and will stop and destroy
+ the cache when all services have released it.</para>
+
+ <section id="clustering-blocks-jbc-cachemanager-stdconfigs">
+ <title>Standard Cache Configurations</title>
+ <para>The following standard configuration ship with JBoss AS 5.
+ You can add others to suit your needs, or edit these configurations
+ to adjust cache behavior. Additions or changes are done by editing
+ the <literal>deploy/cluster/jboss-cache-manager.sar/META-INF/jboss-cache-manager-jboss-beans.xml</literal>
+ file (see <xref linkend="jbosscache-custom-deployment-cachemgr"/>
+ for details). Note however that these configurations are specifically
+ optimized for their intended use, and except as specifically noted
+ in the documentation chapters for each service in this guide,
+ it is not advisable to change them.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">standard-session-cache</emphasis></para>
+ <para>Standard cache used for web sessions.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">field-granularity-session-cache</emphasis></para>
+ <para>Standard cache used for FIELD granularity web sessions.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">sfsb-cache</emphasis></para>
+ <para>Standard cache used for EJB3 SFSB caching.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">ha-partition</emphasis></para>
+ <para>Used by web tier Clustered Single Sign-On,
+ HA-JNDI, Distributed State.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">mvcc-entity</emphasis></para>
+ <para>A config appropriate for JPA/Hibernate entity/collection
+ caching that uses JBC's MVCC locking (see notes below).</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">optimistic-entity</emphasis></para>
+ <para>A config appropriate for JPA/Hibernate entity/collection
+ caching that uses JBC's optimistic locking (see notes below).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">pessimistic-entity</emphasis></para>
+ <para>A config appropriate for JPA/Hibernate entity/collection
+ caching that uses JBC's pessimistic locking (see notes below).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">mvcc-entity-repeatable</emphasis></para>
+ <para>Same as "mvcc-entity" but uses JBC's REPEATABLE_READ
+ isolation level instead of READ_COMMITTED (see notes below).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">pessimistic-entity-repeatable</emphasis></para>
+ <para>Same as "pessimistic-entity" but uses JBC's REPEATABLE_READ
+ isolation level instead of READ_COMMITTED (see notes below).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">local-query</emphasis></para>
+ <para>A config appropriate for JPA/Hibernate query result caching.
+ Does not replicate query results. DO NOT store the timestamp data
+ Hibernate uses to verify query result validity in this cache.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">replicated-query</emphasis></para>
+ <para>A config appropriate for JPA/Hibernate query result caching.
+ Replicates query results. DO NOT store the timestamp data
+ Hibernate uses to verify query result validity in this cache.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">timestamps-cache</emphasis></para>
+ <para>A config appropriate for the timestamp data cached as part
+ of JPA/Hibernate query result caching. A clustered timestamp cache
+ is required if query result caching is used, even if the query results
+ themselves use a non-replicating cache like <literal>local-query</literal>.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">mvcc-shared</emphasis></para>
+ <para>A config appropriate for a cache that's shared for JPA/Hibernate
+ entity, collection, query result and timestamp caching. Not an
+ advised configuration, since it requires cache mode REPL_SYNC,
+ which is the least efficient mode. Also requires a full state
+ transfer at startup, which can be expensive. Maintained for
+ backwards compatibility reasons, as a shared cache was the only
+ option in JBoss 4. Uses JBC's MVCC locking.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">optimistic-shared</emphasis></para>
+ <para>A config appropriate for a cache that's shared for JPA/Hibernate
+ entity, collection, query result and timestamp caching. Not an
+ advised configuration, since it requires cache mode REPL_SYNC,
+ which is the least efficient mode. Also requires a full state
+ transfer at startup, which can be expensive. Maintained for
+ backwards compatibility reasons, as a shared cache was the only
+ option in JBoss 4. Uses JBC's optimistic locking.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">pessimistic-shared</emphasis></para>
+ <para>A config appropriate for a cache that's shared for JPA/Hibernate
+ entity, collection, query result and timestamp caching. Not an
+ advised configuration, since it requires cache mode REPL_SYNC,
+ which is the least efficient mode. Also requires a full state
+ transfer at startup, which can be expensive. Maintained for
+ backwards compatibility reasons, as a shared cache was the only
+ option in JBoss 4. Uses JBC's pessimistic locking.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">mvcc-shared-repeatable</emphasis></para>
+ <para>Same as "mvcc-shared" but uses JBC's REPEATABLE_READ
+ isolation level instead of READ_COMMITTED (see notes below).
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">pessimistic-shared-repeatable</emphasis></para>
+ <para>Same as "pessimistic-shared" but uses JBC's REPEATABLE_READ
+ isolation level instead of READ_COMMITTED. (see notes below).
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <note><para>For more on JBoss Cache's locking schemes, see
+ <xref linkend="jbosscache-configuration-concurrency"/>)</para></note>
+
+ <note><para>For JPA/Hibernate second level caching, REPEATABLE_READ is
+ only useful if the application evicts/clears entities from the
+ EntityManager/Hibernate Session and then expects to repeatably
+ re-read them in the same transaction. Otherwise, the Session's
+ internal cache provides a repeatable-read semantic.</para></note>
+
+ </section>
+
+ <section>
+ <title>Cache Configuration Aliases</title>
+ <para>The CacheManager also supports aliasing of caches; i.e.
+ allowing caches registered under one name to be looked up under a
+ different name. Aliasing is useful for sharing caches between
+ services whose configuration may specify different cache config
+ names. It's also useful for supporting legacy EJB3 application
+ configurations ported over from AS 4.</para>
+ <para>Aliases can be configured by editing the "CacheManager"
+ bean in the <literal>jboss-cache-manager-jboss-beans.xml</literal>
+ file. The following redacted config shows the standard aliases in
+ AS 5.0.0.GA:</para>
+
+ <programlisting><![CDATA[
+<bean name="CacheManager" class="org.jboss.ha.cachemanager.CacheManager">
+
+ . . .
+
+ <!-- Aliases for cache names. Allows caches to be shared across
+ services that may expect different cache config names. -->
+ <property name="configAliases">
+ <map keyClass="java.lang.String" valueClass="java.lang.String">
+ <!-- Use the HAPartition cache for ClusteredSSO caching -->
+ <entry>
+ <key>clustered-sso</key>
+ <value>ha-partition</value>
+ </entry>
+ <!-- Handle the legacy name for the EJB3 SFSB cache -->
+ <entry>
+ <key>jboss.cache:service=EJB3SFSBClusteredCache</key>
+ <value>sfsb-cache</value>
+ </entry>
+ <!-- Handle the legacy name for the EJB3 Entity cache -->
+ <entry>
+ <key>jboss.cache:service=EJB3EntityTreeCache</key>
+ <value>mvcc-shared</value>
+ </entry>
+ </map>
+ </property>
+
+ . . .
+
+</bean>]]></programlisting>
</section>
</section>
</section>
+
+ </section>
<section id="clustering-intro-farm">
<title>Farming Deployment</title>
@@ -957,7 +1178,6 @@
</itemizedlist>
</section>
-
-
+
</chapter>
More information about the jboss-cvs-commits
mailing list