// $Id: Agent.java,v 1.1 2000/05/18 22:00:49 tucker Exp $
// Hive. Copyright (c) 1998-1999, The Massachusetts Institute of Technology.
// All rights reserved. Distributed with no warranty, without even the
// implied warranty of merchantability or fitness for a particular purpose.
// For more details see COPYING.GPL, the GNU General Public License.

package net.hivecell.hive.agent;

import java.awt.event.ActionEvent;
import java.rmi.Remote;
import java.rmi.RemoteException;
import java.util.Vector;

import net.hivecell.hive.cell.RemoteCell;
import net.hivecell.hive.description.Description;
import net.hivecell.hive.description.RemoteDescribable;
import net.hivecell.hive.support.CellAddress;
import net.hivecell.hive.support.SerializableImage;

import org.w3c.dom.Document;

/** 
 * the base remote interface for all agents. methods in this interface
 * and its children are visible over the network. all methods must
 * throw remoteexception.
 *
 * @version $Revision: 1.1 $
 */
public interface Agent 
extends RemoteDescribable { 

    /** 
     * find out which server the agent lives on. 
     *
     * @return the remote server of the agent
     */
    public RemoteCell getCell() 
    throws RemoteException;

    /**
     * return what cell address this agent is on
     *
     * @return the cell address of this agent
     */
    public CellAddress getAddress() 
    throws RemoteException;

    /**
     * see if this agent is ready for business
     *
     * @return true if this agent is ready to go, false otherwise
     */
    public boolean isReady()
    throws RemoteException;

    /**m
     * block if this agent is not yet ready, this method will release
     * the caller when this agent has become ready
     */
    public void blockUntilReady()
    throws RemoteException;

    /** 
     * ask this agent to politely die */
    public void diePlease() 
    throws RemoteException;

    /** 
     * connects this agent to some other agent.  it is up to the agent
     * to define the semantics of what this means.
     *
     * @param otherAgent reference to the agent to connect to
     * @return whether the connection was successful
     */
    public boolean connectTo( Agent otherAgent ) 
    throws RemoteException;

    /** 
     * disconnects this agent from all agents. 
     */
    public void disconnectFromAll() 
    throws RemoteException;

    /** 
     * disconnects this agent from the specified other agent. 
     *
     * @param otherAgent the agent that we are going to disappear from
     */
    public void disconnectFrom( Agent otherAgent ) 
    throws RemoteException;


    /** 
     * ask this agent for all its incoming connections 
     *
     * @return a vector of agents which are all on incoming edges
     */
    public Vector listAllIncomingConnections() 
    throws RemoteException;

    /** 
     * ask this agent for all its outgoing connections 
     *
     * @return a vector of agents which are out outgoing edges
     */
    public Vector listAllOutgoingConnections() 
    throws RemoteException;


    /** 
     * get the semantic description of this agent. 
     *
     * @return the description of the agent
     */
    public Description getDescription() 
    throws RemoteException;

    /** 
     * get the icon for this agent. 
     *
     * @return the serializable image of the agent's icon 
     */
    public SerializableImage getIcon() 
    throws RemoteException;
    
    /** 
     * get a name for this agent. 
     *
     * @return the name that this agent has chosen for itself
     */
    public String getName() 
    throws RemoteException;

    /**
      * Tells the agent to configure itself from the DOM Node doc.
      *
      * @param o the object that asked to configure the agent
      * @param doc The DOM Document (root node)
      */
    public void configure( Object o, Description desc )
    throws RemoteException;

    /**
     * get a list of strings which are the labels for this agent's command menu
     *
     * @return a vector of strings
     */
    public Vector getActionCommands() 
    throws RemoteException;

    /** 
     * ask this agent to invoke a command from the agent's command menu
     *
     * @param com a string representing the command that we wish to have called
     * @return true if the method was called, false otherwise
     */
    public boolean invokeActionCommand( String com ) 
    throws RemoteException;

}