javax.management

Class StandardMBean

Implemented Interfaces:
DynamicMBean
Known Direct Subclasses:
BeanImpl

public class StandardMBean
extends Object
implements DynamicMBean

Provides a dynamic management bean by using reflection on an interface and an implementing class. By default, a bean instance is paired up with its interface based on specific naming conventions (if the implementation is called X, the interface must be XMBean). Using this class removes the need to use a specific naming system to match up the two. Instead, an instance of this bean is created either via explicit construction or subclassing, and this provides access to the attributes, constructors and operations of the implementation via reflection. Various hooks are provided in order to allow customization of this process.
Since:
1.5

Constructor Summary

StandardMBean(T impl, Class iface)
Constructs a new StandardMBean using the specified interface and the supplied instance as the implementation.
StandardMBean(Class iface)
Constructs a new StandardMBean using the specified interface and this as the instance.

Method Summary

protected void
cacheMBeanInfo(MBeanInfo info)
Caches the MBeanInfo instance for this object.
Object
getAttribute(String name)
Obtains the value of the specified attribute of the management bean.
AttributeList
getAttributes(String[] names)
Obtains the values of each of the specified attributes of the management bean.
protected MBeanInfo
getCachedMBeanInfo()
Returns the cached MBeanInfo instance for this object.
protected String
getClassName(MBeanInfo info)
Returns the class name that will be used in the MBeanInfo instance.
protected MBeanConstructorInfo[]
getConstructors(MBeanConstructorInfo[] constructors, Object impl)
Returns information on the constructors that will be used in the MBeanInfo instance.
protected String
getDescription(MBeanAttributeInfo info)
Returns the description of the attribute that will be used in the supplied MBeanAttributeInfo instance.
protected String
getDescription(MBeanConstructorInfo info)
Returns the description of the constructor that will be used in the supplied MBeanConstructorInfo instance.
protected String
getDescription(MBeanConstructorInfo info, MBeanParameterInfo param, int n)
Returns the description of the nth parameter of the constructor that will be used in the supplied MBeanParameterInfo instance.
protected String
getDescription(MBeanFeatureInfo info)
Returns the description of the supplied feature that will be used in the supplied MBeanFeatureInfo instance.
protected String
getDescription(MBeanInfo info)
Returns the description of the bean that will be used in the supplied MBeanInfo instance.
protected String
getDescription(MBeanOperationInfo info)
Returns the description of the operation that will be used in the supplied MBeanOperationInfo instance.
protected String
getDescription(MBeanOperationInfo info, MBeanParameterInfo param, int n)
Returns the description of the nth parameter of the operation that will be used in the supplied MBeanParameterInfo instance.
protected int
getImpact(MBeanOperationInfo info)
Returns the impact of the operation that will be used in the supplied MBeanOperationInfo instance.
Object
getImplementation()
Returns the instance that implements this bean.
Class
getImplementationClass()
Returns the class of the instance that implements this bean.
MBeanInfo
getMBeanInfo()
Returns an information object which lists the attributes and actions associated with the management bean.
Class
getMBeanInterface()
Returns the interface for this management bean.
protected String
getParameterName(MBeanConstructorInfo info, MBeanParameterInfo param, int n)
Returns the name of the nth parameter of the constructor that will be used in the supplied MBeanParameterInfo instance.
protected String
getParameterName(MBeanOperationInfo info, MBeanParameterInfo param, int n)
Returns the name of the nth parameter of the operation that will be used in the supplied MBeanParameterInfo instance.
Object
invoke(String name, Object[] params, String[] signature)
Invokes the specified action on the management bean using the supplied parameters.
void
setAttribute(Attribute attribute)
Sets the value of the specified attribute of the management bean.
AttributeList
setAttributes(AttributeList attributes)
Sets the value of each of the specified attributes to that supplied by the Attribute object.
void
setImplementation(Object impl)
Replaces the implementation of the interface used by this instance with the one specified.

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

StandardMBean

public  StandardMBean(T impl,
                         Class iface)
            throws NotCompliantMBeanException
Constructs a new StandardMBean using the specified interface and the supplied instance as the implementation.
Parameters:
impl - the implementation.
iface - the interface the bean implements, or null if the interface should be determined using the naming convention (class X has interface XMBean).
Throws:
IllegalArgumentException - if impl is null.
NotCompliantMBeanException - if impl doesn't implement the interface or a method appears in the interface that doesn't comply with the naming conventions.

StandardMBean

protected StandardMBean(Class iface)
            throws NotCompliantMBeanException
Constructs a new StandardMBean using the specified interface and this as the instance. This should be used to create an instance via subclassing.
Parameters:
iface - the interface this bean implements, or null if the interface should be determined using the naming convention (class X has interface XMBean).
Throws:
NotCompliantMBeanException - if this class doesn't implement the interface or a method appears in the interface that doesn't comply with the naming conventions.

Method Details

cacheMBeanInfo

protected void cacheMBeanInfo(MBeanInfo info)
Caches the MBeanInfo instance for this object. This is a customization hook, so that subclasses can choose the caching policy used. The default implementation caches the value in the instance itself. Subclasses may override this so as to not cache the data at all, or so as to use a cache shared between multiple beans.
Parameters:
info - the MBeanInfo instance to cache, or null if there is no new value to cache. When the value is not null, the cache should replace the current value with the value supplied here.

getAttribute

public Object getAttribute(String name)
            throws AttributeNotFoundException,
                   MBeanException,
                   ReflectionException
Obtains the value of the specified attribute of the management bean. The management bean should perform a lookup for the named attribute, and return its value by calling the appropriate getter method, if possible.
Specified by:
getAttribute in interface DynamicMBean
Parameters:
name - the name of the attribute to retrieve.
Returns:
the value of the specified attribute.
Throws:
AttributeNotFoundException - if the name does not correspond to an attribute of the bean.
MBeanException - if retrieving the attribute causes the bean to throw an exception (which becomes the cause of this exception).
ReflectionException - if an exception occurred in trying to use the reflection interface to lookup the attribute. The thrown exception is the cause of this exception.
See Also:
setAttribute(String)

getAttributes

public AttributeList getAttributes(String[] names)
Obtains the values of each of the specified attributes of the management bean. The returned list includes those attributes that were retrieved and their corresponding values.
Specified by:
getAttributes in interface DynamicMBean
Parameters:
names - the names of the attributes to retrieve.
Returns:
a list of the retrieved attributes.

getCachedMBeanInfo

protected MBeanInfo getCachedMBeanInfo()
Returns the cached MBeanInfo instance for this object. This is a customization hook, so that subclasses can choose the caching policy used. The default implementation caches the value in the instance itself, and returns this value on calls to this method.
Returns:
the cached MBeanInfo instance, or null if no value is cached.

getClassName

protected String getClassName(MBeanInfo info)
Returns the class name that will be used in the MBeanInfo instance. This is a customization hook, so that subclasses can provide a custom class name. By default, this returns the class name from the supplied MBeanInfo instance.
Parameters:
info - the MBeanInfo instance constructed via reflection.
Returns:
the class name to use in the instance.

getConstructors

protected MBeanConstructorInfo[] getConstructors(MBeanConstructorInfo[] constructors,
                                                 Object impl)
Returns information on the constructors that will be used in the MBeanInfo instance. This is a customization hook, so that subclasses can provide their own information on the bean's constructors, if necessary. By default, this method returns null unless the implementation supplied is either null or this. This default implementation prevents the use of MBeanServer.createMBean in cases where the bean is not created as a subclass of StandardMBean.
Parameters:
constructors - the constructor information created via reflection.
impl - the implementation, or null if this should be ignored.
Returns:
the constructor information to use.

getDescription

protected String getDescription(MBeanAttributeInfo info)
Returns the description of the attribute that will be used in the supplied MBeanAttributeInfo instance. This is a customization hook, so that subclasses can provide a custom description. By default, this calls getDescription(MBeanFeatureInfo) with the supplied MBeanAttributeInfo instance.
Parameters:
info - the MBeanAttributeInfo instance constructed via reflection.
Returns:
the description to use in the instance.

getDescription

protected String getDescription(MBeanConstructorInfo info)
Returns the description of the constructor that will be used in the supplied MBeanConstructorInfo instance. This is a customization hook, so that subclasses can provide a custom description. By default, this calls getDescription(MBeanFeatureInfo) with the supplied MBeanConstructorInfo instance.
Parameters:
info - the MBeanConstructorInfo instance constructed via reflection.
Returns:
the description to use in the instance.

getDescription

protected String getDescription(MBeanConstructorInfo info,
                                MBeanParameterInfo param,
                                int n)
Returns the description of the nth parameter of the constructor that will be used in the supplied MBeanParameterInfo instance. This is a customization hook, so that subclasses can provide a custom description. By default, this calls param.getDescription().
Parameters:
info - the MBeanConstructorInfo instance constructed via reflection.
param - the MBeanParameterInfo instance constructed via reflection.
n - the number of the parameter, in order to link it to the information on the constructor.
Returns:
the description to use in the instance.

getDescription

protected String getDescription(MBeanFeatureInfo info)
Returns the description of the supplied feature that will be used in the supplied MBeanFeatureInfo instance. This is a customization hook, so that subclasses can provide a custom description. By default, this calls info.getDescription(). This method is also called by default for the more specific description methods for attributes, constructors and operations.
Parameters:
info - the MBeanFeatureInfo instance constructed via reflection.
Returns:
the description to use in the instance.

getDescription

protected String getDescription(MBeanInfo info)
Returns the description of the bean that will be used in the supplied MBeanInfo instance. This is a customization hook, so that subclasses can provide a custom description. By default, this calls info.getDescription().
Parameters:
info - the MBeanInfo instance constructed via reflection.
Returns:
the description to use in the instance.

getDescription

protected String getDescription(MBeanOperationInfo info)
Returns the description of the operation that will be used in the supplied MBeanOperationInfo instance. This is a customization hook, so that subclasses can provide a custom description. By default, this calls getDescription(MBeanFeatureInfo) with the supplied MBeanOperationInfo instance.
Parameters:
info - the MBeanOperationInfo instance constructed via reflection.
Returns:
the description to use in the instance.

getDescription

protected String getDescription(MBeanOperationInfo info,
                                MBeanParameterInfo param,
                                int n)
Returns the description of the nth parameter of the operation that will be used in the supplied MBeanParameterInfo instance. This is a customization hook, so that subclasses can provide a custom description. By default, this calls param.getDescription().
Parameters:
info - the MBeanOperationInfo instance constructed via reflection.
param - the MBeanParameterInfo instance constructed via reflection.
n - the number of the parameter, in order to link it to the information on the operation.
Returns:
the description to use in the instance.

getImpact

protected int getImpact(MBeanOperationInfo info)
Returns the impact of the operation that will be used in the supplied MBeanOperationInfo instance. This is a customization hook, so that subclasses can provide a custom impact flag. By default, this returns info.getImpact().
Parameters:
info - the MBeanOperationInfo instance constructed via reflection.
Returns:
the impact flag to use in the instance.

getImplementation

public Object getImplementation()
Returns the instance that implements this bean.
Returns:
the implementation.

getImplementationClass

public Class getImplementationClass()
Returns the class of the instance that implements this bean.
Returns:
the implementation class.

getMBeanInfo

public MBeanInfo getMBeanInfo()
Returns an information object which lists the attributes and actions associated with the management bean. This implementation proceeds as follows:
  1. getCachedMBeanInfo() is called to obtain the cached instance. If this returns a non-null value, this value is returned.
  2. If there is no cached value, then the method proceeds to create one. During this process, the customization hooks detailed in this class are called to allow the values used to be overrided:
    • For each attribute, getDescription(MBeanAttributeInfo) is called.
    • For each constructor, getDescription(MBeanConstructorInfo) is called, along with getDescription(MBeanConstructorInfo,MBeanParameterInfo,int) and getParameterName(MBeanConstructorInfo,MBeanParameterInfo,int) for each parameter.
    • The constructors may be replaced as a whole by a call to getConstructors(MBeanConstructorInfo[],Object).
    • For each operation, getDescription(MBeanOperationInfo) and getImpact(MBeanOperationInfo) are called, along with getDescription(MBeanOperationInfo,MBeanParameterInfo,int) and getParameterName(MBeanOperationInfo,MBeanParameterInfo,int) for each parameter.
    • getClassName(MBeanInfo) and getDescription(MBeanInfo) are called to customise the basic information about the class.
    • Finally, cacheMBeanInfo(MBeanInfo) is called with the created instance before it is returned.
    Specified by:
    getMBeanInfo in interface DynamicMBean
    Returns:
    a description of the management bean, including all exposed attributes and actions.

    getMBeanInterface

    public final Class getMBeanInterface()
    Returns the interface for this management bean.
    Returns:
    the management interface.

    getParameterName

    protected String getParameterName(MBeanConstructorInfo info,
                                      MBeanParameterInfo param,
                                      int n)
    Returns the name of the nth parameter of the constructor that will be used in the supplied MBeanParameterInfo instance. This is a customization hook, so that subclasses can provide a custom name. By default, this calls param.getName().
    Parameters:
    info - the MBeanConstructorInfo instance constructed via reflection.
    param - the MBeanParameterInfo instance constructed via reflection.
    n - the number of the parameter, in order to link it to the information on the constructor.
    Returns:
    the name to use in the instance.

    getParameterName

    protected String getParameterName(MBeanOperationInfo info,
                                      MBeanParameterInfo param,
                                      int n)
    Returns the name of the nth parameter of the operation that will be used in the supplied MBeanParameterInfo instance. This is a customization hook, so that subclasses can provide a custom name. By default, this calls param.getName().
    Parameters:
    info - the MBeanOperationInfo instance constructed via reflection.
    param - the MBeanParameterInfo instance constructed via reflection.
    n - the number of the parameter, in order to link it to the information on the operation.
    Returns:
    the name to use in the instance.

    invoke

    public Object invoke(String name,
                         Object[] params,
                         String[] signature)
                throws MBeanException,
                       ReflectionException
    Invokes the specified action on the management bean using the supplied parameters. The signature of the action is specified by a String array, which lists the classes corresponding to each parameter. The class loader used to load these classes is the same as that used for loading the management bean itself.
    Specified by:
    invoke in interface DynamicMBean
    Parameters:
    name - the name of the action to invoke.
    params - the parameters used to call the action.
    signature - the signature of the action.
    Returns:
    the return value of the action.
    Throws:
    MBeanException - if the action throws an exception. The thrown exception is the cause of this exception.
    ReflectionException - if an exception occurred in trying to use the reflection interface to invoke the action. The thrown exception is the cause of this exception.

    setAttribute

    public void setAttribute(Attribute attribute)
                throws AttributeNotFoundException,
                       InvalidAttributeValueException,
                       MBeanException,
                       ReflectionException
    Sets the value of the specified attribute of the management bean. The management bean should perform a lookup for the named attribute, and sets its value using the associated setter method, if possible.
    Specified by:
    setAttribute in interface DynamicMBean
    Parameters:
    attribute - the attribute to set.
    Throws:
    AttributeNotFoundException - if the attribute does not correspond to an attribute of the bean.
    InvalidAttributeValueException - if the value is invalid for this particular attribute of the bean.
    MBeanException - if setting the attribute causes the bean to throw an exception (which becomes the cause of this exception).
    ReflectionException - if an exception occurred in trying to use the reflection interface to lookup the attribute. The thrown exception is the cause of this exception.

    setAttributes

    public AttributeList setAttributes(AttributeList attributes)
    Sets the value of each of the specified attributes to that supplied by the Attribute object. The returned list contains the attributes that were set and their new values.
    Specified by:
    setAttributes in interface DynamicMBean
    Parameters:
    attributes - the attributes to set.
    Returns:
    a list of the changed attributes.
    See Also:
    getAttributes(AttributeList)

    setImplementation

    public void setImplementation(Object impl)
                throws NotCompliantMBeanException
    Replaces the implementation of the interface used by this instance with the one specified. The new implementation must be non-null and implement the interface specified on construction of this instance.
    Throws:
    IllegalArgumentException - if impl is null.
    NotCompliantMBeanException - if impl doesn't implement the interface or a method appears in the interface that doesn't comply with the naming conventions.

    StandardMBean.java -- A standard reflection-based management bean. Copyright (C) 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.