[jboss-cvs] JBossAS SVN: r82791 - 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:46:03 EST 2009
Author: bstansberry at jboss.com
Date: 2009-01-12 22:46:03 -0500 (Mon, 12 Jan 2009)
New Revision: 82791
Modified:
projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_JBoss_Cache.xml
Log:
[JBAS-6350] More JBC content
Modified: projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_JBoss_Cache.xml
===================================================================
--- projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_JBoss_Cache.xml 2009-01-13 03:45:37 UTC (rev 82790)
+++ projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_JBoss_Cache.xml 2009-01-13 03:46:03 UTC (rev 82791)
@@ -12,7 +12,7 @@
services the AS provides. We then discuss the different options available
for deploying a custom cache in the AS.
</para>
- <para>Users considering deploying JBoss Cache as part of their own
+ <para>Users considering deploying JBoss Cache for direct use by their own
application are strongly encouraged to read the JBoss Cache
documentation available at http://www.jboss.org/jbosscache.</para>
@@ -22,8 +22,9 @@
<section id="jbosscache-configuration">
<title>Key JBoss Cache Configuration Options</title>
<para>JBoss AS ships with a reasonable set of default JBoss Cache
- configurations that are suitable for standard clustered service
- use cases. Most applications that involve the standard
+ configurations that are suitable for the standard clustered service
+ use cases (e.g. 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
has special network or performance requirements. In this section we
@@ -38,6 +39,235 @@
the standard JBoss AS CacheManager service uses the JBoss Microcontainer
schema to be consistent with most other internal AS 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>
+
+ <section id="jbosscache-configuration-cachemanager">
+ <title>Editing the CacheManager Configuration</title>
+ <para>As discussed in <xref linkend="clustering-blocks-jbc-cachemanager"/>,
+ the standard JBoss AS 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>
+
+ <note><para>Users can also use the CacheManager 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"
+ bean, which maintains a registry of all the named JBC configurations
+ the CacheManager 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>
+
+ <programlisting><![CDATA[
+<bean name="CacheConfigurationRegistry"
+ class="org.jboss.ha.cachemanager.DependencyInjectedConfigurationRegistry">
+
+ <!-- If users wish to add configs using a more familiar JBC config format
+ they can add them to a cache-configs.xml file specified by this property.
+ However, use of the microcontainer format used below is recommended.
+ <property name="configResource">META-INF/jboss-cache-configs.xml</property>
+ -->
+
+ <!-- The configurations. A Map<String name, Configuration config> -->
+ <property name="newConfigurations">
+ <map keyClass="java.lang.String" valueClass="org.jboss.cache.config.Configuration">
+
+ <!-- The standard configurations follow. You can add your own and/or edit these. -->
+
+ <!-- Standard cache used for web sessions -->
+ <entry><key>standard-session-cache</key>
+ <value>
+ <bean name="StandardSessionCacheConfig" class="org.jboss.cache.config.Configuration">
+
+ <!-- Provides batching functionality for caches that don't want to
+ interact with regular JTA Transactions -->
+ <property name="transactionManagerLookupClass">
+ org.jboss.cache.transaction.BatchModeTransactionManagerLookup
+ </property>
+
+ <!-- Name of cluster. Needs to be the same for all members -->
+ <property name="clusterName">${jboss.partition.name:DefaultPartition}-SessionCache</property>
+ <!-- Use a UDP (multicast) based stack. Need JGroups flow control (FC)
+ because we are using asynchronous replication. -->
+ <property name="multiplexerStack">${jboss.default.jgroups.stack:udp}</property>
+ <property name="fetchInMemoryState">true</property>
+
+ <property name="nodeLockingScheme">PESSIMISTIC</property>
+ <property name="isolationLevel">REPEATABLE_READ</property>
+ <property name="cacheMode">REPL_ASYNC</property>
+
+ .... more details of the standard-session-cache configuration
+ </bean>
+ </value>
+ </entry>
+
+ <!-- Appropriate for web sessions with FIELD granularity -->
+ <entry><key>field-granularity-session-cache</key>
+ <value>
+
+ <bean name="FieldSessionCacheConfig" class="org.jboss.cache.config.Configuration">
+ .... details of the field-granularity-standard-session-cache configuration
+ </bean>
+
+ </value>
+
+ </entry>
+
+ ... entry elements for the other configurations
+
+ </map>
+ </property>
+</bean>]]></programlisting>
+
+ <para>The actual JBoss Cache configurations are specified using the
+ 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
+ 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
+ let the AS's microcontainer do it directly. This has the advantage
+ of making the microcontainer aware of the configuration beans, which
+ in later AS 5.x 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 AS 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>
+
+ <programlisting><![CDATA[
+<bean name="StandardSFSBCacheConfig" class="org.jboss.cache.config.Configuration">
+
+ <!-- No transaction manager lookup -->
+
+ <!-- Name of cluster. Needs to be the same for all members -->
+ <property name="clusterName">${jboss.partition.name:DefaultPartition}-SFSBCache</property>
+ <!-- Use a UDP (multicast) based stack. Need JGroups flow control (FC)
+ because we are using asynchronous replication. -->
+ <property name="multiplexerStack">${jboss.default.jgroups.stack:udp}</property>
+ <property name="fetchInMemoryState">true</property>
+
+ <property name="nodeLockingScheme">PESSIMISTIC</property>
+ <property name="isolationLevel">REPEATABLE_READ</property>
+ <property name="cacheMode">REPL_ASYNC</property>
+
+ <!-- Number of milliseconds to wait until all responses for a
+ synchronous call have been received. Make this longer
+ than lockAcquisitionTimeout.-->
+ <property name="syncReplTimeout">17500</property>
+ <!-- Max number of milliseconds to wait for a lock acquisition -->
+ <property name="lockAcquisitionTimeout">15000</property>
+ <!-- The max amount of time (in milliseconds) we wait until the
+ state (ie. the contents of the cache) are retrieved from
+ existing members at startup. -->
+ <property name="stateRetrievalTimeout">60000</property>
+
+ <!--
+ SFSBs use region-based marshalling to provide for partial state
+ transfer during deployment/undeployment.
+ -->
+ <property name="useRegionBasedMarshalling">false</property>
+ <!-- Must match the value of "useRegionBasedMarshalling" -->
+ <property name="inactiveOnStartup">false</property>
+
+ <!-- Disable asynchronous RPC marshalling/sending -->
+ <property name="serializationExecutorPoolSize">0</property>
+ <!-- We have no asynchronous notification listeners -->
+ <property name="listenerAsyncPoolSize">0</property>
+
+ <property name="exposeManagementStatistics">true</property>
+
+ <property name="buddyReplicationConfig">
+ <bean class="org.jboss.cache.config.BuddyReplicationConfig">
+
+ <!-- Just set to true to turn on buddy replication -->
+ <property name="enabled">false</property>
+
+ <!-- A way to specify a preferred replication group. We try
+ and pick a buddy who shares the same pool name (falling
+ back to other buddies if not available). -->
+ <property name="buddyPoolName">default</property>
+
+ <property name="buddyCommunicationTimeout">17500</property>
+
+ <!-- Do not change these -->
+ <property name="autoDataGravitation">false</property>
+ <property name="dataGravitationRemoveOnFind">true</property>
+ <property name="dataGravitationSearchBackupTrees">true</property>
+
+ <property name="buddyLocatorConfig">
+ <bean class="org.jboss.cache.buddyreplication.NextMemberBuddyLocatorConfig">
+ <!-- The number of backup nodes we maintain -->
+ <property name="numBuddies">1</property>
+ <!-- Means that each node will *try* to select a buddy on
+ a different physical host. If not able to do so
+ though, it will fall back to colocated nodes. -->
+ <property name="ignoreColocatedBuddies">true</property>
+ </bean>
+ </property>
+ </bean>
+ </property>
+ <property name="cacheLoaderConfig">
+ <bean class="org.jboss.cache.config.CacheLoaderConfig">
+ <!-- Do not change these -->
+ <property name="passivation">true</property>
+ <property name="shared">false</property>
+
+ <property name="individualCacheLoaderConfigs">
+ <list>
+ <bean class="org.jboss.cache.loader.FileCacheLoaderConfig">
+ <!-- Where passivated sessions are stored -->
+ <property name="location">${jboss.server.data.dir}${/}sfsb</property>
+ <!-- Do not change these -->
+ <property name="async">false</property>
+ <property name="fetchPersistentState">true</property>
+ <property name="purgeOnStartup">true</property>
+ <property name="ignoreModifications">false</property>
+ <property name="checkCharacterPortability">false</property>
+ </bean>
+ </list>
+ </property>
+ </bean>
+ </property>
+
+ <!-- EJBs use JBoss Cache eviction -->
+ <property name="evictionConfig">
+ <bean class="org.jboss.cache.config.EvictionConfig">
+ <property name="wakeupInterval">5000</property>
+ <!-- Overall default -->
+ <property name="defaultEvictionRegionConfig">
+ <bean class="org.jboss.cache.config.EvictionRegionConfig">
+ <property name="regionName">/</property>
+ <property name="evictionAlgorithmConfig">
+ <bean class="org.jboss.cache.eviction.NullEvictionAlgorithmConfig"/>
+ </property>
+ </bean>
+ </property>
+ <!-- EJB3 integration code will programatically create
+ other regions as beans are deployed -->
+ </bean>
+ </property>
+</bean>]]></programlisting>
+
+ <para>Basically, the XML specifies the creation of an
+ <literal>org.jboss.cache.config.Configuration</literal> 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>
+
+ <para>Next we'll look at some of the key configuration options.</para>
+
+ </section>
<section id="jbosscache-configuration-cachemode">
<title>Cache Mode</title>
@@ -58,7 +288,7 @@
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, leading to a high need for consistency.
+ 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
@@ -207,7 +437,7 @@
<listitem><para>Readers that don't block writers</para></listitem>
<listitem><para>Writers that fail fast</para></listitem>
</itemizedlist>
- and achieves this by using data versioning and copying for concurrent
+ 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
@@ -221,13 +451,13 @@
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 lesser concurrency,
+ 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
+ deprecated as of JBoss Cache 3.0. But, for the session caching usage
in JBoss AS 5.0.0, PESSIMISTIC is still the default. This is largely
because 1) for the session use case there are generally not concurrent
threads accessing the same cache location, so the benefits of MVCC
@@ -238,15 +468,15 @@
<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 is <emphasis>copied</emphasis>
- into the workspace (which is adds overhead). All data is versioned;
+ 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.</para>
+ instead, which provides the same benefits at lower cost.</para>
</listitem>
</itemizedlist>
</para>
@@ -269,7 +499,7 @@
<section id="jbosscache-configuration-jgroups">
<title>JGroups Integration</title>
- <para>Each JBoss Cache instance internally uses JGroups <literal>Channel</literal>
+ <para>Each JBoss Cache instance internally uses a JGroups <literal>Channel</literal>
to handle group communications. Inside JBoss AS, we strongly recommend
that you use the AS's JGroups Channel Factory service (see
<xref linkend="clustering-blocks-jgroups-channelfactory"/>) as the
@@ -285,20 +515,22 @@
task is to configure the name of the JGroups protocol stack configuration
to use.</para>
- <para>If you are configuring your cache via the
- <literal>deploy/cluster/jboss-cache-manager.sar/META-INF/jboss-cache-manager-jboss-beans.xml</literal>
+ <para>If you are configuring your cache via the CacheManager service's
+ <literal>jboss-cache-manager-jboss-beans.xml</literal>
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>
<programlisting><![CDATA[<property name="multiplexerStack">udp</property>]]></programlisting>
+ <!--
<para>If you are using the CacheManager service's <literal>jboss-cache-configs.xml</literal>
file to configure your cache using the JBoss Cache 3 schema
(see <xref linkend="jbosscache-custom-deployment-cachemgr-cacheconfigs"/>),
you add the following to your cache configuration:</para>
<programlisting><![CDATA[<jgroupsConfig multiplexerStack="udp"/>]]></programlisting>
+ -->
<para><emphasis role="bold">Caches Deployed via a <literal>-jboss-beans.xml</literal> File</emphasis></para>
@@ -356,8 +588,8 @@
<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
+ 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 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
@@ -381,7 +613,7 @@
<para>HttpSession and SFSB passivation rely on JBoss Cache's
Cache Loader passivation for storing and retrieving the passivated
sessions. Therefore the cache instance used by your webapp's clustered
- session manager or your bean's container must be configured to enable
+ session manager or your bean's EJB container must be configured to enable
Cache Loader passivaton.</para>
<para>In most cases you don't need to do anything to alter the cache
loader configurations for the standard web session and SFSB caches;
@@ -494,7 +726,7 @@
EJB3 SFSB caches. Do not add buddy replication to the cache configurations
used for other standard clustering services (e.g. JPA/Hibernate
caching). Services not specifically engineered for buddy replication
- are unlikely to work correctly if it is introduced.</para>
+ 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
@@ -564,26 +796,220 @@
<section id="jbosscache-custom-deployment">
<title>Deploying Your Own JBoss Cache Instance</title>
- <para></para>
+ <para>It's quite common for users to deploy their own instances of
+ JBoss Cache inside JBoss AS for custom use by their applications.
+ In this section we describe the various ways caches can be
+ deployed.</para>
+
<section id="jbosscache-custom-deployment-cachemgr">
<title>Deployment Via the CacheManager Service</title>
- <para></para>
- <section id="jbosscache-custom-deployment-cachemgr-cacheconfigs">
+ <para>The standard JBoss clustered services that use JBoss Cache
+ obtain a reference to their cache from the AS's CacheManager service
+ (see <xref linkend="clustering-blocks-jbc-cachemanager"/>). End
+ user applications can do the same thing; here's how.</para>
+
+ <para><xref linkend="jbosscache-configuration-cachemanager"/> shows
+ the configuration of the CacheManager's "CacheConfigurationRegistry" bean.
+ To add a new configuration, you would add an additional element inside
+ that bean's <literal>newConfigurations</literal> <map>:.</para>
+
+ <programlisting><![CDATA[
+<bean name="CacheConfigurationRegistry"
+ class="org.jboss.ha.cachemanager.DependencyInjectedConfigurationRegistry">
+ .....
+ <property name="newConfigurations">
+ <map keyClass="java.lang.String" valueClass="org.jboss.cache.config.Configuration">
+
+ <entry><key>my-custom-cache</key>
+ <value>
+ <bean name="MyCustomCacheConfig" class="org.jboss.cache.config.Configuration">
+ .... details of the my-custom-cache configuration
+ </bean>
+ </value>
+ </entry>
+ .....
+]]></programlisting>
+
+ <para>See <xref linkend="jbosscache-configuration-cachemanager"/>
+ for an example configuration.</para>
+
+ <!-- <section id="jbosscache-custom-deployment-cachemgr-cacheconfigs">
<title>Using <literal>jboss-cache-configs.xml</literal></title>
<para></para>
- </section>
+ </section>-->
</section>
<section id="jbosscache-custom-deployment-service.xml">
<title>Deployment Via a <literal>-service.xml</literal> File</title>
- <para></para>
+
+ <para>As in JBoss 4, 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 is the value of the <literal>code</literal>
+ attribute in the <literal>mbean</literal> element. In JBoss 4, this
+ was <literal>org.jboss.cache.TreeCache</literal>; in JBoss 5 it is
+ <literal>org.jboss.cache.jmx.CacheJmxWrapper</literal>. Here's an
+ example:</para>
+
+ <programlisting><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+
+<server>
+ <mbean code="org.jboss.cache.jmx.CacheJmxWrapper"
+ name="foo:service=ExampleCacheJmxWrapper">
+
+ <attribute name="TransactionManagerLookupClass">
+ org.jboss.cache.transaction.JBossTransactionManagerLookup
+ </attribute>
+
+ <attribute name="MuxChannelFactory"><inject bean="JChannelFactory"/></attribute>
+
+ <attribute name="MultiplexerStack">udp</attribute>
+ <attribute name="ClusterName">Example-EntityCache</attribute>
+ <attribute name="IsolationLevel">REPEATABLE_READ</attribute>
+ <attribute name="CacheMode">REPL_SYNC</attribute>
+ <attribute name="InitialStateRetrievalTimeout">15000</attribute>
+ <attribute name="SyncReplTimeout">20000</attribute>
+ <attribute name="LockAcquisitionTimeout">15000</attribute>
+ <attribute name="ExposeManagementStatistics">true</attribute>
+
+ </mbean>
+</server>]]></programlisting>
+
+ <para>The <literal>CacheJmxWrapper</literal> is not the cache itself (i.e.
+ 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>
</section>
<section id="jbosscache-custom-deployment-beans.xml">
<title>Deployment Via a <literal>-jboss-beans.xml</literal> File</title>
- <para></para>
+
+ <para>Much like it can deploy MBean services described with a
+ <literal>-service.xml</literal>, JBoss AS 5 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>
+ 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
+ is an example:</para>
+
+ <programlisting><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+
+<deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <!-- First we create a Configuration object for the cache -->
+ <bean name="ExampleCacheConfig"
+ class="org.jboss.cache.config.Configuration">
+
+ <!-- Externally injected services -->
+ <property name="runtimeConfig">
+ <bean name="ExampleCacheRuntimeConfig" class="org.jboss.cache.config.RuntimeConfig">
+ <property name="transactionManager">
+ <inject bean="jboss:service=TransactionManager"
+ property="TransactionManager"/>
+ </property>
+ <property name="muxChannelFactory"><inject bean="JChannelFactory"/></property>
+ </bean>
+ </property>
+
+ <property name="multiplexerStack">udp</property>
+ <property name="clusterName">Example-EntityCache</property>
+ <property name="isolationLevel">REPEATABLE_READ</property>
+ <property name="cacheMode">REPL_SYNC</property>
+ <property name="initialStateRetrievalTimeout">15000</property>
+ <property name="syncReplTimeout">20000</property>
+ <property name="lockAcquisitionTimeout">15000</property>
+ <property name="exposeManagementStatistics">true</property>
+
+ </bean>
+
+ <!-- Factory to build the Cache. -->
+ <bean name="DefaultCacheFactory" class="org.jboss.cache.DefaultCacheFactory">
+ <constructor factoryClass="org.jboss.cache.DefaultCacheFactory" />
+ </bean>
+
+ <!-- The cache itself -->
+ <bean name="ExampleCache" class="org.jboss.cache.Cache">
+ <constructor factoryMethod="createCache">
+ <factory bean="DefaultCacheFactory"/>
+ <parameter class="org.jboss.cache.config.Configuration"><inject bean="ExampleCacheConfig"/></parameter>
+ <parameter class="boolean">false</false>
+ </constructor>
+ </bean>
+
+ <bean name="ExampleService" class="org.foo.ExampleService">
+ <property name="cache"><inject bean="ExampleCache"/></property>
+ </bean>
+
+</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
+ (see <xref linkend="jbosscache-configuration-cachemanager"/>). In this
+ case we're not using the CacheManager 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
+ injected into a (fictitious) service that needs it.</para>
+
+ <para>An interesting thing to note in the above example is the use of the
+ <literal>RuntimeConfig</literal> object. External resources like a
+ <literal>TransactionManager</literal> and a JGroups <literal>ChannelFactory</literal>
+ that are visible to the microcontainer are dependency injected into the
+ <literal>RuntimeConfig</literal>. The assumption here is that in some
+ other deployment descriptor in the AS, the referenced beans have already
+ been described.</para>
+
+ <para>Using the configuration above, the "ExampleCache" cache will not
+ be visible in JMX. Here's an alternate approach that results in
+ the cache being bound into JMX:</para>
+
+ <programlisting><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+
+<deployment xmlns="urn:jboss:bean-deployer:2.0">
+
+ <!-- First we create a Configuration object for the cache -->
+ <bean name="ExampleCacheConfig"
+ class="org.jboss.cache.config.Configuration">
+
+ .... same as above
+
+ </bean>
+
+ <bean name="ExampleCacheJmxWrapper" class="org.jboss.cache.jmx.CacheJmxWrapper">
+
+ <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="foo:service=ExampleCacheJmxWrapper",
+ exposedInterface=org.jboss.cache.jmx.CacheJmxWrapperMBean.class, registerDirectly=true)
+ </annotation>
+
+ <property name="configuration"><inject bean="ExampleCacheConfig"/></property>
+
+ </bean>
+
+ <bean name="ExampleService" class="org.foo.ExampleService">
+ <property name="cache"><inject bean="ExampleCacheJmxWrapper" property="cache"/></property>
+ </bean>
+
+</deployment>]]></programlisting>
+
+ <para>Here the "ExampleCacheJmxWrapper" bean handles the task of creating
+ the cache from the configuration. <literal>CacheJmxWrapper</literal> is
+ a JBoss Cache class that provides an MBean interface for a cache.
+ Adding an <annotation> element binds the JBoss Microcontainer
+ <literal>@JMX</literal> annotation to the bean; that in turn results
+ in JBoss AS registering the bean in JXM 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>
</section>
</section>
More information about the jboss-cvs-commits
mailing list