import java.util.Iterator;

/**
 * <p>
 * IAgent is the interface for robotic agents executing a distributed
 * control law.
 * </p>
 * <p>
 * Because of the mixed discrete/continuous state of the system, this
 * interface is designed to be handled by two different state evolution 
 * engines operating at two different time scales.  GetDerivs 
 * (in IControlFunc, part of StateBundle) is intended
 * for use in a numerical ODE solver that handles the continuous-time
 * evolution of the system.  The discrete state ({@link ILogicVarBundle})
 * and the message passing along the communication graph are 
 * handled by a discrete simulator, operating in bursts determined
 * by the scheduler ({@link ICommunicationScheduler}).
 * </p>
 * @author     Michael Schuresko
 * @version    %I%, %G%
 * @since      1.0
 */
public interface IAgent
{
    /**
     * checks that a particular discrete state is valid for this agent
     */
    public boolean checkStateValidity(StateBundle state);

    // Discrete state components

    /**
     * <p> Given the state of an agent, and the channels
     * it can send messages on, push the next set of messages
     * onto the appropriate channels. 
     * Channels are assumed to be modified by this operation.
     * One weakness of this signature is that it requires
     * programmer discipline not to look at the continuous state
     * of agents other then your neighbors.</p>
     * @param discreteState discrete component of agent state
     * @param arrLfStateCont global vector of continuous state
     * @param nIdxStateOffset offset into global state vector 
     * corresonding to this agent.
     * @param channelsToSendOn Iterator containing objects of type
     * CommLink corresponding to channels to send messages
     * on (neighbor indices can be ascertained from channels).
     * @see CommLink for type handled by iterator
     */
    public void getMsgs(ILogicVarBundle discreteState,
    		IDiscreteDynamicsCallback dynCallback,
			double arrLfStateCont[], 
			double lfCurrTime, 
			int nIdxStateOffset,
			Iterator<CommLink> channelsToSendOn);

    /**
     * <p> Given the previous state of an agent, and the channels
     * to recieve messages from, recieve messages (destructively)
     * and return new state (non-destructively). </p>
     * @param statePrev previous state (do not modify)
     * @param arrLfStateCont vector of all continuous states (do not modify)
     * @param nIdxStateOffset offset into arrLfStateCont corresponding to
     * start of this agents continuous variables
     * @param channelsRecieveFrom iterator storing CommLink 
     * classes corresponding incoming channels
     * @see CommLink for type handled by iterator
     * @return new state bundle containing discrete state of agent
     * and new control function
     */
    public StateBundle updateState(ILogicVarBundle statePrev,
				   double arrLfStateCont[], double lfCurrTime,
				   int nIdxStateOffset, IEnvironment env,
				   Iterator<CommLink> channelsRecieveFrom);

    /**
     * in case the agent has some internal state, this 
     * allows synchronized wrapper calls to cache a snapshot of the
     * agent at some rational point in time.
     * If the agent has no internal state, this function can just return
     * "this".
     */
    public IAgent makeCopy();


}