/*********************************************************************/
/*                                                                   */
/*                     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 AgentService.Platform.AMS;
using AgentService.Platform.DF;
using AgentService.Platform.MTS;
using AgentService.Interop;

namespace AgentService.Platform
{
	/// <summary>
	/// Interface IServiceController. Procvides access to
	/// the services of the platform. In particular, exposes
	/// the services provided through the AMS and the DF like
	/// white and yellow pages.
	/// </summary>
	public interface IServiceController
	{

		#region AMS Commands
		/// <summary>
		/// Returns all the agents registered with the platform
		/// </summary>
		/// <returns></returns>
		AID[] GetRegisteredAgents();

		/// <summary>
		/// Creates an agent with the given name and configuration file by using the specified template with
		/// </summary>
		/// <param name="name">name of the agent</param>
		/// <param name="type">full name of the AgentTemplate derived class that defines the agent</param>
		/// <param name="config">configuration file</param>
		/// <param name="bPersist">true, if the agent need to be created as persistent</param>
		/// <returns>AID of the newly created agent</returns>		
		AID CreateAgent(string type, string name, string config, bool bPersist);
        //MOD : 19/05/2006 : Marco Garr : Add CreateAgent override
        /// <summary>
        /// Creates an agent with the given name and configuration file by using the specified template with
        /// </summary>
        /// <param name="name">name of the agent</param>
        /// <param name="type">full name of the AgentTemplate derived class that defines the agent</param>
        /// <param name="config">configuration file</param>
        /// <param name="bPersist">true, if the agent need to be created as persistent</param>
        /// <param name="bDomain">true, if the agent will be created in an Application Domain</param>
        /// <returns>AID of the newly created agent</returns>		
        AID CreateAgent(string type, string name, string config, bool bPersist, bool bDomain);
        /// <summary>
        /// Creates an agent with the given name and configuration file by using the specified template with
        /// </summary>
        /// <param name="name">name of the agent</param>
        /// <param name="type">full name of the AgentTemplate derived class that defines the agent</param>
        /// <param name="config">configuration file</param>
        /// <param name="bPersist">true, if the agent need to be created as persistent</param>
        /// <param name="domainName">name of the Application Domain in which Agent will be created</param>
        /// <returns>AID of the newly created agent</returns>		
        AID CreateAgent(string type, string name, string config, bool bPersist, string domainName);
        //ENDMOD
		/// <summary>
		/// Activates the given list of agents
		/// </summary>
		/// <param name="aids">list of aids identifying the agents that need to be activated</param>
		void ActivateAgent(params AID[] aids);
		/// <summary>
		/// Activates the given list of agents
		/// </summary>
		/// <param name="aids">list of aids identifying the agents that need to be activated</param>
		void ActivateAllAgents();
		/// <summary>
		/// Wait for all the termination of all the active agent
		/// </summary>
		void WaitForAllAgents();
		/// <summary>
		/// Terminate the given list of agents
		/// </summary>
		/// <param name="aid">agent that will be terminated</param>
		/// <returns>True if the agent kill process succeds</returns>
		bool KillAgent(params AID[] aids);
		/// <summary>
		/// Terminate all the agents running into AgentService platform
		/// </summary>
		void KillEmAll();
		/// <summary>
		/// Suspends the given list of agents
		/// </summary>
		/// <param name="aids">list of agents that will be suspended</param>
		/// <returns>true if operation succeds</returns>
		bool SuspendAgent(params AID[] aids);
		/// <summary>
		/// Suspends all the agents
		/// </summary>
		void SuspendAllAgents();
		/// <summary>
		/// Wakes up the given list of agents
		/// </summary>
		/// <param name="aids">list of agents that will be suspended</param>
		bool WakeUpAgent(params AID[] aids);
		/// <summary>
		/// Wakes up all the suspended agents
		/// </summary>
		void WakeUpAllAgents();

		/// <summary>
		/// Retrieves the description of an agent.
		/// </summary>
		/// <param name="aid">agent identifier</param>
		/// <returns>description of the agent</returns>
		AgentDescription GetAgentDescription(AID aid);
		/// <summary>
		/// Searches for agents that partially matches the pattern.
		/// </summary>
		/// <param name="pattern">search pattern</param>
		/// <returns>array of containing all the description of agents 
		/// corresponding to the search pattern</returns>
		AgentDescription[] SearchAgent(string pattern);
		/// <summary>
		/// Searches for an agent that exactly matches the given name.
		/// </summary>
		/// <param name="name">agent name</param>
		/// <returns>description of the corresponding agent if found, null otherwise</returns>
		AgentDescription SearchExactAgent(string name);
		#endregion

		#region DF Commands
		/// <summary>
		/// Searches for an agent that offers the given service.
		/// </summary>
		/// <param name="sd">service description</param>
		/// <returns>array of agent services description</returns>
		DFAgentDescription[] SearchAgent(ServiceDescription sd);
		/// <summary>
		/// Searches for an agent that offers the given service.
		/// </summary>
		/// <param name="sd">service description</param>
		/// <param name="constraint">search contstraint</param>
		/// <returns>array of agent services description</returns>
		DFAgentDescription[] SearchAgent(ServiceDescription sd, SearchConstraints constraint);
		/// <summary>
		/// Registers an agent with a given description.
		/// </summary>
		/// <param name="description">agent services description</param>
		void Register(DFAgentDescription description);
		/// <summary>
		/// Edits an existing agent description.
		/// </summary>
		/// <param name="description">agent services description</param>
		void Edit(DFAgentDescription description);
		/// <summary>
		/// Deregisters an agent corresponding to the given AID.
		/// </summary>
		/// <param name="aid">agent identifier</param>
		void Deregister(AID aid);
		#endregion

        #region Messaging
        /// <summary>
        /// Gets a client for managing a message queue associated to the batch process
        /// </summary>
        /// <param name="clientId">Name of the batch the message queue belongs to</param>
        /// <returns>messaging client</returns>
        IMsgService GetMsgClient(string clientId);
        /// <summary>
        /// Gets a collection of filtered messages
        /// </summary>
        /// <param name="aid">aid of the agent</param>
        /// <param name="filter">filter criteria</param>
        /// <returns>list of filtered messages</returns>
        AgentMessageCollection FilterMessage(AID aid, MessageFilter filter);
        /// <summary>
        /// Clears all the messages in the storage.
        /// </summary>		
        void ClearAllMessages();
        /// <summary>
        /// Clears all the messages in the storage for a given agent.
        /// </summary>
        /// <param name="aid">AID identifing the agent</param>
        /// <returns>true, if the process is successful</returns>
        bool ClearAllMessages(AID aid);
        #endregion


	}
}