javax.management
Interface MBeanServerConnection

All Known Subinterfaces:

MBeanServer

All Known Implementing Classes:

MBeanServerImpl

public interface MBeanServerConnection

An interface used to talk to an MBeanServer that is either remote or local. The local interface MBeanServer extends this one.

Version:

$Revision: 1.4.2.1 $

Author:

Adrian Brock.

See Also:

MBeanServer

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.
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.
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	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
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

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

Create an MBean registered using the given object name.

Uses the default contructor.

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

IOException - for a communication problem during this operation

createMBean

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

Create an MBean registered using the given object name.

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

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

IOException - for a communication problem during this operation

createMBean

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

Create an MBean registered using the given object name.

Uses the specified constructor.

Parameters:

className - the class name of the mbean

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

IOException - for a communication problem during this operation

createMBean

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

Create an MBean registered using the given object name.

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

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

IOException - for a communication problem during this operation

unregisterMBean

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

Unregisters an mbean.

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

IOException - for a communication problem during this operation

getObjectInstance

public ObjectInstance getObjectInstance(ObjectName name)
                                 throws InstanceNotFoundException,
                                        IOException

Retrieve an MBean's registration information.

Parameters:

name - the object name of the mbean

Throws:

InstanceNotFoundException - if the mbean is not registered in the MBeanServer

IOException - for a communication problem during this operation

queryMBeans

public Set queryMBeans(ObjectName name,
                       QueryExp query)
                throws IOException

Retrieve a set of Object instances

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

Throws:

IOException - for a communication problem during this operation

queryNames

public Set queryNames(ObjectName name,
                      QueryExp query)
               throws IOException

Retrieve a set of Object names

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

Throws:

IOException - for a communication problem during this operation

isRegistered

public boolean isRegistered(ObjectName name)
                     throws IOException

Test whether an mbean is registered.

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

IOException - for a communication problem during this operation

getMBeanCount

public Integer getMBeanCount()
                      throws IOException

Retrieve the number of mbeans registered in the server.

Returns:

true the number of registered mbeans

Throws:

IOException - for a communication problem during this operation

getAttribute

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

Retrieve a value from an MBean.

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

IOException - for a communication problem during this operation

getAttributes

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

Retrieve a list of values from an MBean.

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

IOException - for a communication problem during this operation

setAttribute

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

Set a value for an MBean.

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

IOException - for a communication problem during this operation

setAttributes

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

Set a list of values for an MBean.

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

IOException - for a communication problem during this operation

invoke

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

Invokes an operation on an mbean.

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

IOException - for a communication problem during this operation

getDefaultDomain

public String getDefaultDomain()
                        throws IOException

Retrieve the default domain of the mbeanserver.

Returns:

the default domain

Throws:

IOException - for a communication problem during this operation

getDomains

public String[] getDomains()
                    throws IOException

Retrieve the domains of the mbeanserver.

Returns:

the domains

Throws:

IOException - for a communication problem during this operation

addNotificationListener

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

Add a notification listener to an MBean.

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

IOException - for a communication problem during this operation

addNotificationListener

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

Add a notification listener to an MBean.

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

IOException - for a communication problem during this operation

removeNotificationListener

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

Removes a listener from an mbean.

All registrations of the listener are removed.

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

IOException - for a communication problem during this operation

removeNotificationListener

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

Removes a listener from an mbean.

All registrations of the listener are removed.

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

IOException - for a communication problem during this operation

removeNotificationListener

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

Removes a listener from an mbean.

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

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

IOException - for a communication problem during this operation

removeNotificationListener

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

Removes a listener from an mbean.

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

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

IOException - for a communication problem during this operation

getMBeanInfo

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

Retrieves the jmx metadata for an mbean

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

IOException - for a communication problem during this operation

isInstanceOf

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

Tests whether an mbean can be cast to the given type

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

IOException - for a communication problem during this operation