javax.management
Interface MBeanServer

All Superinterfaces:

MBeanServerConnection

All Known Implementing Classes:

MBeanServerImpl

public interface MBeanServer
extends MBeanServerConnection

The interface used to access the MBean server instances.

Version:

$Revision: 1.10.6.1 $

Author:

Juha Lindfors., Adrian Brock.

See Also:

MBeanServerFactory, ClassLoaderRepository

Method Summary

void	addNotificationListener(ObjectName name, NotificationListener listener, NotificationFilter filter, Object handback) Add a notification listener to an MBean.
void	addNotificationListener(ObjectName name, ObjectName listener, NotificationFilter filter, Object handback) Add a notification listener to an MBean.
ObjectInstance	createMBean(String className, ObjectName name) Create an MBean registered using the given object name.
ObjectInstance	createMBean(String className, ObjectName name, Object[] params, String[] signature) Create an MBean registered using the given object name.
ObjectInstance	createMBean(String className, ObjectName name, ObjectName loaderName) Create an MBean registered using the given object name.
ObjectInstance	createMBean(String className, ObjectName name, ObjectName loaderName, Object[] params, String[] signature) Create an MBean registered using the given object name.
ObjectInputStream	deserialize(ObjectName name, byte[] data) Deprecated. use getClassLoaderFor(ObjectName) to obtain the appropriate classloader for deserialization
ObjectInputStream	deserialize(String className, byte[] data) Deprecated. use getClassLoaderFor(ObjectName) to obtain the appropriate classloader for deserialization
ObjectInputStream	deserialize(String className, ObjectName loaderName, byte[] data) Deprecated. use getClassLoaderFor(ObjectName) to obtain the appropriate classloader for deserialization
Object	getAttribute(ObjectName name, String attribute) Retrieve a value from an MBean.
AttributeList	getAttributes(ObjectName name, String[] attributes) Retrieve a list of values from an MBean.
ClassLoader	getClassLoader(ObjectName name) Retrieve the classloader registered as an MBean
ClassLoader	getClassLoaderFor(ObjectName name) Retrieve the classloader for an mbean
ClassLoaderRepository	getClassLoaderRepository() Retrieve the classloader repository for this mbean server
String	getDefaultDomain() Retrieve the default domain of the mbeanserver.
String[]	getDomains() Retrieve the domains of the mbeanserver.
Integer	getMBeanCount() Retrieve the number of mbeans registered in the server.
MBeanInfo	getMBeanInfo(ObjectName name) Retrieves the jmx metadata for an mbean
ObjectInstance	getObjectInstance(ObjectName name) Retrieve an MBean's registration information.
Object	instantiate(String className) Instantiates an object using the default loader repository and default no-args constructor.
Object	instantiate(String className, Object[] params, String[] signature) Instantiates an object using the default loader repository and a given constructor.
Object	instantiate(String className, ObjectName loaderName) Instantiates an object using the given class loader.
Object	instantiate(String className, ObjectName loaderName, Object[] params, String[] signature) Instantiates an object using the given class loader.
Object	invoke(ObjectName name, String operationName, Object[] params, String[] signature) Invokes an operation on an mbean.
boolean	isInstanceOf(ObjectName name, String className) Tests whether an mbean can be cast to the given type
boolean	isRegistered(ObjectName name) Test whether an mbean is registered.
Set	queryMBeans(ObjectName name, QueryExp query) Retrieve a set of Object instances
Set	queryNames(ObjectName name, QueryExp query) Retrieve a set of Object names
ObjectInstance	registerMBean(Object object, ObjectName name) Registers an mbean.
void	removeNotificationListener(ObjectName name, NotificationListener listener) Removes a listener from an mbean.
void	removeNotificationListener(ObjectName name, NotificationListener listener, NotificationFilter filter, Object handback) Removes a listener from an mbean.
void	removeNotificationListener(ObjectName name, ObjectName listener) Removes a listener from an mbean.
void	removeNotificationListener(ObjectName name, ObjectName listener, NotificationFilter filter, Object handback) Removes a listener from an mbean.
void	setAttribute(ObjectName name, Attribute attribute) Set a value for an MBean.
AttributeList	setAttributes(ObjectName name, AttributeList attributes) Set a list of values for an MBean.
void	unregisterMBean(ObjectName name) Unregisters an mbean.

Method Detail

createMBean

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

Create an MBean registered using the given object name.

Uses the default contructor.

Specified by:

createMBean in interface MBeanServerConnection

Parameters:

className - the class name of the mbean

name - the object name for registration, can be null

Returns:

an ObjectInstance describing the registration

Throws:

ReflectionException - for class not found or an exception invoking the contructor

InstanceAlreadyExistsException - for an MBean already registered with the passed or generated ObjectName

MBeanRegistrationException - for any exception thrown by the MBean's preRegister

MBeanException - for any exception thrown by the MBean's constructor

NotCompliantMBeanException - if the class name does not correspond to a valid MBean

RuntimeOperationsException - wrapping an IllegalArgumentException for a null class name, the ObjectName could not be determined or it is a pattern

createMBean

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

Create an MBean registered using the given object name.

The MBean is loaded using the passed classloader. Uses the default contructor.

Specified by:

createMBean in interface MBeanServerConnection

Parameters:

className - the class name of the mbean

loaderName - an MBean that implements a classloader

name - the object name for registration, can be null

Returns:

an ObjectInstance describing the registration

Throws:

ReflectionException - for class not found or an exception invoking the contructor

InstanceAlreadyExistsException - for an MBean already registered with the passed or generated ObjectName

MBeanRegistrationException - for any exception thrown by the MBean's preRegister

MBeanException - for any exception thrown by the MBean's constructor

InstanceNotFoundException - if the loaderName is not a classloader registered in the MBeanServer

NotCompliantMBeanException - if the class name does not correspond to a valid MBean

RuntimeOperationsException - wrapping an IllegalArgumentException for a null class name, the ObjectName could not be determined or it is a pattern

createMBean

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

Create an MBean registered using the given object name.

Uses the specified constructor.

Specified by:

createMBean in interface MBeanServerConnection

Parameters:

className - the class name of the mbean

loaderName - an MBean that implements a classloader

params - the parameters for the constructor

signature - the signature of the constructor

Returns:

an ObjectInstance describing the registration

Throws:

ReflectionException - for class not found or an exception invoking the contructor

InstanceAlreadyExistsException - for an MBean already registered with the passed or generated ObjectName

MBeanRegistrationException - for any exception thrown by the MBean's preRegister

MBeanException - for any exception thrown by the MBean's constructor

NotCompliantMBeanException - if the class name does not correspond to a valid MBean

RuntimeOperationsException - wrapping an IllegalArgumentException for a null class name, the ObjectName could not be determined or it is a pattern

createMBean

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

Create an MBean registered using the given object name.

The MBean is loaded using the passed classloader. Uses the specified constructor.

Specified by:

createMBean in interface MBeanServerConnection

Parameters:

className - the class name of the mbean

loaderName - an MBean that implements a classloader

name - the object name for registration, can be null

params - the parameters for the constructor

signature - the signature of the constructor

Returns:

an ObjectInstance describing the registration

Throws:

ReflectionException - for class not found or an exception invoking the contructor

InstanceAlreadyExistsException - for an MBean already registered with the passed or generated ObjectName

MBeanRegistrationException - for any exception thrown by the MBean's preRegister

MBeanException - for any exception thrown by the MBean's constructor

InstanceNotFoundException - if the loaderName is not a classloader registered in the MBeanServer

NotCompliantMBeanException - if the class name does not correspond to a valid MBean

RuntimeOperationsException - wrapping an IllegalArgumentException for a null class name, the ObjectName could not be determined or it is a pattern

registerMBean

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

Registers an mbean.

Parameters:

object - the mbean implementation to register

name - the object name of the mbean to register

Throws:

InstanceAlreadyExistsException - if the object name is already registered in the MBeanServer

MBeanRegistrationException - for any exception thrown by the MBean's preDeregister

NotCompliantMBeanException - if the class name does not correspond to a valid MBean

RuntimeOperationsException - wrapping an IllegalArgumentException for a null name, or trying to register a JMX implementation MBean

unregisterMBean

void unregisterMBean(ObjectName name)
                     throws InstanceNotFoundException,
                            MBeanRegistrationException

Unregisters an mbean.

Specified by:

unregisterMBean in interface MBeanServerConnection

Parameters:

name - the object name of the mbean to unregister

Throws:

InstanceNotFoundException - if the mbean is not registered in the MBeanServer

MBeanRegistrationException - for any exception thrown by the MBean's preDeregister

RuntimeOperationsException - wrapping an IllegalArgumentException for a null name, or trying to unregister a JMX implementation MBean

getObjectInstance

ObjectInstance getObjectInstance(ObjectName name)
                                 throws InstanceNotFoundException

Retrieve an MBean's registration information.

Specified by:

getObjectInstance in interface MBeanServerConnection

Parameters:

name - the object name of the mbean

Throws:

InstanceNotFoundException - if the mbean is not registered in the MBeanServer

queryMBeans

Set queryMBeans(ObjectName name,
                QueryExp query)

Retrieve a set of Object instances

Specified by:

queryMBeans in interface MBeanServerConnection

Parameters:

name - an ObjectName pattern, can be null for all mbeans

query - a query expression to further filter the mbeans, can be null for no query

queryNames

Set queryNames(ObjectName name,
               QueryExp query)

Retrieve a set of Object names

Specified by:

queryNames in interface MBeanServerConnection

Parameters:

name - an ObjectName pattern, can be null for all mbeans

query - a query expression to further filter the mbeans, can be null for no query

isRegistered

boolean isRegistered(ObjectName name)

Test whether an mbean is registered.

Specified by:

isRegistered in interface MBeanServerConnection

Parameters:

name - the object name of the mbean

Returns:

true when the mbean is registered, false otherwise

Throws:

RuntimeOperationsException - wrapping an IllegalArgumentException for a null name

getMBeanCount

Integer getMBeanCount()

Retrieve the number of mbeans registered in the server.

Specified by:

getMBeanCount in interface MBeanServerConnection

Returns:

true the number of registered mbeans

getAttribute

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

Retrieve a value from an MBean.

Specified by:

getAttribute in interface MBeanServerConnection

Parameters:

name - the object name of the mbean

attribute - the attribute name of the value to retrieve

Returns:

the value

Throws:

ReflectionException - for an exception invoking the mbean

MBeanException - for any exception thrown by the mbean

InstanceNotFoundException - if the mbean is not registered

AttributeNotFoundException - if the mbean has no such attribute

RuntimeOperationsException - wrapping an IllegalArgumentException for a null name or attribute

getAttributes

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

Retrieve a list of values from an MBean.

Specified by:

getAttributes in interface MBeanServerConnection

Parameters:

name - the object name of the mbean

attributes - the attribute names of the values to retrieve

Returns:

the list of values, attributes with errors are ignored

Throws:

ReflectionException - for an exception invoking the mbean

InstanceNotFoundException - if the mbean is not registered

RuntimeOperationsException - wrapping an IllegalArgumentException for a null name or attributes

setAttribute

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

Set a value for an MBean.

Specified by:

setAttribute in interface MBeanServerConnection

Parameters:

name - the object name of the mbean

attribute - the attribute name and value to set

Throws:

ReflectionException - for an exception invoking the mbean

MBeanException - for any exception thrown by the mbean

InstanceNotFoundException - if the mbean is not registered

AttributeNotFoundException - if the mbean has no such attribute

InvalidAttributeValueException - if the new value has an incorrect type

RuntimeOperationsException - wrapping an IllegalArgumentException for a null name or attribute

setAttributes

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

Set a list of values for an MBean.

Specified by:

setAttributes in interface MBeanServerConnection

Parameters:

name - the object name of the mbean

attributes - the attribute names and values to set

Returns:

the list of values, attributes with errors are ignored

Throws:

ReflectionException - for an exception invoking the mbean

InstanceNotFoundException - if the mbean is not registered

RuntimeOperationsException - wrapping an IllegalArgumentException for a null name or attributes

invoke

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

Invokes an operation on an mbean.

Specified by:

invoke in interface MBeanServerConnection

Parameters:

name - the object name of the mbean

operationName - the operation to perform

params - the parameters

signature - the signature of the operation

Returns:

any result of the operation

Throws:

ReflectionException - for an exception invoking the mbean

MBeanException - for any exception thrown by the mbean

InstanceNotFoundException - if the mbean is not registered

getDefaultDomain

String getDefaultDomain()

Retrieve the default domain of the mbeanserver.

Specified by:

getDefaultDomain in interface MBeanServerConnection

Returns:

the default domain

getDomains

String[] getDomains()

Retrieve the domains of the mbeanserver.

Specified by:

getDomains in interface MBeanServerConnection

Returns:

the domains

addNotificationListener

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

Add a notification listener to an MBean.

Specified by:

addNotificationListener in interface MBeanServerConnection

Parameters:

name - the name of the MBean broadcasting notifications

listener - the listener to add

filter - a filter to preprocess notifications

handback - a object to add to any notifications

Throws:

InstanceNotFoundException - if the broadcaster is not registered

addNotificationListener

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

Add a notification listener to an MBean.

Specified by:

addNotificationListener in interface MBeanServerConnection

Parameters:

name - the name of the MBean broadcasting notifications

listener - the object name listener to add

filter - a filter to preprocess notifications

handback - a object to add to any notifications

Throws:

InstanceNotFoundException - if the broadcaster or listener is not registered

RuntimeOperationsException - wrapping an IllegalArgumentException for a null listener or the listener does not implement the Notification Listener interface

removeNotificationListener

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

Removes a listener from an mbean.

All registrations of the listener are removed.

Specified by:

removeNotificationListener in interface MBeanServerConnection

Parameters:

name - the name of the MBean broadcasting notifications

listener - the object name of the listener to remove

Throws:

InstanceNotFoundException - if the broadcaster or listener is not registered

ListenerNotFoundException - if the listener is not registered against the broadcaster

removeNotificationListener

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

Removes a listener from an mbean.

Only the listener that was registered with the same filter and handback is removed.

Specified by:

removeNotificationListener in interface MBeanServerConnection

Parameters:

name - the name of the MBean broadcasting notifications

listener - the object name of listener to remove

filter - the filter of the listener to remove

Throws:

InstanceNotFoundException - if the broadcaster or listener is not registered

ListenerNotFoundException - if the listener, filter, handback is not registered against the broadcaster

removeNotificationListener

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

Removes a listener from an mbean.

All registrations of the listener are removed.

Specified by:

removeNotificationListener in interface MBeanServerConnection

Parameters:

name - the name of the MBean broadcasting notifications

listener - the listener to remove

Throws:

InstanceNotFoundException - if the broadcaster is not registered

ListenerNotFoundException - if the listener is not registered against the broadcaster

removeNotificationListener

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

Removes a listener from an mbean.

Only the listener that was registered with the same filter and handback is removed.

Specified by:

removeNotificationListener in interface MBeanServerConnection

Parameters:

name - the name of the MBean broadcasting notifications

listener - the listener to remove

filter - the filter of the listener to remove

Throws:

InstanceNotFoundException - if the broadcaster is not registered

ListenerNotFoundException - if the listener, filter, handback is not registered against the broadcaster

getMBeanInfo

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

Retrieves the jmx metadata for an mbean

Specified by:

getMBeanInfo in interface MBeanServerConnection

Parameters:

name - the name of the mbean

Returns:

the metadata

Throws:

IntrospectionException - for any error during instrospection

InstanceNotFoundException - if the mbean is not registered

ReflectionException - for any error trying to invoke the operation on the mbean

isInstanceOf

boolean isInstanceOf(ObjectName name,
                     String className)
                     throws InstanceNotFoundException

Tests whether an mbean can be cast to the given type

Specified by:

isInstanceOf in interface MBeanServerConnection

Parameters:

name - the name of the mbean

className - the class name to check

Returns:

true when it is of that type, false otherwise

Throws:

InstanceNotFoundException - if the mbean is not registered

instantiate

Object instantiate(String className)
                   throws ReflectionException,
                          MBeanException

Instantiates an object using the default loader repository and default no-args constructor.

Parameters:

className - Class to instantiate. Must have a public no-args constructor. Cannot contain a null reference.

Returns:

instantiated object

Throws:

ReflectionException - If there was an error while trying to invoke the class's constructor or the given class was not found. This exception wraps the actual exception thrown.

MBeanException - If the object constructor threw a checked exception during the initialization. This exception wraps the actual exception thrown.

RuntimeMBeanException - If the class constructor threw a runtime exception. This exception wraps the actual exception thrown.

RuntimeErrorException - If the class constructor threw an error. This exception wraps the actual error thrown.

RuntimeOperationsException - If the className is null. Wraps an IllegalArgumentException instance.

See Also:

DefaultLoaderRepository

instantiate

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

Instantiates an object using the given class loader. If the loader name contains a null reference, the class loader of the MBean server implementation will be used. The object must have a default, no-args constructor.

Parameters:

className - Class to instantiate. Must have a public no args constructor. Cannot contain a null reference.

loaderName - Object name of a class loader that has been registered to the server. If null, the class loader of the MBean server is used.

Returns:

instantiated object

Throws:

ReflectionException - If there was an error while trying to invoke the class's constructor or the given class was not found. This exception wraps the actual exception thrown.

MBeanException - If the object constructor threw a checked exception during the initialization. This exception wraps the actual exception thrown.

InstanceNotFoundException - if the specified class loader was not registered to the agent

RuntimeMBeanException - If the class constructor raised a runtime exception. This exception wraps the actual exception thrown.

RuntimeErrorException - If the class constructor raised an error. This exception wraps the actual error thrown.

RuntimeOperationsException - if the className is null. Wraps an IllegalArgumentException instance.

instantiate

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

Instantiates an object using the default loader repository and a given constructor. The class being instantiated must contain a constructor that matches the signature given as an argument to this method call.

Parameters:

className - class to instantiate

params - argument values for the constructor call

signature - signature of the constructor as fully qualified class names

Returns:

instantiated object

Throws:

ReflectionException - If there was an error while trying to invoke the class's constructor or the given class was not found. This exception wraps the actual exception thrown.

MBeanException - If the object constructor raised a checked exception during the initialization. This exception wraps the actual exception thrown.

RuntimeMBeanException - If the class constructor raised a runtime exception. This exception wraps the actual exception thrown.

RuntimeErrorException - If the class constructor raised an error. This exception wraps the actual error thrown.

RuntimeOperationsException - if the className is null. Wraps an IllegalArgumentException instance.

See Also:

DefaultLoaderRepository

instantiate

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

Instantiates an object using the given class loader. If the loader name contains a null reference, the class loader of the MBean server implementation will be used. The object must contain a constructor with a matching signature given as a parameter to this call.

Parameters:

className - class to instantiate

loaderName - object name of a registered class loader in the agent.

params - argument values for the constructor call

signature - signature of the constructor as fully qualified class name strings

Returns:

instantiated object

Throws:

ReflectionException - If there was an error while trying to invoke the class's constructor or the given class was not found. this exception wraps the actual exception thrown.

MBeanException - If the object constructor raised a checked exception during the initialization. This exception wraps the actual exception thrown.

InstanceNotFoundException - if the specified class loader was not registered to the agent.

RuntimeMBeanException - If the class constructor raised a runtime exception. This exception wraps the actual exception thrown.

RuntimeErrorException - If the class constructor raised an error. This exception wraps the actual error thrown.

RuntimeOperationsException - if the className argument is null. Wraps an IllegalArgumentException instance.

deserialize

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

Deprecated. use getClassLoaderFor(ObjectName) to obtain the appropriate classloader for deserialization

Throws:

InstanceNotFoundException

OperationsException

deserialize

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

Deprecated. use getClassLoaderFor(ObjectName) to obtain the appropriate classloader for deserialization

Throws:

OperationsException

ReflectionException

deserialize

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

Deprecated. use getClassLoaderFor(ObjectName) to obtain the appropriate classloader for deserialization

Throws:

InstanceNotFoundException

OperationsException

ReflectionException

getClassLoaderFor

ClassLoader getClassLoaderFor(ObjectName name)
                              throws InstanceNotFoundException

Retrieve the classloader for an mbean

Parameters:

name - the object name of the mbean

Returns:

the classloader

Throws:

InstanceNotFoundException - when the mbean is not registered

getClassLoader

ClassLoader getClassLoader(ObjectName name)
                           throws InstanceNotFoundException

Retrieve the classloader registered as an MBean

Parameters:

name - the object name of the classloader

Returns:

the classloader

Throws:

InstanceNotFoundException - when the mbean is not registered

getClassLoaderRepository

ClassLoaderRepository getClassLoaderRepository()

Retrieve the classloader repository for this mbean server

Returns:

the classloader repository