javax.management
Interface MBeanServer

All Superinterfaces:

MBeanServerConnection (src)

All Known Subinterfaces:

AdaptorMBean (src)

All Known Implementing Classes:

Adaptor (src) , MBeanServerImpl (src)

public interface MBeanServer

extends MBeanServerConnection (src)

The interface used to access the MBean server instances.

See Also:

MBeanServerFactory (src) , ClassLoaderRepository (src)

createMBean

public ObjectInstance (src)  createMBean(java.lang.String className,
                                  ObjectName (src)  name)
                           throws ReflectionException (src) ,
                                  InstanceAlreadyExistsException (src) ,
                                  MBeanRegistrationException (src) ,
                                  MBeanException (src) ,
                                  NotCompliantMBeanException (src) 

Create an MBean registered using the given object name.

Uses the default contructor.

Specified by:

createMBean in interface MBeanServerConnection (src)

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 (src) - for class not found or an exception invoking the contructor

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

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

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

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

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

createMBean

public ObjectInstance (src)  createMBean(java.lang.String className,
                                  ObjectName (src)  name,
                                  ObjectName (src)  loaderName)
                           throws ReflectionException (src) ,
                                  InstanceAlreadyExistsException (src) ,
                                  MBeanRegistrationException (src) ,
                                  MBeanException (src) ,
                                  NotCompliantMBeanException (src) ,
                                  InstanceNotFoundException (src) 

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 (src)

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 (src) - for class not found or an exception invoking the contructor

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

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

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

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

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

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

createMBean

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

Create an MBean registered using the given object name.

Uses the specified constructor.

Specified by:

createMBean in interface MBeanServerConnection (src)

Parameters:

className - the class name of the mbean

params - the parameters for the constructor

signature - the signature of the constructor

name - the object name for registration, can be null

Returns:

an ObjectInstance describing the registration

Throws:

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

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

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

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

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

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

createMBean

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

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 (src)

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 (src) - for class not found or an exception invoking the contructor

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

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

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

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

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

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

registerMBean

public ObjectInstance (src)  registerMBean(java.lang.Object object,
                                    ObjectName (src)  name)
                             throws InstanceAlreadyExistsException (src) ,
                                    MBeanRegistrationException (src) ,
                                    NotCompliantMBeanException (src) 

Registers an mbean.

Parameters:

object - the mbean implementation to register

name - the object name of the mbean to register

Throws:

InstanceAlreadyExistsException (src) - if the object name is already registered in the MBeanServer

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

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

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

unregisterMBean

public void unregisterMBean(ObjectName (src)  name)
                     throws InstanceNotFoundException (src) ,
                            MBeanRegistrationException (src) 

Unregisters an mbean.

Specified by:

unregisterMBean in interface MBeanServerConnection (src)

Parameters:

name - the object name of the mbean to unregister

Throws:

InstanceNotFoundException (src) - if the mbean is not registered in the MBeanServer

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

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

getObjectInstance

public ObjectInstance (src)  getObjectInstance(ObjectName (src)  name)
                                 throws InstanceNotFoundException (src) 

Retrieve an MBean's registration information.

Specified by:

getObjectInstance in interface MBeanServerConnection (src)

Parameters:

name - the object name of the mbean

Throws:

InstanceNotFoundException (src) - if the mbean is not registered in the MBeanServer

queryMBeans

public java.util.Set queryMBeans(ObjectName (src)  name,
                                 QueryExp (src)  query)

Retrieve a set of Object instances

Specified by:

queryMBeans in interface MBeanServerConnection (src)

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

public java.util.Set queryNames(ObjectName (src)  name,
                                QueryExp (src)  query)

Retrieve a set of Object names

Specified by:

queryNames in interface MBeanServerConnection (src)

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

public boolean isRegistered(ObjectName (src)  name)

Test whether an mbean is registered.

Specified by:

isRegistered in interface MBeanServerConnection (src)

Parameters:

name - the object name of the mbean

Returns:

true when the mbean is registered, false otherwise

Throws:

RuntimeOperationsException (src) - wrapping an IllegalArgumentException for a null name

getMBeanCount

public java.lang.Integer getMBeanCount()

Retrieve the number of mbeans registered in the server.

Specified by:

getMBeanCount in interface MBeanServerConnection (src)

Returns:

true the number of registered mbeans

getAttribute

public java.lang.Object getAttribute(ObjectName (src)  name,
                                     java.lang.String attribute)
                              throws MBeanException (src) ,
                                     AttributeNotFoundException (src) ,
                                     InstanceNotFoundException (src) ,
                                     ReflectionException (src) 

Retrieve a value from an MBean.

Specified by:

getAttribute in interface MBeanServerConnection (src)

Parameters:

name - the object name of the mbean

attribute - the attribute name of the value to retrieve

Returns:

the value

Throws:

ReflectionException (src) - for an exception invoking the mbean

MBeanException (src) - for any exception thrown by the mbean

InstanceNotFoundException (src) - if the mbean is not registered

AttributeNotFoundException (src) - if the mbean has no such attribute

RuntimeOperationsException (src) - wrapping an IllegalArgumentException for a null name or attribute

getAttributes

public AttributeList (src)  getAttributes(ObjectName (src)  name,
                                   java.lang.String[] attributes)
                            throws InstanceNotFoundException (src) ,
                                   ReflectionException (src) 

Retrieve a list of values from an MBean.

Specified by:

getAttributes in interface MBeanServerConnection (src)

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 (src) - for an exception invoking the mbean

InstanceNotFoundException (src) - if the mbean is not registered

RuntimeOperationsException (src) - wrapping an IllegalArgumentException for a null name or attributes

setAttribute

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

Set a value for an MBean.

Specified by:

setAttribute in interface MBeanServerConnection (src)

Parameters:

name - the object name of the mbean

attribute - the attribute name and value to set

Throws:

ReflectionException (src) - for an exception invoking the mbean

MBeanException (src) - for any exception thrown by the mbean

InstanceNotFoundException (src) - if the mbean is not registered

AttributeNotFoundException (src) - if the mbean has no such attribute

InvalidAttributeValueException (src) - if the new value has an incorrect type

RuntimeOperationsException (src) - wrapping an IllegalArgumentException for a null name or attribute

setAttributes

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

Set a list of values for an MBean.

Specified by:

setAttributes in interface MBeanServerConnection (src)

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 (src) - for an exception invoking the mbean

InstanceNotFoundException (src) - if the mbean is not registered

RuntimeOperationsException (src) - wrapping an IllegalArgumentException for a null name or attributes

invoke

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

Invokes an operation on an mbean.

Specified by:

invoke in interface MBeanServerConnection (src)

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 (src) - for an exception invoking the mbean

MBeanException (src) - for any exception thrown by the mbean

InstanceNotFoundException (src) - if the mbean is not registered

getDefaultDomain

public java.lang.String getDefaultDomain()

Retrieve the default domain of the mbeanserver.

Specified by:

getDefaultDomain in interface MBeanServerConnection (src)

Returns:

the default domain

getDomains

public java.lang.String[] getDomains()

Retrieve the domains of the mbeanserver.

Specified by:

getDomains in interface MBeanServerConnection (src)

Returns:

the domains

addNotificationListener

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

Add a notification listener to an MBean.

Specified by:

addNotificationListener in interface MBeanServerConnection (src)

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 (src) - if the broadcaster is not registered

addNotificationListener

public void addNotificationListener(ObjectName (src)  name,
                                    ObjectName (src)  listener,
                                    NotificationFilter (src)  filter,
                                    java.lang.Object handback)
                             throws InstanceNotFoundException (src) 

Add a notification listener to an MBean.

Specified by:

addNotificationListener in interface MBeanServerConnection (src)

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 (src) - if the broadcaster or listener is not registered

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

removeNotificationListener

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

Removes a listener from an mbean.

All registrations of the listener are removed.

Specified by:

removeNotificationListener in interface MBeanServerConnection (src)

Parameters:

name - the name of the MBean broadcasting notifications

listener - the object name of the listener to remove

Throws:

InstanceNotFoundException (src) - if the broadcaster or listener is not registered

ListenerNotFoundException (src) - if the listener is not registered against the broadcaster

removeNotificationListener

public void removeNotificationListener(ObjectName (src)  name,
                                       ObjectName (src)  listener,
                                       NotificationFilter (src)  filter,
                                       java.lang.Object handback)
                                throws InstanceNotFoundException (src) ,
                                       ListenerNotFoundException (src) 

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 (src)

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 (src) - if the broadcaster or listener is not registered

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

removeNotificationListener

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

Removes a listener from an mbean.

All registrations of the listener are removed.

Specified by:

removeNotificationListener in interface MBeanServerConnection (src)

Parameters:

name - the name of the MBean broadcasting notifications

listener - the listener to remove

Throws:

InstanceNotFoundException (src) - if the broadcaster is not registered

ListenerNotFoundException (src) - if the listener is not registered against the broadcaster

removeNotificationListener

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

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 (src)

Parameters:

name - the name of the MBean broadcasting notifications

listener - the listener to remove

filter - the filter of the listener to remove

Throws:

InstanceNotFoundException (src) - if the broadcaster is not registered

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

getMBeanInfo

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

Retrieves the jmx metadata for an mbean

Specified by:

getMBeanInfo in interface MBeanServerConnection (src)

Parameters:

name - the name of the mbean

Returns:

the metadata

Throws:

IntrospectionException (src) - for any error during instrospection

InstanceNotFoundException (src) - if the mbean is not registered

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

isInstanceOf

public boolean isInstanceOf(ObjectName (src)  name,
                            java.lang.String className)
                     throws InstanceNotFoundException (src) 

Tests whether an mbean can be cast to the given type

Specified by:

isInstanceOf in interface MBeanServerConnection (src)

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 (src) - if the mbean is not registered

instantiate

public java.lang.Object instantiate(java.lang.String className)
                             throws ReflectionException (src) ,
                                    MBeanException (src) 

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 (src) - 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 (src) - If the object constructor threw a checked exception during the initialization. This exception wraps the actual exception thrown.

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

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

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

See Also:

DefaultLoaderRepository (src)

instantiate

public java.lang.Object instantiate(java.lang.String className,
                                    ObjectName (src)  loaderName)
                             throws ReflectionException (src) ,
                                    MBeanException (src) ,
                                    InstanceNotFoundException (src) 

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 (src) - 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 (src) - If the object constructor threw a checked exception during the initialization. This exception wraps the actual exception thrown.

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

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

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

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

instantiate

public java.lang.Object instantiate(java.lang.String className,
                                    java.lang.Object[] params,
                                    java.lang.String[] signature)
                             throws ReflectionException (src) ,
                                    MBeanException (src) 

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 (src) - 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 (src) - If the object constructor raised a checked exception during the initialization. This exception wraps the actual exception thrown.

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

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

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

See Also:

DefaultLoaderRepository (src)

instantiate

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

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 (src) - 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 (src) - If the object constructor raised a checked exception during the initialization. This exception wraps the actual exception thrown.

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

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

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

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

deserialize

public java.io.ObjectInputStream deserialize(ObjectName (src)  name,
                                             byte[] data)
                                      throws InstanceNotFoundException (src) ,
                                             OperationsException (src) 

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

Throws:

InstanceNotFoundException (src)

OperationsException (src)

deserialize

public java.io.ObjectInputStream deserialize(java.lang.String className,
                                             byte[] data)
                                      throws OperationsException (src) ,
                                             ReflectionException (src) 

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

Throws:

OperationsException (src)

ReflectionException (src)

deserialize

public java.io.ObjectInputStream deserialize(java.lang.String className,
                                             ObjectName (src)  loaderName,
                                             byte[] data)
                                      throws InstanceNotFoundException (src) ,
                                             OperationsException (src) ,
                                             ReflectionException (src) 

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

Throws:

InstanceNotFoundException (src)

OperationsException (src)

ReflectionException (src)

getClassLoaderFor

public java.lang.ClassLoader getClassLoaderFor(ObjectName (src)  name)
                                        throws InstanceNotFoundException (src) 

Retrieve the classloader for an mbean

Parameters:

name - the object name of the mbean

Returns:

the classloader

Throws:

InstanceNotFoundException (src) - when the mbean is not registered

getClassLoader

public java.lang.ClassLoader getClassLoader(ObjectName (src)  name)
                                     throws InstanceNotFoundException (src) 

Retrieve the classloader registered as an MBean

Parameters:

name - the object name of the classloader

Returns:

the classloader

Throws:

InstanceNotFoundException (src) - when the mbean is not registered

getClassLoaderRepository

public ClassLoaderRepository (src)  getClassLoaderRepository()

Retrieve the classloader repository for this mbean server

Returns:

the classloader repository