javax.management
Interface MBeanServerConnection

All Known Subinterfaces:
MBeanServer

public interface MBeanServerConnection

This interface represents a communication mechanism which may be used to access an MBean server, whether this be local or remote. The MBeanServer interface extends this with additional methods that apply only to local servers.

Since:
1.5

Method Summary
 void addNotificationListener(ObjectName name, NotificationListener listener, NotificationFilter filter, Object passback)
          Registers the supplied listener with the specified management bean.
 void addNotificationListener(ObjectName name, ObjectName listener, NotificationFilter filter, Object passback)
           Registers the supplied listener with the specified management bean.
 ObjectInstance createMBean(String className, ObjectName name)
           Instantiates a new instance of the specified management bean using the default constructor and registers it with the server under the supplied name.
 ObjectInstance createMBean(String className, ObjectName name, Object[] params, String[] sig)
           Instantiates a new instance of the specified management bean using the given constructor and registers it with the server under the supplied name.
 ObjectInstance createMBean(String className, ObjectName name, ObjectName loaderName)
           Instantiates a new instance of the specified management bean using the default constructor and registers it with the server under the supplied name.
 ObjectInstance createMBean(String className, ObjectName name, ObjectName loaderName, Object[] params, String[] sig)
           Instantiates a new instance of the specified management bean using the given constructor and registers it with the server under the supplied name.
 Object getAttribute(ObjectName bean, String name)
          Returns the value of the supplied attribute from the specified management bean.
 AttributeList getAttributes(ObjectName bean, String[] names)
          Returns the values of the named attributes from the specified management bean.
 String getDefaultDomain()
          Returns the default domain this server applies to beans that have no specified domain.
 String[] getDomains()
          Returns an array containing all the domains used by beans registered with this server.
 Integer getMBeanCount()
          Returns the number of management beans registered with this server.
 MBeanInfo getMBeanInfo(ObjectName name)
          Returns information on the given management bean.
 ObjectInstance getObjectInstance(ObjectName name)
          Returns the ObjectInstance created for the specified management bean on registration.
 Object invoke(ObjectName bean, String name, Object[] params, String[] sig)
          Invokes the supplied operation on the specified management bean.
 boolean isInstanceOf(ObjectName name, String className)
           Returns true if the specified management bean is an instance of the supplied class.
 boolean isRegistered(ObjectName name)
          Returns true if the specified management bean is registered with the server.
 Set<ObjectInstance> queryMBeans(ObjectName name, QueryExp query)
           Returns a set of ObjectInstances matching the specified criteria.
 Set<ObjectName> queryNames(ObjectName name, QueryExp query)
           Returns a set of ObjectNames matching the specified criteria.
 void removeNotificationListener(ObjectName name, NotificationListener listener)
          Removes the specified listener from the list of recipients of notifications from the supplied bean.
 void removeNotificationListener(ObjectName name, NotificationListener listener, NotificationFilter filter, Object passback)
          Removes the specified listener from the list of recipients of notifications from the supplied bean.
 void removeNotificationListener(ObjectName name, ObjectName listener)
          Removes the specified listener from the list of recipients of notifications from the supplied bean.
 void removeNotificationListener(ObjectName name, ObjectName listener, NotificationFilter filter, Object passback)
          Removes the specified listener from the list of recipients of notifications from the supplied bean.
 void setAttribute(ObjectName name, Attribute attribute)
          Sets the value of the specified attribute of the supplied management bean.
 AttributeList setAttributes(ObjectName name, AttributeList attributes)
          Sets the value of each of the specified attributes of the supplied management bean to that specified by the Attribute object.
 void unregisterMBean(ObjectName name)
          Unregisters the specified management bean.
 

Method Detail

addNotificationListener

void addNotificationListener(ObjectName name,
                             NotificationListener listener,
                             NotificationFilter filter,
                             Object passback)
                             throws InstanceNotFoundException,
                                    IOException
Registers the supplied listener with the specified management bean. Notifications emitted by the management bean are forwarded to the listener via the server, which will convert any MBean references in the source to portable ObjectName instances. The notification is otherwise unchanged.

Parameters:
name - the name of the management bean with which the listener should be registered.
listener - the listener which will handle notifications from the bean.
filter - the filter to apply to incoming notifications, or null if no filtering should be applied.
passback - an object to be passed to the listener when a notification is emitted.
Throws:
InstanceNotFoundException - if the name of the management bean could not be resolved.
IOException - if an I/O error occurred in communicating with the bean server.
See Also:
removeNotificationListener(ObjectName, NotificationListener), removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object), NotificationBroadcaster.addNotificationListener(NotificationListener, NotificationFilter, Object)

addNotificationListener

void addNotificationListener(ObjectName name,
                             ObjectName listener,
                             NotificationFilter filter,
                             Object passback)
                             throws InstanceNotFoundException,
                                    RuntimeOperationsException,
                                    IOException

Registers the supplied listener with the specified management bean. Notifications emitted by the management bean are forwarded to the listener via the server, which will convert any MBean references in the source to portable ObjectName instances. The notification is otherwise unchanged.

The listener that receives notifications will be the one that is registered with the given name at the time this method is called. Even if it later unregisters and ceases to use that name, it will still receive notifications.

Parameters:
name - the name of the management bean with which the listener should be registered.
listener - the name of the listener which will handle notifications from the bean.
filter - the filter to apply to incoming notifications, or null if no filtering should be applied.
passback - an object to be passed to the listener when a notification is emitted.
Throws:
InstanceNotFoundException - if the name of the management bean could not be resolved.
RuntimeOperationsException - if the bean associated with the given object name is not a NotificationListener. This exception wraps an IllegalArgumentException.
IOException - if an I/O error occurred in communicating with the bean server.
See Also:
removeNotificationListener(ObjectName, NotificationListener), removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object), NotificationBroadcaster.addNotificationListener(NotificationListener, NotificationFilter, Object)

createMBean

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

Instantiates a new instance of the specified management bean using the default constructor and registers it with the server under the supplied name. The class is loaded using the default loader repository of the server.

If the name supplied is null, then the bean is expected to implement the MBeanRegistration interface. The preRegister method of this interface will be used to obtain the name in this case.

This method is equivalent to calling createMBean(className, name, (Object[]) null, (String[]) null) with null parameters and signature.

Parameters:
className - the class of the management bean, of which an instance should be created.
name - the name to register the new bean with.
Returns:
an ObjectInstance containing the ObjectName and Java class name of the created instance.
Throws:
ReflectionException - if an exception occurs in creating an instance of the bean.
InstanceAlreadyExistsException - if a matching instance already exists.
MBeanRegistrationException - if an exception occurs in calling the preRegister method.
MBeanException - if the bean's constructor throws an exception.
NotCompliantMBeanException - if the created bean is not compliant with the JMX specification.
RuntimeOperationsException - if an IllegalArgumentException is thrown by the server due to a null class name or object name or if the object name is a pattern.
IOException - if an I/O error occurred in communicating with the bean server.
See Also:
createMBean(String, ObjectName, Object[], String[])

createMBean

ObjectInstance createMBean(String className,
                           ObjectName name,
                           Object[] params,
                           String[] sig)
                           throws ReflectionException,
                                  InstanceAlreadyExistsException,
                                  MBeanRegistrationException,
                                  MBeanException,
                                  NotCompliantMBeanException,
                                  IOException

Instantiates a new instance of the specified management bean using the given constructor and registers it with the server under the supplied name. The class is loaded using the default loader repository of the server.

If the name supplied is null, then the bean is expected to implement the MBeanRegistration interface. The preRegister method of this interface will be used to obtain the name in this case.

Parameters:
className - the class of the management bean, of which an instance should be created.
name - the name to register the new bean with.
params - the parameters for the bean's constructor.
sig - the signature of the constructor to use.
Returns:
an ObjectInstance containing the ObjectName and Java class name of the created instance.
Throws:
ReflectionException - if an exception occurs in creating an instance of the bean.
InstanceAlreadyExistsException - if a matching instance already exists.
MBeanRegistrationException - if an exception occurs in calling the preRegister method.
MBeanException - if the bean's constructor throws an exception.
NotCompliantMBeanException - if the created bean is not compliant with the JMX specification.
RuntimeOperationsException - if an IllegalArgumentException is thrown by the server due to a null class name or object name or if the object name is a pattern.
IOException - if an I/O error occurred in communicating with the bean server.

createMBean

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

Instantiates a new instance of the specified management bean using the default constructor and registers it with the server under the supplied name. The class is loaded using the given class loader. If this argument is null, then the same class loader as was used to load the server is used.

If the name supplied is null, then the bean is expected to implement the MBeanRegistration interface. The preRegister method of this interface will be used to obtain the name in this case.

This method is equivalent to calling createMBean(className, name, loaderName, (Object[]) null, (String) null) with null parameters and signature.

Parameters:
className - the class of the management bean, of which an instance should be created.
name - the name to register the new bean with.
loaderName - the name of the class loader.
Returns:
an ObjectInstance containing the ObjectName and Java class name of the created instance.
Throws:
ReflectionException - if an exception occurs in creating an instance of the bean.
InstanceAlreadyExistsException - if a matching instance already exists.
MBeanRegistrationException - if an exception occurs in calling the preRegister method.
MBeanException - if the bean's constructor throws an exception.
NotCompliantMBeanException - if the created bean is not compliant with the JMX specification.
InstanceNotFoundException - if the specified class loader is not registered with the server.
RuntimeOperationsException - if an IllegalArgumentException is thrown by the server due to a null class name or object name or if the object name is a pattern.
IOException - if an I/O error occurred in communicating with the bean server.
See Also:
createMBean(String, ObjectName, ObjectName, Object[], String[])

createMBean

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

Instantiates a new instance of the specified management bean using the given constructor and registers it with the server under the supplied name. The class is loaded using the given class loader. If this argument is null, then the same class loader as was used to load the server is used.

If the name supplied is null, then the bean is expected to implement the MBeanRegistration interface. The preRegister method of this interface will be used to obtain the name in this case.

Parameters:
className - the class of the management bean, of which an instance should be created.
name - the name to register the new bean with.
loaderName - the name of the class loader.
params - the parameters for the bean's constructor.
sig - the signature of the constructor to use.
Returns:
an ObjectInstance containing the ObjectName and Java class name of the created instance.
Throws:
ReflectionException - if an exception occurs in creating an instance of the bean.
InstanceAlreadyExistsException - if a matching instance already exists.
MBeanRegistrationException - if an exception occurs in calling the preRegister method.
MBeanException - if the bean's constructor throws an exception.
NotCompliantMBeanException - if the created bean is not compliant with the JMX specification.
InstanceNotFoundException - if the specified class loader is not registered with the server.
RuntimeOperationsException - if an IllegalArgumentException is thrown by the server due to a null class name or object name or if the object name is a pattern.
IOException - if an I/O error occurred in communicating with the bean server.

getAttribute

Object getAttribute(ObjectName bean,
                    String name)
                    throws MBeanException,
                           AttributeNotFoundException,
                           InstanceNotFoundException,
                           ReflectionException,
                           IOException
Returns the value of the supplied attribute from the specified management bean.

Parameters:
bean - the bean to retrieve the value from.
name - the name of the attribute to retrieve.
Returns:
the value of the attribute.
Throws:
AttributeNotFoundException - if the attribute could not be accessed from the bean.
MBeanException - if the management bean's accessor throws an exception.
InstanceNotFoundException - if the bean can not be found.
ReflectionException - if an exception was thrown in trying to invoke the bean's accessor.
RuntimeOperationsException - if an IllegalArgumentException is thrown by the server due to a null bean or attribute name.
IOException - if an I/O error occurred in communicating with the bean server.
See Also:
DynamicMBean.getAttribute(String)

getAttributes

AttributeList getAttributes(ObjectName bean,
                            String[] names)
                            throws InstanceNotFoundException,
                                   ReflectionException,
                                   IOException
Returns the values of the named attributes from the specified management bean.

Parameters:
bean - the bean to retrieve the value from.
names - the names of the attributes to retrieve.
Returns:
the values of the attributes.
Throws:
InstanceNotFoundException - if the bean can not be found.
ReflectionException - if an exception was thrown in trying to invoke the bean's accessor.
RuntimeOperationsException - if an IllegalArgumentException is thrown by the server due to a null bean or attribute name.
IOException - if an I/O error occurred in communicating with the bean server.
See Also:
DynamicMBean.getAttributes(String[])

getDefaultDomain

String getDefaultDomain()
                        throws IOException
Returns the default domain this server applies to beans that have no specified domain.

Returns:
the default domain.
Throws:
IOException - if an I/O error occurred in communicating with the bean server.

getDomains

String[] getDomains()
                    throws IOException
Returns an array containing all the domains used by beans registered with this server. The ordering of the array is undefined.

Returns:
the list of domains.
Throws:
IOException - if an I/O error occurred in communicating with the bean server.
See Also:
ObjectName.getDomain()

getMBeanCount

Integer getMBeanCount()
                      throws IOException
Returns the number of management beans registered with this server.

Returns:
the number of registered beans.
Throws:
IOException - if an I/O error occurred in communicating with the bean server.

getMBeanInfo

MBeanInfo getMBeanInfo(ObjectName name)
                       throws InstanceNotFoundException,
                              IntrospectionException,
                              ReflectionException,
                              IOException
Returns information on the given management bean.

Parameters:
name - the name of the management bean.
Returns:
an instance of MBeanInfo for the bean.
Throws:
IntrospectionException - if an exception occurs in examining the bean.
InstanceNotFoundException - if the bean can not be found.
ReflectionException - if an exception occurs when trying to invoke DynamicMBean.getMBeanInfo() on the bean.
IOException - if an I/O error occurred in communicating with the bean server.
See Also:
DynamicMBean.getMBeanInfo()

getObjectInstance

ObjectInstance getObjectInstance(ObjectName name)
                                 throws InstanceNotFoundException,
                                        IOException
Returns the ObjectInstance created for the specified management bean on registration.

Parameters:
name - the name of the bean.
Returns:
the corresponding ObjectInstance instance.
Throws:
InstanceNotFoundException - if the bean can not be found.
IOException - if an I/O error occurred in communicating with the bean server.
See Also:
createMBean(String, ObjectName)

invoke

Object invoke(ObjectName bean,
              String name,
              Object[] params,
              String[] sig)
              throws InstanceNotFoundException,
                     MBeanException,
                     ReflectionException,
                     IOException
Invokes the supplied operation on the specified management bean. The class objects specified in the signature are loaded using the same class loader as was used for the management bean.

Parameters:
bean - the management bean whose operation should be invoked.
name - the name of the operation to invoke.
params - the parameters of the operation.
sig - the signature of the operation.
Returns:
the return value of the method.
Throws:
InstanceNotFoundException - if the bean can not be found.
MBeanException - if the method invoked throws an exception.
ReflectionException - if an exception is thrown in invoking the method.
IOException - if an I/O error occurred in communicating with the bean server.
See Also:
DynamicMBean.invoke(String, Object[], String[])

isInstanceOf

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

Returns true if the specified management bean is an instance of the supplied class.

A bean, B, is an instance of a class, C, if either of the following conditions holds:

Parameters:
name - the name of the management bean.
className - the name of the class to test if name is an instance of.
Returns:
true if either B is directly an instance of the named class, or B is assignable to the class, given that both it and B's current class were loaded using the same class loader.
Throws:
InstanceNotFoundException - if the bean can not be found.
IOException - if an I/O error occurred in communicating with the bean server.

isRegistered

boolean isRegistered(ObjectName name)
                     throws IOException
Returns true if the specified management bean is registered with the server.

Parameters:
name - the name of the management bean.
Returns:
true if the bean is registered.
Throws:
RuntimeOperationsException - if an IllegalArgumentException is thrown by the server due to a null bean name.
IOException - if an I/O error occurred in communicating with the bean server.

queryMBeans

Set<ObjectInstance> queryMBeans(ObjectName name,
                                QueryExp query)
                                throws IOException

Returns a set of ObjectInstances matching the specified criteria. The full set of beans registered with the server are passed through two filters:

  1. Pattern matching is performed using the supplied ObjectName.
  2. The supplied query expression is applied.

If both the object name and the query expression are null, or the object name has no domain and no key properties, no filtering will be performed and all beans are returned.

Parameters:
name - an ObjectName to use as a filter.
query - a query expression to apply to each of the beans that match the given object name.
Returns:
a set of ObjectInstances matching the filtered beans.
Throws:
IOException - if an I/O error occurred in communicating with the bean server.

queryNames

Set<ObjectName> queryNames(ObjectName name,
                           QueryExp query)
                           throws IOException

Returns a set of ObjectNames matching the specified criteria. The full set of beans registered with the server are passed through two filters:

  1. Pattern matching is performed using the supplied ObjectName.
  2. The supplied query expression is applied.

If both the object name and the query expression are null, or the object name has no domain and no key properties, no filtering will be performed and all beans are returned.

Parameters:
name - an ObjectName to use as a filter.
query - a query expression to apply to each of the beans that match the given object name.
Returns:
a set of ObjectNames matching the filtered beans.
Throws:
IOException - if an I/O error occurred in communicating with the bean server.

removeNotificationListener

void removeNotificationListener(ObjectName name,
                                NotificationListener listener)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException,
                                       IOException
Removes the specified listener from the list of recipients of notifications from the supplied bean. This includes all combinations of filters and passback objects registered for this listener. For more specific removal of listeners, see removeNotificationListener(ObjectName, NotificationListener,NotificationFilter,Object)

Parameters:
name - the name of the management bean from which the listener should be removed.
listener - the listener to remove.
Throws:
InstanceNotFoundException - if the bean can not be found.
ListenerNotFoundException - if the specified listener is not registered with the bean.
IOException - if an I/O error occurred in communicating with the bean server.
See Also:
#addNotificationListener(NotificationListener, NotificationFilter, java.lang.Object), NotificationBroadcaster.removeNotificationListener(NotificationListener)

removeNotificationListener

void removeNotificationListener(ObjectName name,
                                NotificationListener listener,
                                NotificationFilter filter,
                                Object passback)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException,
                                       IOException
Removes the specified listener from the list of recipients of notifications from the supplied bean. Only the first instance with the supplied filter and passback object is removed. null is used as a valid value for these parameters, rather than as a way to remove all registration instances for the specified listener; for this behaviour instead, see removeNotificationListener(ObjectName, NotificationListener).

Parameters:
name - the name of the management bean from which the listener should be removed.
listener - the listener to remove.
filter - the filter of the listener to remove.
passback - the passback object of the listener to remove.
Throws:
InstanceNotFoundException - if the bean can not be found.
ListenerNotFoundException - if the specified listener is not registered with the bean.
IOException - if an I/O error occurred in communicating with the bean server.
See Also:
addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object), NotificationEmitter.removeNotificationListener(NotificationListener, NotificationFilter, Object)

removeNotificationListener

void removeNotificationListener(ObjectName name,
                                ObjectName listener)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException,
                                       IOException
Removes the specified listener from the list of recipients of notifications from the supplied bean. This includes all combinations of filters and passback objects registered for this listener. For more specific removal of listeners, see removeNotificationListener(ObjectName, ObjectName,NotificationFilter,Object)

Parameters:
name - the name of the management bean from which the listener should be removed.
listener - the name of the listener to remove.
Throws:
InstanceNotFoundException - if a name doesn't match a registered bean.
ListenerNotFoundException - if the specified listener is not registered with the bean.
IOException - if an I/O error occurred in communicating with the bean server.
See Also:
#addNotificationListener(NotificationListener, NotificationFilter, java.lang.Object), NotificationBroadcaster.removeNotificationListener(NotificationListener)

removeNotificationListener

void removeNotificationListener(ObjectName name,
                                ObjectName listener,
                                NotificationFilter filter,
                                Object passback)
                                throws InstanceNotFoundException,
                                       ListenerNotFoundException,
                                       IOException
Removes the specified listener from the list of recipients of notifications from the supplied bean. Only the first instance with the supplied filter and passback object is removed. null is used as a valid value for these parameters, rather than as a way to remove all registration instances for the specified listener; for this behaviour instead, see removeNotificationListener(ObjectName, ObjectName).

Parameters:
name - the name of the management bean from which the listener should be removed.
listener - the name of the listener to remove.
filter - the filter of the listener to remove.
passback - the passback object of the listener to remove.
Throws:
InstanceNotFoundException - if a name doesn't match a registered bean.
ListenerNotFoundException - if the specified listener is not registered with the bean.
IOException - if an I/O error occurred in communicating with the bean server.
See Also:
addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object), NotificationEmitter.removeNotificationListener(NotificationListener, NotificationFilter, Object)

setAttribute

void setAttribute(ObjectName name,
                  Attribute attribute)
                  throws InstanceNotFoundException,
                         AttributeNotFoundException,
                         InvalidAttributeValueException,
                         MBeanException,
                         ReflectionException,
                         IOException
Sets the value of the specified attribute of the supplied management bean.

Parameters:
name - the name of the management bean.
attribute - the attribute to set.
Throws:
InstanceNotFoundException - if the bean can not be found.
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.
RuntimeOperationsException - if an IllegalArgumentException is thrown by the server due to a null bean or attribute name.
IOException - if an I/O error occurred in communicating with the bean server.
See Also:
getAttribute(ObjectName, String), DynamicMBean.setAttribute(Attribute)

setAttributes

AttributeList setAttributes(ObjectName name,
                            AttributeList attributes)
                            throws InstanceNotFoundException,
                                   ReflectionException,
                                   IOException
Sets the value of each of the specified attributes of the supplied management bean to that specified by the Attribute object. The returned list contains the attributes that were set and their new values.

Parameters:
name - the name of the management bean.
attributes - the attributes to set.
Returns:
a list of the changed attributes.
Throws:
InstanceNotFoundException - if the bean can not be found.
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.
RuntimeOperationsException - if an IllegalArgumentException is thrown by the server due to a null bean or attribute list.
IOException - if an I/O error occurred in communicating with the bean server.
See Also:
getAttributes(ObjectName, String[]), DynamicMBean.setAttributes(AttributeList)

unregisterMBean

void unregisterMBean(ObjectName name)
                     throws InstanceNotFoundException,
                            MBeanRegistrationException,
                            IOException
Unregisters the specified management bean. Following this operation, the bean instance is no longer accessible from the server via this name. Prior to unregistering the bean, the MBeanRegistration.preDeregister() method will be called if the bean implements the MBeanRegistration interface.

Parameters:
name - the name of the management bean.
Throws:
InstanceNotFoundException - if the bean can not be found.
MBeanRegistrationException - if an exception occurs in calling the preDeregister method.
RuntimeOperationsException - if an IllegalArgumentException is thrown by the server due to a null bean name or a request being made to unregister the MBeanServerDelegate bean.
IOException - if an I/O error occurred in communicating with the bean server.