/*********************************************************************/
/*                                                                   */
/*                     AgentService Framework                        */
/*                       www.agentservice.it                         */
/*                                                                   */
/* Copyright (C) 2007 l.i.d.o. - DIST, University of Genoa, Italy    */
/* GNU Lesser General Public License                                 */
/*                                                                   */
/* 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,             */
/* version 2.1 of the License.                                       */
/*                                                                   */
/* 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.                                      */
/*                                                                   */
/*********************************************************************/
using System;
using System.Reflection;

using AgentService.Platform;
using AgentService.Platform.DF;
using AgentService.Platform.AMS;
using AgentService.Platform.MTS;
using AgentService.Platform.Modules;

using AgentService.Agent.Behaviour;
using AgentService.Agent.Knowledge;
using AgentService.Agent.Runtime;

// using AgentService.Interop;

namespace AgentService.Agent
{
    /// <summary>
    //// Interface IAgent. Defines the internal interface
    /// used by the AMS and the platform instance to access
    /// to software agent data. The IAgent interface exposes
    /// all the API required to control a software agent
    /// instance.
    /// </summary>
    public interface IAgent
    {

        # region Members


        #region Agent Events
        /// <summary>
        /// Thrown when the agent is activated.
        /// </summary>
        event AgentDelegate OnActivateAgent;

        /// <summary>
        /// Fires every time an agent has terminated
        /// its activity either because it has been 
        /// stopped by the platform or because it has
        /// terminated.
        /// </summary>
        event AgentDelegate OnReleaseAgent;

        /// <summary>
        /// thrown when the agent is stopped
        /// </summary>
        event AgentDelegate OnStopAgent;

        /// <summary>
        /// thrown when the agent temrminates its execution
        /// </summary>
        event AgentDelegate OnTerminateAgent;

        event PersistAgentDelegate OnPersistAgent;

        #endregion

        #region Behaviour related events

        /// <summary>
        /// Fires every time a new behaviour is created.
        /// </summary>
        event BehaviourDelegate OnNewBehaviour;
        /// <summary>
        /// Fires every time a behaviour is started.
        /// </summary>
        event BehaviourDelegate OnStartBehaviour;
        /// <summary>
        /// Fires every time a behaviour is terminated.
        /// </summary>
        event BehaviourDelegate OnTerminateBehaviour;
        /// <summary>
        /// Fires every time a behaviour is suspended.
        /// </summary>
        event BehaviourDelegate OnSuspendBehaviour;
        /// <summary>
        /// Fires every time a behaviour is woken up.
        /// </summary>
        event BehaviourDelegate OnWakeUpBehaviour;
        #endregion

        /// <summary>
        /// Unique Agent-IDentifier. 
        /// </summary>
        AID AID
        {
            get;
            set;
        }

        /// <summary>
        /// Life cycle state of the Agent.
        AgentState State
        {
            get;
            set;
        }


        /// <summary>
        /// Persistence flag.
        /// </summary>
        bool IsPersistent
        {
            get;
        }

        AgentPersistent Persistent
        {
            get;
            set;
        }

        /// <summary>
        /// Collection of KnowledgeManager objects.
        /// </summary>
        AgentService.Agent.Knowledge.KnowledgeCollection Knowledges
        {
            get;
        }

        /// <summary>
        /// Collection of Behaviour objects belonging to the Agent.
        /// </summary>		
        AgentService.Agent.Behaviour.BehaviourCollection Behaviours
        {
            get;
        }

        /// <summary>
        /// Collection of Knowledge type objects handled by the agent.
        /// </summary>
        TypeDescriptorCollection KnowledgeTypes
        {
            get;
        }
        /// <summary>
        /// Collection of Behaviour type objects handled by the agent.
        /// </summary>
        TypeDescriptorCollection BehaviourTypes
        {
            get;
        }

        /// <summary>
        /// Profile of the agent
        /// </summary>
        AgentProfile Profile
        {
            get;
        }

        /// <summary>
        /// Name of agent's config file
        /// </summary>
        string ConfigFileName
        {
            get;
        }

        #endregion

        # region Agent Activity

        /// <summary>
        /// Initialize the internal Agent's data structures.
        /// </summary>
        /// <param name="configFile">configuration file for agent initialization including the full path</param>
        void Initiate(string configFile);

        /// <summary>
        /// Starts the agent activity.
        /// </summary>
        void Activate();

        /// <summary>
        /// Assigns an AgentTemplate to the Agent and gives him an AID.
        /// </summary>
        /// <param name="fullTemplateName">full template name of the corresponding AgentTemplate subtype</param>
        /// <param name="assemblyName">name of the containing assembly of the AgentTemplate subtype</param>
        void SetTemplate(AgentTemplate template);

        /// <summary>
        /// Commits the agent migration process
        /// </summary>
        /// <param name="bIsSourceInstance">flag used to distinguish the source
        ///									and the target platform</param>
        void CommitMove(bool bIsSourceInstance);

        # endregion

        # region Manage Platform Services

        /// <summary>
        /// Binds the agent to the runtime environemt of the platform.
        /// </summary>
        /// <param name="runtime">gives access to the runtime services of the platform</param>
        void Bind(AgentService.Agent.Runtime.IRuntimeEx runtime);

        /// <summary>
        /// Loads agent data from its persisted version.
        /// </summary>
        /// <param name="agentPersistent">persisted version of the agent</param>
        void ResumeFrom(AgentPersistent agentPersistent);

        /// <summary>
        /// Creates the persistent version of the agent.
        /// </summary>
        /// <returns>persisted version of the agent</returns>
        AgentPersistent GetPersistent();


        #endregion

        #region Manage Agent Behaviours

        /// <summary>
        /// Adds a new behaviour to the agent and starts it.
        /// </summary>
        /// <param name="behaviour">The Behaviour to be added to the Agent</param>
        /// <param name="bStart">if true starts the behaviour</param>
        void SubmitBehaviour(Behaviour.Behaviour behaviour, bool bStart);

        /// <summary>
        /// Suspends a behaviour instance.
        /// </summary>
        /// <param name="behaviour">behaviour instances that will be suspended</param>
        void SuspendBehaviour(AgentService.Agent.Behaviour.Behaviour behaviour);

        /// <summary>
        /// Suspends all the behaviour instances.
        /// </summary> 
        void SuspendAllBehaviours();

        /// <summary>
        /// Resumes a suspended behaviour instance.
        /// </summary>
        /// <param name="behaviour">suspended behaviour instance that will be resumed</param>
        void WakeUpBehaviour(AgentService.Agent.Behaviour.Behaviour behaviour);

        /// <summary>
        /// Resumes all suspended behaviour instances.
        /// </summary>
        void WakeUpAllBehaviours();

        /// <summary>
        /// Removes a behaviour instance.
        /// </summary>
        /// <param name="behaviour">behaviour instance that will be removed</param>
        void RemoveBehaviour(AgentService.Agent.Behaviour.Behaviour behaviour);
        /// <summary>
        /// Removes all behaviours instances.
        /// </summary> 
        void RemoveAllBehaviours();

        /// <summary>
        /// Starts a collection of behaviours instances.
        /// </summary>
        /// <param name="behaviourNames">list of behaviour instances names that will be started</param>
        void StartBehaviours(params string[] behaviourNames);

        /// <summary>
        /// Starts all the behaviour instances previously added.
        /// </summary>  
        void StartAllBehaviours();

        /// <summary>
        /// Kills all the threads belonging to the agent.
        /// </summary>
        void Stop();
       	/// <summary>
		/// Kills all the threads belonging to the agent.
		/// </summary>
        /// <param name="bAbort">stop reason, if true the agent terminated abnormally</param>
        void Stop(bool bAbort);

        # endregion

        # region Manage Agent Knowledges

        /// <summary>
        /// Locks a knowledge instance to be used by a behaviour instance.
        /// </summary>
        /// <param name="lockingBehaviour">behaviour instance that wants to use the knowledge instances</param>
        /// <param name="myKnowledgeList">list of knowledge instancess to be locked</param>
        void LockKnowledge(AgentService.Agent.Behaviour.Behaviour lockingBehaviour, params Knowledge.Knowledge[] myKnowledgeList);

        /// <summary>
        /// Persists the changes for a given Knowledge's item.
        /// </summary>
        ///<param name="sender">knowledge object which fired the update event</param>
        void PersistChanges(object sender);

        /// <summary>
        /// Releases the knowledge instances previously locked by a behaviour instance.
        /// </summary>
        /// <param name="releaseBehaviour">behaviour instance that releases the Knowledge</param>
        void ReleaseKnowledge(AgentService.Agent.Behaviour.Behaviour releaseBehaviour);

        # endregion
    }
}