ehcache

net.sf.ehcache.management
Class ManagementService

java.lang.Object
  extended by net.sf.ehcache.management.ManagementService
All Implemented Interfaces:
CacheManagerEventListener

public class ManagementService
extends Object
implements CacheManagerEventListener

Ehcache CacheManagers and Caches have lifecycles. Often normal use of a CacheManager will be to shut it down and create a new one from within a running JVM. For example, in Java EE environments, applications are often undeployed and then redeployed. A servlet listener avdailable in the web module, net.sf.ehcache.constructs.web.ShutdownListener} enables this to be detected and the CacheManager shutdown.

When a CacheManager is shut down we need to ensure there is no memory, resource or thread leakage. An MBeanServer, particularly a platform MBeanServer, can be expected to exist for the lifespan of the JVM. Accordingly, we need to deregister them when needed without creating a leakage.

The second purpose of this class (and this package) is to keep management concerns away from the core ehcache packages. That way, JMX is not a required dependency, but rather an optional one.

This class is constructable as of 1.5 to support injection via IoC containers.

Since:
1.3
Version:
$Id: ManagementService.java 8506 2013-12-04 09:46:53Z ljacomet $
Author:
Greg Luck

Constructor Summary
ManagementService(CacheManager cacheManager, MBeanServer mBeanServer, boolean registerCacheManager, boolean registerCaches, boolean registerCacheConfigurations, boolean registerCacheStatistics)
          A constructor for a management service for a range of possible MBeans.
ManagementService(CacheManager cacheManager, MBeanServer mBeanServer, boolean registerCacheManager, boolean registerCaches, boolean registerCacheConfigurations, boolean registerCacheStatistics, boolean registerCacheStores)
          A constructor for a management service for a range of possible MBeans.
 
Method Summary
 void dispose()
          Stop the listener and free any resources.
 Status getStatus()
          Returns the listener status.
 void init()
          Call to register the mbeans in the mbean server and start the event listeners and do any other required initialisation.
 void notifyCacheAdded(String cacheName)
          Called immediately after a cache has been added and activated.
 void notifyCacheRemoved(String cacheName)
          Called immediately after a cache has been disposed and removed.
static void registerMBeans(CacheManager cacheManager, MBeanServer mBeanServer, boolean registerCacheManager, boolean registerCaches, boolean registerCacheConfigurations, boolean registerCacheStatistics)
          A convenience static method which creates a ManagementService and initialises it with the supplied parameters.
static void registerMBeans(CacheManager cacheManager, MBeanServer mBeanServer, boolean registerCacheManager, boolean registerCaches, boolean registerCacheConfigurations, boolean registerCacheStatistics, boolean registerCacheStores)
          A convenience static method which creates a ManagementService and initialises it with the supplied parameters.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ManagementService

public ManagementService(CacheManager cacheManager,
                         MBeanServer mBeanServer,
                         boolean registerCacheManager,
                         boolean registerCaches,
                         boolean registerCacheConfigurations,
                         boolean registerCacheStatistics,
                         boolean registerCacheStores)
                  throws CacheException
A constructor for a management service for a range of possible MBeans.

The init() method needs to be called after construction which causes the selected monitoring options to be be registered with the provided MBeanServer for caches in the given CacheManager.

While registering the CacheManager enables traversal to all of the other items, this requires programmatic traversal. The other options allow entry points closer to an item of interest and are more accessible from JMX management tools like JConsole. Moreover CacheManager and Cache are not serializable, so remote monitoring is not possible for CacheManager or Cache, while CacheStatistics and CacheConfiguration are. Finally CacheManager and Cache enable management operations to be performed.

Once monitoring is enabled caches will automatically added and removed from the MBeanServer as they are added and disposed of from the CacheManager. When the CacheManager itself shutsdown all registered MBeans will be unregistered.

Parameters:
cacheManager - the CacheManager to listen to
mBeanServer - the MBeanServer to register MBeans to
registerCacheManager - Whether to register the CacheManager MBean
registerCaches - Whether to register the Cache MBeans
registerCacheConfigurations - Whether to register the CacheConfiguration MBeans
registerCacheStatistics - Whether to register the CacheStatistics MBeans
Throws:
CacheException - if something goes wrong with init()
Since:
2.2

ManagementService

public ManagementService(CacheManager cacheManager,
                         MBeanServer mBeanServer,
                         boolean registerCacheManager,
                         boolean registerCaches,
                         boolean registerCacheConfigurations,
                         boolean registerCacheStatistics)
                  throws CacheException
A constructor for a management service for a range of possible MBeans.

The init() method needs to be called after construction which causes the selected monitoring options to be be registered with the provided MBeanServer for caches in the given CacheManager.

While registering the CacheManager enables traversal to all of the other items, this requires programmatic traversal. The other options allow entry points closer to an item of interest and are more accessible from JMX management tools like JConsole. Moreover CacheManager and Cache are not serializable, so remote monitoring is not possible for CacheManager or Cache, while CacheStatistics and CacheConfiguration are. Finally CacheManager and Cache enable management operations to be performed.

Once monitoring is enabled caches will automatically added and removed from the MBeanServer as they are added and disposed of from the CacheManager. When the CacheManager itself shutsdown all registered MBeans will be unregistered.

Parameters:
cacheManager - the CacheManager to listen to
mBeanServer - the MBeanServer to register MBeans to
registerCacheManager - Whether to register the CacheManager MBean
registerCaches - Whether to register the Cache MBeans
registerCacheConfigurations - Whether to register the CacheConfiguration MBeans
registerCacheStatistics - Whether to register the CacheStatistics MBeans
Throws:
CacheException - if something goes wrong with init()
Method Detail

registerMBeans

public static void registerMBeans(CacheManager cacheManager,
                                  MBeanServer mBeanServer,
                                  boolean registerCacheManager,
                                  boolean registerCaches,
                                  boolean registerCacheConfigurations,
                                  boolean registerCacheStatistics,
                                  boolean registerCacheStores)
                           throws CacheException
A convenience static method which creates a ManagementService and initialises it with the supplied parameters.

Parameters:
cacheManager - the CacheManager to listen to
mBeanServer - the MBeanServer to register MBeans to
registerCacheManager - Whether to register the CacheManager MBean
registerCaches - Whether to register the Cache MBeans
registerCacheConfigurations - Whether to register the CacheConfiguration MBeans
registerCacheStatistics - Whether to register the CacheStatistics MBeans
Throws:
CacheException
Since:
2.2
See Also:
ManagementService(net.sf.ehcache.CacheManager, javax.management.MBeanServer, boolean, boolean, boolean, boolean, boolean)

registerMBeans

public static void registerMBeans(CacheManager cacheManager,
                                  MBeanServer mBeanServer,
                                  boolean registerCacheManager,
                                  boolean registerCaches,
                                  boolean registerCacheConfigurations,
                                  boolean registerCacheStatistics)
                           throws CacheException
A convenience static method which creates a ManagementService and initialises it with the supplied parameters.

This one is provided for backward compatibility

Parameters:
cacheManager - the CacheManager to listen to
mBeanServer - the MBeanServer to register MBeans to
registerCacheManager - Whether to register the CacheManager MBean
registerCaches - Whether to register the Cache MBeans
registerCacheConfigurations - Whether to register the CacheConfiguration MBeans
registerCacheStatistics - Whether to register the CacheStatistics MBeans
Throws:
CacheException
See Also:
ManagementService(net.sf.ehcache.CacheManager, javax.management.MBeanServer, boolean, boolean, boolean, boolean)

init

public void init()
          throws CacheException
Call to register the mbeans in the mbean server and start the event listeners and do any other required initialisation. Once intialised, it registers itself as a CacheManageEvenListener with the backing CacheManager, so that it can participate in lifecycle and other events.

Specified by:
init in interface CacheManagerEventListener
Throws:
CacheException - - all exceptions are wrapped in CacheException

getStatus

public Status getStatus()
Returns the listener status.

Specified by:
getStatus in interface CacheManagerEventListener
Returns:
the status at the point in time the method is called

dispose

public void dispose()
             throws CacheException
Stop the listener and free any resources. Removes registered ObjectNames

Specified by:
dispose in interface CacheManagerEventListener
Throws:
CacheException - - all exceptions are wrapped in CacheException

notifyCacheAdded

public void notifyCacheAdded(String cacheName)
Called immediately after a cache has been added and activated.

Note that the CacheManager calls this method from a synchronized method. Any attempt to call a synchronized method on CacheManager from this method will cause a deadlock.

Note that activation will also cause a CacheEventListener status change notification from Status.STATUS_UNINITIALISED to Status.STATUS_ALIVE. Care should be taken on processing that notification because:

The calling method will block until this method returns.

Specified by:
notifyCacheAdded in interface CacheManagerEventListener
Parameters:
cacheName - the name of the Cache the operation relates to
See Also:
CacheEventListener

notifyCacheRemoved

public void notifyCacheRemoved(String cacheName)
Called immediately after a cache has been disposed and removed. The calling method will block until this method returns.

Note that the CacheManager calls this method from a synchronized method. Any attempt to call a synchronized method on CacheManager from this method will cause a deadlock.

Note that a CacheEventListener status changed will also be triggered. Any attempt from that notification to access CacheManager will also result in a deadlock.

Specified by:
notifyCacheRemoved in interface CacheManagerEventListener
Parameters:
cacheName - the name of the Cache the operation relates to

ehcache

Copyright 2001-2014, Terracotta, Inc.