wt.jmx.core
Class SelfAwareMBean

java.lang.Object
  wt.jmx.core.StandardMBeanFix
      wt.jmx.core.StandardMBean
          wt.jmx.core.SelfAwareMBean

All Implemented Interfaces:

DynamicMBean, MBeanRegistration, BaseObjectNamed

Direct Known Subclasses:

wt.jmx.core.mbeans.AbstractFileView, Dumper, Emailer, Info, MBeanLoader

public abstract class SelfAwareMBean
extends StandardMBean
implements MBeanRegistration, BaseObjectNamed

StandardMBean subclass that knows its own ObjectName -- and thus assumes it is only registered once. Instances of this class can optionally be told of another MBean that plays an "owner" role and derive their ObjectName from this other MBean's ObjectName. This class also provides init(), start(), stop(), and destroy() lifecycle methods for purposes of [de]registering dependent MBeans, starting/stopping background tasks, etc.

Supported API: true

Extendable: true

Constructor Summary

protected	SelfAwareMBean(Class mbeanInterface) Pass through constructor Supported API: true
	SelfAwareMBean(Object implementation, Class mbeanInterface) Pass through constructor Supported API: true

Method Summary

void	deregister() Deregister the given MBean.
void	destroy() Lifecycle method which deregisters (and thus stops) the MBean, delegates to onDestroy(), and finally marks this MBean as not inited (ala isInited()).
ObjectName	getBaseObjectName() Required method for BaseObjectNamed interface.
ObjectName	getObjectName() Returns the ObjectName of this MBean Supported API: true
protected ObjectName	getObjectNameOnPreRegister() Called from within preRegister() if ObjectName passed in is null and this object does not yet have its own object name.
abstract String[][]	getObjectNameSuffix() Provide a set of name/value pairs for use as a suffix in creating a new ObjectName for an MBean instance based on an existing ObjectName used as a context / namespace prefix.
BaseObjectNamed	getOwnerMBean() Returns the MBean that acts as a parent or owner to this MBean Supported API: true
static SelfAwareMBean	getSelfAwareMBean(ObjectName objectName) Get SelfAwareMBean with the given 'objectName' if such an MBean is currently registered.
void	init() Lifecycle method which marks this MBean as inited (ala isInited()) and then delegates to onInit().
boolean	isInited() Returns whether this MBean is currently inited, i.e.
boolean	isRegistered() Returns whether this MBean is currently registered with an MBeanServer Supported API: true
boolean	isStarted() Returns whether this MBean is currently started, i.e.
protected void	onDestroy() Intended for override by sub-classes that need to do cleanup during destroy(), which calls it.
protected void	onInit() Intended for override by sub-classes that need to do initialization during init(), which calls it.
protected void	onStart() Intended for override by sub-classes that need to do initialization during start(), which calls it.
protected void	onStop() Intended for override by sub-classes that need to do cleanup during stop(), which calls it.
void	postDeregister() Required method for MBeanRegistration interface.
void	postRegister(Boolean registrationDone) Required method for MBeanRegistration interface.
void	preDeregister() Required method for MBeanRegistration interface.
ObjectName	preRegister(MBeanServer server, ObjectName name) Required method for MBeanRegistration interface.
ObjectName	register() Register MBean with MBeanServer.
ObjectName	register(BaseObjectNamed parentMBean) The BaseObjectNamed argument is used to set the OwnerMBean attribute, clears the MBean's ObjectName, and then registers this MBean if and only if 'parentMBean' is either not a SelfAwareMBean or is currently registered.
ObjectName	register(ObjectName baseObjectName) Register MBean with MBeanServer.
void	resetObjectName() If not registered, but had been registered, this will reset the ObjectName within this instance thus allowing it to be re-registered under another name.
void	setOwnerMBean(BaseObjectNamed ownerMBean) Sets the MBean that acts as a parent or owner to this MBean Supported API: true
void	start() Lifecycle method which calls init() if the MBean is not yet inited, marks the MBean as started, and then delegates to onStart().
void	stop() Lifecycle method which delegates to onStop() and then marks the MBean as not started.

Methods inherited from class wt.jmx.core.StandardMBean

cacheMBeanInfo, cacheMBeanInfoInInstance, createMBeanInfo, emailThisMBean, getCachedInstanceMBeanInfo, getCachedMBeanInfo, getDescription, getDescription, getDescription, getDescription, getImpact, getMBeanInfo, getParameterName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SelfAwareMBean

public SelfAwareMBean(Object implementation,
                      Class mbeanInterface)
               throws NotCompliantMBeanException

Pass through constructor

Supported API: true

Throws:

NotCompliantMBeanException

SelfAwareMBean

protected SelfAwareMBean(Class mbeanInterface)
                  throws NotCompliantMBeanException

Pass through constructor

Supported API: true

Throws:

NotCompliantMBeanException

Method Detail

isRegistered

public final boolean isRegistered()

Returns whether this MBean is currently registered with an MBeanServer

Supported API: true

isInited

public final boolean isInited()

Returns whether this MBean is currently inited, i.e. init() has been called but destroy() has not

Supported API: true

isStarted

public final boolean isStarted()

Returns whether this MBean is currently started, i.e. start() has been called more recently than stop()

Supported API: true

getObjectName

public final ObjectName getObjectName()

Returns the ObjectName of this MBean

Supported API: true

getBaseObjectName

public ObjectName getBaseObjectName()

Required method for BaseObjectNamed interface. Returns the ObjectName of this MBean in this class, but allows subclasses to direct children to a separate ObjectName base than themselves by overriding this method.

Supported API: true

Specified by:

getBaseObjectName in interface BaseObjectNamed

getOwnerMBean

public BaseObjectNamed getOwnerMBean()

Returns the MBean that acts as a parent or owner to this MBean

Supported API: true

setOwnerMBean

public void setOwnerMBean(BaseObjectNamed ownerMBean)

Sets the MBean that acts as a parent or owner to this MBean

Supported API: true

deregister

public void deregister()

Deregister the given MBean.

Note: Such MBeans are not necessarily cognizant of MBeans that aggregate them, so calls to deregister() other than by such aggregating MBeans themselves or on non-aggregated MBeans should be avoided. Aggregated MBeans really seem to be a use case for the JMX relationship service -- except that the relationship service is extraordinarily complex and unwieldy.

Supported API: true

register

public ObjectName register()

Register MBean with MBeanServer.

ObjectName used is determined by preRegister().

Supported API: true

register

public ObjectName register(ObjectName baseObjectName)

Register MBean with MBeanServer.

If 'baseObjectName' is non-null, it is used to produce an appropriate ObjectName for this MBean from this and the result of getObjectNameSuffix(), otherwise the object name is produced by preRegister() as in register().

Supported API: true

register

public ObjectName register(BaseObjectNamed parentMBean)

The BaseObjectNamed argument is used to set the OwnerMBean attribute, clears the MBean's ObjectName, and then registers this MBean if and only if 'parentMBean' is either not a SelfAwareMBean or is currently registered. The ObjectName of the MBean will be derived by preRegister().

If 'parentMBean' is a SelfAwareMBean then it is assumed its registration status will not change during the duration of this call. Callers should synchronize against 'parentMBean' if necessary to enforce this assumption. [Such synchronization is not done within this routine so as not to produce issues of lock ordering, e.g. deadlocks.]

Supported API: true

resetObjectName

public void resetObjectName()

If not registered, but had been registered, this will reset the ObjectName within this instance thus allowing it to be re-registered under another name.

Supported API: true

init

public final void init()

Lifecycle method which marks this MBean as inited (ala isInited()) and then delegates to onInit(). This method will automatically be called prior to onStart() by the first start() invocation if it has not been called by that point. It may, however, be invoked at any point prior to this as well.

This method generally embodies one-time post-construction initialization to be cleaned up in destroy(), though one can reintialize a destroy()'ed MBean.

This method is a no-op if the MBean is already inited.

Supported API: true

destroy

public final void destroy()

Lifecycle method which deregisters (and thus stops) the MBean, delegates to onDestroy(), and finally marks this MBean as not inited (ala isInited()).

This method generally embodies the inverse of init().

This method is a no-op if the MBean is not inited.

Supported API: true

start

public final void start()

Lifecycle method which calls init() if the MBean is not yet inited, marks the MBean as started, and then delegates to onStart(). This method will automatically be called during MBean registration unless isAutoStart() returns false. An IllegalStateException will be thrown if this method is called when the MBean is not registered.

start() and stop() may be called while an MBean is registered without registering and deregistering the MBean, but such usage is atypical. Rather this method generally embodies an "on registration" notion.

This method is a no-op if the MBean is already started.

Supported API: true

stop

public final void stop()

Lifecycle method which delegates to onStop() and then marks the MBean as not started. This method will automatically be called during MBean deregistration.

stop() may be called while an MBean is registered without deregistering the MBean, but such usage is atypical. Rather this method generally embodies an "on deregistration" notion.

This method is a no-op if the MBean is not started.

Supported API: true

onInit

protected void onInit()

Intended for override by sub-classes that need to do initialization during init(), which calls it.

Generally this is used for any initialization that must be done after construction, but not done and undone by start() and stop(). onInit() and onDestroy() should generally be near inverse operations of one another.

Overrides of this method should call super.onInit() and do so before their own intialization code in order to obtain proper execution of super-classes' onInit()'s as well.

Supported API: true

onDestroy

protected void onDestroy()

Intended for override by sub-classes that need to do cleanup during destroy(), which calls it.

Generally this is used for any cleanup that is necessary after stop() that will not be handled in an efficient and timely manner by garbage collection. onInit() and onDestroy() should generally be near inverse operations of one another.

Overrides of this method should call super.onDestroy() and do so after their own cleanup code in order to obtain proper execution of super-classes' onDestroy()'s as well.

Supported API: true

onStart

protected void onStart()

Intended for override by sub-classes that need to do initialization during start(), which calls it.

Generally this is used for any initialization should be delayed until the MBean is registered and that should be undone as part of unregistering the MBean. onStart() and onStop() should generally be near inverse operations of one another.

Overrides of this method should call super.onStart() and do so before their own intialization code in order to obtain proper execution of super-classes' onStart()'s as well.

Supported API: true

onStop

protected void onStop()

Intended for override by sub-classes that need to do cleanup during stop(), which calls it.

Generally this is used for any cleanup that should be done prior to or coincident with unregistering the MBean. onStart() and onStop() should generally be nearly inverse operations of one another.

Overrides of this method should call super.onStop() and do so after their own cleanup code in order to obtain proper execution of super-classes' onStop()'s as well.

Supported API: true

getObjectNameSuffix

public abstract String[][] getObjectNameSuffix()

Provide a set of name/value pairs for use as a suffix in creating a new ObjectName for an MBean instance based on an existing ObjectName used as a context / namespace prefix.

Supported API: true

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception

Required method for MBeanRegistration interface. If caller provided ObjectName is null will use the existing ObjectName of this MBean if it is already known (e.g. from a previous registration) if it is non-null. If this too is null, will use the ObjectName provided by getObjectNameOnPreRegister().

Supported API: true

Specified by:

preRegister in interface MBeanRegistration

Throws:

Exception

getObjectNameOnPreRegister

protected ObjectName getObjectNameOnPreRegister()
                                         throws Exception

Called from within preRegister() if ObjectName passed in is null and this object does not yet have its own object name.

This implementation computes an ObjectName by using the owner MBean's base object name as a prefix and getObjectNameSuffix() as a suffix when this bean has an owner MBean and the owner has a non-null base object name. Otherwise it uses MBeanRegistry.DOMAIN_NAME and getObjectNameSuffix().

Supported API: true

Throws:

Exception

postRegister

public void postRegister(Boolean registrationDone)

Required method for MBeanRegistration interface. Calls start() if MBean is not already started. Registers MBean for access via getSelfAwareMBean().

Supported API: true

Specified by:

postRegister in interface MBeanRegistration

preDeregister

public void preDeregister()
                   throws Exception

Required method for MBeanRegistration interface. De-registers MBean for access via getSelfAwareMBean().

Supported API: true

Specified by:

preDeregister in interface MBeanRegistration

Throws:

Exception

postDeregister

public void postDeregister()

Required method for MBeanRegistration interface. Calls stop() if MBean is started.

Supported API: true

Specified by:

postDeregister in interface MBeanRegistration

getSelfAwareMBean

public static SelfAwareMBean getSelfAwareMBean(ObjectName objectName)

Get SelfAwareMBean with the given 'objectName' if such an MBean is currently registered.

Supported API: true