|
|
Java example source code file (MBeanServerConnection.java)
This example Java source code file (MBeanServerConnection.java) is included in the alvinalexander.com
"Java Source Code
Warehouse" project. The intent of this project is to help you "Learn
Java by Example" TM.
Learn more about this Java project at its project page.
The MBeanServerConnection.java Java example source code
/*
* Copyright (c) 2002, 2013, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package javax.management;
// java import
import java.io.IOException;
import java.util.Set;
/**
* This interface represents a way to talk to an MBean server, whether
* local or remote. The {@link MBeanServer} interface, representing a
* local MBean server, extends this interface.
*
*
* @since 1.5
*/
public interface MBeanServerConnection {
/**
* <p>Instantiates and registers an MBean in the MBean server. The
* MBean server will use its {@link
* javax.management.loading.ClassLoaderRepository Default Loader
* Repository} to load the class of the MBean. An object name is
* associated with the MBean. If the object name given is null, the
* MBean must provide its own name by implementing the {@link
* javax.management.MBeanRegistration MBeanRegistration} interface
* and returning the name from the {@link
* MBeanRegistration#preRegister preRegister} method.</p>
*
* <p>This method is equivalent to {@link
* #createMBean(String,ObjectName,Object[],String[])
* createMBean(className, name, (Object[]) null, (String[])
* null)}.</p>
*
* @param className The class name of the MBean to be instantiated.
* @param name The object name of the MBean. May be null.
*
* @return An <CODE>ObjectInstance, containing the
* <CODE>ObjectName and the Java class name of the newly
* instantiated MBean. If the contained <code>ObjectName
* is <code>n, the contained Java class name is
* <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName().
*
* @exception ReflectionException Wraps a
* <CODE>java.lang.ClassNotFoundException or a
* <CODE>java.lang.Exception that occurred
* when trying to invoke the MBean's constructor.
* @exception InstanceAlreadyExistsException The MBean is already
* under the control of the MBean server.
* @exception MBeanRegistrationException The
* <CODE>preRegister (MBeanRegistration
* interface) method of the MBean has thrown an exception. The
* MBean will not be registered.
* @exception RuntimeMBeanException If the MBean's constructor or its
* {@code preRegister} or {@code postRegister} method threw
* a {@code RuntimeException}. If the <CODE>postRegister
* (<CODE>MBeanRegistration interface) method of the MBean throws a
* <CODE>RuntimeException, the createMBean method will
* throw a <CODE>RuntimeMBeanException, although the MBean creation
* and registration succeeded. In such a case, the MBean will be actually
* registered even though the <CODE>createMBean method
* threw an exception. Note that <CODE>RuntimeMBeanException can
* also be thrown by <CODE>preRegister, in which case the MBean
* will not be registered.
* @exception RuntimeErrorException If the <CODE>postRegister
* (<CODE>MBeanRegistration interface) method of the MBean throws an
* <CODE>Error, the createMBean method will
* throw a <CODE>RuntimeErrorException, although the MBean creation
* and registration succeeded. In such a case, the MBean will be actually
* registered even though the <CODE>createMBean method
* threw an exception. Note that <CODE>RuntimeErrorException can
* also be thrown by <CODE>preRegister, in which case the MBean
* will not be registered.
* @exception MBeanException The constructor of the MBean has
* thrown an exception
* @exception NotCompliantMBeanException This class is not a JMX
* compliant MBean
* @exception RuntimeOperationsException Wraps a
* <CODE>java.lang.IllegalArgumentException: The className
* passed in parameter is null, the <CODE>ObjectName passed
* in parameter contains a pattern or no <CODE>ObjectName
* is specified for the MBean.
* @exception IOException A communication problem occurred when
* talking to the MBean server.
* @see javax.management.MBeanRegistration
*/
public ObjectInstance createMBean(String className, ObjectName name)
throws ReflectionException, InstanceAlreadyExistsException,
MBeanRegistrationException, MBeanException,
NotCompliantMBeanException, IOException;
/**
* <p>Instantiates and registers an MBean in the MBean server. The
* class loader to be used is identified by its object name. An
* object name is associated with the MBean. If the object name of
* the loader is null, the ClassLoader that loaded the MBean
* server will be used. If the MBean's object name given is null,
* the MBean must provide its own name by implementing the {@link
* javax.management.MBeanRegistration MBeanRegistration} interface
* and returning the name from the {@link
* MBeanRegistration#preRegister preRegister} method.</p>
*
* <p>This method is equivalent to {@link
* #createMBean(String,ObjectName,ObjectName,Object[],String[])
* createMBean(className, name, loaderName, (Object[]) null,
* (String[]) null)}.</p>
*
* @param className The class name of the MBean to be instantiated.
* @param name The object name of the MBean. May be null.
* @param loaderName The object name of the class loader to be used.
*
* @return An <CODE>ObjectInstance, containing the
* <CODE>ObjectName and the Java class name of the newly
* instantiated MBean. If the contained <code>ObjectName
* is <code>n, the contained Java class name is
* <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName().
*
* @exception ReflectionException Wraps a
* <CODE>java.lang.ClassNotFoundException or a
* <CODE>java.lang.Exception that occurred when trying to
* invoke the MBean's constructor.
* @exception InstanceAlreadyExistsException The MBean is already
* under the control of the MBean server.
* @exception MBeanRegistrationException The
* <CODE>preRegister (MBeanRegistration
* interface) method of the MBean has thrown an exception. The
* MBean will not be registered.
* @exception RuntimeMBeanException If the MBean's constructor or its
* {@code preRegister} or {@code postRegister} method threw
* a {@code RuntimeException}. If the <CODE>postRegister
* (<CODE>MBeanRegistration interface) method of the MBean throws a
* <CODE>RuntimeException, the createMBean method will
* throw a <CODE>RuntimeMBeanException, although the MBean creation
* and registration succeeded. In such a case, the MBean will be actually
* registered even though the <CODE>createMBean method
* threw an exception. Note that <CODE>RuntimeMBeanException can
* also be thrown by <CODE>preRegister, in which case the MBean
* will not be registered.
* @exception RuntimeErrorException If the <CODE>postRegister
* (<CODE>MBeanRegistration interface) method of the MBean throws an
* <CODE>Error, the createMBean method will
* throw a <CODE>RuntimeErrorException, although the MBean creation
* and registration succeeded. In such a case, the MBean will be actually
* registered even though the <CODE>createMBean method
* threw an exception. Note that <CODE>RuntimeErrorException can
* also be thrown by <CODE>preRegister, in which case the MBean
* will not be registered.
* @exception MBeanException The constructor of the MBean has
* thrown an exception
* @exception NotCompliantMBeanException This class is not a JMX
* compliant MBean
* @exception InstanceNotFoundException The specified class loader
* is not registered in the MBean server.
* @exception RuntimeOperationsException Wraps a
* <CODE>java.lang.IllegalArgumentException: The className
* passed in parameter is null, the <CODE>ObjectName passed
* in parameter contains a pattern or no <CODE>ObjectName
* is specified for the MBean.
* @exception IOException A communication problem occurred when
* talking to the MBean server.
* @see javax.management.MBeanRegistration
*/
public ObjectInstance createMBean(String className, ObjectName name,
ObjectName loaderName)
throws ReflectionException, InstanceAlreadyExistsException,
MBeanRegistrationException, MBeanException,
NotCompliantMBeanException, InstanceNotFoundException,
IOException;
/**
* Instantiates and registers an MBean in the MBean server. The
* MBean server will use its {@link
* javax.management.loading.ClassLoaderRepository Default Loader
* Repository} to load the class of the MBean. An object name is
* associated with the MBean. If the object name given is null, the
* MBean must provide its own name by implementing the {@link
* javax.management.MBeanRegistration MBeanRegistration} interface
* and returning the name from the {@link
* MBeanRegistration#preRegister preRegister} method.
*
* @param className The class name of the MBean to be instantiated.
* @param name The object name of the MBean. May be null.
* @param params An array containing the parameters of the
* constructor to be invoked.
* @param signature An array containing the signature of the
* constructor to be invoked.
*
* @return An <CODE>ObjectInstance, containing the
* <CODE>ObjectName and the Java class name of the newly
* instantiated MBean. If the contained <code>ObjectName
* is <code>n, the contained Java class name is
* <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName().
*
* @exception ReflectionException Wraps a
* <CODE>java.lang.ClassNotFoundException or a
* <CODE>java.lang.Exception that occurred when trying to
* invoke the MBean's constructor.
* @exception InstanceAlreadyExistsException The MBean is already
* under the control of the MBean server.
* @exception MBeanRegistrationException The
* <CODE>preRegister (MBeanRegistration
* interface) method of the MBean has thrown an exception. The
* MBean will not be registered.
* @exception RuntimeMBeanException If the MBean's constructor or its
* {@code preRegister} or {@code postRegister} method threw
* a {@code RuntimeException}. If the <CODE>postRegister
* (<CODE>MBeanRegistration interface) method of the MBean throws a
* <CODE>RuntimeException, the createMBean method will
* throw a <CODE>RuntimeMBeanException, although the MBean creation
* and registration succeeded. In such a case, the MBean will be actually
* registered even though the <CODE>createMBean method
* threw an exception. Note that <CODE>RuntimeMBeanException can
* also be thrown by <CODE>preRegister, in which case the MBean
* will not be registered.
* @exception RuntimeErrorException If the <CODE>postRegister
* (<CODE>MBeanRegistration interface) method of the MBean throws an
* <CODE>Error, the createMBean method will
* throw a <CODE>RuntimeErrorException, although the MBean creation
* and registration succeeded. In such a case, the MBean will be actually
* registered even though the <CODE>createMBean method
* threw an exception. Note that <CODE>RuntimeErrorException can
* also be thrown by <CODE>preRegister, in which case the MBean
* will not be registered.
* @exception MBeanException The constructor of the MBean has
* thrown an exception
* @exception NotCompliantMBeanException This class is not a JMX
* compliant MBean
* @exception RuntimeOperationsException Wraps a
* <CODE>java.lang.IllegalArgumentException: The className
* passed in parameter is null, the <CODE>ObjectName passed
* in parameter contains a pattern or no <CODE>ObjectName
* is specified for the MBean.
* @exception IOException A communication problem occurred when
* talking to the MBean server.
* @see javax.management.MBeanRegistration
*/
public ObjectInstance createMBean(String className, ObjectName name,
Object params[], String signature[])
throws ReflectionException, InstanceAlreadyExistsException,
MBeanRegistrationException, MBeanException,
NotCompliantMBeanException, IOException;
/**
* <p>Instantiates and registers an MBean in the MBean server. The
* class loader to be used is identified by its object name. An
* object name is associated with the MBean. If the object name of
* the loader is not specified, the ClassLoader that loaded the
* MBean server will be used. If the MBean object name given is
* null, the MBean must provide its own name by implementing the
* {@link javax.management.MBeanRegistration MBeanRegistration}
* interface and returning the name from the {@link
* MBeanRegistration#preRegister preRegister} method.
*
* @param className The class name of the MBean to be instantiated.
* @param name The object name of the MBean. May be null.
* @param params An array containing the parameters of the
* constructor to be invoked.
* @param signature An array containing the signature of the
* constructor to be invoked.
* @param loaderName The object name of the class loader to be used.
*
* @return An <CODE>ObjectInstance, containing the
* <CODE>ObjectName and the Java class name of the newly
* instantiated MBean. If the contained <code>ObjectName
* is <code>n, the contained Java class name is
* <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName().
*
* @exception ReflectionException Wraps a
* <CODE>java.lang.ClassNotFoundException or a
* <CODE>java.lang.Exception that occurred when trying to
* invoke the MBean's constructor.
* @exception InstanceAlreadyExistsException The MBean is already
* under the control of the MBean server.
* @exception MBeanRegistrationException The
* <CODE>preRegister (MBeanRegistration
* interface) method of the MBean has thrown an exception. The
* MBean will not be registered.
* @exception RuntimeMBeanException The MBean's constructor or its
* {@code preRegister} or {@code postRegister} method threw
* a {@code RuntimeException}. If the <CODE>postRegister
* (<CODE>MBeanRegistration interface) method of the MBean throws a
* <CODE>RuntimeException, the createMBean method will
* throw a <CODE>RuntimeMBeanException, although the MBean creation
* and registration succeeded. In such a case, the MBean will be actually
* registered even though the <CODE>createMBean method
* threw an exception. Note that <CODE>RuntimeMBeanException can
* also be thrown by <CODE>preRegister, in which case the MBean
* will not be registered.
* @exception RuntimeErrorException If the <CODE>postRegister method
* (<CODE>MBeanRegistration interface) method of the MBean throws an
* <CODE>Error, the createMBean method will
* throw a <CODE>RuntimeErrorException, although the MBean creation
* and registration succeeded. In such a case, the MBean will be actually
* registered even though the <CODE>createMBean method
* threw an exception. Note that <CODE>RuntimeErrorException can
* also be thrown by <CODE>preRegister, in which case the MBean
* will not be registered.
* @exception MBeanException The constructor of the MBean has
* thrown an exception
* @exception NotCompliantMBeanException This class is not a JMX
* compliant MBean
* @exception InstanceNotFoundException The specified class loader
* is not registered in the MBean server.
* @exception RuntimeOperationsException Wraps a
* <CODE>java.lang.IllegalArgumentException: The className
* passed in parameter is null, the <CODE>ObjectName passed
* in parameter contains a pattern or no <CODE>ObjectName
* is specified for the MBean.
* @exception IOException A communication problem occurred when
* talking to the MBean server.
* @see javax.management.MBeanRegistration
*/
public ObjectInstance createMBean(String className, ObjectName name,
ObjectName loaderName, Object params[],
String signature[])
throws ReflectionException, InstanceAlreadyExistsException,
MBeanRegistrationException, MBeanException,
NotCompliantMBeanException, InstanceNotFoundException,
IOException;
/**
* Unregisters an MBean from the MBean server. The MBean is
* identified by its object name. Once the method has been
* invoked, the MBean may no longer be accessed by its object
* name.
*
* @param name The object name of the MBean to be unregistered.
*
* @exception InstanceNotFoundException The MBean specified is not
* registered in the MBean server.
* @exception MBeanRegistrationException The preDeregister
* ((<CODE>MBeanRegistration interface) method of the MBean
* has thrown an exception.
* @exception RuntimeMBeanException If the <CODE>postDeregister
* (<CODE>MBeanRegistration interface) method of the MBean throws a
* <CODE>RuntimeException, the unregisterMBean method
* will throw a <CODE>RuntimeMBeanException, although the MBean
* unregistration succeeded. In such a case, the MBean will be actually
* unregistered even though the <CODE>unregisterMBean method
* threw an exception. Note that <CODE>RuntimeMBeanException can
* also be thrown by <CODE>preDeregister, in which case the MBean
* will remain registered.
* @exception RuntimeErrorException If the <CODE>postDeregister
* (<CODE>MBeanRegistration interface) method of the MBean throws an
* <CODE>Error, the unregisterMBean method will
* throw a <CODE>RuntimeErrorException, although the MBean
* unregistration succeeded. In such a case, the MBean will be actually
* unregistered even though the <CODE>unregisterMBean method
* threw an exception. Note that <CODE>RuntimeMBeanException can
* also be thrown by <CODE>preDeregister, in which case the MBean
* will remain registered.
* @exception RuntimeOperationsException Wraps a
* <CODE>java.lang.IllegalArgumentException: The object
* name in parameter is null or the MBean you are when trying to
* unregister is the {@link javax.management.MBeanServerDelegate
* MBeanServerDelegate} MBean.
* @exception IOException A communication problem occurred when
* talking to the MBean server.
* @see javax.management.MBeanRegistration
*/
public void unregisterMBean(ObjectName name)
throws InstanceNotFoundException, MBeanRegistrationException,
IOException;
/**
* Gets the <CODE>ObjectInstance for a given MBean
* registered with the MBean server.
*
* @param name The object name of the MBean.
*
* @return The <CODE>ObjectInstance associated with the MBean
* specified by <VAR>name. The contained ObjectName
* is <code>name and the contained class name is
* <code>{@link #getMBeanInfo getMBeanInfo(name)}.getClassName().
*
* @exception InstanceNotFoundException The MBean specified is not
* registered in the MBean server.
* @exception IOException A communication problem occurred when
* talking to the MBean server.
*/
public ObjectInstance getObjectInstance(ObjectName name)
throws InstanceNotFoundException, IOException;
/**
* Gets MBeans controlled by the MBean server. This method allows
* any of the following to be obtained: All MBeans, a set of
* MBeans specified by pattern matching on the
* <CODE>ObjectName and/or a Query expression, a specific
* MBean. When the object name is null or no domain and key
* properties are specified, all objects are to be selected (and
* filtered if a query is specified). It returns the set of
* <CODE>ObjectInstance objects (containing the
* <CODE>ObjectName and the Java Class name) for the
* selected MBeans.
*
* @param name The object name pattern identifying the MBeans to
* be retrieved. If null or no domain and key properties are
* specified, all the MBeans registered will be retrieved.
* @param query The query expression to be applied for selecting
* MBeans. If null no query expression will be applied for
* selecting MBeans.
*
* @return A set containing the <CODE>ObjectInstance
* objects for the selected MBeans. If no MBean satisfies the
* query an empty list is returned.
*
* @exception IOException A communication problem occurred when
* talking to the MBean server.
*/
public Set<ObjectInstance> queryMBeans(ObjectName name, QueryExp query)
throws IOException;
/**
* Gets the names of MBeans controlled by the MBean server. This
* method enables any of the following to be obtained: The names
* of all MBeans, the names of a set of MBeans specified by
* pattern matching on the <CODE>ObjectName and/or a Query
* expression, a specific MBean name (equivalent to testing
* whether an MBean is registered). When the object name is null
* or no domain and key properties are specified, all objects are
* selected (and filtered if a query is specified). It returns the
* set of ObjectNames for the MBeans selected.
*
* @param name The object name pattern identifying the MBean names
* to be retrieved. If null or no domain and key properties are
* specified, the name of all registered MBeans will be retrieved.
* @param query The query expression to be applied for selecting
* MBeans. If null no query expression will be applied for
* selecting MBeans.
*
* @return A set containing the ObjectNames for the MBeans
* selected. If no MBean satisfies the query, an empty list is
* returned.
*
* @exception IOException A communication problem occurred when
* talking to the MBean server.
*/
public Set<ObjectName> queryNames(ObjectName name, QueryExp query)
throws IOException;
/**
* Checks whether an MBean, identified by its object name, is
* already registered with the MBean server.
*
* @param name The object name of the MBean to be checked.
*
* @return True if the MBean is already registered in the MBean
* server, false otherwise.
*
* @exception RuntimeOperationsException Wraps a
* <CODE>java.lang.IllegalArgumentException: The object
* name in parameter is null.
* @exception IOException A communication problem occurred when
* talking to the MBean server.
*/
public boolean isRegistered(ObjectName name)
throws IOException;
/**
* Returns the number of MBeans registered in the MBean server.
*
* @return the number of MBeans registered.
*
* @exception IOException A communication problem occurred when
* talking to the MBean server.
*/
public Integer getMBeanCount()
throws IOException;
/**
* Gets the value of a specific attribute of a named MBean. The MBean
* is identified by its object name.
*
* @param name The object name of the MBean from which the
* attribute is to be retrieved.
* @param attribute A String specifying the name of the attribute
* to be retrieved.
*
* @return The value of the retrieved attribute.
*
* @exception AttributeNotFoundException The attribute specified
* is not accessible in the MBean.
* @exception MBeanException Wraps an exception thrown by the
* MBean's getter.
* @exception InstanceNotFoundException The MBean specified is not
* registered in the MBean server.
* @exception ReflectionException Wraps a
* <CODE>java.lang.Exception thrown when trying to invoke
* the setter.
* @exception RuntimeOperationsException Wraps a
* <CODE>java.lang.IllegalArgumentException: The object
* name in parameter is null or the attribute in parameter is
* null.
* @exception IOException A communication problem occurred when
* talking to the MBean server.
*
* @see #setAttribute
*/
public Object getAttribute(ObjectName name, String attribute)
throws MBeanException, AttributeNotFoundException,
InstanceNotFoundException, ReflectionException,
IOException;
/**
* <p>Retrieves the values of several attributes of a named MBean. The MBean
* is identified by its object name.</p>
*
* <p>If one or more attributes cannot be retrieved for some reason, they
* will be omitted from the returned {@code AttributeList}. The caller
* should check that the list is the same size as the {@code attributes}
* array. To discover what problem prevented a given attribute from being
* retrieved, call {@link #getAttribute getAttribute} for that attribute.</p>
*
* <p>Here is an example of calling this method and checking that it
* succeeded in retrieving all the requested attributes:</p>
*
* <pre>
* String[] attrNames = ...;
* AttributeList list = mbeanServerConnection.getAttributes(objectName, attrNames);
* if (list.size() == attrNames.length)
* System.out.println("All attributes were retrieved successfully");
* else {
* {@code List<String>} missing = new {@code ArrayList}( |