<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><title xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory">Chapter 5. Deploying JBoss Cache</title><link rel="stylesheet" href="css/jbossorg.css" type="text/css"/><meta xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" name="generator" content="DocBook XSL Stylesheets V1.72.0"/><link rel="start" href="index.html" title="JBoss Cache Users' Guide"/><link rel="up" href="pt01.html" title="Part I. Introduction to JBoss Cache"/><link rel="prev" href="batching.html" title="Chapter 4. Batching API"/><link rel="next" href="compatibility.html" title="Chapter 6. Version Compatibility and Interoperability"/></head><body><p id="title"><a href="http://www.jboss.org" class="site_href"><strong>JBoss.org</strong></a><a href="http://docs.jboss.org/" class="doc_href"><strong>Community Documentation</strong></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="batching.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="compatibility.html"><strong>Next</strong></a></li></ul><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="deployment"/>Chapter 5. Deploying JBoss Cache</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="deployment.html#deployment.standalone">5.1. Standalone Use/Programatic Deployment</a></span></dt><dt><span class="section"><a href="deployment.html#deployment.microcontainer">5.2. Via JBoss Microcontainer (JBoss AS 5.x)</a></span></dt><dt><span class="section"><a href="deployment.html#d0e1152">5.3. Automatic binding to JNDI in JBoss AS</a></span></dt><dt><span class="section"><a href="deployment.html#d0e1160">5.4. Runtime Management Information</a></span></dt><dd><dl><dt><span class="section"><a href="deployment.html#jmx.mbeans">5.4.1. JBoss Cache MBeans</a></span></dt><dt><span class="section"><a href="deployment.html#jmx.registration">5.4.2. Registering the CacheJmxWrapper with the MBeanServer</a></span></dt><dt><span class="section"><a href="deployment.html#jmx.statistics">5.4.3. JBoss Cache Statistics</a></span></dt><dt><span class="section"><a href="deployment.html#d0e1300">5.4.4. Receiving JMX Notifications</a></span></dt><dt><span class="section"><a href="deployment.html#jconsole">5.4.5. Accessing Cache MBeans in a Standalone Environment using the <code class="literal">jconsole</code> Utility</a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="deployment.standalone"/>5.1. Standalone Use/Programatic Deployment</h2></div></div></div><p>
When used in a standalone Java program, all that needs to be done is to instantiate the cache using the
<code class="literal">CacheFactory</code>
and a
<code class="literal">Configuration</code>
instance or an XML file, as discussed
in the
<a href="api.html#api.create_start" title="2.2. Instantiating and Starting the Cache">User API</a>
and
<a href="configuration.html#configuration.creation" title="3.2. Creating a Configuration">Configuration</a>
chapters.
</p><p>
The same techniques can be used when an application running in an application
server wishes to programatically deploy a cache rather than relying on an application server's
deployment features. An example of this would be
a webapp deploying a cache via a
<code class="literal">javax.servlet.ServletContextListener</code>.
</p><p>
After creation, you could share your cache instance among different application components either by using an
IOC container such as Spring, JBoss Microcontainer, etc., or by binding it to JNDI, or simply
holding a static reference to the cache.
</p><p>
If, after deploying your cache you wish to expose a management interface
to it in JMX, see the
<a href="deployment.html#jmx.registration.programatic" title="5.4.2.1. Programatic Registration">section on Programatic Registration in JMX</a>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="deployment.microcontainer"/>5.2. Via JBoss Microcontainer (JBoss AS 5.x)</h2></div></div></div><p>
For detailed information on how to deploy JBoss Cache instances this way,
please check section "11.2. Deploying Your Own JBoss Cache Instance" and more
specifically, section "11.2.3. Deployment Via a -jboss-beans.xml File" in the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://jboss.org/file-access/default/members/jbossclustering/freezone/docs/cluster_guide/5.0/draft/en-US/pdf/Clustering_Guide.pdf">
JBoss Application Server 5 Clustering Guide</a>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="d0e1152"/>5.3. Automatic binding to JNDI in JBoss AS</h2></div></div></div><p>
Although access to cache instances bound to JNDI is not possible, JBoss Application
Server 5 binds a CacheManager to JNDI which can be looked up and from where cache
instances can be retrieved. Further detailed information can be found in section
"11.2.1. Deployment Via the CacheManager Service" in the
<a xmlns:xlink="http://www.w3.org/1999/xlink" href="http://jboss.org/file-access/default/members/jbossclustering/freezone/docs/cluster_guide/5.0/draft/en-US/pdf/Clustering_Guide.pdf">
JBoss Application Server 5 Clustering Guide</a>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="d0e1160"/>5.4. Runtime Management Information</h2></div></div></div><p>JBoss Cache includes JMX MBeans to expose cache functionality and provide statistics that can be
used to analyze cache operations. JBoss Cache can also broadcast cache events as MBean notifications for
handling via JMX monitoring tools.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="jmx.mbeans"/>5.4.1. JBoss Cache MBeans</h3></div></div></div><p>
JBoss Cache provides an MBean that can be registered with your environments JMX server to allow access
to the cache instance via JMX. This MBean is the
<code class="literal">org.jboss.cache.jmx.CacheJmxWrapper</code>.
It is a StandardMBean, so its MBean interface is <code class="literal">org.jboss.cache.jmx.CacheJmxWrapperMBean</code>.
This MBean can be used to:
</p><div class="itemizedlist"><ul><li>
Get a reference to the underlying <code class="literal">Cache</code>.
</li><li>
Invoke create/start/stop/destroy lifecycle operations on the underlying <code class="literal">Cache</code>.
</li><li>
Inspect various details about the cache's current state (number of nodes, lock information, etc.)
</li><li>
See numerous details about the cache's configuration, and
change those configuration items that can be changed when the
cache has already been started.
</li></ul></div><p>
See the <code class="literal">CacheJmxWrapperMBean</code> javadoc for more details.
</p><p>
If a <code class="literal">CacheJmxWrapper</code> is registered, JBoss Cache also provides MBeans
for several other internal components and subsystems. These MBeans are used to capture and expose
statistics related to the subsystems they represent. They are hierarchically associated with the
<code class="literal">CacheJmxWrapper</code> MBean and have service names that reflect this relationship. For
example, a replication interceptor MBean for the <code class="literal">jboss.cache:service=TomcatClusteringCache</code>
instance will be accessible through the service named
<code class="literal">jboss.cache:service=TomcatClusteringCache,cache-interceptor=ReplicationInterceptor</code>.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="jmx.registration"/>5.4.2. Registering the CacheJmxWrapper with the MBeanServer</h3></div></div></div><p>
The best way to ensure the <code class="literal">CacheJmxWrapper</code> is registered in JMX depends on how you are
deploying your cache.
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="jmx.registration.programatic"/>5.4.2.1. Programatic Registration</h4></div></div></div><p>
Simplest way to do this is to create your <code class="literal">Cache</code> and pass it to the
<code class="literal">JmxRegistrationManager</code> constructor.
</p><pre xmlns="" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="JAVA"></span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">CacheFactory</span><span class="java_plain"> factory </span><span class="java_operator">=</span><span class="java_plain"> </span><span class="java_keyword">new</span><span class="java_plain"> </span><span class="java_type">DefaultCacheFactory</span><span class="java_separator">();</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_operator">//</span><span class="java_plain"> </span><span class="java_type">Build</span><span class="java_plain"> but don't start the cache</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_operator">//</span><span class="java_plain"> </span><span class="java_separator">(</span><span class="java_plain">although it would work OK </span><span class="java_keyword">if</span><span class="java_plain"> we started it</span><span class="java_separator">)</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">Cache</span><span class="java_plain"> cache </span><span class="java_operator">=</span><span class="java_plain"> factory</span><span class="java_separator">.</span><span class="java_plain">createCache</span><span class="java_separator">(</span><span class="java_literal">"cache-configuration.xml"</span><span class="java_separator">);</span>
</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">MBeanServer</span><span class="java_plain"> server </span><span class="java_operator">=</span><span class="java_plain"> getMBeanServer</span><span class="java_separator">();</span><span class="java_plain"> </span><span class="java_operator">//</span><span class="java_plain"> however you </span><span class="java_keyword">do</span><span class="java_plain"> it</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">ObjectName</span><span class="java_plain"> on </span><span class="java_operator">=</span><span class="java_plain"> </span><span class="java_keyword">new</span><span class="java_plain"> </span><span class="java_type">ObjectName</span><span class="java_separator">(</span><span class="java_literal">"jboss.cache:service=Cache"</span><span class="java_separator">);</span>
<!-- --><br/><span class="java_plain"> </span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">JmxRegistrationManager</span><span class="java_plain"> jmxManager </span><span class="java_operator">=</span><span class="java_plain"> </span><span class="java_keyword">new</span><span class="java_plain"> </span><span class="java_type">JmxRegistrationManager</span><span class="java_separator">(</span><span class="java_plain">server</span><span class="java_separator">,</span><span class="java_plain"> cache</span><span class="java_separator">,</span><span class="java_plain"> on</span><span class="java_separator">);</span>
<!-- --><br/><span class="java_plain"> jmxManager</span><span class="java_separator">.</span><span class="java_plain">registerAllMBeans</span><span class="java_separator">();</span>
</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_separator">...</span><span class="java_plain"> use the cache</span>
</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_separator">...</span><span class="java_plain"> on application shutdown</span>
</span>
<!-- --><br/><span class="java_plain"> jmxManager</span><span class="java_separator">.</span><span class="java_plain">unregisterAllMBeans</span><span class="java_separator">();</span>
<!-- --><br/><span class="java_plain"> cache</span><span class="java_separator">.</span><span class="java_plain">stop</span><span class="java_separator">();</span>
</span>
<!-- --><br/><span class="java_plain"> </span></pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a id="d0e1230"/>5.4.2.2. JMX-Based Deployment in JBoss AS (JBoss AS 5.x)</h4></div></div></div><p>
<code class="literal">CacheJmxWrapper</code> 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
<code class="literal">org.jboss.aop.microcontainer.aspects.jmx.JMX</code>
annotation on the <code class="literal">CacheJmxWrapper</code>
bean:
</p><pre xmlns="" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="XML"><!-- XML : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) -->
<span class="xml_plain"></span><br />
<span class="xml_processing_instruction"><?xml version="1.0" encoding="UTF-8"?></span><span class="xml_plain"></span><br />
<span class="xml_plain"></span><br />
<span class="xml_tag_symbols"><</span><span class="xml_tag_name">deployment</span><span class="xml_plain"> </span><span class="xml_attribute_name">xmlns</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"urn:jboss:bean-deployer:2.0"</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_comment"><!-- First we create a Configuration object for the cache --></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">bean</span><span class="xml_plain"> </span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"ExampleCacheConfig"</span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_attribute_name">class</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"org.jboss.cache.config.Configuration"</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><br />
<span class="xml_plain"> ... build up the Configuration</span><br />
<span class="xml_plain"> </span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">bean</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><br />
<span class="xml_plain"> </span><span class="xml_comment"><!-- Factory to build the Cache. --></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">bean</span><span class="xml_plain"> </span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"DefaultCacheFactory"</span><span class="xml_plain"> </span><span class="xml_attribute_name">class</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"org.jboss.cache.DefaultCacheFactory"</span><span class="xml_tag_symbols">></span><span class="xml_plain"> </span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">constructor</span><span class="xml_plain"> </span><span class="xml_attribute_name">factoryClass</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"org.jboss.cache.DefaultCacheFactory"</span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_attribute_name">factoryMethod</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"getInstance"</span><span class="xml_plain"> </span><span class="xml_tag_symbols">/></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">bean</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><br />
<span class="xml_plain"> </span><span class="xml_comment"><!-- The cache itself --></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">bean</span><span class="xml_plain"> </span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"ExampleCache"</span><span class="xml_plain"> </span><span class="xml_attribute_name">class</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"org.jboss.cache.CacheImpl"</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">constructor</span><span class="xml_plain"> </span><span class="xml_attribute_name">factoryMethod</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"createnewInstance"</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">factory</span><span class="xml_plain"> </span><span class="xml_attribute_name">bean</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"DefaultCacheFactory"</span><span class="xml_tag_symbols">/></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">parameter</span><span class="xml_tag_symbols">><</span><span class="xml_tag_name">inject</span><span class="xml_plain"> </span><span class="xml_attribute_name">bean</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"ExampleCacheConfig"</span><span class="xml_tag_symbols">/></</span><span class="xml_tag_name">parameter</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">parameter</span><span class="xml_tag_symbols">></span><span class="xml_plain">false</span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">parameter</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">constructor</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">bean</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><br />
<span class="xml_plain"> </span><span class="xml_comment"><!-- JMX Management --></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">bean</span><span class="xml_plain"> </span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"ExampleCacheJmxWrapper"</span><span class="xml_plain"> </span><span class="xml_attribute_name">class</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"org.jboss.cache.jmx.CacheJmxWrapper"</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">annotation</span><span class="xml_tag_symbols">></span><span class="xml_plain">@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.cache:service=ExampleTreeCache", </span><br />
<span class="xml_plain"> exposedInterface=org.jboss.cache.jmx.CacheJmxWrapperMBean.class, </span><br />
<span class="xml_plain"> registerDirectly=true)</span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">annotation</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">constructor</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">parameter</span><span class="xml_tag_symbols">><</span><span class="xml_tag_name">inject</span><span class="xml_plain"> </span><span class="xml_attribute_name">bean</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"ExampleCache"</span><span class="xml_tag_symbols">/></</span><span class="xml_tag_name">parameter</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">constructor</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">bean</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"></span><br />
<span class="xml_tag_symbols"></</span><span class="xml_tag_name">deployment</span><span class="xml_tag_symbols">></span><span class="xml_plain"> </span><br />
</pre><p>
As discussed in the <a href="deployment.html#jmx.registration.programatic" title="5.4.2.1. Programatic Registration">Programatic Registration</a>
section, <code class="literal">CacheJmxWrapper</code> can do the work of building, creating and starting the
<code class="literal">Cache</code> if it is provided with a <code class="literal">Configuration</code>. With the
microcontainer, this is the preferred approach, as it saves the boilerplate XML
needed to create the <code class="literal">CacheFactory</code>.
</p><pre xmlns="" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="XML"><!-- XML : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) -->
<span class="xml_plain"></span><br />
<span class="xml_processing_instruction"><?xml version="1.0" encoding="UTF-8"?></span><span class="xml_plain"></span><br />
<span class="xml_plain"></span><br />
<span class="xml_tag_symbols"><</span><span class="xml_tag_name">deployment</span><span class="xml_plain"> </span><span class="xml_attribute_name">xmlns</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"urn:jboss:bean-deployer:2.0"</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_comment"><!-- First we create a Configuration object for the cache --></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">bean</span><span class="xml_plain"> </span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"ExampleCacheConfig"</span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_attribute_name">class</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"org.jboss.cache.config.Configuration"</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><br />
<span class="xml_plain"> ... build up the Configuration</span><br />
<span class="xml_plain"> </span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">bean</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">bean</span><span class="xml_plain"> </span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"ExampleCache"</span><span class="xml_plain"> </span><span class="xml_attribute_name">class</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"org.jboss.cache.jmx.CacheJmxWrapper"</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">annotation</span><span class="xml_tag_symbols">></span><span class="xml_plain">@org.jboss.aop.microcontainer.aspects.jmx.JMX(name="jboss.cache:service=ExampleTreeCache", </span><br />
<span class="xml_plain"> exposedInterface=org.jboss.cache.jmx.CacheJmxWrapperMBean.class, </span><br />
<span class="xml_plain"> registerDirectly=true)</span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">annotation</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">constructor</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"><</span><span class="xml_tag_name">parameter</span><span class="xml_tag_symbols">><</span><span class="xml_tag_name">inject</span><span class="xml_plain"> </span><span class="xml_attribute_name">bean</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">"ExampleCacheConfig"</span><span class="xml_tag_symbols">/></</span><span class="xml_tag_name">parameter</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">constructor</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"> </span><br />
<span class="xml_plain"> </span><span class="xml_tag_symbols"></</span><span class="xml_tag_name">bean</span><span class="xml_tag_symbols">></span><span class="xml_plain"></span><br />
<span class="xml_plain"></span><br />
<span class="xml_tag_symbols"></</span><span class="xml_tag_name">deployment</span><span class="xml_tag_symbols">></span><span class="xml_plain"> </span><br />
</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="jmx.statistics"/>5.4.3. JBoss Cache Statistics</h3></div></div></div><p>
JBoss Cache captures statistics in its interceptors and various other components, and exposes these
statistics through a set of MBeans. Gathering of statistics is enabled by default; this can be disabled for
a specific cache instance through the <code class="literal">Configuration.setExposeManagementStatistics()</code>
setter. Note that the majority of the statistics are provided by the <code class="literal">CacheMgmtInterceptor</code>,
so this MBean is the most significant in this regard. If you want to disable all statistics for performance
reasons, you set <code class="literal">Configuration.setExposeManagementStatistics(false)</code> and this will
prevent the <code class="literal">CacheMgmtInterceptor</code> from being included in the cache's interceptor stack
when the cache is started.
</p><p>
If a <code class="literal">CacheJmxWrapper</code> is registered with JMX, the wrapper also ensures that
an MBean is registered in JMX for each interceptor and component that exposes statistics.
<sup>[<a id="d0e1287" href="#ftn.d0e1287">1</a>]</sup>.
Management tools can then access those MBeans to examine the statistics. See the section in the
<a href="jmx_reference.html#jmx_reference.statistics" title="13.1. JBoss Cache Statistics">JMX Reference chapter</a>
pertaining to the statistics that are made available via JMX.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="d0e1300"/>5.4.4. Receiving JMX Notifications</h3></div></div></div><p>
JBoss Cache users can register a listener to receive cache events described earlier in the
<a href="api.html#api.listener" title="2.7. Adding a Cache Listener - registering for cache events">User API</a>
chapter. Users can alternatively utilize the cache's management information infrastructure to receive these
events via JMX notifications. Cache events are accessible as notifications by registering a
<code class="literal">NotificationListener</code> for the <code class="literal">CacheJmxWrapper</code>.
</p><p>
See the section in the <a href="jmx_reference.html#jmx_reference.notifications" title="13.2. JMX MBean Notifications">JMX Reference chapter</a>
pertaining to JMX notifications for a list of notifications that can be received through the
<code class="literal">CacheJmxWrapper</code>.
</p><p>
The following is an example of how to programmatically receive cache notifications when running in a
JBoss AS environment. In this example, the client uses a filter to specify which events are of interest.
</p><pre xmlns="" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="JAVA"></span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">MyListener</span><span class="java_plain"> listener </span><span class="java_operator">=</span><span class="java_plain"> </span><span class="java_keyword">new</span><span class="java_plain"> </span><span class="java_type">MyListener</span><span class="java_separator">();</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">NotificationFilterSupport</span><span class="java_plain"> filter </span><span class="java_operator">=</span><span class="java_plain"> </span><span class="java_literal">null</span><span class="java_separator">;</span>
</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_operator">//</span><span class="java_plain"> get reference to </span><span class="java_type">MBean</span><span class="java_plain"> server</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">Context</span><span class="java_plain"> ic </span><span class="java_operator">=</span><span class="java_plain"> </span><span class="java_keyword">new</span><span class="java_plain"> </span><span class="java_type">InitialContext</span><span class="java_separator">();</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">MBeanServerConnection</span><span class="java_plain"> server </span><span class="java_operator">=</span><span class="java_plain"> </span><span class="java_separator">(</span><span class="java_type">MBeanServerConnection</span><span class="java_separator">)</span><span class="java_plain">ic</span><span class="java_separator">.</span><span class="java_plain">lookup</span><span class="java_separator">(</span><span class="java_literal">"jmx/invoker/RMIAdaptor"</span><span class="java_separator">);</span>
</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_operator">//</span><span class="java_plain"> get reference to </span><span class="java_type">CacheMgmtInterceptor</span><span class="java_plain"> </span><span class="java_type">MBean</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">String</span><span class="java_plain"> cache_service </span><span class="java_operator">=</span><span class="java_plain"> </span><span class="java_literal">"jboss.cache:service=TomcatClusteringCache"</span><span class="java_separator">;</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">ObjectName</span><span class="java_plain"> mgmt_name </span><span class="java_operator">=</span><span class="java_plain"> </span><span class="java_keyword">new</span><span class="java_plain"> </span><span class="java_type">ObjectName</span><span class="java_separator">(</span><span class="java_plain">cache_service</span><span class="java_separator">);</span>
</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_operator">//</span><span class="java_plain"> configure a filter to only receive node created and removed events</span>
<!-- --><br/><span class="java_plain"> filter </span><span class="java_operator">=</span><span class="java_plain"> </span><span class="java_keyword">new</span><span class="java_plain"> </span><span class="java_type">NotificationFilterSupport</span><span class="java_separator">();</span>
<!-- --><br/><span class="java_plain"> filter</span><span class="java_separator">.</span><span class="java_plain">disableAllTypes</span><span class="java_separator">();</span>
<!-- --><br/><span class="java_plain"> filter</span><span class="java_separator">.</span><span class="java_plain">enableType</span><span class="java_separator">(</span><span class="java_type">CacheNotificationBroadcaster</span><span class="java_separator">.</span><span class="java_plain">NOTIF_NODE_CREATED</span><span class="java_separator">);</span>
<!-- --><br/><span class="java_plain"> filter</span><span class="java_separator">.</span><span class="java_plain">enableType</span><span class="java_separator">(</span><span class="java_type">CacheNotificationBroadcaster</span><span class="java_separator">.</span><span class="java_plain">NOTIF_NODE_REMOVED</span><span class="java_separator">);</span>
</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_operator">//</span><span class="java_plain"> register the listener with a filter</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_operator">//</span><span class="java_plain"> leave the filter </span><span class="java_literal">null</span><span class="java_plain"> to receive all cache events</span>
<!-- --><br/><span class="java_plain"> server</span><span class="java_separator">.</span><span class="java_plain">addNotificationListener</span><span class="java_separator">(</span><span class="java_plain">mgmt_name</span><span class="java_separator">,</span><span class="java_plain"> listener</span><span class="java_separator">,</span><span class="java_plain"> filter</span><span class="java_separator">,</span><span class="java_plain"> </span><span class="java_literal">null</span><span class="java_separator">);</span>
</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_operator">//</span><span class="java_plain"> </span><span class="java_separator">...</span>
</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_operator">//</span><span class="java_plain"> on completion of processing</span><span class="java_separator">,</span><span class="java_plain"> unregister the listener</span>
<!-- --><br/><span class="java_plain"> server</span><span class="java_separator">.</span><span class="java_plain">removeNotificationListener</span><span class="java_separator">(</span><span class="java_plain">mgmt_name</span><span class="java_separator">,</span><span class="java_plain"> listener</span><span class="java_separator">,</span><span class="java_plain"> filter</span><span class="java_separator">,</span><span class="java_plain"> </span><span class="java_literal">null</span><span class="java_separator">);</span>
<!-- --><br/><span class="java_plain"> </span></pre><p>The following is the simple notification listener implementation used in the previous example.</p><pre xmlns="" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="JAVA"></span>
<!-- --><br/><span class="java_plain"> </span><span class="java_keyword">private</span><span class="java_plain"> </span><span class="java_keyword">class</span><span class="java_plain"> </span><span class="java_type">MyListener</span><span class="java_plain"> </span><span class="java_keyword">implements</span><span class="java_plain"> </span><span class="java_type">NotificationListener</span><span class="java_separator">,</span><span class="java_plain"> </span><span class="java_type">Serializable</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_separator">{</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_keyword">public</span><span class="java_plain"> </span><span class="java_type">void</span><span class="java_plain"> handleNotification</span><span class="java_separator">(</span><span class="java_type">Notification</span><span class="java_plain"> notification</span><span class="java_separator">,</span><span class="java_plain"> </span><span class="java_type">Object</span><span class="java_plain"> handback</span><span class="java_separator">)</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_separator">{</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">String</span><span class="java_plain"> message </span><span class="java_operator">=</span><span class="java_plain"> notification</span><span class="java_separator">.</span><span class="java_plain">getMessage</span><span class="java_separator">();</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">String</span><span class="java_plain"> type </span><span class="java_operator">=</span><span class="java_plain"> notification</span><span class="java_separator">.</span><span class="java_plain">getType</span><span class="java_separator">();</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">Object</span><span class="java_plain"> userData </span><span class="java_operator">=</span><span class="java_plain"> notification</span><span class="java_separator">.</span><span class="java_plain">getUserData</span><span class="java_separator">();</span>
</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">System</span><span class="java_separator">.</span><span class="java_plain">out</span><span class="java_separator">.</span><span class="java_plain">println</span><span class="java_separator">(</span><span class="java_plain">type </span><span class="java_operator">+</span><span class="java_plain"> </span><span class="java_literal">": "</span><span class="java_plain"> </span><span class="java_operator">+</span><span class="java_plain"> message</span><span class="java_separator">);</span>
</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_keyword">if</span><span class="java_plain"> </span><span class="java_separator">(</span><span class="java_plain">userData </span><span class="java_operator">==</span><span class="java_plain"> </span><span class="java_literal">null</span><span class="java_separator">)</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_separator">{</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">System</span><span class="java_separator">.</span><span class="java_plain">out</span><span class="java_separator">.</span><span class="java_plain">println</span><span class="java_separator">(</span><span class="java_literal">"notification data is null"</span><span class="java_separator">);</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_separator">}</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_keyword">else</span><span class="java_plain"> </span><span class="java_keyword">if</span><span class="java_plain"> </span><span class="java_separator">(</span><span class="java_plain">userData </span><span class="java_keyword">instanceof</span><span class="java_plain"> </span><span class="java_type">String</span><span class="java_separator">)</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_separator">{</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">System</span><span class="java_separator">.</span><span class="java_plain">out</span><span class="java_separator">.</span><span class="java_plain">println</span><span class="java_separator">(</span><span class="java_literal">"notification data: "</span><span class="java_plain"> </span><span class="java_operator">+</span><span class="java_plain"> </span><span class="java_separator">(</span><span class="java_type">String</span><span class="java_separator">)</span><span class="java_plain"> userData</span><span class="java_separator">);</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_separator">}</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_keyword">else</span><span class="java_plain"> </span><span class="java_keyword">if</span><span class="java_plain"> </span><span class="java_separator">(</span><span class="java_plain">userData </span><span class="java_keyword">instanceof</span><span class="java_plain"> </span><span class="java_type">Object</span><span class="java_separator">[])</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_separator">{</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">Object</span><span class="java_separator">[]</span><span class="java_plain"> ud </span><span class="java_operator">=</span><span class="java_plain"> </span><span class="java_separator">(</span><span class="java_type">Object</span><span class="java_separator">[])</span><span class="java_plain"> userData</span><span class="java_separator">;</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_keyword">for</span><span class="java_plain"> </span><span class="java_separator">(</span><span class="java_type">Object</span><span class="java_plain"> data </span><span class="java_operator">:</span><span class="java_plain"> ud</span><span class="java_separator">)</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_separator">{</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">System</span><span class="java_separator">.</span><span class="java_plain">out</span><span class="java_separator">.</span><span class="java_plain">println</span><span class="java_separator">(</span><span class="java_literal">"notification data: "</span><span class="java_plain"> </span><span class="java_operator">+</span><span class="java_plain"> data</span><span class="java_separator">.</span><span class="java_plain">toString</span><span class="java_separator">());</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_separator">}</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_separator">}</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_keyword">else</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_separator">{</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_type">System</span><span class="java_separator">.</span><span class="java_plain">out</span><span class="java_separator">.</span><span class="java_plain">println</span><span class="java_separator">(</span><span class="java_literal">"notification data class: "</span><span class="java_plain"> </span><span class="java_operator">+</span><span class="java_plain"> userData</span><span class="java_separator">.</span><span class="java_plain">getClass</span><span class="java_separator">().</span><span class="java_plain">getName</span><span class="java_separator">());</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_separator">}</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_separator">}</span>
<!-- --><br/><span class="java_plain"> </span><span class="java_separator">}</span>
<!-- --><br/><span class="java_plain"> </span></pre><p>Note that the JBoss Cache management implementation only listens to cache events after a client registers
to receive MBean notifications. As soon as no clients are registered for notifications, the MBean will
remove
itself as a cache listener.
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a id="jconsole"/>5.4.5. Accessing Cache MBeans in a Standalone Environment using the <code class="literal">jconsole</code> Utility</h3></div></div></div><p>
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 your server documentation
for instructions on how to access MBeans running in a server's MBean container.
</p><p>
In addition, though, JBoss Cache MBeans are also accessible when running in a non-server environment using
your JDK's <code class="literal">jconsole</code> tool. When running a standalone cache outside of an application server,
you can access the cache's MBeans as follows.
</p><p>
</p><div xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="orderedlist"><ol><li>
Set the system property <code class="literal">-Dcom.sun.management.jmxremote</code>
when starting the JVM where the cache will run.
</li><li>
Once the JVM is running, start the <code class="literal">jconsole</code> utility, located in your JDK's
<code class="literal">/bin</code> directory.
</li><li>
When the utility loads, you will be able to select your running JVM and connect to it. The
JBoss Cache MBeans will be available on the MBeans panel.
</li></ol></div><p>
</p><p>Note that the <code class="literal">jconsole</code> utility will automatically register as a listener for cache
notifications when connected to a JVM running JBoss Cache instances.
</p></div></div><div xmlns="" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="footnotes"><br/><hr/><div xmlns="http://www.w3.org/1999/xhtml" class="footnote"><p><sup>[<a id="ftn.d0e1287" href="#d0e1287">1</a>] </sup>
Note that if the
<code class="literal">CacheJmxWrapper</code>
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
<code class="literal">MBeanServer</code>
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.
</p></div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="batching.html"><strong>Prev</strong>Chapter 4. Batching API</a></li><li class="up"><a accesskey="u" href="#"><strong>Top of page</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Front page</strong></a></li><li class="next"><a accesskey="n" href="compatibility.html"><strong>Next</strong>Chapter 6. Version Compatibility and Interoperabi...</a></li></ul></body></html>