/*

 * Copyright (c) 2002, 2008, 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</CODE>, containing the

     * <CODE>ObjectName</CODE> and the Java class name of the newly

     * instantiated MBean.  If the contained <code>ObjectName</code>

     * is <code>n</code>, the contained Java class name is

     * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.

     *

     * @exception ReflectionException Wraps a

     * <CODE>java.lang.ClassNotFoundException</CODE> or a

     * <CODE>java.lang.Exception</CODE> 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</CODE> (<CODE>MBeanRegistration</CODE>

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

     * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws a

     * <CODE>RuntimeException</CODE>, the <CODE>createMBean</CODE> method will

     * throw a <CODE>RuntimeMBeanException</CODE>, although the MBean creation

     * and registration succeeded. In such a case, the MBean will be actually

     * registered even though the <CODE>createMBean</CODE> method

     * threw an exception. Note that <CODE>RuntimeMBeanException</CODE> can

     * also be thrown by <CODE>preRegister</CODE>, in which case the MBean

     * will not be registered.

     * @exception RuntimeErrorException If the <CODE>postRegister</CODE>

     * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws an

     * <CODE>Error</CODE>, the <CODE>createMBean</CODE> method will

     * throw a <CODE>RuntimeErrorException</CODE>, although the MBean creation

     * and registration succeeded. In such a case, the MBean will be actually

     * registered even though the <CODE>createMBean</CODE> method

     * threw an exception.  Note that <CODE>RuntimeErrorException</CODE> can

     * also be thrown by <CODE>preRegister</CODE>, 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</CODE>: The className

     * passed in parameter is null, the <CODE>ObjectName</CODE> passed

     * in parameter contains a pattern or no <CODE>ObjectName</CODE>

     * 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</CODE>, containing the

     * <CODE>ObjectName</CODE> and the Java class name of the newly

     * instantiated MBean.  If the contained <code>ObjectName</code>

     * is <code>n</code>, the contained Java class name is

     * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.

     *

     * @exception ReflectionException Wraps a

     * <CODE>java.lang.ClassNotFoundException</CODE> or a

     * <CODE>java.lang.Exception</CODE> 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</CODE> (<CODE>MBeanRegistration</CODE>

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

     * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws a

     * <CODE>RuntimeException</CODE>, the <CODE>createMBean</CODE> method will

     * throw a <CODE>RuntimeMBeanException</CODE>, although the MBean creation

     * and registration succeeded. In such a case, the MBean will be actually

     * registered even though the <CODE>createMBean</CODE> method

     * threw an exception.  Note that <CODE>RuntimeMBeanException</CODE> can

     * also be thrown by <CODE>preRegister</CODE>, in which case the MBean

     * will not be registered.

     * @exception RuntimeErrorException If the <CODE>postRegister</CODE>

     * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws an

     * <CODE>Error</CODE>, the <CODE>createMBean</CODE> method will

     * throw a <CODE>RuntimeErrorException</CODE>, although the MBean creation

     * and registration succeeded. In such a case, the MBean will be actually

     * registered even though the <CODE>createMBean</CODE> method

     * threw an exception.  Note that <CODE>RuntimeErrorException</CODE> can

     * also be thrown by <CODE>preRegister</CODE>, 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</CODE>: The className

     * passed in parameter is null, the <CODE>ObjectName</CODE> passed

     * in parameter contains a pattern or no <CODE>ObjectName</CODE>

     * 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</CODE>, containing the

     * <CODE>ObjectName</CODE> and the Java class name of the newly

     * instantiated MBean.  If the contained <code>ObjectName</code>

     * is <code>n</code>, the contained Java class name is

     * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.

     *

     * @exception ReflectionException Wraps a

     * <CODE>java.lang.ClassNotFoundException</CODE> or a

     * <CODE>java.lang.Exception</CODE> 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</CODE> (<CODE>MBeanRegistration</CODE>

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

     * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws a

     * <CODE>RuntimeException</CODE>, the <CODE>createMBean</CODE> method will

     * throw a <CODE>RuntimeMBeanException</CODE>, although the MBean creation

     * and registration succeeded. In such a case, the MBean will be actually

     * registered even though the <CODE>createMBean</CODE> method

     * threw an exception.  Note that <CODE>RuntimeMBeanException</CODE> can

     * also be thrown by <CODE>preRegister</CODE>, in which case the MBean

     * will not be registered.

     * @exception RuntimeErrorException If the <CODE>postRegister</CODE>

     * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws an

     * <CODE>Error</CODE>, the <CODE>createMBean</CODE> method will

     * throw a <CODE>RuntimeErrorException</CODE>, although the MBean creation

     * and registration succeeded. In such a case, the MBean will be actually

     * registered even though the <CODE>createMBean</CODE> method

     * threw an exception.  Note that <CODE>RuntimeErrorException</CODE> can

     * also be thrown by <CODE>preRegister</CODE>, 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</CODE>: The className

     * passed in parameter is null, the <CODE>ObjectName</CODE> passed

     * in parameter contains a pattern or no <CODE>ObjectName</CODE>

     * 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</CODE>, containing the

     * <CODE>ObjectName</CODE> and the Java class name of the newly

     * instantiated MBean.  If the contained <code>ObjectName</code>

     * is <code>n</code>, the contained Java class name is

     * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.

     *

     * @exception ReflectionException Wraps a

     * <CODE>java.lang.ClassNotFoundException</CODE> or a

     * <CODE>java.lang.Exception</CODE> 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</CODE> (<CODE>MBeanRegistration</CODE>

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

     * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws a

     * <CODE>RuntimeException</CODE>, the <CODE>createMBean</CODE> method will

     * throw a <CODE>RuntimeMBeanException</CODE>, although the MBean creation

     * and registration succeeded. In such a case, the MBean will be actually

     * registered even though the <CODE>createMBean</CODE> method

     * threw an exception.  Note that <CODE>RuntimeMBeanException</CODE> can

     * also be thrown by <CODE>preRegister</CODE>, in which case the MBean

     * will not be registered.

     * @exception RuntimeErrorException If the <CODE>postRegister</CODE> method

     * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws an

     * <CODE>Error</CODE>, the <CODE>createMBean</CODE> method will

     * throw a <CODE>RuntimeErrorException</CODE>, although the MBean creation

     * and registration succeeded. In such a case, the MBean will be actually

     * registered even though the <CODE>createMBean</CODE> method

     * threw an exception.  Note that <CODE>RuntimeErrorException</CODE> can

     * also be thrown by <CODE>preRegister</CODE>, 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</CODE>: The className

     * passed in parameter is null, the <CODE>ObjectName</CODE> passed

     * in parameter contains a pattern or no <CODE>ObjectName</CODE>

     * 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</CODE> interface) method of the MBean

     * has thrown an exception.

     * @exception RuntimeMBeanException If the <CODE>postDeregister</CODE>

     * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws a

     * <CODE>RuntimeException</CODE>, the <CODE>unregisterMBean</CODE> method

     * will throw a <CODE>RuntimeMBeanException</CODE>, although the MBean

     * unregistration succeeded. In such a case, the MBean will be actually

     * unregistered even though the <CODE>unregisterMBean</CODE> method

     * threw an exception.  Note that <CODE>RuntimeMBeanException</CODE> can

     * also be thrown by <CODE>preDeregister</CODE>, in which case the MBean

     * will remain registered.

     * @exception RuntimeErrorException If the <CODE>postDeregister</CODE>

     * (<CODE>MBeanRegistration</CODE> interface) method of the MBean throws an

     * <CODE>Error</CODE>, the <CODE>unregisterMBean</CODE> method will

     * throw a <CODE>RuntimeErrorException</CODE>, although the MBean

     * unregistration succeeded. In such a case, the MBean will be actually

     * unregistered even though the <CODE>unregisterMBean</CODE> method

     * threw an exception.  Note that <CODE>RuntimeMBeanException</CODE> can

     * also be thrown by <CODE>preDeregister</CODE>, in which case the MBean

     * will remain registered.

     * @exception RuntimeOperationsException Wraps a

     * <CODE>java.lang.IllegalArgumentException</CODE>: 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</CODE> for a given MBean

     * registered with the MBean server.

     *

     * @param name The object name of the MBean.

     *

     * @return The <CODE>ObjectInstance</CODE> associated with the MBean

     * specified by <VAR>name</VAR>.  The contained <code>ObjectName</code>

     * is <code>name</code> and the contained class name is

     * <code>{@link #getMBeanInfo getMBeanInfo(name)}.getClassName()</code>.

     *

     * @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</CODE> 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</CODE> objects (containing the

     * <CODE>ObjectName</CODE> 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</CODE>

     * 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</CODE> 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</CODE>: 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