javax.management
class StandardMBean

java.lang.Object javax.management.StandardMBean

All Implemented Interfaces:

DynamicMBean, MBeanRegistration

Direct Known Subclasses:

StandardEmitterMBean

public class StandardMBean
extends Object
implements DynamicMBean, MBeanRegistration

An MBean whose management interface is determined by reflection on a Java interface.

This class brings more flexibility to the notion of Management Interface in the use of Standard MBeans. Straightforward use of the patterns for Standard MBeans described in the JMX Specification means that there is a fixed relationship between the implementation class of an MBean and its management interface (i.e., if the implementation class is Thing, the management interface must be ThingMBean). This class makes it possible to keep the convenience of specifying the management interface with a Java interface, without requiring that there be any naming relationship between the implementation and interface classes.

By making a DynamicMBean out of an MBean, this class makes it possible to select any interface implemented by the MBean as its management interface, provided that it complies with JMX patterns (i.e., attributes defined by getter/setter etc...).

This class also provides hooks that make it possible to supply custom descriptions and names for the {@link MBeanInfo} returned by the DynamicMBean interface.

Using this class, an MBean can be created with any implementation class name Impl and with a management interface defined (as for current Standard MBeans) by any interface Intf, in one of two general ways:

• Using the public constructor {@link #StandardMBean(java.lang.Object, java.lang.Class, boolean) StandardMBean(impl,interface)}:

       MBeanServer mbs;
       ...
       Impl impl = new Impl(...);
       StandardMBean mbean = new StandardMBean(impl, Intf.class, false);
       mbs.registerMBean(mbean, objectName);
       

• Subclassing StandardMBean:

       public class Impl extends StandardMBean implements Intf {
          public Impl() {
            super(Intf.class, false);
         }
         // implement methods of Intf
       }
  
       [...]
  
       MBeanServer mbs;
       ....
       Impl impl = new Impl();
       mbs.registerMBean(impl, objectName);
       

In either case, the class Impl must implement the interface Intf.

Standard MBeans based on the naming relationship between implementation and interface classes are of course still available.

This class may also be used to construct MXBeans. The usage is exactly the same as for Standard MBeans except that in the examples above, the {@code false} parameter to the constructor or {@code super(...)} invocation is instead {@code true}.

StandardMBean

protected StandardMBean(Class mbeanInterface)
                 throws NotCompliantMBeanException

Make a DynamicMBean out of this, using the specified mbeanInterface class.

Call {@link #StandardMBean(java.lang.Object, java.lang.Class) this(this,mbeanInterface)}. This constructor is reserved to subclasses.

Parameters:

mbeanInterface - The Management Interface exported by this MBean.

Throws:

NotCompliantMBeanException - if the mbeanInterface does not follow JMX design patterns for Management Interfaces, or if this does not implement the specified interface.

StandardMBean

protected StandardMBean(Class mbeanInterface,
                        boolean isMXBean)

Make a DynamicMBean out of this, using the specified mbeanInterface class. This constructor can be used to make either Standard MBeans or MXBeans. Unlike the constructor {@link #StandardMBean(Object, Class)}, it does not throw NotCompliantMBeanException.

Call {@link #StandardMBean(java.lang.Object, java.lang.Class, boolean) this(this, mbeanInterface, isMXBean)}. This constructor is reserved to subclasses.

Parameters:

mbeanInterface - The Management Interface exported by this MBean.

isMXBean - If true, the {@code mbeanInterface} parameter names an MXBean interface and the resultant MBean is an MXBean.

StandardMBean

public StandardMBean(Object implementation,
                     Class mbeanInterface)
              throws NotCompliantMBeanException

Make a DynamicMBean out of the object implementation, using the specified mbeanInterface class.

Parameters:

implementation - The implementation of this MBean.

mbeanInterface - The Management Interface exported by this MBean's implementation. If null, then this object will use standard JMX design pattern to determine the management interface associated with the given implementation.

Throws:

NotCompliantMBeanException - if the mbeanInterface does not follow JMX design patterns for Management Interfaces, or if the given implementation does not implement the specified interface.

StandardMBean

public StandardMBean(Object implementation,
                     Class mbeanInterface,
                     boolean isMXBean)

Make a DynamicMBean out of the object implementation, using the specified mbeanInterface class. This constructor can be used to make either Standard MBeans or MXBeans. Unlike the constructor {@link #StandardMBean(Object, Class)}, it does not throw NotCompliantMBeanException.

Parameters:

implementation - The implementation of this MBean.

mbeanInterface - The Management Interface exported by this MBean's implementation. If null, then this object will use standard JMX design pattern to determine the management interface associated with the given implementation.

isMXBean - If true, the {@code mbeanInterface} parameter names an MXBean interface and the resultant MBean is an MXBean.

cacheMBeanInfo

protected void cacheMBeanInfo(MBeanInfo info)

Customization hook: cache the MBeanInfo built for this object.

Subclasses may redefine this method in order to implement their own caching policy. The default implementation stores info in this instance. A subclass can define other policies, such as not saving info (so it is reconstructed every time {@link #getMBeanInfo()} is called) or sharing a unique {@link MBeanInfo} object when several StandardMBean instances have equal {@link MBeanInfo} values.

Parameters:

info - the new MBeanInfo to cache. Any previously cached value is discarded. This parameter may be null, in which case there is no new cached value.

getAttribute

public Object getAttribute(String attribute)
                    throws AttributeNotFoundException,
                           MBeanException,
                           ReflectionException

Parameters:

attribute

Throws:

AttributeNotFoundException

MBeanException

ReflectionException

getAttributes

public AttributeList getAttributes(String[] attributes)

Parameters:

attributes

getCachedMBeanInfo

protected MBeanInfo getCachedMBeanInfo()

Customization hook: Return the MBeanInfo cached for this object.

Subclasses may redefine this method in order to implement their own caching policy. The default implementation stores one {@link MBeanInfo} object per instance.

Returns:

The cached MBeanInfo, or null if no MBeanInfo is cached.

getClassName

protected String getClassName(MBeanInfo info)

Customization hook: Get the className that will be used in the MBeanInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom class name. The default implementation returns {@link MBeanInfo#getClassName() info.getClassName()}.

Parameters:

info - The default MBeanInfo derived by reflection.

Returns:

the class name for the new MBeanInfo.

getConstructors

protected MBeanConstructorInfo[] getConstructors(MBeanConstructorInfo[] ctors,
                                                 Object impl)

Customization hook: Get the MBeanConstructorInfo[] that will be used in the MBeanInfo returned by this MBean.
By default, this method returns null if the wrapped implementation is not this. Indeed, if the wrapped implementation is not this object itself, it will not be possible to recreate a wrapped implementation by calling the implementation constructors through MBeanServer.createMBean(...).
Otherwise, if the wrapped implementation is this, ctors is returned.
Subclasses may redefine this method in order to modify this behavior, if needed.

Parameters:

ctors - The default MBeanConstructorInfo[] derived by reflection.

impl - The wrapped implementation. If null is passed, the wrapped implementation is ignored and ctors is returned.

Returns:

the MBeanConstructorInfo[] for the new MBeanInfo.

getDescription

protected String getDescription(MBeanAttributeInfo info)

Customization hook: Get the description that will be used in the MBeanAttributeInfo returned by this MBean.

Subclasses may redefine this method in order to supply their custom description. The default implementation returns {@link #getDescription(MBeanFeatureInfo) getDescription((MBeanFeatureInfo) info)}.

Parameters:

info - The default MBeanAttributeInfo derived by reflection.

Returns:

the description for the given MBeanAttributeInfo.

getDescription

protected String getDescription(MBeanConstructorInfo info)

Customization hook: Get the description that will be used in the MBeanConstructorInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom description. The default implementation returns {@link #getDescription(MBeanFeatureInfo) getDescription((MBeanFeatureInfo) info)}.

Parameters:

info - The default MBeanConstructorInfo derived by reflection.

Returns:

the description for the given MBeanConstructorInfo.

getDescription

protected String getDescription(MBeanConstructorInfo ctor,
                                MBeanParameterInfo param,
                                int sequence)

Customization hook: Get the description that will be used for the sequence MBeanParameterInfo of the MBeanConstructorInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom description. The default implementation returns {@link MBeanParameterInfo#getDescription() param.getDescription()}.

Parameters:

ctor - The default MBeanConstructorInfo derived by reflection.

param - The default MBeanParameterInfo derived by reflection.

sequence - The sequence number of the parameter considered ("0" for the first parameter, "1" for the second parameter, etc...).

Returns:

the description for the given MBeanParameterInfo.

getDescription

protected String getDescription(MBeanFeatureInfo info)

Customization hook: Get the description that will be used in the MBeanFeatureInfo returned by this MBean.

Subclasses may redefine this method in order to supply their custom description. The default implementation returns {@link MBeanFeatureInfo#getDescription() info.getDescription()}.

This method is called by {@link #getDescription(MBeanAttributeInfo)}, {@link #getDescription(MBeanOperationInfo)}, {@link #getDescription(MBeanConstructorInfo)}.

Parameters:

info - The default MBeanFeatureInfo derived by reflection.

Returns:

the description for the given MBeanFeatureInfo.

getDescription

protected String getDescription(MBeanInfo info)

Customization hook: Get the description that will be used in the MBeanInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom MBean description. The default implementation returns {@link MBeanInfo#getDescription() info.getDescription()}.

Parameters:

info - The default MBeanInfo derived by reflection.

Returns:

the description for the new MBeanInfo.

getDescription

protected String getDescription(MBeanOperationInfo info)

Customization hook: Get the description that will be used in the MBeanOperationInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom description. The default implementation returns {@link #getDescription(MBeanFeatureInfo) getDescription((MBeanFeatureInfo) info)}.

Parameters:

info - The default MBeanOperationInfo derived by reflection.

Returns:

the description for the given MBeanOperationInfo.

getDescription

protected String getDescription(MBeanOperationInfo op,
                                MBeanParameterInfo param,
                                int sequence)

Customization hook: Get the description that will be used for the sequence MBeanParameterInfo of the MBeanOperationInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom description. The default implementation returns {@link MBeanParameterInfo#getDescription() param.getDescription()}.

Parameters:

op - The default MBeanOperationInfo derived by reflection.

param - The default MBeanParameterInfo derived by reflection.

sequence - The sequence number of the parameter considered ("0" for the first parameter, "1" for the second parameter, etc...).

Returns:

the description for the given MBeanParameterInfo.

getImpact

protected int getImpact(MBeanOperationInfo info)

Customization hook: Get the impact flag of the operation that will be used in the MBeanOperationInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom impact flag. The default implementation returns {@link MBeanOperationInfo#getImpact() info.getImpact()}.

Parameters:

info - The default MBeanOperationInfo derived by reflection.

Returns:

the impact flag for the given MBeanOperationInfo.

getImplementation

public Object getImplementation()

Get the implementation of this Standard MBean (or MXBean).

Returns:

The implementation of this Standard MBean (or MXBean).

getImplementationClass

public Class getImplementationClass()

Get the class of the implementation of this Standard MBean (or MXBean).

Returns:

The class of the implementation of this Standard MBean (or MXBean).

getMBeanInfo

public MBeanInfo getMBeanInfo()

Get the {@link MBeanInfo} for this MBean.

This method implements {@link javax.management.DynamicMBean#getMBeanInfo() DynamicMBean.getMBeanInfo()}.

This method first calls {@link #getCachedMBeanInfo()} in order to retrieve the cached MBeanInfo for this MBean, if any. If the MBeanInfo returned by {@link #getCachedMBeanInfo()} is not null, then it is returned.
Otherwise, this method builds a default MBeanInfo for this MBean, using the Management Interface specified for this MBean.

While building the MBeanInfo, this method calls the customization hooks that make it possible for subclasses to supply their custom descriptions, parameter names, etc...
Finally, it calls {@link #cacheMBeanInfo(javax.management.MBeanInfo) cacheMBeanInfo()} in order to cache the new MBeanInfo.

Returns:

The cached MBeanInfo for that MBean, if not null, or a newly built MBeanInfo if none was cached.

getMBeanInterface

public final Class getMBeanInterface()

Get the Management Interface of this Standard MBean (or MXBean).

Returns:

The management interface of this Standard MBean (or MXBean).

getParameterName

protected String getParameterName(MBeanConstructorInfo ctor,
                                  MBeanParameterInfo param,
                                  int sequence)

Customization hook: Get the name that will be used for the sequence MBeanParameterInfo of the MBeanConstructorInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom parameter name. The default implementation returns {@link MBeanParameterInfo#getName() param.getName()}.

Parameters:

ctor - The default MBeanConstructorInfo derived by reflection.

param - The default MBeanParameterInfo derived by reflection.

sequence - The sequence number of the parameter considered ("0" for the first parameter, "1" for the second parameter, etc...).

Returns:

the name for the given MBeanParameterInfo.

getParameterName

protected String getParameterName(MBeanOperationInfo op,
                                  MBeanParameterInfo param,
                                  int sequence)

Customization hook: Get the name that will be used for the sequence MBeanParameterInfo of the MBeanOperationInfo returned by this MBean.
Subclasses may redefine this method in order to supply their custom parameter name. The default implementation returns {@link MBeanParameterInfo#getName() param.getName()}.

Parameters:

op - The default MBeanOperationInfo derived by reflection.

param - The default MBeanParameterInfo derived by reflection.

sequence - The sequence number of the parameter considered ("0" for the first parameter, "1" for the second parameter, etc...).

Returns:

the name to use for the given MBeanParameterInfo.

invoke

public Object invoke(String actionName,
                     Object[] params,
                     String[] signature)
              throws MBeanException,
                     ReflectionException

Parameters:

actionName

params

signature

Throws:

MBeanException

ReflectionException

postDeregister

public void postDeregister()

Allows the MBean to perform any operations needed after having been unregistered in the MBean server.

The default implementation of this method does nothing for Standard MBeans. For MXBeans, it removes any information that was recorded by the {@link #preRegister preRegister} method.

It is good practice for a subclass that overrides this method to call the overridden method via {@code super.postRegister(...)}. This is necessary if this object is an MXBean that is referenced by attributes or operations in other MXBeans.

postRegister

public void postRegister(Boolean registrationDone)

Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.

The default implementation of this method does nothing for Standard MBeans. For MXBeans, it undoes any work done by {@link #preRegister preRegister} if registration fails.

It is good practice for a subclass that overrides this method to call the overridden method via {@code super.postRegister(...)}. This is necessary if this object is an MXBean that is referenced by attributes or operations in other MXBeans.

Parameters:

registrationDone - Indicates whether or not the MBean has been successfully registered in the MBean server. The value false means that the registration phase has failed.

preDeregister

public void preDeregister()
                   throws Exception

Allows the MBean to perform any operations it needs before being unregistered by the MBean server.

The default implementation of this method does nothing.

It is good practice for a subclass that overrides this method to call the overridden method via {@code super.preDeegister(...)}.

Throws:

Exception - no checked exceptions are throw by this method but {@code Exception} is declared so that subclasses can override this method and throw their own exceptions.

preRegister

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

Allows the MBean to perform any operations it needs before being registered in the MBean server. If the name of the MBean is not specified, the MBean can provide a name for its registration. If any exception is raised, the MBean will not be registered in the MBean server.

The default implementation of this method returns the {@code name} parameter. It does nothing else for Standard MBeans. For MXBeans, it records the {@code MBeanServer} and {@code ObjectName} parameters so they can be used to translate inter-MXBean references.

It is good practice for a subclass that overrides this method to call the overridden method via {@code super.preRegister(...)}. This is necessary if this object is an MXBean that is referenced by attributes or operations in other MXBeans.

Parameters:

server - The MBean server in which the MBean will be registered.

name - The object name of the MBean. This name is null if the name parameter to one of the createMBean or registerMBean methods in the {@link MBeanServer} interface is null. In that case, this method must return a non-null ObjectName for the new MBean.

Returns:

The name under which the MBean is to be registered. This value must not be null. If the name parameter is not null, it will usually but not necessarily be the returned value.

Throws:

Exception - no other checked exceptions are thrown by this method but {@code Exception} is declared so that subclasses can override the method and throw their own exceptions.

setAttribute

public void setAttribute(Attribute attribute)
                  throws AttributeNotFoundException,
                         InvalidAttributeValueException,
                         MBeanException,
                         ReflectionException

Parameters:

attribute

Throws:

AttributeNotFoundException

InvalidAttributeValueException

MBeanException

ReflectionException

setAttributes

public AttributeList setAttributes(AttributeList attributes)

Parameters:

attributes

setImplementation

public void setImplementation(Object implementation)
                       throws NotCompliantMBeanException

Replace the implementation object wrapped in this object.

Parameters:

implementation - The new implementation of this Standard MBean (or MXBean). The implementation object must implement the Standard MBean (or MXBean) interface that was supplied when this StandardMBean was constructed.

Throws:

NotCompliantMBeanException - if the given implementation does not implement the Standard MBean (or MXBean) interface that was supplied at construction.