Please note that this documentation is not final and is subject to change.

javax.management.namespace
Class MBeanServerSupport

java.lang.Object
  javax.management.namespace.MBeanServerSupport

All Implemented Interfaces:

NotificationManager, MBeanServer, MBeanServerConnection

public abstract class MBeanServerSupport
extends Object
implements MBeanServer

Base class for custom implementations of the MBeanServer interface. The commonest use of this class is as the source server for a JMXNamespace, although this class can be used anywhere an MBeanServer instance is required. Note that the usual ways to obtain an MBeanServer instance are either to use ManagementFactory.getPlatformMBeanServer() or to use the newMBeanServer or createMBeanServer methods from MBeanServerFactory. MBeanServerSupport is for certain cases where those are not appropriate.

There are two main use cases for this class: special-purpose MBeanServer implementations, and namespaces containing Virtual MBeans. The next sections explain these use cases.

In the simplest case, a subclass needs to implement only two methods:

• getNames which returns the name of all MBeans handled by this MBeanServer.
• getDynamicMBeanFor which returns a DynamicMBean that can be used to invoke operations and obtain meta data (MBeanInfo) on a given MBean.

Subclasses can create such DynamicMBean MBeans on the fly - for instance, using the class StandardMBean, just for the duration of an MBeanServer method call.

Special-purpose MBeanServer implementations

In some cases the general-purpose MBeanServer that you get from MBeanServerFactory is not appropriate. You might need different security checks, or you might want a mock MBeanServer suitable for use in tests, or you might want a simplified and optimized MBeanServer for a special purpose.

As an example of a special-purpose MBeanServer, the class QueryNotificationFilter constructs an MBeanServer instance every time it filters a notification, with just one MBean that represents the notification. Although it could use MBeanServerFactory.newMBeanServer, a special-purpose MBeanServer will be quicker to create, use less memory, and have simpler methods that execute faster.

Here is an example of a special-purpose MBeanServer implementation that contains exactly one MBean, which is specified at the time of creation.

 public class SingletonMBeanServer extends MBeanServerSupport {
     private final ObjectName objectName;
     private final DynamicMBean mbean;

     public SingletonMBeanServer(ObjectName objectName, DynamicMBean mbean) {
         this.objectName = objectName;
         this.mbean = mbean;
     }

     @Override
     protected Set<ObjectName> getNames() {
         return Collections.singleton(objectName);
     }

     @Override
     public DynamicMBean getDynamicMBeanFor(ObjectName name)
             throws InstanceNotFoundException {
         if (objectName.equals(name))
             return mbean;
         else
             throw new InstanceNotFoundException(name);
     }
 }
 

Using this class, you could make an MBeanServer that contains a Timer MBean like this:

     Timer timer = new Timer();
     DynamicMBean mbean = new StandardMBean(timer, TimerMBean.class);
     ObjectName name = new ObjectName("com.example:type=Timer");
     MBeanServer timerMBS = new SingletonMBeanServer(name, mbean);
 

When getDynamicMBeanFor always returns the same object for the same name, as here, notifications work in the expected way: if the object is a NotificationEmitter then listeners can be added using MBeanServer.addNotificationListener. If getDynamicMBeanFor does not always return the same object for the same name, more work is needed to make notifications work, as described below.

Namespaces containing Virtual MBeans

Virtual MBeans are MBeans that do not exist as Java objects, except transiently while they are being accessed. This is useful when there might be very many of them, or when keeping track of their creation and deletion might be expensive or hard. For example, you might have one MBean per system process. With an ordinary MBeanServer, you would have to list the system processes in order to create an MBean object for each one, and you would have to track the arrival and departure of system processes in order to create or delete the corresponding MBeans. With Virtual MBeans, you only need the MBean for a given process at the exact point where it is referenced with a call such as MBeanServer.getAttribute.

Here is an example of an MBeanServer implementation that has one MBean for every system property. The system property "java.home" is represented by the MBean called com.example:type=Property,name="java.home", with an attribute called Value that is the value of the property.

 public interface PropertyMBean {
     public String getValue();
 }

 public class PropsMBS extends MBeanServerSupport {
     public static class PropertyImpl implements PropertyMBean {
         private final String name;

         public PropertyImpl(String name) {
             this.name = name;
         }

         public String getValue() {
             return System.getProperty(name);
         }
     }

     @Override
     public DynamicMBean getDynamicMBeanFor(ObjectName name)
             throws InstanceNotFoundException {

         // Check that the name is a legal one for a Property MBean
         ObjectName namePattern = ObjectName.valueOf(
                     "com.example:type=Property,name=\"*\"");
         if (!namePattern.apply(name))
             throw new InstanceNotFoundException(name);

         // Extract the name of the property that the MBean corresponds to
         String propName = ObjectName.unquote(name.getKeyProperty("name"));
         if (System.getProperty(propName) == null)
             throw new InstanceNotFoundException(name);

         // Construct and return a transient MBean object
         PropertyMBean propMBean = new PropertyImpl(propName);
         return new StandardMBean(propMBean, PropertyMBean.class, false);
     }

     @Override
     protected Set<ObjectName> getNames() {
         Set<ObjectName> names = new TreeSet<ObjectName>();
         Properties props = System.getProperties();
         for (String propName : props.stringPropertyNames()) {
             ObjectName objectName = ObjectName.valueOf(
                     "com.example:type=Property,name=" +
                     ObjectName.quote(propName));
             names.add(objectName);
         }
         return names;
     }
 }
 

Because the getDynamicMBeanFor method returns a different object every time it is called, the default handling of notifications will not work, as explained below. In this case it does not matter, because the object returned by getDynamicMBeanFor is not a NotificationEmitter, so MBeanServer.addNotificationListener will always fail. But if we wanted to extend PropsMBS so that the MBean for property "foo" emitted a notification every time that property changed, we would need to do it as shown below. (Because there is no API to be informed when a property changes, this code assumes that some other code calls the propertyChanged method every time a property changes.)

 public class PropsMBS {
     ...as above...

     private final VirtualEventManager vem = new VirtualEventManager();

     @Override
     public NotificationEmitter getNotificationEmitterFor(
             ObjectName name) throws InstanceNotFoundException {
         getDynamicMBeanFor(name);  // check that the name is valid
         return vem.getNotificationEmitterFor(name);
     }

     public void propertyChanged(String name, String newValue) {
         ObjectName objectName = ObjectName.valueOf(
                 "com.example:type=Property,name=" + ObjectName.quote(name));
         Notification n = new Notification(
                 "com.example.property.changed", objectName, 0L,
                 "Property " + name + " changed");
         n.setUserData(newValue);
         vem.publish(objectName, n);
     }
 }
 

MBean creation and deletion

MBean creation through MBeanServer.createMBean is disabled by default. Subclasses which need to support MBean creation through createMBean need to implement a single method createMBean(String, ObjectName, ObjectName, Object[], String[], boolean).

Similarly MBean registration and unregistration through registerMBean and unregisterMBean are disabled by default. Subclasses which need to support MBean registration and unregistration will need to implement registerMBean and unregisterMBean.

Notifications

By default addNotificationListener is accepted for an MBean name if getDynamicMBeanFor(name) returns an object that is a NotificationEmitter. That is appropriate if getDynamicMBeanFor(name) always returns the same object for the same name. But with Virtual MBeans, every call to getDynamicMBeanFor returns a new object, which is discarded as soon as the MBean request has finished. So a listener added to that object would be immediately forgotten.

The simplest way for a subclass that defines Virtual MBeans to support notifications is to create a private VirtualEventManager and override the method getNotificationEmitterFor as follows:

     private final VirtualEventManager vem = new VirtualEventManager();

     @Override
     public NotificationEmitter getNotificationEmitterFor(
             ObjectName name) throws InstanceNotFoundException {
         // Check that the name is a valid Virtual MBean.
         // This is the easiest way to do that, but not always the
         // most efficient:
         getDynamicMBeanFor(name);

         // Return an object that supports add/removeNotificationListener
         // through the VirtualEventManager.
         return vem.getNotificationEmitterFor(name);
     }
 

A notification n can then be sent from the Virtual MBean called name by calling vem.publish(name, n). See the example above.

Since:

1.7

Constructor Summary

Modifier	Constructor and Description
protected	MBeanServerSupport() Make a new MBeanServerSupport instance.

Method Summary

Modifier and Type	Method and Description
void	addNotificationListener(ObjectName name, NotificationListener listener, NotificationFilter filter, Object handback) Adds a listener to a registered MBean.
void	addNotificationListener(ObjectName name, ObjectName listenerName, NotificationFilter filter, Object handback) Adds a listener to a registered MBean.
ObjectInstance	createMBean(String className, ObjectName name) Calls createMBean(className, name, null, null, null, true);
ObjectInstance	createMBean(String className, ObjectName name, Object[] params, String[] signature) Calls createMBean(className, name, null, params, signature, true);
ObjectInstance	createMBean(String className, ObjectName name, ObjectName loaderName) Calls createMBean(className, name, loaderName, null, null, false);
ObjectInstance	createMBean(String className, ObjectName name, ObjectName loaderName, Object[] params, String[] signature) Calls createMBean(className,name, loaderName, params, signature, false);
ObjectInstance	createMBean(String className, ObjectName name, ObjectName loaderName, Object[] params, String[] signature, boolean useCLR) Creates a new MBean in the MBean name space.
ObjectInputStream	deserialize(ObjectName name, byte[] data) Deprecated.
ObjectInputStream	deserialize(String className, byte[] data) Deprecated.
ObjectInputStream	deserialize(String className, ObjectName loaderName, byte[] data) Deprecated.
Object	getAttribute(ObjectName name, String attribute) Gets the value of a specific attribute of a named MBean.
AttributeList	getAttributes(ObjectName name, String[] attributes) Retrieves the values of several attributes of a named MBean.
ClassLoader	getClassLoader(ObjectName loaderName) Return the named ClassLoader.
ClassLoader	getClassLoaderFor(ObjectName mbeanName) Return the ClassLoader that was used for loading the class of the named MBean.
ClassLoaderRepository	getClassLoaderRepository() Return the ClassLoaderRepository for this MBeanServer.
String	getDefaultDomain() Returns the default domain used for naming the MBean.
String[]	getDomains() Returns the list of domains in which any MBean is currently registered.
abstract DynamicMBean	getDynamicMBeanFor(ObjectName name) Returns a dynamically created handle that makes it possible to access the named MBean for the duration of a method call.
protected Set<ObjectName>	getMatchingNames(ObjectName pattern) List names matching the given pattern.
Integer	getMBeanCount() Returns the number of MBeans registered in the MBean server.
MBeanInfo	getMBeanInfo(ObjectName name) This method discovers the attributes and operations that an MBean exposes for management.
protected abstract Set<ObjectName>	getNames() Subclasses should implement this method to return the names of all MBeans handled by this object instance.
NotificationEmitter	getNotificationEmitterFor(ObjectName name) Returns a NotificationEmitter which can be used to subscribe or unsubscribe for notifications with the named mbean.
ObjectInstance	getObjectInstance(ObjectName name) Gets the ObjectInstance for a given MBean registered with the MBean server.
Object	instantiate(String className) Instantiates an object using the list of all class loaders registered in the MBean server's Class Loader Repository.
Object	instantiate(String className, Object[] params, String[] signature) Instantiates an object using the list of all class loaders registered in the MBean server Class Loader Repository.
Object	instantiate(String className, ObjectName loaderName) Instantiates an object using the class Loader specified by its ObjectName.
Object	instantiate(String className, ObjectName loaderName, Object[] params, String[] signature) Instantiates an object.
Object	invoke(ObjectName name, String operationName, Object[] params, String[] signature) Invokes an operation on an MBean.
boolean	isInstanceOf(ObjectName name, String className) Attempts to determine whether the named MBean should be considered as an instance of a given class.
boolean	isRegistered(ObjectName name) Checks whether an MBean, identified by its object name, is already registered with the MBean server.
Set<ObjectInstance>	queryMBeans(ObjectName pattern, QueryExp query) Gets MBeans controlled by the MBean server.
Set<ObjectName>	queryNames(ObjectName pattern, QueryExp query) Gets the names of MBeans controlled by the MBean server.
ObjectInstance	registerMBean(Object object, ObjectName name) Registers a pre-existing object as an MBean with the MBean server.
void	removeNotificationListener(ObjectName name, NotificationListener listener) Removes a listener from a registered MBean.
void	removeNotificationListener(ObjectName name, NotificationListener listener, NotificationFilter filter, Object handback) Removes a listener from a registered MBean.
void	removeNotificationListener(ObjectName name, ObjectName listenerName) Removes a listener from a registered MBean.
void	removeNotificationListener(ObjectName name, ObjectName listenerName, NotificationFilter filter, Object handback) Removes a listener from a registered MBean.
void	setAttribute(ObjectName name, Attribute attribute) Sets the value of a specific attribute of a named MBean.
AttributeList	setAttributes(ObjectName name, AttributeList attributes) Sets the values of several attributes of a named MBean.
void	unregisterMBean(ObjectName name) Unregisters an MBean from the MBean server.

Methods inherited from class java.lang.Object

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

Constructor Detail

MBeanServerSupport

protected MBeanServerSupport()

Make a new MBeanServerSupport instance.

Method Detail

getDynamicMBeanFor

public abstract DynamicMBean getDynamicMBeanFor(ObjectName name)
                                         throws InstanceNotFoundException

Returns a dynamically created handle that makes it possible to access the named MBean for the duration of a method call.

An easy way to create such a DynamicMBean handle is, for instance, to create a temporary MXBean instance and to wrap it in an instance of StandardMBean. This handle should remain valid for the duration of the call but can then be discarded.

Parameters:

name - the name of the MBean for which a request was received.

Returns:

a DynamicMBean handle that can be used to invoke operations on the named MBean.

Throws:

InstanceNotFoundException - if no such MBean is supposed to exist.

getNames

protected abstract Set<ObjectName> getNames()

Subclasses should implement this method to return the names of all MBeans handled by this object instance.

The object returned by getNames() should be safely iterable even in the presence of other threads that may cause the set of names to change. Typically this means one of the following:

• the returned set of names is always the same; or
• the returned set of names is an object such as a CopyOnWriteArraySet that is safely iterable even if the set is changed by other threads; or
• a new Set is constructed every time this method is called.

Returns:

the names of all MBeans handled by this object.

getMatchingNames

protected Set<ObjectName> getMatchingNames(ObjectName pattern)

List names matching the given pattern. The default implementation of this method calls getNames() and returns the subset of those names matching pattern.

Parameters:

pattern - an ObjectName pattern

Returns:

the list of MBean names that match the given pattern.

getNotificationEmitterFor

public NotificationEmitter getNotificationEmitterFor(ObjectName name)
                                              throws InstanceNotFoundException

Returns a NotificationEmitter which can be used to subscribe or unsubscribe for notifications with the named mbean.

The default implementation of this method calls getDynamicMBeanFor(name) and returns that object if it is a NotificationEmitter, otherwise null. See above for further discussion of notification handling.

Parameters:

name - The name of the MBean whose notifications are being subscribed, or unsuscribed.

Returns:

A NotificationEmitter that can be used to subscribe or unsubscribe for notifications emitted by the named MBean, or null if the MBean does not emit notifications and should not be considered as a NotificationEmitter.

Throws:

InstanceNotFoundException - if name is not the name of an MBean in this MBeanServer.

createMBean

public ObjectInstance createMBean(String className,
                                  ObjectName name,
                                  ObjectName loaderName,
                                  Object[] params,
                                  String[] signature,
                                  boolean useCLR)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException,
                                  InstanceNotFoundException

Creates a new MBean in the MBean name space. This operation is not supported in this base class implementation.

The default implementation of this method always throws an UnsupportedOperationException wrapped in a RuntimeOperationsException.

Subclasses may redefine this method to provide an implementation. All the various flavors of MBeanServer.createMBean methods will eventually call this method. A subclass that wishes to support MBean creation through createMBean thus only needs to provide an implementation for this one method.

A subclass implementation of this method should respect the contract of the various createMBean methods in the MBeanServer interface, in particular as regards exception wrapping.

Parameters:

className - The class name of the MBean to be instantiated.

name - The object name of the MBean. May be null.

params - An array containing the parameters of the constructor to be invoked.

signature - An array containing the signature of the constructor to be invoked.

loaderName - The object name of the class loader to be used.

useCLR - This parameter is true when this method is called from one of the MBeanServer.createMBean methods whose signature does not include the ObjectName of an MBean class loader to use for loading the MBean class.

Returns:

An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().

Throws:

ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.

InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.

MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.

RuntimeMBeanException - If the MBean's constructor or its preRegister or postRegister method threw a RuntimeException. If the postRegister (MBeanRegistration interface) method of the MBean throws a RuntimeException, the createMBean method will throw a RuntimeMBeanException, although the MBean creation and registration succeeded. In such a case, the MBean will be actually registered even though the createMBean method threw an exception. Note that RuntimeMBeanException can also be thrown by preRegister, in which case the MBean will not be registered.

MBeanException - The constructor of the MBean has thrown an exception

NotCompliantMBeanException - This class is not a JMX compliant MBean

InstanceNotFoundException - The specified class loader is not registered in the MBean server.

RuntimeOperationsException - Wraps either:

• a java.lang.IllegalArgumentException: The className passed in parameter is null, the ObjectName passed in parameter contains a pattern or no ObjectName is specified for the MBean; or
• an UnsupportedOperationException if creating MBeans is not supported by this MBeanServer implementation.

isInstanceOf

public boolean isInstanceOf(ObjectName name,
                            String className)
                     throws InstanceNotFoundException

Attempts to determine whether the named MBean should be considered as an instance of a given class. The default implementation of this method calls getDynamicMBeanFor(name) to get an MBean object. Then its behaviour is the same as the standard MBeanServer.isInstanceOf method.

Returns true if the MBean specified is an instance of the specified class, false otherwise.

If name does not name an MBean, this method throws InstanceNotFoundException.

Otherwise, let
X be the MBean named by name,
L be the ClassLoader of X,
N be the class name in X's MBeanInfo.

If N equals className, the result is true.

Otherwise, if L successfully loads className and X is an instance of this class, the result is true.

Otherwise, if L successfully loads both N and className, and the second class is assignable from the first, the result is true.

Otherwise, the result is false.

If the MBean implements the DynamicWrapperMBean interface, then in the above rules X is the result of the MBean's getWrappedObject() method and L is the result of its getWrappedClassLoader() method.

Specified by:

isInstanceOf in interface MBeanServer

Specified by:

isInstanceOf in interface MBeanServerConnection

Parameters:

name - The ObjectName of the MBean.

className - The name of the class.

Returns:

true if the MBean specified is an instance of the specified class according to the rules above, false otherwise.

Throws:

InstanceNotFoundException - The MBean specified is not registered in the MBean server.

See Also:

Class.isInstance(java.lang.Object)

getDefaultDomain

public String getDefaultDomain()

Returns the default domain used for naming the MBean. The default domain name is used as the domain part in the ObjectName of MBeans if no domain is specified by the user.

The default implementation of this method returns the string "DefaultDomain".

Specified by:

getDefaultDomain in interface MBeanServer

Specified by:

getDefaultDomain in interface MBeanServerConnection

Returns:

the default domain.

getMBeanCount

public Integer getMBeanCount()

Returns the number of MBeans registered in the MBean server.

The default implementation of this method returns getNames().size().

Specified by:

getMBeanCount in interface MBeanServer

Specified by:

getMBeanCount in interface MBeanServerConnection

Returns:

the number of registered MBeans, wrapped in an Integer. If the caller's permissions are restricted, this number may be greater than the number of MBeans the caller can access.

getDomains

public String[] getDomains()

Returns the list of domains in which any MBean is currently registered. A string is in the returned array if and only if there is at least one MBean registered with an ObjectName whose getDomain() is equal to that string. The order of strings within the returned array is not defined.

The default implementation of this method first calls getNames() to get a list of all MBean names, and from this set of names, derives the set of domains which contain MBeans.

Specified by:

getDomains in interface MBeanServer

Specified by:

getDomains in interface MBeanServerConnection

Returns:

the list of domains.

getAttribute

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

Gets the value of a specific attribute of a named MBean. The MBean is identified by its object name.

The default implementation of this method will first call getDynamicMBeanFor(name) to obtain a handle to the named MBean, and then call getAttribute on that DynamicMBean handle.

Specified by:

getAttribute in interface MBeanServer

Specified by:

getAttribute in interface MBeanServerConnection

Parameters:

name - The object name of the MBean from which the attribute is to be retrieved.

attribute - A String specifying the name of the attribute to be retrieved.

Returns:

The value of the retrieved attribute.

Throws:

RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null or the attribute in parameter is null.

MBeanException - Wraps an exception thrown by the MBean's getter.

AttributeNotFoundException - The attribute specified is not accessible in the MBean.

InstanceNotFoundException - The MBean specified is not registered in the MBean server.

ReflectionException - Wraps a java.lang.Exception thrown when trying to invoke the setter.

See Also:

MBeanServerConnection.setAttribute(javax.management.ObjectName, javax.management.Attribute)

setAttribute

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

Sets the value of a specific attribute of a named MBean. The MBean is identified by its object name.

The default implementation of this method will first call getDynamicMBeanFor(name) to obtain a handle to the named MBean, and then call setAttribute on that DynamicMBean handle.

Specified by:

setAttribute in interface MBeanServer

Specified by:

setAttribute in interface MBeanServerConnection

Parameters:

name - The name of the MBean within which the attribute is to be set.

attribute - The identification of the attribute to be set and the value it is to be set to.

Throws:

RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null or the attribute in parameter is null.

InstanceNotFoundException - The MBean specified is not registered in the MBean server.

AttributeNotFoundException - The attribute specified is not accessible in the MBean.

InvalidAttributeValueException - The value specified for the attribute is not valid.

MBeanException - Wraps an exception thrown by the MBean's setter.

ReflectionException - Wraps a java.lang.Exception thrown when trying to invoke the setter.

See Also:

MBeanServerConnection.getAttribute(javax.management.ObjectName, java.lang.String)

getAttributes

public AttributeList getAttributes(ObjectName name,
                                   String[] attributes)
                            throws InstanceNotFoundException,
                                   ReflectionException

Retrieves the values of several attributes of a named MBean. The MBean is identified by its object name.

If one or more attributes cannot be retrieved for some reason, they will be omitted from the returned AttributeList. The caller should check that the list is the same size as the attributes array. To discover what problem prevented a given attribute from being retrieved, call getAttribute for that attribute.

Here is an example of calling this method and checking that it succeeded in retrieving all the requested attributes:

 String[] attrNames = ...;
 AttributeList list = mbeanServerConnection.getAttributes(objectName, attrNames);
 if (list.size() == attrNames.length)
     System.out.println("All attributes were retrieved successfully");
 else {
     List<String> missing = new ArrayList<String>(Arrays.asList(attrNames));
     missing.removeAll(list.toMap().keySet());
     System.out.println("Did not retrieve: " + missing);
 }
 

The default implementation of this method will first call getDynamicMBeanFor(name) to obtain a handle to the named MBean, and then call getAttributes on that DynamicMBean handle.

Specified by:

getAttributes in interface MBeanServer

Specified by:

getAttributes in interface MBeanServerConnection

Parameters:

name - The object name of the MBean from which the attributes are retrieved.

attributes - A list of the attributes to be retrieved.

Returns:

The list of the retrieved attributes.

Throws:

RuntimeOperationsException - Wrap a java.lang.IllegalArgumentException: The object name in parameter is null or attributes in parameter is null.

InstanceNotFoundException - The MBean specified is not registered in the MBean server.

ReflectionException - An exception occurred when trying to invoke the getAttributes method of a Dynamic MBean.

See Also:

MBeanServerConnection.setAttributes(javax.management.ObjectName, javax.management.AttributeList)

setAttributes

public AttributeList setAttributes(ObjectName name,
                                   AttributeList attributes)
                            throws InstanceNotFoundException,
                                   ReflectionException

Sets the values of several attributes of a named MBean. The MBean is identified by its object name.

If one or more attributes cannot be set for some reason, they will be omitted from the returned AttributeList. The caller should check that the input AttributeList is the same size as the output one. To discover what problem prevented a given attribute from being retrieved, it will usually be possible to call setAttribute for that attribute, although this is not guaranteed to work. (For example, the values of two attributes may have been rejected because they were inconsistent with each other. Setting one of them alone might be allowed.)

Here is an example of calling this method and checking that it succeeded in setting all the requested attributes:

 AttributeList inputAttrs = ...;
 AttributeList outputAttrs = mbeanServerConnection.setAttributes(objectName, inputAttrs);
 if (inputAttrs.size() == outputAttrs.size())
     System.out.println("All attributes were set successfully");
 else {
     List<String> missing = new ArrayList<String>(inputAttrs.toMap().keySet());
     missing.removeAll(outputAttrs.toMap().keySet());
     System.out.println("Did not set: " + missing);
 }
 

The default implementation of this method will first call getDynamicMBeanFor(name) to obtain a handle to the named MBean, and then call setAttributes on that DynamicMBean handle.

Specified by:

setAttributes in interface MBeanServer

Specified by:

setAttributes in interface MBeanServerConnection

Parameters:

name - The object name of the MBean within which the attributes are to be set.

attributes - A list of attributes: The identification of the attributes to be set and the values they are to be set to.

Returns:

The list of attributes that were set, with their new values.

Throws:

RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null or attributes in parameter is null.

InstanceNotFoundException - The MBean specified is not registered in the MBean server.

ReflectionException - An exception occurred when trying to invoke the getAttributes method of a Dynamic MBean.

See Also:

MBeanServerConnection.getAttributes(javax.management.ObjectName, java.lang.String[])

invoke

public Object invoke(ObjectName name,
                     String operationName,
                     Object[] params,
                     String[] signature)
              throws InstanceNotFoundException,
                     MBeanException,
                     ReflectionException

Invokes an operation on an MBean.

Because of the need for a signature to differentiate possibly-overloaded operations, it is much simpler to invoke operations through an MBean proxy where possible. For example, suppose you have a Standard MBean interface like this:

 public interface FooMBean {
     public int countMatches(String[] patterns, boolean ignoreCase);
 }
 

The countMatches operation can be invoked as follows:

 String[] myPatterns = ...;
 int count = (Integer) mbeanServerConnection.invoke(
         objectName,
         "countMatches",
         new Object[] {myPatterns, true},
         new String[] {String[].class.getName(), boolean.class.getName()});
 

Alternatively, it can be invoked through a proxy as follows:

 String[] myPatterns = ...;
 FooMBean fooProxy = JMX.newMBeanProxy(
         mbeanServerConnection, objectName, FooMBean.class);
 int count = fooProxy.countMatches(myPatterns, true);
 

The default implementation of this method will first call getDynamicMBeanFor(name) to obtain a handle to the named MBean, and then call invoke on that DynamicMBean handle.

Specified by:

invoke in interface MBeanServer

Specified by:

invoke in interface MBeanServerConnection

Parameters:

name - The object name of the MBean on which the method is to be invoked.

operationName - The name of the operation to be invoked.

params - An array containing the parameters to be set when the operation is invoked

signature - An array containing the signature of the operation, an array of class names in the format returned by Class.getName(). The class objects will be loaded using the same class loader as the one used for loading the MBean on which the operation was invoked.

Returns:

The object returned by the operation, which represents the result of invoking the operation on the MBean specified.

Throws:

InstanceNotFoundException - The MBean specified is not registered in the MBean server.

MBeanException - Wraps an exception thrown by the MBean's invoked method.

ReflectionException - Wraps a java.lang.Exception thrown while trying to invoke the method.

getMBeanInfo

public MBeanInfo getMBeanInfo(ObjectName name)
                       throws InstanceNotFoundException,
                              IntrospectionException,
                              ReflectionException

This method discovers the attributes and operations that an MBean exposes for management.

The default implementation of this method will first call getDynamicMBeanFor(name) to obtain a handle to the named MBean, and then call getMBeanInfo on that DynamicMBean handle.

Specified by:

getMBeanInfo in interface MBeanServer

Specified by:

getMBeanInfo in interface MBeanServerConnection

Parameters:

name - The name of the MBean to analyze

Returns:

An instance of MBeanInfo allowing the retrieval of all attributes and operations of this MBean.

Throws:

InstanceNotFoundException - The MBean specified was not found.

IntrospectionException - An exception occurred during introspection.

ReflectionException - An exception occurred when trying to invoke the getMBeanInfo of a Dynamic MBean.

getObjectInstance

public ObjectInstance getObjectInstance(ObjectName name)
                                 throws InstanceNotFoundException

Gets the ObjectInstance for a given MBean registered with the MBean server.

The default implementation of this method will call getDynamicMBeanFor(name).getMBeanInfo().getClassName() to get the class name to combine with name to produce a new ObjectInstance.

Specified by:

getObjectInstance in interface MBeanServer

Specified by:

getObjectInstance in interface MBeanServerConnection

Parameters:

name - The object name of the MBean.

Returns:

The ObjectInstance associated with the MBean specified by name. The contained ObjectName is name and the contained class name is getMBeanInfo(name).getClassName().

Throws:

InstanceNotFoundException - The MBean specified is not registered in the MBean server.

isRegistered

public boolean isRegistered(ObjectName name)

Checks whether an MBean, identified by its object name, is already registered with the MBean server.

The default implementation of this method will first call getDynamicMBeanFor(name) to obtain a handle to the named MBean. If getDynamicMBeanFor returns an object, isRegistered will return true. If getDynamicMBeanFor returns null or throws InstanceNotFoundException, isRegistered will return false.

Specified by:

isRegistered in interface MBeanServer

Specified by:

isRegistered in interface MBeanServerConnection

Parameters:

name - The object name of the MBean to be checked.

Returns:

True if the MBean is already registered in the MBean server, false otherwise.

Throws:

RuntimeOperationsException - Wraps a java.lang.IllegalArgumentException: The object name in parameter is null.

queryMBeans

public Set<ObjectInstance> queryMBeans(ObjectName pattern,
                                       QueryExp query)

Gets MBeans controlled by the MBean server. This method allows any of the following to be obtained: All MBeans, a set of MBeans specified by pattern matching on the ObjectName and/or a Query expression, a specific MBean. When the object name is null or no domain and key properties are specified, all objects are to be selected (and filtered if a query is specified). It returns the set of ObjectInstance objects (containing the ObjectName and the Java Class name) for the selected MBeans.

The default implementation of this method will first call queryNames to get a list of all matching MBeans, and then, for each returned name, call getObjectInstance(name).

Specified by:

queryMBeans in interface MBeanServer

Specified by:

queryMBeans in interface MBeanServerConnection

Parameters:

pattern - The object name pattern identifying the MBeans to be retrieved. If null or no domain and key properties are specified, all the MBeans registered will be retrieved.

query - The query expression to be applied for selecting MBeans. If null no query expression will be applied for selecting MBeans. ObjectName patterns that may be contained in the query expression will be evaluated in the context of the namespace in which the MBeans selected by name are registered. Thus, in the query parameter, no ObjectName pattern containing a namespace path can match any of the MBean names selected by name. See the namespaces documentation for more details.

Returns:

A set containing the ObjectInstance objects for the selected MBeans. If no MBean satisfies the query an empty list is returned.

queryNames

public Set<ObjectName> queryNames(ObjectName pattern,
                                  QueryExp query)

Gets the names of MBeans controlled by the MBean server. This method enables any of the following to be obtained: The names of all MBeans, the names of a set of MBeans specified by pattern matching on the ObjectName and/or a Query expression, a specific MBean name (equivalent to testing whether an MBean is registered). When the object name is null or no domain and key properties are specified, all objects are selected (and filtered if a query is specified). It returns the set of ObjectNames for the MBeans selected.

The default implementation of this method calls getMatchingNames(pattern) to obtain a list of MBeans matching the given name pattern. If the query parameter is null, this will be the result. Otherwise, it will evaluate the query parameter for each of the returned names, exactly as an MBeanServer would. This might result in getDynamicMBeanFor being called several times for each returned name.

Specified by:

queryNames in interface MBeanServer

Specified by:

queryNames in interface MBeanServerConnection

Parameters:

pattern - The object name pattern identifying the MBean names to be retrieved. If null or no domain and key properties are specified, the name of all registered MBeans will be retrieved.

query - The query expression to be applied for selecting MBeans. If null no query expression will be applied for selecting MBeans. ObjectName patterns that may be contained in the query expression will be evaluated in the context of the namespace in which the MBeans slected by name are registered. Thus, in the query parameter, no ObjectName pattern containing a namespace path can match any of the MBean names selected by name. See the namespaces documentation for more details.

Returns:

A set containing the ObjectNames for the MBeans selected. If no MBean satisfies the query, an empty list is returned.

addNotificationListener

public void addNotificationListener(ObjectName name,
                                    NotificationListener listener,
                                    NotificationFilter filter,
                                    Object handback)
                             throws InstanceNotFoundException

Adds a listener to a registered MBean. A notification emitted by the MBean will be forwarded to the listener.

This implementation calls getNotificationEmitterFor and invokes addNotificationListener on the NotificationEmitter it returns.

Specified by:

addNotificationListener in interface NotificationManager

Specified by:

addNotificationListener in interface MBeanServer

Specified by:

addNotificationListener in interface MBeanServerConnection

Parameters:

name - The name of the MBean on which the listener should be added.

listener - The listener object which will handle the notifications emitted by the registered MBean.

filter - The filter object. If filter is null, no filtering will be performed before handling notifications.

handback - The context to be sent to the listener when a notification is emitted.

Throws:

InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.

See Also:

getDynamicMBeanFor, getNotificationEmitterFor

removeNotificationListener

public void removeNotificationListener(ObjectName name,
                                       NotificationListener listener)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException

Removes a listener from a registered MBean.

If the listener is registered more than once, perhaps with different filters or callbacks, this method will remove all those registrations.

This implementation calls getNotificationEmitterFor and invokes removeNotificationListener on the NotificationEmitter it returns.

Specified by:

removeNotificationListener in interface NotificationManager

Specified by:

removeNotificationListener in interface MBeanServer

Specified by:

removeNotificationListener in interface MBeanServerConnection

Parameters:

name - The name of the MBean on which the listener should be removed.

listener - The listener to be removed.

Throws:

InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.

ListenerNotFoundException - The listener is not registered in the MBean.

See Also:

getDynamicMBeanFor, getNotificationEmitterFor

removeNotificationListener

public void removeNotificationListener(ObjectName name,
                                       NotificationListener listener,
                                       NotificationFilter filter,
                                       Object handback)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException

Removes a listener from a registered MBean.

The MBean must have a listener that exactly matches the given listener, filter, and handback parameters. If there is more than one such listener, only one is removed.

The filter and handback parameters may be null if and only if they are null in a listener to be removed.

This implementation calls getNotificationEmitterFor and invokes removeNotificationListener on the NotificationEmitter it returns.

Specified by:

removeNotificationListener in interface NotificationManager

Specified by:

removeNotificationListener in interface MBeanServer

Specified by:

removeNotificationListener in interface MBeanServerConnection

Parameters:

name - The name of the MBean on which the listener should be removed.

listener - The listener to be removed.

filter - The filter that was specified when the listener was added.

handback - The handback that was specified when the listener was added.

Throws:

InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.

ListenerNotFoundException - The listener is not registered in the MBean, or it is not registered with the given filter and handback.

See Also:

getDynamicMBeanFor, getNotificationEmitterFor

addNotificationListener

public void addNotificationListener(ObjectName name,
                                    ObjectName listenerName,
                                    NotificationFilter filter,
                                    Object handback)
                             throws InstanceNotFoundException

Adds a listener to a registered MBean.

The default implementation of this method first calls getDynamicMBeanFor(listenerName). If that successfully returns an object, call it mbean, then (a) if mbean is an instance of NotificationListener then this method calls addNotificationListener(name, mbean, filter, handback), otherwise (b) this method throws an exception as specified for this case.

This default implementation is not appropriate for Virtual MBeans, although that only matters if the object returned by getDynamicMBeanFor can be an instance of NotificationListener.

Specified by:

addNotificationListener in interface MBeanServer

Specified by:

addNotificationListener in interface MBeanServerConnection

Parameters:

name - The name of the MBean on which the listener should be added.

listenerName - The object name of the listener which will handle the notifications emitted by the registered MBean.

filter - The filter object. If filter is null, no filtering will be performed before handling notifications.

handback - The context to be sent to the listener when a notification is emitted.

Throws:

RuntimeOperationsException - Wraps an IllegalArgumentException. The MBean named by listener exists but does not implement the NotificationListener interface.

InstanceNotFoundException - The MBean name of the notification listener or of the notification broadcaster does not match any of the registered MBeans.

See Also:

MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName), MBeanServerConnection.removeNotificationListener(ObjectName, ObjectName, NotificationFilter, Object)

removeNotificationListener

public void removeNotificationListener(ObjectName name,
                                       ObjectName listenerName)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException

Removes a listener from a registered MBean.

If the listener is registered more than once, perhaps with different filters or callbacks, this method will remove all those registrations.

This operation is not supported in this base class implementation. The default implementation of this method always throws RuntimeOperationsException wrapping UnsupportedOperationException.

Specified by:

removeNotificationListener in interface MBeanServer

Specified by:

removeNotificationListener in interface MBeanServerConnection

Parameters:

name - The name of the MBean on which the listener should be removed.

listenerName - The object name of the listener to be removed.

Throws:

RuntimeOperationsException - wrapping UnsupportedOperationException

InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.

ListenerNotFoundException - The listener is not registered in the MBean.

See Also:

MBeanServerConnection.addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object)

removeNotificationListener

public void removeNotificationListener(ObjectName name,
                                       ObjectName listenerName,
                                       NotificationFilter filter,
                                       Object handback)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException

Removes a listener from a registered MBean.

The MBean must have a listener that exactly matches the given listener, filter, and handback parameters. If there is more than one such listener, only one is removed.

The filter and handback parameters may be null if and only if they are null in a listener to be removed.

This operation is not supported in this base class implementation. The default implementation of this method always throws RuntimeOperationsException wrapping UnsupportedOperationException.

Specified by:

removeNotificationListener in interface MBeanServer

Specified by:

removeNotificationListener in interface MBeanServerConnection

Parameters:

name - The name of the MBean on which the listener should be removed.

listenerName - The object name of the listener to be removed.

filter - The filter that was specified when the listener was added.

handback - The handback that was specified when the listener was added.

Throws:

RuntimeOperationsException - wrapping UnsupportedOperationException

InstanceNotFoundException - The MBean name provided does not match any of the registered MBeans.

ListenerNotFoundException - The listener is not registered in the MBean, or it is not registered with the given filter and handback.

See Also:

MBeanServerConnection.addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object)

getClassLoader

public ClassLoader getClassLoader(ObjectName loaderName)
                           throws InstanceNotFoundException

Return the named ClassLoader.

This operation is not supported in this base class implementation. The default implementation of this method always throws InstanceNotFoundException wrapping UnsupportedOperationException.

Specified by:

getClassLoader in interface MBeanServer

Parameters:

loaderName - The ObjectName of the ClassLoader. May be null, in which case the MBean server's own ClassLoader is returned.

Returns:

the default implementation of this method never returns.

Throws:

RuntimeOperationsException - wrapping UnsupportedOperationException

InstanceNotFoundException - if the named ClassLoader is not found.

getClassLoaderFor

public ClassLoader getClassLoaderFor(ObjectName mbeanName)
                              throws InstanceNotFoundException

Return the ClassLoader that was used for loading the class of the named MBean. If the MBean implements the DynamicWrapperMBean interface, then the returned value is the result of the DynamicWrapperMBean.getWrappedClassLoader() method.

The default implementation of this method calls getDynamicMBeanFor(mbeanName) and applies the logic just described to the result.

Specified by:

getClassLoaderFor in interface MBeanServer

Parameters:

mbeanName - The ObjectName of the MBean.

Returns:

The ClassLoader used for that MBean. If l is the value specified by the rules above, and r is the returned value, then either:

• r is identical to l; or
• the result of r.loadClass(s) is the same as l.loadClass(s) for any string s.

What this means is that the ClassLoader may be wrapped in another ClassLoader for security or other reasons.

Throws:

InstanceNotFoundException - if the named MBean is not found.

getClassLoaderRepository

public ClassLoaderRepository getClassLoaderRepository()

Return the ClassLoaderRepository for this MBeanServer.

The default implementation of this method returns a ClassLoaderRepository containing exactly one loader, the context class loader for the current thread. Subclasses can override this method to return a different ClassLoaderRepository.

Specified by:

getClassLoaderRepository in interface MBeanServer

Returns:

The ClassLoaderRepository for this MBeanServer.

registerMBean

public ObjectInstance registerMBean(Object object,
                                    ObjectName name)
                             throws InstanceAlreadyExistsException,
                                    MBeanRegistrationException,
                                    NotCompliantMBeanException

Registers a pre-existing object as an MBean with the MBean server. If the object name given is null, the MBean must provide its own name in one or both of two ways: by implementing the MBeanRegistration interface and returning the name from the preRegister method; or by defining an objectNameTemplate field in its Descriptor, typically using the @ObjectNameTemplate annotation.

If this method successfully registers an MBean, a notification is sent as described above.

This operation is not supported in this base class implementation. The default implementation of this method always throws RuntimeOperationsException wrapping UnsupportedOperationException.

Specified by:

registerMBean in interface MBeanServer

Parameters:

object - The MBean to be registered as an MBean.

name - The object name of the MBean. May be null.

Returns:

An ObjectInstance, containing the ObjectName and the Java class name of the newly registered MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().

Throws:

RuntimeOperationsException - wrapping UnsupportedOperationException

InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.

MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.

NotCompliantMBeanException - This object is not a JMX compliant MBean

See Also:

MBeanRegistration

unregisterMBean

public void unregisterMBean(ObjectName name)
                     throws InstanceNotFoundException,
                            MBeanRegistrationException

Unregisters an MBean from the MBean server. The MBean is identified by its object name. Once the method has been invoked, the MBean may no longer be accessed by its object name.

If this method successfully unregisters an MBean, a notification is sent as described above.

This operation is not supported in this base class implementation. The default implementation of this method always throws RuntimeOperationsException wrapping UnsupportedOperationException.

Specified by:

unregisterMBean in interface MBeanServer

Specified by:

unregisterMBean in interface MBeanServerConnection

Parameters:

name - The object name of the MBean to be unregistered.

Throws:

RuntimeOperationsException - wrapping UnsupportedOperationException

InstanceNotFoundException - The MBean specified is not registered in the MBean server.

MBeanRegistrationException - The preDeregister ((MBeanRegistration interface) method of the MBean has thrown an exception.

See Also:

MBeanRegistration

createMBean

public final ObjectInstance createMBean(String className,
                                        ObjectName name,
                                        Object[] params,
                                        String[] signature)
                                 throws ReflectionException,
                                        InstanceAlreadyExistsException,
                                        MBeanRegistrationException,
                                        MBeanException,
                                        NotCompliantMBeanException

Calls createMBean(className, name, null, params, signature, true);

Specified by:

createMBean in interface MBeanServer

Specified by:

createMBean in interface MBeanServerConnection

Parameters:

className - The class name of the MBean to be instantiated.

name - The object name of the MBean. May be null.

params - An array containing the parameters of the constructor to be invoked.

signature - An array containing the signature of the constructor to be invoked.

Returns:

An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().

Throws:

ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.

InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.

MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.

MBeanException - The constructor of the MBean has thrown an exception

NotCompliantMBeanException - This class is not a JMX compliant MBean

See Also:

MBeanRegistration

createMBean

public final ObjectInstance createMBean(String className,
                                        ObjectName name,
                                        ObjectName loaderName,
                                        Object[] params,
                                        String[] signature)
                                 throws ReflectionException,
                                        InstanceAlreadyExistsException,
                                        MBeanRegistrationException,
                                        MBeanException,
                                        NotCompliantMBeanException,
                                        InstanceNotFoundException

Calls createMBean(className,name, loaderName, params, signature, false);

Specified by:

createMBean in interface MBeanServer

Specified by:

createMBean in interface MBeanServerConnection

Parameters:

className - The class name of the MBean to be instantiated.

name - The object name of the MBean. May be null.

loaderName - The object name of the class loader to be used.

params - An array containing the parameters of the constructor to be invoked.

signature - An array containing the signature of the constructor to be invoked.

Returns:

An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().

Throws:

ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.

InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.

MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.

MBeanException - The constructor of the MBean has thrown an exception

NotCompliantMBeanException - This class is not a JMX compliant MBean

InstanceNotFoundException - The specified class loader is not registered in the MBean server.

See Also:

MBeanRegistration

createMBean

public final ObjectInstance createMBean(String className,
                                        ObjectName name)
                                 throws ReflectionException,
                                        InstanceAlreadyExistsException,
                                        MBeanRegistrationException,
                                        MBeanException,
                                        NotCompliantMBeanException

Calls createMBean(className, name, null, null, null, true);

Specified by:

createMBean in interface MBeanServer

Specified by:

createMBean in interface MBeanServerConnection

Parameters:

className - The class name of the MBean to be instantiated.

name - The object name of the MBean. May be null.

Returns:

An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().

Throws:

ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.

InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.

MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.

MBeanException - The constructor of the MBean has thrown an exception

NotCompliantMBeanException - This class is not a JMX compliant MBean

See Also:

MBeanRegistration

createMBean

public final ObjectInstance createMBean(String className,
                                        ObjectName name,
                                        ObjectName loaderName)
                                 throws ReflectionException,
                                        InstanceAlreadyExistsException,
                                        MBeanRegistrationException,
                                        MBeanException,
                                        NotCompliantMBeanException,
                                        InstanceNotFoundException

Calls createMBean(className, name, loaderName, null, null, false);

Specified by:

createMBean in interface MBeanServer

Specified by:

createMBean in interface MBeanServerConnection

Parameters:

className - The class name of the MBean to be instantiated.

name - The object name of the MBean. May be null.

loaderName - The object name of the class loader to be used.

Returns:

An ObjectInstance, containing the ObjectName and the Java class name of the newly instantiated MBean. If the contained ObjectName is n, the contained Java class name is getMBeanInfo(n).getClassName().

Throws:

ReflectionException - Wraps a java.lang.ClassNotFoundException or a java.lang.Exception that occurred when trying to invoke the MBean's constructor.

InstanceAlreadyExistsException - The MBean is already under the control of the MBean server.

MBeanRegistrationException - The preRegister (MBeanRegistration interface) method of the MBean has thrown an exception. The MBean will not be registered.

MBeanException - The constructor of the MBean has thrown an exception

NotCompliantMBeanException - This class is not a JMX compliant MBean

InstanceNotFoundException - The specified class loader is not registered in the MBean server.

See Also:

MBeanRegistration

instantiate

public Object instantiate(String className)
                   throws ReflectionException,
                          MBeanException

Instantiates an object using the list of all class loaders registered in the MBean server's Class Loader Repository. The object's class should have a public constructor. This method returns a reference to the newly created object. The newly created object is not registered in the MBean server.

This method is equivalent to instantiate(className, (Object[]) null, (String[]) null).

This operation is not supported in this base class implementation. The default implementation of this method always throws RuntimeOperationsException wrapping UnsupportedOperationException.

Specified by:

instantiate in interface MBeanServer

Parameters:

className - The class name of the object to be instantiated.

Returns:

The newly instantiated object.

Throws:

RuntimeOperationsException - wrapping UnsupportedOperationException

ReflectionException - Wraps a java.lang.ClassNotFoundException or the java.lang.Exception that occurred when trying to invoke the object's constructor.

MBeanException - The constructor of the object has thrown an exception

instantiate

public Object instantiate(String className,
                          ObjectName loaderName)
                   throws ReflectionException,
                          MBeanException,
                          InstanceNotFoundException

Instantiates an object using the class Loader specified by its ObjectName. If the loader name is null, the ClassLoader that loaded the MBean Server will be used. The object's class should have a public constructor. This method returns a reference to the newly created object. The newly created object is not registered in the MBean server.

This method is equivalent to instantiate(className, loaderName, (Object[]) null, (String[]) null).

This operation is not supported in this base class implementation. The default implementation of this method always throws RuntimeOperationsException wrapping UnsupportedOperationException.

Specified by:

instantiate in interface MBeanServer

Parameters:

className - The class name of the MBean to be instantiated.

loaderName - The object name of the class loader to be used.

Returns:

The newly instantiated object.

Throws:

RuntimeOperationsException - wrapping UnsupportedOperationException

ReflectionException - Wraps a java.lang.ClassNotFoundException or the java.lang.Exception that occurred when trying to invoke the object's constructor.

MBeanException - The constructor of the object has thrown an exception.

InstanceNotFoundException - The specified class loader is not registered in the MBeanServer.

instantiate

public Object instantiate(String className,
                          Object[] params,
                          String[] signature)
                   throws ReflectionException,
                          MBeanException

Instantiates an object using the list of all class loaders registered in the MBean server Class Loader Repository. The object's class should have a public constructor. The call returns a reference to the newly created object. The newly created object is not registered in the MBean server.

This operation is not supported in this base class implementation. The default implementation of this method always throws RuntimeOperationsException wrapping UnsupportedOperationException.

Specified by:

instantiate in interface MBeanServer

Parameters:

className - The class name of the object to be instantiated.

params - An array containing the parameters of the constructor to be invoked.

signature - An array containing the signature of the constructor to be invoked.

Returns:

The newly instantiated object.

Throws:

RuntimeOperationsException - wrapping UnsupportedOperationException

ReflectionException - Wraps a java.lang.ClassNotFoundException or the java.lang.Exception that occurred when trying to invoke the object's constructor.

MBeanException - The constructor of the object has thrown an exception

instantiate

public Object instantiate(String className,
                          ObjectName loaderName,
                          Object[] params,
                          String[] signature)
                   throws ReflectionException,
                          MBeanException,
                          InstanceNotFoundException

Instantiates an object. The class loader to be used is identified by its object name. If the object name of the loader is null, the ClassLoader that loaded the MBean server will be used. The object's class should have a public constructor. The call returns a reference to the newly created object. The newly created object is not registered in the MBean server.

This operation is not supported in this base class implementation. The default implementation of this method always throws RuntimeOperationsException wrapping UnsupportedOperationException.

Specified by:

instantiate in interface MBeanServer

Parameters:

className - The class name of the object to be instantiated.

loaderName - The object name of the class loader to be used.

params - An array containing the parameters of the constructor to be invoked.

signature - An array containing the signature of the constructor to be invoked.

Returns:

The newly instantiated object.

Throws:

RuntimeOperationsException - wrapping UnsupportedOperationException

ReflectionException - Wraps a java.lang.ClassNotFoundException or the java.lang.Exception that occurred when trying to invoke the object's constructor.

MBeanException - The constructor of the object has thrown an exception

InstanceNotFoundException - The specified class loader is not registered in the MBean server.

deserialize

@Deprecated
public ObjectInputStream deserialize(ObjectName name,
                                                byte[] data)
                              throws InstanceNotFoundException,
                                     OperationsException

Deprecated.

De-serializes a byte array in the context of the class loader of an MBean.

This operation is not supported in this base class implementation. The default implementation of this method always throws RuntimeOperationsException wrapping UnsupportedOperationException.

Specified by:

deserialize in interface MBeanServer

Parameters:

name - The name of the MBean whose class loader should be used for the de-serialization.

data - The byte array to be de-sererialized.

Returns:

The de-serialized object stream.

Throws:

RuntimeOperationsException - wrapping UnsupportedOperationException

InstanceNotFoundException - The MBean specified is not found.

OperationsException - Any of the usual Input/Output related exceptions.

deserialize

@Deprecated
public ObjectInputStream deserialize(String className,
                                                byte[] data)
                              throws OperationsException,
                                     ReflectionException

Deprecated.

De-serializes a byte array in the context of a given MBean class loader. The class loader is found by loading the class className through the Class Loader Repository. The resultant class's class loader is the one to use.

This operation is not supported in this base class implementation. The default implementation of this method always throws RuntimeOperationsException wrapping UnsupportedOperationException.

Specified by:

deserialize in interface MBeanServer

Parameters:

className - The name of the class whose class loader should be used for the de-serialization.

data - The byte array to be de-sererialized.

Returns:

The de-serialized object stream.

Throws:

RuntimeOperationsException - wrapping UnsupportedOperationException

OperationsException - Any of the usual Input/Output related exceptions.

ReflectionException - The specified class could not be loaded by the class loader repository

deserialize

@Deprecated
public ObjectInputStream deserialize(String className,
                                                ObjectName loaderName,
                                                byte[] data)
                              throws InstanceNotFoundException,
                                     OperationsException,
                                     ReflectionException

Deprecated.

De-serializes a byte array in the context of a given MBean class loader. The class loader is the one that loaded the class with name "className". The name of the class loader to be used for loading the specified class is specified. If null, the MBean Server's class loader will be used.

This operation is not supported in this base class implementation. The default implementation of this method always throws RuntimeOperationsException wrapping UnsupportedOperationException.

Specified by:

deserialize in interface MBeanServer

Parameters:

className - The name of the class whose class loader should be used for the de-serialization.

loaderName - The name of the class loader to be used for loading the specified class. If null, the MBean Server's class loader will be used.

data - The byte array to be de-sererialized.

Returns:

The de-serialized object stream.

Throws:

RuntimeOperationsException - wrapping UnsupportedOperationException

InstanceNotFoundException - The specified class loader MBean is not found.

OperationsException - Any of the usual Input/Output related exceptions.

ReflectionException - The specified class could not be loaded by the specified class loader.