/*
 * 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.remote.rmi;

import java.io.Closeable;
import java.io.IOException;
import java.rmi.MarshalledObject;
import java.rmi.Remote;
import java.util.Set;

import javax.management.AttributeList;
import javax.management.AttributeNotFoundException;
import javax.management.InstanceAlreadyExistsException;
import javax.management.InstanceNotFoundException;
import javax.management.IntrospectionException;
import javax.management.InvalidAttributeValueException;
import javax.management.ListenerNotFoundException;
import javax.management.MBeanException;
import javax.management.MBeanInfo;
import javax.management.MBeanRegistrationException;
import javax.management.MBeanServerConnection;
import javax.management.NotCompliantMBeanException;

import javax.management.ObjectInstance;
import javax.management.ObjectName;
import javax.management.ReflectionException;
import javax.management.RuntimeMBeanException;
import javax.management.RuntimeOperationsException;
import javax.management.remote.NotificationResult;
import javax.security.auth.Subject;

/**
 * <p>RMI object used to forward an MBeanServer request from a client
 * to its MBeanServer implementation on the server side.  There is one
 * Remote object implementing this interface for each remote client
 * connected to an RMI connector.</p>
 *
 * <p>User code does not usually refer to this interface.  It is
 * specified as part of the public API so that different
 * implementations of that API will interoperate.</p>
 *
 * <p>To ensure that client parameters will be deserialized at the
 * server side with the correct classloader, client parameters such as
 * parameters used to invoke a method are wrapped in a {@link
 * MarshalledObject}.  An implementation of this interface must first
 * get the appropriate class loader for the operation and its target,
 * then deserialize the marshalled parameters with this classloader.
 * Except as noted, a parameter that is a
 * <code>MarshalledObject</code> or <code>MarshalledObject[]</code>
 * must not be null; the behavior is unspecified if it is.</p>
 *
 * <p>Class loading aspects are detailed in the
 * <a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf">
 * JMX Specification, version 1.4</a> PDF document.</p>
 *
 * <p>Most methods in this interface parallel methods in the {@link
 * MBeanServerConnection} interface.  Where an aspect of the behavior
 * of a method is not specified here, it is the same as in the
 * corresponding <code>MBeanServerConnection</code> method.
 *
 * @since 1.5
 */
/*
 * Notice that we omit the type parameter from MarshalledObject everywhere,
 * even though it would add useful information to the documentation.  The
 * reason is that it was only added in Mustang (Java SE 6), whereas versions
 * 1.4 and 2.0 of the JMX API must be implementable on Tiger per our
 * commitments for JSR 255.  This is also why we suppress rawtypes warnings.
 */
@SuppressWarnings("rawtypes")
public interface RMIConnection extends Closeable, Remote {
    /**
     * <p>Returns the connection ID.  This string is different for
     * every open connection to a given RMI connector server.</p>
     *
     * @return the connection ID
     *
     * @see RMIConnector#connect RMIConnector.connect
     *
     * @throws IOException if a general communication exception occurred.
     */
    public String getConnectionId() throws IOException;

    /**
     * <p>Closes this connection.  On return from this method, the RMI
     * object implementing this interface is unexported, so further
     * remote calls to it will fail.</p>
     *
     * @throws IOException if the connection could not be closed,
     * or the Remote object could not be unexported, or there was a
     * communication failure when transmitting the remote close
     * request.
     */
    public void close() throws IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#createMBean(String,
     * ObjectName)}.
     *
     * @param className The class name of the MBean to be instantiated.
     * @param name The object name of the MBean. May be null.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @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>.
     *
     * @throws 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.
     * @throws InstanceAlreadyExistsException The MBean is already
     * under the control of the MBean server.
     * @throws MBeanRegistrationException The
     * <code>preRegister</code> (<code>MBeanRegistration</code>
     * interface) method of the MBean has thrown an exception. The
     * MBean will not be registered.
     * @throws MBeanException The constructor of the MBean has
     * thrown an exception.
     * @throws NotCompliantMBeanException This class is not a JMX
     * compliant MBean.
     * @throws 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.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     */
    public ObjectInstance createMBean(String className,
                                      ObjectName name,
                                      Subject delegationSubject)
        throws
        ReflectionException,
        InstanceAlreadyExistsException,
        MBeanRegistrationException,
        MBeanException,
        NotCompliantMBeanException,
        IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#createMBean(String,
     * ObjectName, ObjectName)}.
     *
     * @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.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @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>.
     *
     * @throws 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.
     * @throws InstanceAlreadyExistsException The MBean is already
     * under the control of the MBean server.
     * @throws MBeanRegistrationException The
     * <code>preRegister</code> (<code>MBeanRegistration</code>
     * interface) method of the MBean has thrown an exception. The
     * MBean will not be registered.
     * @throws MBeanException The constructor of the MBean has
     * thrown an exception.
     * @throws NotCompliantMBeanException This class is not a JMX
     * compliant MBean.
     * @throws InstanceNotFoundException The specified class loader
     * is not registered in the MBean server.
     * @throws 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.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     */
    public ObjectInstance createMBean(String className,
                                      ObjectName name,
                                      ObjectName loaderName,
                                      Subject delegationSubject)
        throws
        ReflectionException,
        InstanceAlreadyExistsException,
        MBeanRegistrationException,
        MBeanException,
        NotCompliantMBeanException,
        InstanceNotFoundException,
        IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#createMBean(String,
     * ObjectName, Object[], String[])}.  The <code>Object[]</code>
     * parameter is wrapped in a <code>MarshalledObject</code>.
     *
     * @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, encapsulated into a
     * <code>MarshalledObject</code>.  The encapsulated array can be
     * null, equivalent to an empty array.
     * @param signature An array containing the signature of the
     * constructor to be invoked.  Can be null, equivalent to an empty
     * array.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @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>.
     *
     * @throws 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.
     * @throws InstanceAlreadyExistsException The MBean is already
     * under the control of the MBean server.
     * @throws MBeanRegistrationException The
     * <code>preRegister</code> (<code>MBeanRegistration</code>
     * interface) method of the MBean has thrown an exception. The
     * MBean will not be registered.
     * @throws MBeanException The constructor of the MBean has
     * thrown an exception.
     * @throws NotCompliantMBeanException This class is not a JMX
     * compliant MBean.
     * @throws 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.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     */
    public ObjectInstance createMBean(String className,
                                ObjectName name,
                                MarshalledObject params,
                                String signature[],
                                Subject delegationSubject)
        throws
        ReflectionException,
        InstanceAlreadyExistsException,
        MBeanRegistrationException,
        MBeanException,
        NotCompliantMBeanException,
        IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#createMBean(String,
     * ObjectName, ObjectName, Object[], String[])}.  The
     * <code>Object[]</code> parameter is wrapped in a
     * <code>MarshalledObject</code>.
     *
     * @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.
     * @param params An array containing the parameters of the
     * constructor to be invoked, encapsulated into a
     * <code>MarshalledObject</code>.  The encapsulated array can be
     * null, equivalent to an empty array.
     * @param signature An array containing the signature of the
     * constructor to be invoked.  Can be null, equivalent to an empty
     * array.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @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>.
     *
     * @throws 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.
     * @throws InstanceAlreadyExistsException The MBean is already
     * under the control of the MBean server.
     * @throws MBeanRegistrationException The
     * <code>preRegister</code> (<code>MBeanRegistration</code>
     * interface) method of the MBean has thrown an exception. The
     * MBean will not be registered.
     * @throws MBeanException The constructor of the MBean has
     * thrown an exception.
     * @throws NotCompliantMBeanException This class is not a JMX
     * compliant MBean.
     * @throws InstanceNotFoundException The specified class loader
     * is not registered in the MBean server.
     * @throws 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.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     */
    public ObjectInstance createMBean(String className,
                                ObjectName name,
                                ObjectName loaderName,
                                MarshalledObject params,
                                String signature[],
                                Subject delegationSubject)
        throws
        ReflectionException,
        InstanceAlreadyExistsException,
        MBeanRegistrationException,
        MBeanException,
        NotCompliantMBeanException,
        InstanceNotFoundException,
        IOException;

    /**
     * Handles the method
     * {@link javax.management.MBeanServerConnection#unregisterMBean(ObjectName)}.
     *
     * @param name The object name of the MBean to be unregistered.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @throws InstanceNotFoundException The MBean specified is not
     * registered in the MBean server.
     * @throws MBeanRegistrationException The preDeregister
     * ((<code>MBeanRegistration</code> interface) method of the MBean
     * has thrown an exception.
     * @throws 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.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     */
    public void unregisterMBean(ObjectName name, Subject delegationSubject)
        throws
        InstanceNotFoundException,
        MBeanRegistrationException,
        IOException;

    /**
     * Handles the method
     * {@link javax.management.MBeanServerConnection#getObjectInstance(ObjectName)}.
     *
     * @param name The object name of the MBean.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @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>.
     *
     * @throws InstanceNotFoundException The MBean specified is not
     * registered in the MBean server.
     * @throws RuntimeOperationsException Wraps a
     * <code>java.lang.IllegalArgumentException</code>: The object
     * name in parameter is null.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     */
    public ObjectInstance getObjectInstance(ObjectName name,
                                            Subject delegationSubject)
        throws InstanceNotFoundException, IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#queryMBeans(ObjectName,
     * QueryExp)}.  The <code>QueryExp</code> is wrapped in a
     * <code>MarshalledObject</code>.
     *
     * @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, encapsulated into a <code>MarshalledObject</code>. If
     * the <code>MarshalledObject</code> encapsulates a null value no
     * query expression will be applied for selecting MBeans.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @return A set containing the <code>ObjectInstance</code>
     * objects for the selected MBeans.  If no MBean satisfies the
     * query an empty list is returned.
     *
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     */
    public Set<ObjectInstance>
        queryMBeans(ObjectName name,
                    MarshalledObject query,
                    Subject delegationSubject)
        throws IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#queryNames(ObjectName,
     * QueryExp)}.  The <code>QueryExp</code> is wrapped in a
     * <code>MarshalledObject</code>.
     *
     * @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, encapsulated into a <code>MarshalledObject</code>. If
     * the <code>MarshalledObject</code> encapsulates a null value no
     * query expression will be applied for selecting MBeans.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @return A set containing the ObjectNames for the MBeans
     * selected.  If no MBean satisfies the query, an empty list is
     * returned.
     *
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     */
    public Set<ObjectName>
        queryNames(ObjectName name,
                   MarshalledObject query,
                   Subject delegationSubject)
        throws IOException;

    /**
     * Handles the method
     * {@link javax.management.MBeanServerConnection#isRegistered(ObjectName)}.
     *
     * @param name The object name of the MBean to be checked.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @return True if the MBean is already registered in the MBean
     * server, false otherwise.
     *
     * @throws RuntimeOperationsException Wraps a
     * <code>java.lang.IllegalArgumentException</code>: The object
     * name in parameter is null.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     */
    public boolean isRegistered(ObjectName name, Subject delegationSubject)
        throws IOException;

    /**
     * Handles the method
     * {@link javax.management.MBeanServerConnection#getMBeanCount()}.
     *
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @return the number of MBeans registered.
     *
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     */
    public Integer getMBeanCount(Subject delegationSubject)
        throws IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#getAttribute(ObjectName,
     * String)}.
     *
     * @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.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @return  The value of the retrieved attribute.
     *
     * @throws AttributeNotFoundException The attribute specified
     * is not accessible in the MBean.
     * @throws MBeanException Wraps an exception thrown by the
     * MBean's getter.
     * @throws InstanceNotFoundException The MBean specified is not
     * registered in the MBean server.
     * @throws ReflectionException Wraps a
     * <code>java.lang.Exception</code> thrown when trying to invoke
     * the getter.
     * @throws RuntimeOperationsException Wraps a
     * <code>java.lang.IllegalArgumentException</code>: The object
     * name in parameter is null or the attribute in parameter is
     * null.
     * @throws RuntimeMBeanException Wraps a runtime exception thrown
     * by the MBean's getter.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     *
     * @see #setAttribute
     */
    public Object getAttribute(ObjectName name,
                               String attribute,
                               Subject delegationSubject)
        throws
        MBeanException,
        AttributeNotFoundException,
        InstanceNotFoundException,
        ReflectionException,
        IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#getAttributes(ObjectName,
     * String[])}.
     *
     * @param name The object name of the MBean from which the
     * attributes are retrieved.
     * @param attributes A list of the attributes to be retrieved.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @return The list of the retrieved attributes.
     *
     * @throws InstanceNotFoundException The MBean specified is not
     * registered in the MBean server.
     * @throws ReflectionException An exception occurred when
     * trying to invoke the getAttributes method of a Dynamic MBean.
     * @throws RuntimeOperationsException Wrap a
     * <code>java.lang.IllegalArgumentException</code>: The object
     * name in parameter is null or attributes in parameter is null.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     *
     * @see #setAttributes
     */
    public AttributeList getAttributes(ObjectName name,
                                       String[] attributes,
                                       Subject delegationSubject)
        throws
        InstanceNotFoundException,
        ReflectionException,
        IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#setAttribute(ObjectName,
     * Attribute)}.  The <code>Attribute</code> parameter is wrapped
     * in a <code>MarshalledObject</code>.
     *
     * @param name The name of the MBean within which the attribute is
     * to be set.
     * @param attribute The identification of the attribute to be set
     * and the value it is to be set to, encapsulated into a
     * <code>MarshalledObject</code>.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @throws InstanceNotFoundException The MBean specified is not
     * registered in the MBean server.
     * @throws AttributeNotFoundException The attribute specified
     * is not accessible in the MBean.
     * @throws InvalidAttributeValueException The value specified
     * for the attribute is not valid.
     * @throws MBeanException Wraps an exception thrown by the
     * MBean's setter.
     * @throws ReflectionException Wraps a
     * <code>java.lang.Exception</code> thrown when trying to invoke
     * the setter.
     * @throws RuntimeOperationsException Wraps a
     * <code>java.lang.IllegalArgumentException</code>: The object
     * name in parameter is null or the attribute in parameter is
     * null.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     *
     * @see #getAttribute
     */
    public void setAttribute(ObjectName name,
                             MarshalledObject attribute,
                             Subject delegationSubject)
        throws
        InstanceNotFoundException,
        AttributeNotFoundException,
        InvalidAttributeValueException,
        MBeanException,
        ReflectionException,
        IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#setAttributes(ObjectName,
     * AttributeList)}.  The <code>AttributeList</code> parameter is
     * wrapped in a <code>MarshalledObject</code>.
     *
     * @param name The object name of the MBean within which the
     * attributes are to be set.
     * @param attributes A list of attributes: The identification of
     * the attributes to be set and the values they are to be set to,
     * encapsulated into a <code>MarshalledObject</code>.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @return The list of attributes that were set, with their new
     * values.
     *
     * @throws InstanceNotFoundException The MBean specified is not
     * registered in the MBean server.
     * @throws ReflectionException An exception occurred when
     * trying to invoke the getAttributes method of a Dynamic MBean.
     * @throws RuntimeOperationsException Wraps a
     * <code>java.lang.IllegalArgumentException</code>: The object
     * name in parameter is null or attributes in parameter is null.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     *
     * @see #getAttributes
     */
    public AttributeList setAttributes(ObjectName name,
                          MarshalledObject attributes,
                          Subject delegationSubject)
        throws
        InstanceNotFoundException,
        ReflectionException,
        IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#invoke(ObjectName,
     * String, Object[], String[])}.  The <code>Object[]</code>
     * parameter is wrapped in a <code>MarshalledObject</code>.
     *
     * @param name The object name of the MBean on which the method is
     * to be invoked.
     * @param operationName The name of the operation to be invoked.
     * @param params An array containing the parameters to be set when
     * the operation is invoked, encapsulated into a
     * <code>MarshalledObject</code>.  The encapsulated array can be
     * null, equivalent to an empty array.
     * @param signature An array containing the signature of the
     * operation. The class objects will be loaded using the same
     * class loader as the one used for loading the MBean on which the
     * operation was invoked.  Can be null, equivalent to an empty
     * array.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @return The object returned by the operation, which represents
     * the result of invoking the operation on the MBean specified.
     *
     * @throws InstanceNotFoundException The MBean specified is not
     * registered in the MBean server.
     * @throws MBeanException Wraps an exception thrown by the
     * MBean's invoked method.
     * @throws ReflectionException Wraps a
     * <code>java.lang.Exception</code> thrown while trying to invoke
     * the method.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     * @throws RuntimeOperationsException Wraps an {@link
     * IllegalArgumentException} when <code>name</code> or
     * <code>operationName</code> is null.
     */
    public Object invoke(ObjectName name,
                         String operationName,
                         MarshalledObject params,
                         String signature[],
                         Subject delegationSubject)
        throws
        InstanceNotFoundException,
        MBeanException,
        ReflectionException,
        IOException;

    /**
     * Handles the method
     * {@link javax.management.MBeanServerConnection#getDefaultDomain()}.
     *
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @return the default domain.
     *
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     */
    public String getDefaultDomain(Subject delegationSubject)
        throws IOException;

    /**
     * Handles the method
     * {@link javax.management.MBeanServerConnection#getDomains()}.
     *
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @return the list of domains.
     *
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     */
    public String[] getDomains(Subject delegationSubject)
        throws IOException;

    /**
     * Handles the method
     * {@link javax.management.MBeanServerConnection#getMBeanInfo(ObjectName)}.
     *
     * @param name The name of the MBean to analyze
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @return An instance of <code>MBeanInfo</code> allowing the
     * retrieval of all attributes and operations of this MBean.
     *
     * @throws IntrospectionException An exception occurred during
     * introspection.
     * @throws InstanceNotFoundException The MBean specified was
     * not found.
     * @throws ReflectionException An exception occurred when
     * trying to invoke the getMBeanInfo of a Dynamic MBean.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     * @throws RuntimeOperationsException Wraps a
     * <code>java.lang.IllegalArgumentException</code>: The object
     * name in parameter is null.
     */
    public MBeanInfo getMBeanInfo(ObjectName name, Subject delegationSubject)
        throws
        InstanceNotFoundException,
        IntrospectionException,
        ReflectionException,
        IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#isInstanceOf(ObjectName,
     * String)}.
     *
     * @param name The <code>ObjectName</code> of the MBean.
     * @param className The name of the class.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @return true if the MBean specified is an instance of the
     * specified class according to the rules above, false otherwise.
     *
     * @throws InstanceNotFoundException The MBean specified is not
     * registered in the MBean server.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     * @throws RuntimeOperationsException Wraps a
     * <code>java.lang.IllegalArgumentException</code>: The object
     * name in parameter is null.
     */
    public boolean isInstanceOf(ObjectName name,
                                String className,
                                Subject delegationSubject)
        throws InstanceNotFoundException, IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#addNotificationListener(ObjectName,
     * ObjectName, NotificationFilter, Object)}.  The
     * <code>NotificationFilter</code> parameter is wrapped in a
     * <code>MarshalledObject</code>.  The <code>Object</code>
     * (handback) parameter is also wrapped in a
     * <code>MarshalledObject</code>.
     *
     * @param name The name of the MBean on which the listener should
     * be added.
     * @param listener The object name of the listener which will
     * handle the notifications emitted by the registered MBean.
     * @param filter The filter object, encapsulated into a
     * <code>MarshalledObject</code>. If filter encapsulated in the
     * <code>MarshalledObject</code> has a null value, no filtering
     * will be performed before handling notifications.
     * @param handback The context to be sent to the listener when a
     * notification is emitted, encapsulated into a
     * <code>MarshalledObject</code>.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @throws InstanceNotFoundException The MBean name of the
     * notification listener or of the notification broadcaster does
     * not match any of the registered MBeans.
     * @throws RuntimeOperationsException Wraps an {@link
     * IllegalArgumentException}.  The MBean named by
     * <code>listener</code> exists but does not implement the
     * {@link javax.management.NotificationListener} interface,
     * or <code>name</code> or <code>listener</code> is null.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     *
     * @see #removeNotificationListener(ObjectName, ObjectName, Subject)
     * @see #removeNotificationListener(ObjectName, ObjectName,
     * MarshalledObject, MarshalledObject, Subject)
     */
    public void addNotificationListener(ObjectName name,
                        ObjectName listener,
                        MarshalledObject filter,
                        MarshalledObject handback,
                        Subject delegationSubject)
        throws InstanceNotFoundException, IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,
     * ObjectName)}.
     *
     * @param name The name of the MBean on which the listener should
     * be removed.
     * @param listener The object name of the listener to be removed.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @throws InstanceNotFoundException The MBean name provided
     * does not match any of the registered MBeans.
     * @throws ListenerNotFoundException The listener is not
     * registered in the MBean.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     * @throws RuntimeOperationsException Wraps an {@link
     * IllegalArgumentException} when <code>name</code> or
     * <code>listener</code> is null.
     *
     * @see #addNotificationListener
     */
    public void removeNotificationListener(ObjectName name,
                                           ObjectName listener,
                                           Subject delegationSubject)
        throws
        InstanceNotFoundException,
        ListenerNotFoundException,
        IOException;

    /**
     * Handles the method {@link
     * javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,
     * ObjectName, NotificationFilter, Object)}.  The
     * <code>NotificationFilter</code> parameter is wrapped in a
     * <code>MarshalledObject</code>.  The <code>Object</code>
     * parameter is also wrapped in a <code>MarshalledObject</code>.
     *
     * @param name The name of the MBean on which the listener should
     * be removed.
     * @param listener A listener that was previously added to this
     * MBean.
     * @param filter The filter that was specified when the listener
     * was added, encapsulated into a <code>MarshalledObject</code>.
     * @param handback The handback that was specified when the
     * listener was added, encapsulated into a <code>MarshalledObject</code>.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @throws InstanceNotFoundException The MBean name provided
     * does not match any of the registered MBeans.
     * @throws ListenerNotFoundException The listener is not
     * registered in the MBean, or it is not registered with the given
     * filter and handback.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to perform this operation.
     * @throws IOException if a general communication exception occurred.
     * @throws RuntimeOperationsException Wraps an {@link
     * IllegalArgumentException} when <code>name</code> or
     * <code>listener</code> is null.
     *
     * @see #addNotificationListener
     */
    public void removeNotificationListener(ObjectName name,
                      ObjectName listener,
                      MarshalledObject filter,
                      MarshalledObject handback,
                      Subject delegationSubject)
        throws
        InstanceNotFoundException,
        ListenerNotFoundException,
        IOException;

    // Special Handling of Notifications -------------------------------------

    /**
     * <p>Handles the method {@link
     * javax.management.MBeanServerConnection#addNotificationListener(ObjectName,
     * NotificationListener, NotificationFilter, Object)}.</p>
     *
     * <p>Register for notifications from the given MBeans that match
     * the given filters.  The remote client can subsequently retrieve
     * the notifications using the {@link #fetchNotifications
     * fetchNotifications} method.</p>
     *
     * <p>For each listener, the original
     * <code>NotificationListener</code> and <code>handback</code> are
     * kept on the client side; in order for the client to be able to
     * identify them, the server generates and returns a unique
     * <code>listenerID</code>.  This <code>listenerID</code> is
     * forwarded with the <code>Notifications</code> to the remote
     * client.</p>
     *
     * <p>If any one of the given (name, filter) pairs cannot be
     * registered, then the operation fails with an exception, and no
     * names or filters are registered.</p>
     *
     * @param names the <code>ObjectNames</code> identifying the
     * MBeans emitting the Notifications.
     * @param filters an array of marshalled representations of the
     * <code>NotificationFilters</code>.  Elements of this array can
     * be null.
     * @param delegationSubjects the <code>Subjects</code> on behalf
     * of which the listeners are being added.  Elements of this array
     * can be null.  Also, the <code>delegationSubjects</code>
     * parameter itself can be null, which is equivalent to an array
     * of null values with the same size as the <code>names</code> and
     * <code>filters</code> arrays.
     *
     * @return an array of <code>listenerIDs</code> identifying the
     * local listeners.  This array has the same number of elements as
     * the parameters.
     *
     * @throws IllegalArgumentException if <code>names</code> or
     * <code>filters</code> is null, or if <code>names</code> contains
     * a null element, or if the three arrays do not all have the same
     * size.
     * @throws ClassCastException if one of the elements of
     * <code>filters</code> unmarshalls as a non-null object that is
     * not a <code>NotificationFilter</code>.
     * @throws InstanceNotFoundException if one of the
     * <code>names</code> does not correspond to any registered MBean.
     * @throws SecurityException if, for one of the MBeans, the
     * client, or the delegated Subject if any, does not have
     * permission to add a listener.
     * @throws IOException if a general communication exception occurred.
     */
    public Integer[] addNotificationListeners(ObjectName[] names,
                    MarshalledObject[] filters,
                    Subject[] delegationSubjects)
        throws InstanceNotFoundException, IOException;

    /**
     * <p>Handles the
     * {@link javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,NotificationListener)
     * removeNotificationListener(ObjectName, NotificationListener)} and
     * {@link javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,NotificationListener,NotificationFilter,Object)
     * removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)} methods.</p>
     *
     * <p>This method removes one or more
     * <code>NotificationListener</code>s from a given MBean in the
     * MBean server.</p>
     *
     * <p>The <code>NotificationListeners</code> are identified by the
     * IDs which were returned by the {@link
     * #addNotificationListeners(ObjectName[], MarshalledObject[],
     * Subject[])} method.</p>
     *
     * @param name the <code>ObjectName</code> identifying the MBean
     * emitting the Notifications.
     * @param listenerIDs the list of the IDs corresponding to the
     * listeners to remove.
     * @param delegationSubject The <code>Subject</code> containing the
     * delegation principals or <code>null</code> if the authentication
     * principal is used instead.
     *
     * @throws InstanceNotFoundException if the given
     * <code>name</code> does not correspond to any registered MBean.
     * @throws ListenerNotFoundException if one of the listeners was
     * not found on the server side.  This exception can happen if the
     * MBean discarded a listener for some reason other than a call to
     * <code>MBeanServer.removeNotificationListener</code>.
     * @throws SecurityException if the client, or the delegated Subject
     * if any, does not have permission to remove the listeners.
     * @throws IOException if a general communication exception occurred.
     * @throws IllegalArgumentException if <code>ObjectName</code> or
     * <code>listenerIds</code> is null or if <code>listenerIds</code>
     * contains a null element.
     */
    public void removeNotificationListeners(ObjectName name,
                                            Integer[] listenerIDs,
                                            Subject delegationSubject)
        throws
        InstanceNotFoundException,
        ListenerNotFoundException,
        IOException;

    /**
     * <p>Retrieves notifications from the connector server.  This
     * method can block until there is at least one notification or
     * until the specified timeout is reached.  The method can also
     * return at any time with zero notifications.</p>
     *
     * <p>A notification can be included in the result if its sequence
     * number is no less than <code>clientSequenceNumber</code> and
     * this client has registered at least one listener for the MBean
     * generating the notification, with a filter that accepts the
     * notification.  Each listener that is interested in the
     * notification is identified by an Integer ID that was returned
     * by {@link #addNotificationListeners(ObjectName[],
     * MarshalledObject[], Subject[])}.</p>
     *
     * @param clientSequenceNumber the first sequence number that the
     * client is interested in.  If negative, it is interpreted as
     * meaning the sequence number that the next notification will
     * have.
     *
     * @param maxNotifications the maximum number of different
     * notifications to return.  The <code>TargetedNotification</code>
     * array in the returned <code>NotificationResult</code> can have
     * more elements than this if the same notification appears more
     * than once.  The behavior is unspecified if this parameter is
     * negative.
     *
     * @param timeout the maximum time in milliseconds to wait for a
     * notification to arrive.  This can be 0 to indicate that the
     * method should not wait if there are no notifications, but
     * should return at once.  It can be <code>Long.MAX_VALUE</code>
     * to indicate that there is no timeout.  The behavior is
     * unspecified if this parameter is negative.
     *
     * @return A <code>NotificationResult</code>.
     *
     * @throws IOException if a general communication exception occurred.
     */
    public NotificationResult fetchNotifications(long clientSequenceNumber,
                                                 int maxNotifications,
                                                 long timeout)
            throws IOException;
}