Package net.sf.ehcache.management

Class ManagementService

java.lang.Object

net.sf.ehcache.management.ManagementService

All Implemented Interfaces:

CacheManagerEventListener

public class ManagementService
extends java.lang.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$

Author:

Greg Luck

Constructor Summary

Constructors

Constructor	Description
ManagementService(CacheManager cacheManager, javax.management.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, javax.management.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

Modifier and Type	Method	Description
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(java.lang.String cacheName)	Called immediately after a cache has been added and activated.
void	notifyCacheRemoved(java.lang.String cacheName)	Called immediately after a cache has been disposed and removed.
static void	registerMBeans(CacheManager cacheManager, javax.management.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, javax.management.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,
                         javax.management.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,
                         javax.management.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,
                                  javax.management.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,
                                  javax.management.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(java.lang.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 cache will not yet be accessible from the CacheManager.
• the addCaches methods which cause this notification are synchronized on the CacheManager. An attempt to call CacheManager.getEhcache(String) will cause a deadlock.

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(java.lang.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