/*

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