Top Description Fields Constructors Methods
net.sf.ehcache.management

public Class ManagementService

extends Object
implements CacheManagerEventListener
Class Inheritance
All Implemented Interfaces
net.sf.ehcache.event.CacheManagerEventListener
Imports
net.sf.ehcache.CacheException, .Status, net.sf.ehcache.distribution.CacheManagerPeerProvider, net.sf.ehcache.event.CacheManagerEventListener, net.sf.ehcache.hibernate.management.impl.EhcacheHibernateMbeanNames, org.slf4j.Logger, .LoggerFactory, java.util.Iterator, .List, .Map, .Set, javax.management.InstanceAlreadyExistsException, .MBeanRegistrationException, .MBeanServer, .MalformedObjectNameException, .NotCompliantMBeanException, .ObjectName
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.

Author
Greg Luck
Since
1.3
Version
$Id: ManagementService.java 10789 2018-04-26 02:08:13Z adahanne $

Field Summary

Modifier and TypeField and Description
private final CacheManager
backingCacheManager

private static final Logger
LOG

private final MBeanServer
mBeanServer

private final boolean
registerCacheConfigurations

private final boolean
registerCacheManager

private final boolean
registerCaches

private final boolean
registerCacheStatistics

private final boolean
registerCacheStores

private Status
status

Constructor Summary

AccessConstructor and Description
public
ManagementService(CacheManager
the CacheManager to listen to
cacheManager, MBeanServer
the MBeanServer to register MBeans to
mBeanServer, boolean
Whether to register the CacheManager MBean
registerCacheManager, boolean
Whether to register the Cache MBeans
registerCaches, boolean
Whether to register the CacheConfiguration MBeans
registerCacheConfigurations, boolean
Whether to register the CacheStatistics MBeans
registerCacheStatistics, boolean registerCacheStores)

A constructor for a management service for a range of possible MBeans.

public
ManagementService(CacheManager
the CacheManager to listen to
cacheManager, MBeanServer
the MBeanServer to register MBeans to
mBeanServer, boolean
Whether to register the CacheManager MBean
registerCacheManager, boolean
Whether to register the Cache MBeans
registerCaches, boolean
Whether to register the CacheConfiguration MBeans
registerCacheConfigurations, boolean
Whether to register the CacheStatistics MBeans
registerCacheStatistics)

A constructor for a management service for a range of possible MBeans.

Method Summary

Modifier and TypeMethod and Description
public void
dispose()

Implements net.sf.ehcache.event.CacheManagerEventListener.dispose.

Stop the listener and free any resources.
public Status

Returns:

the status at the point in time the method is called
getStatus()

Implements net.sf.ehcache.event.CacheManagerEventListener.getStatus.

Returns the listener status.
public void
init()

Implements net.sf.ehcache.event.CacheManagerEventListener.init.

Call to register the mbeans in the mbean server and start the event listeners and do any other required initialisation.
public void
notifyCacheAdded(String
the name of the Cache the operation relates to
cacheName)

Implements net.sf.ehcache.event.CacheManagerEventListener.notifyCacheAdded.

Called immediately after a cache has been added and activated.
public void
notifyCacheRemoved(String
the name of the Cache the operation relates to
cacheName)

Implements net.sf.ehcache.event.CacheManagerEventListener.notifyCacheRemoved.

Called immediately after a cache has been disposed and removed.
private void
registerCacheConfigurationIfRequired(Cache cache)

private void
registerCacheManager(CacheManager cacheManager)

private void
registerCachesIfRequired(Cache cache)

private void
registerCacheStatisticsIfRequired(Cache cache)

private void
registerCacheStoreIfRequired(Cache cache)

public static void
registerMBeans(CacheManager
the CacheManager to listen to
cacheManager, MBeanServer
the MBeanServer to register MBeans to
mBeanServer, boolean
Whether to register the CacheManager MBean
registerCacheManager, boolean
Whether to register the Cache MBeans
registerCaches, boolean
Whether to register the CacheConfiguration MBeans
registerCacheConfigurations, boolean
Whether to register the CacheStatistics MBeans
registerCacheStatistics, boolean registerCacheStores)

A convenience static method which creates a ManagementService and initialises it with the supplied parameters.

public static void
registerMBeans(CacheManager
the CacheManager to listen to
cacheManager, MBeanServer
the MBeanServer to register MBeans to
mBeanServer, boolean
Whether to register the CacheManager MBean
registerCacheManager, boolean
Whether to register the Cache MBeans
registerCaches, boolean
Whether to register the CacheConfiguration MBeans
registerCacheConfigurations, boolean
Whether to register the CacheStatistics MBeans
registerCacheStatistics)

A convenience static method which creates a ManagementService and initialises it with the supplied parameters.

private void
registerPeerProviders()

private void
unregisterMBean(ObjectName objectName)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

backingCacheManagerback to summary
private final CacheManager backingCacheManager
LOGback to summary
private static final Logger LOG
mBeanServerback to summary
private final MBeanServer mBeanServer
registerCacheConfigurationsback to summary
private final boolean registerCacheConfigurations
registerCacheManagerback to summary
private final boolean registerCacheManager
registerCachesback to summary
private final boolean registerCaches
registerCacheStatisticsback to summary
private final boolean registerCacheStatistics
registerCacheStoresback to summary
private final boolean registerCacheStores
statusback to summary
private Status status

Constructor Detail

ManagementServiceback to summary
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:CacheManager

the CacheManager to listen to

mBeanServer:MBeanServer

the MBeanServer to register MBeans to

registerCacheManager:boolean

Whether to register the CacheManager MBean

registerCaches:boolean

Whether to register the Cache MBeans

registerCacheConfigurations:boolean

Whether to register the CacheConfiguration MBeans

registerCacheStatistics:boolean

Whether to register the CacheStatistics MBeans

Exceptions
CacheException:
if something goes wrong with init()
Since
2.2
ManagementServiceback to summary
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:CacheManager

the CacheManager to listen to

mBeanServer:MBeanServer

the MBeanServer to register MBeans to

registerCacheManager:boolean

Whether to register the CacheManager MBean

registerCaches:boolean

Whether to register the Cache MBeans

registerCacheConfigurations:boolean

Whether to register the CacheConfiguration MBeans

registerCacheStatistics:boolean

Whether to register the CacheStatistics MBeans

Exceptions
CacheException:
if something goes wrong with init()

Method Detail

disposeback to summary
public void dispose() throws CacheException

Implements net.sf.ehcache.event.CacheManagerEventListener.dispose.

Stop the listener and free any resources. Removes registered ObjectNames

Exceptions
CacheException:
- all exceptions are wrapped in CacheException
getStatusback to summary
public Status getStatus()

Implements net.sf.ehcache.event.CacheManagerEventListener.getStatus.

Returns the listener status.

Returns:Status

the status at the point in time the method is called

initback to summary
public void init() throws CacheException

Implements net.sf.ehcache.event.CacheManagerEventListener.init.

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.

Exceptions
CacheException:
- all exceptions are wrapped in CacheException
notifyCacheAddedback to summary
public void notifyCacheAdded(String cacheName)

Implements net.sf.ehcache.event.CacheManagerEventListener.notifyCacheAdded.

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 net.sf.ehcache.Status#STATUS_UNINITIALISED to net.sf.ehcache.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 net.sf.ehcache.CacheManager#getEhcache(String) will cause a deadlock.
The calling method will block until this method returns.

Parameters
cacheName:String

the name of the Cache the operation relates to

See Also
net.sf.ehcache.event.CacheEventListener
notifyCacheRemovedback to summary
public void notifyCacheRemoved(String cacheName)

Implements net.sf.ehcache.event.CacheManagerEventListener.notifyCacheRemoved.

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 net.sf.ehcache.event.CacheEventListener status changed will also be triggered. Any attempt from that notification to access CacheManager will also result in a deadlock.

Parameters
cacheName:String

the name of the Cache the operation relates to

registerCacheConfigurationIfRequiredback to summary
private void registerCacheConfigurationIfRequired(Cache cache) throws InstanceAlreadyExistsException, MBeanRegistrationException, NotCompliantMBeanException
registerCacheManagerback to summary
private void registerCacheManager(CacheManager cacheManager) throws InstanceAlreadyExistsException, MBeanRegistrationException, NotCompliantMBeanException
registerCachesIfRequiredback to summary
private void registerCachesIfRequired(Cache cache) throws InstanceAlreadyExistsException, MBeanRegistrationException, NotCompliantMBeanException
registerCacheStatisticsIfRequiredback to summary
private void registerCacheStatisticsIfRequired(Cache cache) throws InstanceAlreadyExistsException, MBeanRegistrationException, NotCompliantMBeanException
registerCacheStoreIfRequiredback to summary
private void registerCacheStoreIfRequired(Cache cache) throws InstanceAlreadyExistsException, MBeanRegistrationException, NotCompliantMBeanException
registerMBeansback to summary
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:CacheManager

the CacheManager to listen to

mBeanServer:MBeanServer

the MBeanServer to register MBeans to

registerCacheManager:boolean

Whether to register the CacheManager MBean

registerCaches:boolean

Whether to register the Cache MBeans

registerCacheConfigurations:boolean

Whether to register the CacheConfiguration MBeans

registerCacheStatistics:boolean

Whether to register the CacheStatistics MBeans

Since
2.2
See Also
ManagementService#ManagementService(net.sf.ehcache.CacheManager, javax.management.MBeanServer, boolean, boolean, boolean, boolean, boolean)
registerMBeansback to summary
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:CacheManager

the CacheManager to listen to

mBeanServer:MBeanServer

the MBeanServer to register MBeans to

registerCacheManager:boolean

Whether to register the CacheManager MBean

registerCaches:boolean

Whether to register the Cache MBeans

registerCacheConfigurations:boolean

Whether to register the CacheConfiguration MBeans

registerCacheStatistics:boolean

Whether to register the CacheStatistics MBeans

See Also
ManagementService#ManagementService(net.sf.ehcache.CacheManager, javax.management.MBeanServer, boolean, boolean, boolean, boolean)
registerPeerProvidersback to summary
private void registerPeerProviders()
unregisterMBeanback to summary
private void unregisterMBean(ObjectName objectName)