[jboss-cvs] JBossCache/docs/JBossCache-UserGuide/en/modules ...
Manik Surtani
manik at jboss.org
Wed Jun 6 10:07:40 EDT 2007
User: msurtani
Date: 07/06/06 10:07:40
Modified: docs/JBossCache-UserGuide/en/modules configuration.xml
deployment.xml
Log:
Minor tweaks
Revision Changes Path
1.11 +279 -189 JBossCache/docs/JBossCache-UserGuide/en/modules/configuration.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: configuration.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/configuration.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -b -r1.10 -r1.11
--- configuration.xml 2 Jun 2007 03:41:05 -0000 1.10
+++ configuration.xml 6 Jun 2007 14:07:40 -0000 1.11
@@ -5,35 +5,51 @@
<title>Configuration Overview</title>
<para>
- The <literal>org.jboss.cache.config.Configuration</literal> class
+ The
+ <literal>org.jboss.cache.config.Configuration</literal>
+ class
(along with its
- <link linkend="configuration.elements">component parts</link>)
+ <link linkend="configuration.elements">component parts</link>
+ )
is a Java Bean that encapsulates the configuration of the
- <literal>Cache</literal> and all of its architectural elements
+ <literal>Cache</literal>
+ and all of its architectural elements
(cache loaders, evictions policies, etc.)
</para>
<para>
- The <literal>Configuration</literal> exposes numerous properties which
+ The
+ <literal>Configuration</literal>
+ exposes numerous properties which
are summarized in the
<link linkend="configuration_reference">configuration reference</link>
section of this book and many of which are discussed in later
chapters. Any time you see a configuration option
- discussed in this book, you can assume that the <literal>Configuration</literal>
+ discussed in this book, you can assume that the
+ <literal>Configuration</literal>
class or one of its component parts exposes a simple property setter/getter for that configuration option.
</para>
</section>
<section id="configuration.creation">
- <title>Creating a <literal>Configuration</literal></title>
-
- <para>
- As discussed in the <link linkend="api.create_start">User API section</link>,
- before a <literal>Cache</literal> can be created, the
- <literal>CacheFactory</literal> must be provided with a
- <literal>Configuration</literal> object or with a file name or
- input stream to use to parse a <literal>Configuration</literal>
+ <title>Creating a
+ <literal>Configuration</literal>
+ </title>
+
+ <para>
+ As discussed in the
+ <link linkend="api.create_start">User API section</link>
+ ,
+ before a
+ <literal>Cache</literal>
+ can be created, the
+ <literal>CacheFactory</literal>
+ must be provided with a
+ <literal>Configuration</literal>
+ object or with a file name or
+ input stream to use to parse a
+ <literal>Configuration</literal>
from XML. The following sections describe how to accomplish this.
</para>
@@ -119,15 +135,21 @@
For historical reasons, the format of the JBoss Cache configuraton
file follows that of a JBoss AS Service Archive (SAR) deployment
descriptor (and still can be used as such
- <link linkend="deployment.microkernel">inside JBoss AS</link>). Because
+ <link linkend="deployment.microkernel">inside JBoss AS</link>
+ ). Because
of this dual usage, you may see elements in some configuration files
(such as
- <literal>depends</literal> or <literal>classpath</literal>) that are
+ <literal>depends</literal>
+ or
+ <literal>classpath</literal>
+ ) that are
not relevant outside JBoss AS. These can safely be ignored.
</para>
<para>
- Here's how you tell the <literal>CacheFactory</literal> to create
+ Here's how you tell the
+ <literal>CacheFactory</literal>
+ to create
and start a cache by finding and parsing a configuration file on the
classpath:
</para>
@@ -143,18 +165,24 @@
<title>Programmatic Configuration</title>
<para>
In addition to the XML-based configuration above, the
- <literal>Configuration</literal> can be built up programatically,
+ <literal>Configuration</literal>
+ can be built up programatically,
using the simple property mutators exposed by
- <literal>Configuration</literal> and its components. When constructed,
- the <literal>Configuration</literal> object is preset with JBoss Cache
+ <literal>Configuration</literal>
+ and its components. When constructed,
+ the
+ <literal>Configuration</literal>
+ object is preset with JBoss Cache
defaults and can even be used as-is for a quick start.
</para>
<para>
Following is an example of programatically creating a
- <literal>Configuration</literal> configured to match the one produced
+ <literal>Configuration</literal>
+ configured to match the one produced
by the XML example above, and then using it to create a
- <literal>Cache</literal>:
+ <literal>Cache</literal>
+ :
</para>
<programlisting>
@@ -196,15 +224,21 @@
hence the preferred use of XML-based configuration. However, if your
application requires it, there is no reason not to use XML-based
configuration for most of the attributes, and then access the
- <literal>Configuration</literal> object to programatically change
+ <literal>Configuration</literal>
+ object to programatically change
a few items from the defaults, add an eviction region, etc.
</para>
<para>
Note that configuration values may not be changed programmatically when a cache is running,
- except those annotated as <literal>@Dynamic</literal>. Dynamic properties are also marked as such in the
- <link linkend="configuration_reference">configuration reference</link> table. Attempting to change a non-dynamic
- property will result in a <literal>ConfigurationException</literal>.
+ except those annotated as
+ <literal>@Dynamic</literal>
+ . Dynamic properties are also marked as such in the
+ <link linkend="configuration_reference">configuration reference</link>
+ table. Attempting to change a non-dynamic
+ property will result in a
+ <literal>ConfigurationException</literal>
+ .
</para>
</section>
@@ -212,11 +246,15 @@
<title>Using an IOC Framework</title>
<para>
- The <literal>Configuration</literal> class and its
+ The
+ <literal>Configuration</literal>
+ class and its
<link linkend="configuration.elements">component parts</link>
are all Java Beans that expose all config elements via simple setters
and getters. Therefore, any good IOC framework should be able to
- build up a <literal>Configuration</literal> from an XML file in
+ build up a
+ <literal>Configuration</literal>
+ from an XML file in
the framework's own format. See the
<link linkend="deployment.microcontainer">deployment via the JBoss micrcontainer</link>
section for an example of this.
@@ -225,10 +263,15 @@
</section>
<section id="configuration.elements">
- <title>Composition of a <literal>Configuration</literal> Object</title>
+ <title>Composition of a
+ <literal>Configuration</literal>
+ Object
+ </title>
<para>
- A <literal>Configuration</literal> is composed of a number of
+ A
+ <literal>Configuration</literal>
+ is composed of a number of
subobjects:
<mediaobject>
@@ -240,55 +283,99 @@
<para>
Following is a brief overview of the components of a
- <literal>Configuration</literal>. See the javadoc and the linked
+ <literal>Configuration</literal>
+ . See the javadoc and the linked
chapters in this book for a more complete explanation of the
configurations associated with each component.
<itemizedlist>
- <listitem><literal>Configuration</literal>: top level object
+ <listitem>
+ <literal>Configuration</literal>
+ : top level object
in the hierarchy; exposes the configuration properties listed in the
<link linkend="configuration_reference">configuration reference</link>
section of this book.
</listitem>
- <listitem><literal>BuddyReplicationConfig</literal>: only relevant if
- <link linkend="br">buddy replication</link> is used. General
- buddy replication configuration options. Must include a:</listitem>
+ <listitem>
+ <literal>BuddyReplicationConfig</literal>
+ : only relevant if
+ <link linkend="br">buddy replication</link>
+ is used. General
+ buddy replication configuration options. Must include a:
+ </listitem>
- <listitem><literal>BuddyLocatorConfig</literal>: implementation-specific
- configuration object for the <literal>BuddyLocator</literal> implementation
+ <listitem>
+ <literal>BuddyLocatorConfig</literal>
+ : implementation-specific
+ configuration object for the
+ <literal>BuddyLocator</literal>
+ implementation
being used. What configuration elements are exposed depends on
- the needs of the <literal>BuddyLocator</literal> implementation.</listitem>
+ the needs of the
+ <literal>BuddyLocator</literal>
+ implementation.
+ </listitem>
- <listitem><literal>EvictionConfig</literal>: only relevant if
- <link linkend="eviction_policies">eviction</link> is used. General
- eviction configuration options. Must include at least one:</listitem>
+ <listitem>
+ <literal>EvictionConfig</literal>
+ : only relevant if
+ <link linkend="eviction_policies">eviction</link>
+ is used. General
+ eviction configuration options. Must include at least one:
+ </listitem>
- <listitem><literal>EvictionRegionConfig</literal>: one for each
+ <listitem>
+ <literal>EvictionRegionConfig</literal>
+ : one for each
eviction region; names the region, etc. Must include a:
</listitem>
- <listitem><literal>EvictionPolicyConfig</literal>: implementation-specific
- configuration object for the <literal>EvictionPolicy</literal> implementation
+ <listitem>
+ <literal>EvictionPolicyConfig</literal>
+ : implementation-specific
+ configuration object for the
+ <literal>EvictionPolicy</literal>
+ implementation
being used. What configuration elements are exposed depends on
- the needs of the <literal>EvictionPolicy</literal> implementation.</listitem>
+ the needs of the
+ <literal>EvictionPolicy</literal>
+ implementation.
+ </listitem>
- <listitem><literal>CacheLoaderConfig</literal>: only relevant if a
- <link linkend="cache_loaders">cache loader</link> is used. General
- cache loader configuration options. Must include at least one:</listitem>
+ <listitem>
+ <literal>CacheLoaderConfig</literal>
+ : only relevant if a
+ <link linkend="cache_loaders">cache loader</link>
+ is used. General
+ cache loader configuration options. Must include at least one:
+ </listitem>
- <listitem><literal>IndividualCacheLoaderConfig</literal>: implementation-specific
- configuration object for the <literal>CacheLoader</literal> implementation
+ <listitem>
+ <literal>IndividualCacheLoaderConfig</literal>
+ : implementation-specific
+ configuration object for the
+ <literal>CacheLoader</literal>
+ implementation
being used. What configuration elements are exposed depends on
- the needs of the <literal>CacheLoader</literal> implementation.</listitem>
+ the needs of the
+ <literal>CacheLoader</literal>
+ implementation.
+ </listitem>
- <listitem><literal>RuntimeConfig</literal>: exposes to cache clients
+ <listitem>
+ <literal>RuntimeConfig</literal>
+ : exposes to cache clients
certain information about the cache's runtime environment (e.g. membership
in buddy replication groups if
- <link linkend="br">buddy replication</link> is used.) Also allows
+ <link linkend="br">buddy replication</link>
+ is used.) Also allows
direct injection into the cache of needed external services like a
- JTA <literal>TransactionManager</literal> or a JGroups
- <literal>ChannelFactory</literal>.
+ JTA
+ <literal>TransactionManager</literal>
+ or a JGroups
+ <literal>ChannelFactory</literal>
+ .
</listitem>
</itemizedlist>
</para>
@@ -297,8 +384,11 @@
<section>
<title>Dynamic Reconfiguration</title>
<para>
- Dynamically changing the configuration of <emphasis>some</emphasis> options while the cache is running is supported,
- by programmatically obtaining the <literal>Configuration</literal>
+ Dynamically changing the configuration of
+ <emphasis>some</emphasis>
+ options while the cache is running is supported,
+ by programmatically obtaining the
+ <literal>Configuration</literal>
object from the running cache and changing values. E.g.,
<programlisting>
@@ -332,7 +422,7 @@
E.g., to override the default node versioning used with optimistic locking:
<programlisting>
- MyCustomDataVersion v = new MyCustomDataVersion();
+ DataVersion v = new MyCustomDataVersion();
cache.getInvocationContext().getOptionOverrides().setDataVersion(v);
Node ch = cache.getRoot().addChild(Fqn.fromString("/a/b/c"));
1.10 +448 -267 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.9
retrieving revision 1.10
diff -u -b -r1.9 -r1.10
--- deployment.xml 6 Jun 2007 03:17:07 -0000 1.9
+++ deployment.xml 6 Jun 2007 14:07:40 -0000 1.10
@@ -4,22 +4,31 @@
<title>Standalone Use / Programatic Deployment</title>
<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</link> and
- <link linkend="configuration.creation">Configuration</link> chapters.
+ <literal>CacheFactory</literal>
+ and a
+ <literal>Configuration</literal>
+ instance or an XML file, as discussed
+ 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
+ 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 <literal>javax.servlet.ServletContextListener</literal>.
+ 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>.
+ <link linkend="jmx.registration.programatic">section on Programatic Registration in JMX</link>
+ .
</para>
</section>
@@ -27,24 +36,35 @@
<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
+ <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
+ <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
+ 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
+ <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>
+ <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
+ 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>
+ <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>
@@ -61,15 +81,23 @@
</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
+ 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
+ <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>.
+ for more on the
+ <literal>CacheJmxWrapper</literal>
+ .
</para>
<para>
@@ -92,8 +120,10 @@
<para>The MBeanServerLocator class is a helper to find the (only) JBoss
MBean server inside the current JVM. The
- <literal>javax.management.MBeanServerInvocationHandler</literal> class'
- <literal>newProxyInstance</literal> method creates a
+ <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
@@ -101,9 +131,14 @@
</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.
+ 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>
@@ -113,29 +148,41 @@
<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>.
+ 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>
+ 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
+ (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>.
+ 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
+ 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>
@@ -254,17 +301,26 @@
<footnote>
<para>http://labs.jboss.com/jbossmc/docs</para>
</footnote>
- for details on the above syntax. Basically, each <literal>bean</literal>
+ 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>.
+ <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>.
+ <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>
@@ -274,10 +330,13 @@
<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>
+ 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
+ like a
+ <literal>Cache</literal>
+ is under development by the JBoss AS
team
<footnote>
<para>http://jira.jboss.com/jira/browse/JBAS-4456</para>
@@ -300,37 +359,68 @@
<title>JBoss Cache MBeans</title>
<para>
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 <literal>org.jboss.cache.jmx.CacheJmxWrapper</literal>.
- It is a StandardMBean, so it's MBean interface is <literal>org.jboss.cache.jmx.CacheJmxWrapperMBean</literal>.
+ to the 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>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>
+ 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>
+ cache has already been started.
+ </listitem>
</itemizedlist>
- See the <literal>CacheJmxWrapperMBean</literal> javadoc for more details.
+ 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
+ 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
+ <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.
+ 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>
- If a <literal>CacheJmxWrapper</literal> is registered, JBoss Cache also provides MBeans
+ 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 <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>.
+ 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>
@@ -338,7 +428,9 @@
<title>Registering the CacheJmxWrapper with the MBeanServer</title>
<para>
- The best way to ensure the <literal>CacheJmxWrapper</literal> is registered
+ The best way to ensure the
+ <literal>CacheJmxWrapper</literal>
+ is registered
in JMX depends on how you are deploying your cache:
</para>
@@ -346,8 +438,11 @@
<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.
+ Simplest way to do this is to create your
+ <literal>Cache</literal>
+ and pass it to the
+ <literal>CacheJmxWrapper</literal>
+ constructor.
</para>
<programlisting>
@@ -377,9 +472,15 @@
</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>:
+ 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>
@@ -412,10 +513,17 @@
<para>
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.
+ <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>
@@ -423,11 +531,15 @@
<title>Via JBoss Microcontainer (JBoss AS 5.x)</title>
<para>
- <literal>CacheJmxWrapper</literal> is a POJO, so the microcontainer
+ <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:
+ specifying the
+ <literal>org.jboss.aop.microcontainer.aspects.jmx.JMX</literal>
+ annotation on the
+ <literal>CacheJmxWrapper</literal>
+ bean:
</para>
<programlisting>
@@ -479,12 +591,21 @@
</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,
+ 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>:
+ needed to create the
+ <literal>CacheFactory</literal>
+ :
</para>
<programlisting>
@@ -525,21 +646,37 @@
<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>,
+ 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 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
+ 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>
- If a <literal>CacheJmxWrapper</literal> is registered with JMX, the wrapper also ensures that
+ 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
+ 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
+ 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.
@@ -547,26 +684,50 @@
</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
+ <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
+ <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>.
+ <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.
+ 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>
+ <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>
</para>
<para>
@@ -576,15 +737,24 @@
<section>
<title>Receiving JMX Notifications</title>
<para>
- JBoss Cache users can register a listener to receive cache events described earlier in the <link linkend="api.listener">User API</link>
- 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 <literal>NotificationListener</literal> for the
- <literal>CacheJmxWrapper</literal>.
+ JBoss Cache users can register a listener to receive cache events described earlier in the
+ <link linkend="api.listener">User API</link>
+ 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
+ <literal>NotificationListener</literal>
+ for the
+ <literal>CacheJmxWrapper</literal>
+ .
</para>
<para>
- See the section in the <link linkend="jmx_reference.notifications">JMX Reference chapter</link> pertaining
- to JMX notifications for a list of notifications that can be received through the <literal>CacheJmxWrapper</literal>.
+ See the section in the
+ <link linkend="jmx_reference.notifications">JMX Reference chapter</link>
+ pertaining
+ to JMX notifications for a list of notifications that can be received through the
+ <literal>CacheJmxWrapper</literal>
+ .
</para>
@@ -662,7 +832,8 @@
</programlisting>
<para>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
+ to receive MBean notifications. As soon as no clients are registered for notifications, the MBean will
+ remove
itself as a cache listener.
</para>
@@ -683,26 +854,36 @@
<para>
<orderedlist>
<listitem>
- Set the system property <literal>-Dcom.sun.management.jmxremote</literal> when starting the JVM
+ Set the system property
+ <literal>-Dcom.sun.management.jmxremote</literal>
+ when starting the JVM
where the cache will run.
</listitem>
<listitem>
- Once the JVM is running, start the JDK 5.0 <literal>jconsole</literal> utility, located in your JDK's <literal>/bin</literal>
+ Once the JVM is running, start the JDK 5.0
+ <literal>jconsole</literal>
+ utility, located in your JDK's
+ <literal>/bin</literal>
directory.
</listitem>
- <listitem>When the utility loads, you will be able to select your running JVM and connect to it. The JBoss Cache
+ <listitem>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.
</listitem>
</orderedlist>
</para>
<para>Note that the
- <literal>jconsole</literal> utility will automatically register as a listener for cache notifications when
+ <literal>jconsole</literal>
+ utility will automatically register as a listener for cache notifications when
connected to a JVM running JBoss Cache instances.
</para>
<para>The following figure shows cache interceptor MBeans in
- <literal>jconsole</literal>. Cache statistics are displayed
- for the <literal>CacheMgmtInterceptor</literal>:
+ <literal>jconsole</literal>
+ . Cache statistics are displayed
+ for the
+ <literal>CacheMgmtInterceptor</literal>
+ :
</para>
<figure>
More information about the jboss-cvs-commits
mailing list