
INterceptor MBeans - JBCACHE-56
===============================

Revision: $Id: InterceptorMBeans.txt,v 1.3 2006/01/25 12:53:48 jerrygauth Exp $

Enabling Dynamic Registration
-----------------------------
TreeCacheMBean now has a boolean attribute named "useInterceptorMbeans."  This 
attribute can be added to a cache's configuration to enable or disable 
interceptor mbean registration.  By default it's configured to true so 
interceptors will be registered as enabled if the attribute isn't explicitly 
added to a cache's configuration.

Dynamic Registration
--------------------
JBCACHE-56 (in JBossCache 1.3) provides for dynamic registration of cache 
interceptor mbeans.  The intent of these mbeans is to expose management data 
(e.g., cache hits, misses, evictions) associated with various interceptors.  
The registration process is as follows.

After a cache is started and the interceptor chain is constructed, the 
interceptor mbeans are registered (assuming useInterceptorMbeans=true).  
Registration requires that an interceptor's mbean have the same name as the 
interceptor with a suffix of "MBean."  For example, the ReplicationInterceptor 
class would require an mbean named ReplicationInterceptorMBean.  If the 
interceptor has an associated mbean class, the interceptor is registered as the 
mbean implementation.  If the interceptor has no associated mbean, a new class 
named BaseInterceptor is registered as the implementation class.  This class 
doesn't provide any functionality but it does extend Interceptor so that it has 
empty implementations of the common interceptor mbean operations.  Consequently 
if an interceptor doesn't have an mbean, this class will be used and the 
interceptor will still be represented in the list of registered interceptors.  
Note that this only occurs if registration of interceptor mbeans is enabled 
(useInterceptorMbeans=true).

Core Cache Management Interceptor
--------------------------------- 
The JBossCache interceptor stack contains a new interceptor named 
CacheMgmtInterceptor.  This interceptor executes next to last so that it sees 
cache operations after the other interceptors.  This interceptor will capture 
basic cache statistics not associated with the other interceptors (e.g., cache 
hits, cache misses, store operations, time running).  An mbean named 
CacheMgmtInterceptorMBean has been provided to expose the statistics captured 
by this interceptor.

Base Cache Management Interceptor MBean
---------------------------------------
A class named InterceptorMBean has been provided to define common interceptor 
mbean operations.  The existing Interceptor class has been modified to provide 
empty implementations for the methods and attributes in this class.  Initially 
the following methods/attributes are provided.

- StatisticsEnabled(attribute) - disables statistics for individual interceptor
- resetStatistics() - resets an interceptor's statistics
- dumpStatistics(Map) - returns a map of statistics relevant to an interceptor

Note that each interceptor can have its statistics gathering individually 
enabled via the StatisticsEnabled flag that exposed in the mbean.  Each 
interceptor must provide its own logic to handle this as appropriate since the 
base interceptor simply sets the flag.

Registration Process
--------------------
After a cache is created and the interceptor chain is constructed, the 
interceptor mbeans are registered (assuming useInterceptorMbeans=true).  
Registration assumes that an interceptor's mbean has the same name as the 
interceptor with an "MBean" suffix (e.g., ReplicationInterceptorMBean).  
If the interceptor has an associated mbean class, the interceptor is registered 
as the mbean implementation.  If the interceptor has no associated mbean, a new 
class named BaseInterceptor is registered as the implementation class.  
This class doesn't provide any functionality but it does extend Interceptor so 
it has the empty implementations of the common interceptor mbean operations.  
If an interceptor doesn't have an mbean, this class will be used and the 
interceptor will still be represented in the list of registered interceptors.

If the cache is running in a standalone environment, the primary tree cache 
mbean (TreeCacheMbean) will also be registered if an mbean server is available 
(e.g., Sun's jconsole utility in JDK 1.5).

Registration Name
-----------------
Interceptors will be registered with a name composed of the cache's service 
name and the interceptor's name.  For example, the TomcatClusteringCache 
service will have its replication interceptor registered as 
"service=TomcatClusteringCache, treecache-interceptor=ReplicationInterceptor."  
Note that the JBoss JMX Console currently sequences and displays service names 
in key name order (e.g., "interceptor=" preceeds "service=") so the interceptor 
key has been named "treecache-interceptor" to ensure that interceptors are 
displayed hierarchically in JMX Console.  This isn't an issue when mbeans are 
displayed in jconsole.  

Providing an MBean for an Interceptor
-------------------------------------
To provide an mbean for an interceptor, you minimally need to provide an 
associated mbean class.  You'll need to capture your statistics in the 
interceptor and expose them in the interceptor's mbean.  You should provide 
concrete implementations of resetStatistics(0 and dumpStatistics(), overriding 
the empty implementations provided in Interceptor.  You should also use the 
useInterceptorMbeans and StatisticsEnabled flags for your interceptors to 
ascertain whether you should actually capture statistics (if this makes sense 
for your interceptors).

InvalidationInterceptor and InvalidationInterceptorMBean provide an example 
of how this might be implemented.
