/**
 * JOnAS: Java(TM) Open Application Server
 * Copyright (C) 1999 Bull S.A.
 * Contact: jonas-team@objectweb.org
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or any later version.
 *
 * This library 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
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307
 * USA
 *
 * --------------------------------------------------------------------------
 * $Id$
 * --------------------------------------------------------------------------
 */
package org.objectweb.jonas.jmx;

import java.rmi.Remote;
import java.rmi.RemoteException;

import javax.management.Attribute;
import javax.management.AttributeList;
import javax.management.AttributeNotFoundException;
import javax.management.InstanceNotFoundException;
import javax.management.IntrospectionException;
import javax.management.InvalidAttributeValueException;
import javax.management.MBeanException;
import javax.management.MBeanInfo;
import javax.management.NotificationFilter;
import javax.management.NotificationListener;
import javax.management.ObjectName;
import javax.management.QueryExp;
import javax.management.ReflectionException;

/**
 * Interface for JMX Remote Calls. Only methods used by the management applications are listed here,
 * but potentially we could list all operations from JMXServer.
 *
 * @author Michel Bruno and Guillaume Riviere
 */
public interface RMIConnector extends Remote {

    /**
     * Gets the names of MBeans controlled by the MBean server.
     * @param name - The object name pattern identifying the MBeans to be retrieved.
     * @param query - The query expression to 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.
     */
    public java.util.Set queryNames(ObjectName name,
                    QueryExp query)
    throws RemoteException;

    /**
     * Checks whether an MBean, identified by its object name, is
     * already registered with the MBean server.
     * @param name - The object name pattern identifying the MBeans
     */
    public boolean isRegistered(ObjectName name)
    throws RemoteException;

    /**
     * Gets the value of a specific attribute of a named MBean.
     * @param name - The name of the MBean
     * @param attribute - the name of the attribute to be retrieved.
     * @return The value of the retrieved attribute.
     */
    public java.lang.Object getAttribute(ObjectName name,
                     String attribute)
    throws MBeanException,
           AttributeNotFoundException,
           InstanceNotFoundException,
           ReflectionException,
           RemoteException;

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

    /**
     * Sets the value of a specific attribute of a named MBean.
     * @param name - The name of the MBean
     */
    public void setAttribute(ObjectName name,
                 Attribute attribute)
    throws InstanceNotFoundException,
           AttributeNotFoundException,
           InvalidAttributeValueException,
           MBeanException,
           ReflectionException,
           RemoteException;

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

    /**
     * Invokes an operation on an MBean.
     * @param name - The name of the MBean
     * @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
     * @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.
     * @return The object returned by the operation
     */
    public Object invoke(ObjectName name,
             String operationName,
             Object[] params,
             String[] signature)
    throws InstanceNotFoundException,
           MBeanException,
           ReflectionException,
           RemoteException;

    /**
     * This method discovers the attributes and operations that an MBean
     * exposes for management.
     * @param name - The name of the MBean to analyze
     * @return An instance of MBeanInfo allowing the retrieval of all
     * attributes and operations of this MBean.
     */
    public MBeanInfo getMBeanInfo(ObjectName name)
    throws InstanceNotFoundException,
           IntrospectionException,
           ReflectionException,
           RemoteException;

    /**
     * Adds a listener to a registered MBean.
     * @param name - The name of the MBean on which the listener should be added.
     * @param listener - The listener object which will handle the notifications emitted by the registered MBean.
     * @param listener - The listener object which will handle the notifications emitted by the registered MBean.
     * @param filter - The filter object. If filter is null, no filtering will be performed before handling notifications.
     * @param handback - The context to be sent to the listener when a notification is emitted.
     */
    public void addNotificationListener(ObjectName name,
                                    NotificationListener listener,
                                    NotificationFilter filter,
                                    Object handback)
        throws InstanceNotFoundException,
               RemoteException;

    /**
     * Adds a listener to a registered MBean.
     * @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 listener - The listener object which will handle the notifications emitted by the registered MBean.
     * @param filter - The filter object. If filter is null, no filtering will be performed before handling notifications.
     * @param handback - The context to be sent to the listener when a notification is emitted.
     */
    public void addNotificationListener(ObjectName name,
                                    ObjectName listener,
                                    NotificationFilter filter,
                                    Object handback)
        throws InstanceNotFoundException,
               RemoteException;
}
