//  Copyright (C) 2007-2010  CEA/DEN, EDF R&D, OPEN CASCADE
//
//  Copyright (C) 2003-2007  OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN,
//  CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS
//
//  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; either
//  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
//
//  See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
//

#ifndef _SALOME_CONTAINERMANAGER_IDL_
#define _SALOME_CONTAINERMANAGER_IDL_

#include "SALOME_Exception.idl"
#include "SALOME_Component.idl"

/*! \file SALOME_ContainerManager.idl \brief interfaces for %SALOME launcher and container manager
*/

module Engines
{

//!  Type to transmit list of resources.
typedef sequence<string> ResourceList;
//! components list
typedef sequence<string> CompoList;
//! files list
typedef sequence<string> FilesList;
//! modules list
typedef sequence<string> ModulesList;

//! A generic parameter
struct Parameter
{
  string name;
  string value;
};
//! Generic parameter list
typedef sequence<Engines::Parameter> ParameterList;

//! Type to describe required properties of a resource
struct ResourceParameters
{
  //! resource name - manual selection
  string name;
  //! host name
  string hostname;
  //! if given required operating system 
  string OS;
  //! if given list of components that could be loaded on a container
  //! Optional if no resource are found with this constraint
  CompoList componentList;

  // Permits to order resources
  //! required number of proc
  long nb_proc;
  //! required memory size
  long mem_mb;
  //! required frequency
  long cpu_clock;
  //! required number of node
  long nb_node;
  //! required number of proc per node
  long nb_proc_per_node;

  // Permits to configure SALOME resource management
  //! resource management policy : first, cycl, altcycl or best (can be extended)
  string policy;
  //! restricted list of resources to search in
  ResourceList resList;
};

//! Type to describe required properties of a container
struct ContainerParameters
{
  //! container name if given else automatic
  string container_name;

  //! creation mode for GiveContainer if given else automatic 
  /*!start creates a new container
   * get  try to find an existing container
   * getorstart   use an existing container if it exists or creates a new one
   */
  string mode;

  //! container working directory if given else automatic
  string workingdir;

  // Parallel part
  //! Number of proc of a parallel container
  long nb_proc;
  //! if true start a MPI container
  boolean isMPI;
  //! PaCO specific informations
  string parallelLib;

  //! Parameters to choose a resource
  ResourceParameters resource_params;
};

//!  Type to describe a resource
struct ResourceDefinition
{
  //! name 
  string name;
  //! hostname 
  string hostname;
  //! protocol to connect to the resource
  //! protocol used to start a remote container (ssh or rsh)
  string protocol;
  //! login name to use to start a remote container
  string username;
  //! salome application to use to start a remote container
  string applipath;
  //! list of available components 
  CompoList componentList;
  //! Type of resource: interactive or batch
  string mode;

  //! operating system 
  string OS;
  //! memory size per node
  long mem_mb;
  //! frequency
  long cpu_clock;
  //! number of node
  long nb_node;
  //! number of proc per node
  long nb_proc_per_node;
  //! batch system
  string batch;
  //! MPI implementation
  string mpiImpl;
  //! if the resource is a cluster:
  //! internal protocol to use to start a remote container (ssh or rsh) on the cluster
  string iprotocol;
};

//! exception thrown if a computer is not found in the catalog
exception NotFound {};

struct JobParameters
{
  //! Job Type - Could be equal to "command" or "yacs_file" or "python_salome"
  string job_type;

  // Common values
  string job_file;
  string env_file; 
  FilesList in_files;
  FilesList out_files;
  string work_directory;
  string local_directory;
  string result_directory;

  /*! Time for the batch (has to be like this : hh:mm) - Could be empty, in
       this case, default value of the selected resource will be used.
  */
  string maximum_duration; 

  // Memory is expressed in megabytes -> mem_mb
  // Number of Processors -> nb_proc
  ResourceParameters resource_required;

  /*!
    Name of the batch queue choosed - optional
  */
  string queue;

  /*!
    Specific parameters for each type of job - optional
  */
  Engines::ParameterList specific_parameters;
};

/*! \brief Interface of the %salomelauncher
    This interface is used for interaction with the unique instance
    of SalomeLauncher
*/
interface SalomeLauncher
{
  // Main methods
  long   createJob    (in Engines::JobParameters job_parameters) raises (SALOME::SALOME_Exception);
  void   launchJob    (in long job_id)                           raises (SALOME::SALOME_Exception);
  string getJobState  (in long job_id)                           raises (SALOME::SALOME_Exception);
  void   getJobResults(in long job_id, in string directory)      raises (SALOME::SALOME_Exception);
  void   removeJob    (in long job_id)                           raises (SALOME::SALOME_Exception);

  // Useful methods
  long    createJobWithFile(in string xmlJobFile, in string clusterName) raises (SALOME::SALOME_Exception);
  boolean testBatch        (in ResourceParameters params)		 raises (SALOME::SALOME_Exception);

  // SALOME kernel service methods
  void Shutdown();
  long getPID();
};
  
/*! \brief Interface of the %containerManager
    This interface is used for interaction with the unique instance
    of ContainerManager
*/
interface ContainerManager
{
  //! GiveContainer - use mode parameter of ContainerParameters to configure
  //! how this method works
  //! Currently: get, start, getorstart, findorstart, find
  Container GiveContainer(in ContainerParameters params);

  //!  Shutdown all containers that have been launched by the container manager
  void ShutdownContainers();
} ;
  
/*! \brief Interface of the %resourcesManager
    This interface is used for interaction with the unique instance
    of ResourcesManager
*/
interface ResourcesManager
{
  //!  Find first available resource in a resources list
  string FindFirst(in ResourceList possibleResources);

  //!  Find best available computer according to policy in a computers list
  string Find(in string policy, in ResourceList possibleResources);

  //!  Get a list of resources that are best suited to launch a container given constraints 
  /*! 
       The constraints are resource constraints (params) and components constraints (componentList)
  */
  ResourceList GetFittingResources(in ResourceParameters params) raises (SALOME::SALOME_Exception);

  //!  Get definition of a resource
  ResourceDefinition GetResourceDefinition(in string name);

  //! Add a new resource to the resource_manager
  /*!
      write -> true, resource manager will add it into a xml_file
      xml_file -> could be empty, in this case if write is true, resource manager will write
      the resource in its first ResourceCatalog file
    */
  void AddResource(in ResourceDefinition new_resource, in boolean write, in string xml_file) 
    raises (SALOME::SALOME_Exception);

  //! Remove a new resource to the resource_manager
  /*!
      write -> true, resource manager will write a new xml_file
      xml_file -> could be empty, in this case if write is true, resource manager will write
      the resource in its first ResourceCatalog file
    */
  void RemoveResource(in string resource_name, in boolean write, in string xml_file) 
    raises (SALOME::SALOME_Exception);
};


// For compatibility - will be erased on SALOME 6
typedef sequence<string> MachineList;
//!  Type to describe required properties of a container.
struct MachineParameters
{
  //! container name if given else automatic
  string container_name;
  //! host name if given else automatic
  string hostname;
  //! if given list of components that could be loaded on the container
  CompoList componentList;
  //! if given restricted list of machines to search in
  MachineList computerList;
  //! required operating system 
  string OS;
  //! required memory size
  long mem_mb;
  //! required frequency
  long cpu_clock;
  //! required number of proc per node
  long nb_proc_per_node;
  //! required number of node
  long nb_node;
  //! if true start a MPI container
  boolean isMPI;
  //! container working directory 
  string workingdir;
  //! creation mode for GiveContainer. 
  /*!start creates a new container
   * get  try to find an existing container
   * getorstart   use an existing container if it exists or creates a new one
   */
  string mode;
  //! resource management policy : first, cycl, altcycl or best (can be extended)
  string policy;

  //! PaCO specific informations
  string parallelLib;
  long nb_component_nodes;
};
};
  
#endif