[jboss-cvs] JBossCache/docs/JBossCache-UserGuide/en/modules ...
Brian Stansberry
brian.stansberry at jboss.com
Fri Jun 1 23:45:16 EDT 2007
User: bstansberry
Date: 07/06/01 23:45:16
Modified: docs/JBossCache-UserGuide/en/modules deployment.xml
Log:
[JBCACHE-809] Document configuration for the microcontainer
[JBCACHE-1052] JMX Docs
Revision Changes Path
1.8 +524 -68 JBossCache/docs/JBossCache-UserGuide/en/modules/deployment.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: deployment.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/deployment.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -b -r1.7 -r1.8
--- deployment.xml 31 May 2007 05:23:07 -0000 1.7
+++ deployment.xml 2 Jun 2007 03:45:16 -0000 1.8
@@ -5,59 +5,287 @@
<para>
When used in a standalone Java program, all that needs to be done is to instantiate the cache using the
<literal>CacheFactory</literal> and a <literal>Configuration</literal> instance or an XML file, as discussed
- in the <link linkend="api.create_start">User API chapter</link>.
+ in the <link linkend="api.create_start">User API</link> and
+ <link linkend="configuration.creation">Configuration</link> chapters.
+ </para>
+
+ <para>
+ The same techniques can be used when an application running in an application
+ server wishes to programatically deploy a cache rather than relying on the appserver's
+ deployment features. An example of this would be
+ a webapp deploying a cache via a <literal>javax.servlet.ServletContextListener</literal>.
+ </para>
+
+ <para>
+ If, after deploying your cache you wish to expose a management interface
+ to it in JMX, see the
+ <link linkend="jmx.registration.programatic">section on Programatic Registration in JMX</link>.
</para>
</section>
<section id="deployment.microkernel">
- <title>JMX-Based Deployment in JBoss AS (JBoss AS 4.x and 5.x)</title>
- <para>If JBoss Cache is run in JBoss AS 4.x then JBoss Cache can be deployed as an
- MBean. The steps below illustrate how to do this. We do not deploy JBoss Cache as a
- Service Archive (SAR), but as a JAR (
- <literal>jboss-cache.jar</literal> and all it's dependent jars in the lib directory) and
- an XML file defining the MBean. Of course, JBoss Cache can also be
- deployed as a SAR, or even as part of a WAR, EJB or EAR.
- </para>
-
- <para>First, the
- <literal>jboss-cache.jar</literal> and all it's dependent jars
- have to be copied to the server's <literal>/lib</literal>
- directory and JBoss AS has to be restarted. Then a regular JBoss Cache
- configuration file in XML format has to be copied to the /deploy
- directory. The XML file format is the same as discussed in
- the <link linkend="configuration">configuration chapter</link>.
+ <title>JMX-Based Deployment in JBoss AS (JBoss AS 5.x and 4.x)</title>
+ <para>If JBoss Cache is run in JBoss AS then the cache can be deployed as an
+ MBean simply by copying a standard cache configuration file to the server's
+ <literal>deploy</literal> directory. The standard format of JBoss Cache's
+ standard XML configuration file (as shown in the
+ <link linkend="sample_xml_file">Configuration Reference</link>) is the same
+ as a JBoss AS MBean deployment descriptor, so the AS's SAR Deployer has
+ no trouble handling it. Also, you don't have to place the configuration
+ file directly in <literal>deploy</literal>; you can package it along
+ with other services or JEE components in a SAR or EAR.
+ </para>
+
+ <para>
+ In AS 5, if you're using a server config based on the standard
+ <literal>all</literal> config, then that's all you need to do; all required
+ jars will be on the classpath. Otherwise, you will need to ensure
+ <literal>jbosscache.jar</literal> and <literal>jgroups-all.jar</literal>
+ are on the classpath. You may need to add other jars if you're using
+ things like <literal>JdbmCacheLoader</literal>. The simplest way to do
+ this is to copy the jars from the JBoss Cache distribution's
+ <literal>lib</literal> directory to the server config's <literal>lib</literal>
+ directory. You could also package the jars with the configuration file
+ in Service Archive (.sar) file or an EAR.
</para>
- <para>In order to be used from a client such as a servlet in the Tomcat web
- container inside the same JBoss container, a JMX lookup can be used:
+ <para>
+ It is possible to deploy a JBoss Cache 2.0 instance in JBoss AS 4.x
+ (at least in 4.2.0.GA; other AS releases are completely untested).
+ However, the significant API changes between the JBoss Cache 2.x and 1.x releases
+ mean none of the standard AS 4.x clustering services (e.g.
+ http session replication) that rely on JBoss Cache will work with
+ JBoss Cache 2.x. Also, be aware that usage of JBoss Cache 2.x in AS 4.x is not
+ something the JBoss Cache developers are making any significant effort to test,
+ so be sure to test your application well (which of course you're doing anyway.)
+ </para>
+
+ <para>
+ Note in the <link linkend="sample_xml_file">example</link>
+ the value of the <literal>mbean</literal> element's
+ <literal>code</literal> attribute:
+ <literal>org.jboss.cache.jmx.CacheJmxWrapper</literal>. This is the
+ class JBoss Cache uses to handle JMX integration; the
+ <literal>Cache</literal> itself does not expose an MBean
+ interface. See the
+ <link linkend="jmx.mbeans">JBoss Cache MBeans section</link>
+ for more on the <literal>CacheJmxWrapper</literal>.
+ </para>
+
+ <para>
+ Once your cache is deployed, in order to use it with an in-VM client
+ such as a servlet, a JMX proxy can be used to get a reference to
+ the cache:
</para>
<programlisting>
<![CDATA[
- MBeanServer server=MBeanServerLocator.locateJBoss();
- org.jboss.cache.jmx.CacheJmxWrapperMBean cacheWrapper;
- cacheWrapper = (org.jboss.cache.jmx.CacheJmxWrapperMBean) MBeanProxyExt.create(CacheJmxWrapperMBean.class, "jboss.cache:service=Cache", server);
+ MBeanServer server = MBeanServerLocator.locateJBoss();
+ ObjectName on = new ObjectName("jboss.cache:service=Cache");
+ CacheJmxWrapperMBean cacheWrapper =
+ (CacheJmxWrapperMBean) MBeanServerInvocationHandler.newProxyInstance(server, on,
+ CacheJmxWrapperMBean.class, false);
Cache cache = cacheWrapper.getCache();
- cache.getRoot(); // etc etc
+ Node root = cache.getRoot(); // etc etc
]]>
</programlisting>
<para>The MBeanServerLocator class is a helper to find the (only) JBoss
- MBean server inside the current JVM. The static create() method creates a
- dynamic proxy to the given interface and uses JMX to dynamically dispatch
- methods invoked against the generated interface. The name used to look up
- the MBean is the same as defined in the configuration file.
+ MBean server inside the current JVM. The
+ <literal>javax.management.MBeanServerInvocationHandler</literal> class'
+ <literal>newProxyInstance</literal> method creates a
+ dynamic proxy implementing the given interface and uses JMX to
+ dynamically dispatch methods invoked against the generated interface
+ to the MBean. The name used to look up the MBean is the same as defined
+ in the cache's configuration file.
+ </para>
+
+ <para>
+ Once the proxy to the <literal>CacheJmxWrapper</literal> is obtained,
+ the <literal>getCache()</literal> will return a reference to the
+ <literal>Cache</literal> itself.
</para>
- </section>
- <section>
- <title>Binding to JNDI</title>
- <para><emphasis>TODO</emphasis></para>
</section>
<section id="deployment.microcontainer">
<title>Via JBoss Microcontainer (JBoss AS 5.x)</title>
- <para><emphasis>TODO</emphasis></para>
+
+ <para>
+ Beginning with AS 5, JBoss AS also supports deployment of POJO services via
+ deployment of a file whose name ends with <literal>-beans.xml</literal>.
+ A POJO service is one whose implementation is via a "Plain Old Java Object",
+ meaning a simple java bean that isn't required to implement any special
+ interfaces or extend any particular superclass. A <literal>Cache</literal>
+ is a POJO service, and all the components in a <literal>Configuration</literal>
+ are also POJOS, so deploying a cache in this way is a natural step.
+ </para>
+ <para>
+ Deployment of the cache is done using the JBoss Microcontainer that forms the
+ core of JBoss AS. JBoss Microcontainer is a sophisticated IOC framework
+ (similar to Spring). A <literal>-beans.xml</literal> file is basically
+ a descriptor that tells the IOC framework how to assemble the various
+ beans that make up a POJO service.
+ </para>
+ <para>
+ The rules for how to deploy the file, how to package it, how to
+ ensure the required jars are on the classpath, etc. are the same
+ as for a <link linkend="deployment.microkernel">JMX-based deployment</link>.
+ </para>
+
+ <para>
+ Following is an example <literal>-beans.xml</literal> file. If you
+ look in the <literal>server/all/deploy</literal> directory of an AS 5
+ installation, you can find several more examples.
+ </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>
+
+ <!--
+ Node locking level : SERIALIZABLE
+ REPEATABLE_READ (default)
+ READ_COMMITTED
+ READ_UNCOMMITTED
+ NONE
+ -->
+ <property name="isolationLevel">REPEATABLE_READ</property>
+
+ <!-- Valid modes are LOCAL
+ REPL_ASYNC
+ REPL_SYNC
+ -->
+ <property name="cacheMode">REPL_SYNC</property>
+
+ <!-- The max amount of time (in milliseconds) we wait until the
+ initial state (ie. the contents of the cache) are retrieved from
+ existing members in a clustered environment
+ -->
+ <property name="initialStateRetrievalTimeout">15000</property>
+
+ <!-- Number of milliseconds to wait until all responses for a
+ synchronous call have been received.
+ -->
+ <property name="syncReplTimeout">20000</property>
+
+ <!-- Max number of milliseconds to wait for a lock acquisition -->
+ <property name="lockAcquisitionTimeout">15000</property>
+
+ <property name="exposeManagementStatistics">true</property>
+
+ <!-- Must be true if any entity deployment uses a scoped classloader -->
+ <property name="useRegionBasedMarshalling">true</property>
+ <!-- Must match the value of "useRegionBasedMarshalling" -->
+ <property name="inactiveOnStartup">true</property>
+
+ <!-- Specific eviction policy configurations. This is LRU -->
+ <property name="evictionConfig">
+ <bean name="ExampleEvictionConfig"
+ class="org.jboss.cache.config.EvictionConfig">
+ <property name="defaultEvictionPolicyClass">
+ org.jboss.cache.eviction.LRUPolicy
+ </property>
+ <property name="wakeupIntervalSeconds">5</property>
+ <property name="evictionRegionConfigs">
+ <list>
+ <bean name="ExampleDefaultEvictionRegionConfig"
+ class="org.jboss.cache.config.EvictionRegionConfig">
+ <property name="regionName">/_default_</property>
+ <property name="evictionPolicyConfig">
+ <bean name="ExampleDefaultLRUConfig"
+ class="org.jboss.cache.eviction.LRUConfiguration">
+ <property name="maxNodes">5000</property>
+ <property name="timeToLiveSeconds">1000</property>
+ </bean>
+ </property>
+ </bean>
+ </list>
+ </property>
+ </bean>
+ </property>
+
+ </bean>
+
+ <!-- Factory to build the Cache. -->
+ <bean name="DefaultCacheFactory" class="org.jboss.cache.DefaultCacheFactory">
+ <constructor factoryClass="org.jboss.cache.DefaultCacheFactory"
+ factoryMethod="getInstance"/>
+ </bean>
+
+ <!-- The cache itself -->
+ <bean name="ExampleCache" class="org.jboss.cache.CacheImpl">
+
+ <constructor factoryMethod="createCache">
+ <factory bean="DefaultCacheFactory"/>
+ <parameter><inject bean="ExampleCacheConfig"/></parameter>
+ <parameter>false</false>
+ </constructor>
+
+ </bean>
+
+</deployment>
+]]>
+ </programlisting>
+
+ <para>
+ See the JBoss Microcontainer documentation
+ <footnote>
+ <para>http://labs.jboss.com/jbossmc/docs</para>
+ </footnote>
+ for details on the above syntax. Basically, each <literal>bean</literal>
+ element represents an object; most going to create a
+ <literal>Configuration</literal> and its
+ <link linkend="configuration.elements">constituent parts</link>.
+ </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 been described.
+ </para>
+ </section>
+
+ <section>
+ <title>Binding to JNDI in JBoss AS</title>
+ <para>
+ With the 1.x JBoss Cache releases, a proxy to the cache could be bound
+ into JBoss AS's JNDI tree using the AS's <literal>JRMPProxyFactory</literal>
+ service. With JBoss Cache 2.x, this no longer works. An alternative
+ way of doing a similar thing with a POJO (i.e. non-JMX-based) service
+ like a <literal>Cache</literal> is under development by the JBoss AS
+ team
+ <footnote>
+ <para>http://jira.jboss.com/jira/browse/JBAS-4456</para>
+ </footnote>
+ . That feature is not available as of the time of this writing,
+ although it will be completed before AS 5.0.0.GA is released.
+ We will add a wiki page describing how to use it once it becomes available.
+ </para>
</section>
<section>
@@ -68,53 +296,281 @@
via JMX monitoring tools.
</para>
- <section>
+ <section id="jmx.mbeans">
<title>JBoss Cache MBeans</title>
<para>
- JBoss Cache provides an MBean that allows JMX access to a cache instance. This MBean is accessible from
- an MBean server through the service name specified in the cache instance's configuration. For example,
- the Tomcat clustering cache instance is accessible through the service named
- <literal>jboss.cache:service=TomcatClusteringCache</literal>. This MBean can be used to perform most cache
- operations via JMX, as shown earlier.
+ JBoss Cache provides an MBean that can be registered with your environments JMX server to allow access
+ to thea cache instance via JMX. This MBean is the <literal>org.jboss.cache.jmx.CacheJmxWrapper</literal>.
+ It is a StandardMBean, so it's MBean interface is <literal>org.jboss.cache.jmx.CacheJmxWrapperMBean</literal>.
+ This MBean can be used to:
+ <itemizedlist>
+ <listitem>Get a reference to the underlying <literal>Cache</literal>.</listitem>
+ <listitem>Invoke create/start/stop/destroy lifecycle operations on
+ the underlying <literal>Cache</literal>.</listitem>
+ <listitem>Inspect various details about the cache's current state (number of nodes, lock information, etc.)</listitem>
+ <listitem>See numerous details about the cache's configuration, and
+ change those configuration items that can be changed when the
+ cache has already been started.</listitem>
+ </itemizedlist>
+ See the <literal>CacheJmxWrapperMBean</literal> javadoc for more details.
+ </para>
+ <para>
+ It is important to note a significant architectural difference between JBoss Cache 1.x and 2.x. In 1.x,
+ the old <literal>TreeCache</literal> class was itself an MBean, and essentially exposed the cache's entire
+ API via JMX. In 2.x, JMX has been returned to it's fundamental role as a management layer. The
+ <literal>Cache</literal> object itself is completely unaware of JMX; instead JMX functionality is added
+ through a wrapper class designed for that purpose. Furthermore, the interface exposed through JMX
+ has been limited to management functions; the general <literal>Cache</literal> API is no longer exposed
+ through JMX. For example, it is no longer possible to invoke a cache <literal>put</literal> or
+ <literal>get</literal> via the JMX interface.
</para>
<para>
- JBoss Cache also provides MBeans for each interceptor configured in the cache's interceptor stack. These
+ If a <literal>CacheJmxWrapper</literal> is registered, JBoss Cache also provides MBeans
+ for each interceptor configured in the cache's interceptor stack. These
MBeans are used to capture and expose statistics related to cache operations. They are hierarchically
- associated with the cache's primary MBean and have service names that reflect this relationship. For
- example, a replication interceptor MBean for the <literal>TomcatClusteringCache</literal> instance will be
+ associated with the <literal>CacheJmxWrapper</literal> MBean and have service names that reflect this relationship. For
+ example, a replication interceptor MBean for the <literal>jboss.cache:service=TomcatClusteringCache</literal> instance will be
accessible through the service named <literal>jboss.cache:service=TomcatClusteringCache,cache-interceptor=ReplicationInterceptor</literal>.
</para>
</section>
+ <section id="jmx.registration">
+ <title>Registering the CacheJmxWrapper with the MBeanServer</title>
+
+ <para>
+ The best way to ensure the <literal>CacheJmxWrapper</literal> is registered
+ in JMX depends on how you are deploying your cache:
+ </para>
+
+ <section id="jmx.registration.programatic">
+ <title>Programatic Registration</title>
+
+ <para>
+ Simplest way to do this is to create your <literal>Cache</literal>
+ and pass it to the <literal>CacheJmxWrapper</literal> constructor.
+ </para>
+
+ <programlisting>
+ CacheFactory factory = DefaultCacheFactory.getInstance();
+ // Build but don't start the cache
+ // (although it would work OK if we started it)
+ Cache cache = factory.createCache("cache-configuration.xml", false);
+
+ CacheJmxWrapperMBean wrapper = new CacheJmxWrapper(cache);
+ MBeanServer server = getMBeanServer(); // however you do it
+ ObjectName on = new ObjectName("jboss.cache:service=TreeCache");
+ server.registerMBean(wrapper, on);
+
+ // Invoking lifecycle methods on the wrapper results
+ // in a call through to the cache
+ wrapper.create();
+ wrapper.start();
+
+ ... use the cache
+
+ ... on application shutdown
+
+ // Invoking lifecycle methods on the wrapper results
+ // in a call through to the cache
+ wrapper.stop();
+ wrapper.destroy();
+ </programlisting>
+
+ <para>
+ Alternatively, build a <literal>Configuration</literal> object
+ and pass it to the <literal>CacheJmxWrapper</literal>. The wrapper
+ will construct the <literal>Cache</literal>:
+ </para>
+
+ <programlisting>
+ Configuration config = buildConfiguration(); // whatever it does
+
+ CacheJmxWrapperMBean wrapper = new CacheJmxWrapper(config);
+ MBeanServer server = getMBeanServer(); // however you do it
+ ObjectName on = new ObjectName("jboss.cache:service=TreeCache");
+ server.registerMBean(wrapper, on);
+
+ // Call to wrapper.create() will build the Cache if one wasn't injected
+ wrapper.create();
+ wrapper.start();
+
+ // Now that it's built, created and started, get the cache from the wrapper
+ Cache cache = wrapper.getCache();
+
+ ... use the cache
+
+ ... on application shutdown
+
+ wrapper.stop();
+ wrapper.destroy();
+
+ </programlisting>
+ </section>
+
<section>
- <title>JBoss Cache Statistics</title>
+ <title>JMX-Based Deployment in JBoss AS (JBoss AS 4.x and 5.x)</title>
+
<para>
- JBoss Cache captures statistics in its interceptors and exposes the statistics through interceptor
- MBeans. Cache interceptor MBeans are enabled by default; these MBeans can be disabled for a specific cache
- instance through the <literal>ExposeManagementStatistics</literal> configuration attribute. See the
- <link linkend="configuration_reference">Configuration Reference chapter</link> for further details on
- this attribute.
+ When you
+ <link linkend="deployment.microkernel">deploy your cache in JBoss AS using a -service.xml file</link>,
+ a <literal>CacheJmxWrapper</literal> is automatically registered. There is no need
+ to do anything further. The <literal>CacheJmxWrapper</literal> is accessible from an MBean server
+ through the service name specified in the cache configuration file's <literal>mbean</literal> element.
</para>
+ </section>
+
+ <section>
+ <title>Via JBoss Microcontainer (JBoss AS 5.x)</title>
+
<para>
- Each interceptor's MBean provides an attribute that can be used to disable maintenance of statistics for
- that interceptor. Note that the majority of the statistics are provided by the <literal>CacheMgmtInterceptorMBean</literal>
+ <literal>CacheJmxWrapper</literal> is a POJO, so the microcontainer
+ has no problem creating one. The trick is
+ getting it to register your bean in JMX. This can be done by
+ specifying the <literal>org.jboss.aop.microcontainer.aspects.jmx.JMX</literal>
+ annotation on the <literal>CacheJmxWrapper</literal> bean:
+ </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">
+
+ ... build up the Configuration
+
+ </bean>
+
+ <!-- Factory to build the Cache. -->
+ <bean name="DefaultCacheFactory" class="org.jboss.cache.DefaultCacheFactory">
+ <constructor factoryClass="org.jboss.cache.DefaultCacheFactory"
+ factoryMethod="getInstance"/>
+ </bean>
+
+ <!-- The cache itself -->
+ <bean name="ExampleCache" class="org.jboss.cache.CacheImpl">
+
+ <constructor factoryMethod="createnewInstance">
+ <factory bean="DefaultCacheFactory"/>
+ <parameter><inject bean="ExampleCacheConfig"/></parameter>
+ <parameter>false</false>
+ </constructor>
+
+ </bean>
+
+ <!-- JMX Management -->
+ <bean name="ExampleCacheJmxWrapper" class="org.jboss.cache.jmx.CacheJmxWrapper">
+
+ <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.cache:service=ExampleTreeCache",
+ exposedInterface=org.jboss.cache.jmx.CacheJmxWrapperMBean.class,
+ registerDirectly=true)</annotation>
+
+ <constructor>
+ <parameter><inject bean="ExampleCache"/></parameter>
+ </constructor>
+
+ </bean>
+
+</deployment>
+]]>
+ </programlisting>
+
+ <para>
+ As discussed in the <link linkend="jmx.registration.programatic">Programatic Registration</link>
+ section, <literal>CacheJmxWrapper</literal> can do the work of building,
+ creating and starting the <literal>Cache</literal> if it is provided
+ with a <literal>Configuration</literal>. With the microcontainer,
+ this is the preferred approach, as it saves the boilerplate XML
+ needed to create the <literal>CacheFactory</literal>:
+ </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">
+
+ ... build up the Configuration
+
+ </bean>
+
+ <bean name="ExampleCache" class="org.jboss.cache.jmx.CacheJmxWrapper">
+
+ <annotation>@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.cache:service=ExampleTreeCache",
+ exposedInterface=org.jboss.cache.jmx.CacheJmxWrapperMBean.class,
+ registerDirectly=true)</annotation>
+
+ <constructor>
+ <parameter><inject bean="ExampleCacheConfig"/></parameter>
+ </constructor>
+
+ </bean>
+
+</deployment>
+]]>
+ </programlisting>
+ </section>
+
+ </section>
+
+ <section id="jmx.statistics">
+ <title>JBoss Cache Statistics</title>
+ <para>
+ JBoss Cache captures statistics in its interceptors and exposes the statistics through interceptor
+ MBeans. Gathering of statistics is enabled by default; this can be disabled for a specific cache
+ instance through the <literal>ExposeManagementStatistics</literal> configuration attribute. Note that
+ the majority of the statistics are provided by the <literal>CacheMgmtInterceptor</literal>,
so this MBean is the most significant in this regard. If you want to disable all statistics for performance
- reasons, you should utilize the <literal>ExposeManagementStatistics</literal> configuration setting as this will
+ reasons, you set <literal>ExposeManagementStatistics</literal> to <literal>false</literal> as this will
prevent the <literal>CacheMgmtInterceptor</literal> from being included in the cache's interceptor stack
when the cache is started.
</para>
-
- <para>Each interceptor provides the following common operations and attributes.
+ <para>
+ If a <literal>CacheJmxWrapper</literal> is registered with JMX, the wrapper also ensures that
+ an MBean is registered in JMX for each interceptor that exposes statistics
+ <footnote>
+ <para>
+ Note that if the <literal>CacheJmxWrapper</literal> is not registered in JMX, the
+ interceptor MBeans will not be registered either. The JBoss Cache 1.4 releases
+ included code that would try to "discover" an <literal>MBeanServer</literal> and
+ automatically register the interceptor MBeans with it. For JBoss Cache 2.x we decided
+ that this sort of "discovery" of the JMX environment was beyond the proper scope of
+ a caching library, so we removed this functionality.
+ </para>
+ </footnote>
+ .
+ Management tools can then access those MBeans to examine the statistics. See the section in the
+ <link linkend="jmx_reference.statistics">JMX Reference chapter</link> pertaining to the
+ statistics that are made available via JMX.
+ </para>
+ <para>
+ The name under which the interceptor MBeans will be registered is derived by taking the
+ <literal>ObjectName</literal> under which the <literal>CacheJmxWrapper</literal> is
+ registered and adding a <literal>cache-interceptor</literal> attribute key whose value
+ is the non-qualified name of the interceptor class. So, for example, if the
+ <literal>CacheJmxWrapper</literal> were registered under
+ <literal>jboss.cache:service=TreeCache</literal>, the name of the
+ <literal>CacheMgmtInterceptor</literal> MBean would be
+ <literal>jboss.cache:service=TreeCache,cache-interceptor=CacheMgmtInterceptor</literal>.
+ </para>
+ <para>
+ Each interceptor's MBean exposes a <literal>StatisticsEnabled</literal> attribute that can be used to disable maintenance of statistics for
+ that interceptor. In addition, each interceptor MBean provides the following common operations and attributes.
<itemizedlist>
<listitem><literal>dumpStatistics</literal> - returns a <literal>Map</literal> containing the interceptor's attributes and values.</listitem>
<listitem><literal>resetStatistics</literal> - resets all statistics maintained by the interceptor.</listitem>
<listitem><literal>setStatisticsEnabled(boolean)</literal> - allows statistics to be disabled for a specific interceptor.</listitem>
</itemizedlist>
- See the section in the <link linkend="jmx_reference.statistics">JMX Reference chapter</link> pertaining to the
- statistics that are made available via JMX.
</para>
-
-
+ <para>
+ </para>
</section>
<section>
@@ -216,8 +672,8 @@
<title>Accessing Cache MBeans in a Standalone Environment</title>
<para>
JBoss Cache MBeans are easily accessed when running cache instances in an application server that
- provides an MBean server interface such as JBoss JMX Console. Refer to server documentation for instructions on how
- to access MBeans running in a server's MBean container.
+ provides an MBean server interface such as JBoss JMX Console. Refer to your server documentation
+ for instructions on how to access MBeans running in a server's MBean container.
</para>
<para>
In addition, though, JBoss Cache MBeans are also accessible when running in a non-server environment if the
@@ -246,11 +702,11 @@
<para>The following figure shows cache interceptor MBeans in
<literal>jconsole</literal>. Cache statistics are displayed
- for the <literal>CacheMgmtInterceptorMBean</literal>:
+ for the <literal>CacheMgmtInterceptor</literal>:
</para>
<figure>
- <title>CacheMgmtInterceptorMBean in jconsole</title>
+ <title>CacheMgmtInterceptor MBean in jconsole</title>
<mediaobject>
<imageobject>
More information about the jboss-cvs-commits
mailing list