/*********************************************************************/
/*                                                                   */
/*                     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.Collections.Generic;
using System.Text;
using AgentService.Interop;
using AgentService.Agent.Runtime;
using AgentService.Agent;
using AgentService.Platform.MTS;

namespace AgentService.Platform.AMS
{
    /// <summary>
    /// Interface IAMS. Exposes themethods that are used 
    /// to interact with IAMS from within the classes that
    /// constitute the runtime.
    /// </summary>
    public interface IAMS
    {
        # region Members

        /// <summary>
        /// Gets a copy of the collection of agents registered with the ams
        /// </summary>
        AgentDescriptionCollection RegisteredAgents
        {
            get;
        }

        /// <summary>
        /// Gets the White Pages service.
        /// </summary>
        IWhitePagesServer WhitePages
        {
            get;
        }

        # endregion

        # region Manage Agent SetUp and Registration

        /// <summary>
        /// Initites and register the created agent with the AMS.
        /// </summary>
        /// <param name="agent">Agent.</param>
        /// <param name="configFile">the configfile of the Agent</param>
        /// <param name="param">List of value to inizialize Agent's attribute</param>
        /// <param name="bPersist">persistence flag</param>
        /// <param name="bDomain">domain flag</param>
        /// <param name="domainName"></param>
        void Register(AgentService.Agent.IAgent agent, string configFile, bool bPersist);

        /// <summary>
        /// Starts agent activity
        /// </summary>
        /// <param name="aid">agent identifier to be started</param>
        void Activate(AID aid);

        /// <summary>
        /// Starts the activity of all the registered agents
        /// </summary>
        void ActivateAll();

        /// <summary>
        /// Puts the agent in the previous persisted state.
        /// </summary>
        /// <param name="agent">Agent.</param>
        void Resume(AgentService.Agent.IAgent agent);


        /// <summary>
        /// Deregister a specific Agent. Deregistration
        /// implies the removal of the agent object from 
        /// the collection of managed agents
        /// </summary>
        /// <param name="aid">The Agent's AID</param>
        bool Deregister(AID aid, bool bDestroy);


        # endregion

        #region Override

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


        #endregion

        # region Manage Agent State

        /// <summary>
        /// Put Agent in active state after transition
        /// </summary>
        /// <param name="agent">The persisted version of the agent</param>
        void Execute(AID aid);

        // MOD: 21/07/2006 Simone Belotti: changed the Move method to support timeout value
        /// <summary>
        /// Put Agent in the transit state before its migration
        /// </summary>
        /// <param name="aid">The Agent's AID</param>
        /// <param name="destination">The name of the destination platform</param>
        /// <param name="isSystemRequest">Flag that indicates if the request to move
        ///								  the agent was originated by the platform
        ///								  (i.e. load balancing motivation), or it 
        ///								  was originated by the agent itself</param>
        void Move(AID aid, string destination, TimeSpan timeout, bool bIsSystemRequest);

        /// <summary>
        /// Put the Agent in the active state after its suspention
        /// </summary>
        /// <param name="aid">The Agent's AID</param>
        /// <returns>true if operation succeds</returns>
        bool ResumeAgent(AID aid);

        /// <summary>
        /// Puts Agent in the suspended state
        /// </summary>
        /// <param name="aid">The Agent's AID</param>
        /// <returns>true if operation succeds</returns>
        bool Suspend(AID aid);

        /// <summary>
        /// Suspends all the active agents
        /// </summary>
        void SuspendAll();

        /// <summary>
        /// Stops the agent activity
        /// </summary>
        /// <param name="aid">agent identifier</param>
        /// <returns></returns>
        bool StopAgent(AID aid);

        /// <summary>
        /// Kill the Agent putting it in the unknown state
        /// </summary>
        /// <param name="aid">the Agent's AID</param>
        /// <returns>true if operation succeds</returns>
        bool Destroy(AID aid);

        /// <summary>
        /// Kill all agents putting it in the unknown state
        /// </summary>
        void DestroyAll();
        /// <summary>
        /// Puts Agent in the active state from the waiting state
        /// </summary>
        /// <param name="aid">The Agent's AID</param>
        /// <returns>True if operation succeds</returns>
        bool WakeUp(AID aid);

        /// <summary>
        /// Put Agent in the active state from the waiting state
        /// </summary>
        void WakeUpAll();

        # endregion

        #region CallBacks
        /// <summary>
        /// Handler of messages directed to the AMS
        /// </summary>
        /// <param name="msg"></param>
        void DispatchMessage(AgentMessage msg);

        /// <summary>
        /// Delegate: invoked when the agentTransferred event is raised. It 
        /// creates the received agent and resumes from the persisted version. The
        /// agent is added in the agentsToExecute list. It sends
        /// a message to the remote AMS to inform it of completion of the operation,
        /// either it is succesfull or not.
        /// </summary>
        /// <param name="persistedAgent">Received persisted version of the agent</param>
        /// <param name="ticket">Ticket owned by the transferred agent. Parameter for an internal check</param>
        void ResumeAgentTransferred(AgentPersistent persistedAgent, int ticket);

        #endregion
    }
}