// Copyright (C) 2007-2014  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, or (at your option) any later version.
//
// 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_LAUNCHER_IDL_
#define _SALOME_LAUNCHER_IDL_

#include "SALOME_Exception.idl"
#include "SALOME_ResourcesManager.idl"

/*! \file SALOME_Launcher.idl \brief interfaces for %SALOME Launcher service
*/

module Engines
{

//! files list
typedef sequence<string> FilesList;

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

struct JobParameters
{
  //! Name of the job.
  string job_name;

  /*! \brief Type of the job.
      There are three supported types:
        - "command" : execute #job_file script without SALOME environment
        - "python_salome" : execute #job_file python script by SALOME
        - "yacs_file" : execute #job_file by YACS module as a xml YACS schema
  */
  string job_type;

  // Common values
  /*! \brief Local path to the file to be executed by the job.
      The type of the file depends on #job_type.
  */
  string job_file;

  /*! \brief Local path to a script to be sourced in the environment of the job.
      It may contain modifications of environment variables.
  */
  string env_file; 

  /*! List of local data files to be copied to #work_directory.
      #job_file and #env_file are automaticaly copied, without adding them
      to this list. The actual path of the files could be prefixed by
      #local_directory.
  */
  FilesList in_files;

  /*! List of results to get back at the end of the job.
      These results can be names of files or directories, produced by the job
      in #work_directory. Directories will be copied recursively.
      It is also possible to use an absolute path instead of the simple name,
      (string beginning with '/') and this absolute path will be used instead
      of #result_directory when SalomeLauncher::getJobResults is called.
      \see SalomeLauncher::getJobResults
  */
  FilesList out_files;

  //! Remote directory where the job will be executed.
  string work_directory;

  //! Prefix to be applied to #in_files.
  string local_directory;

  /*! Local directory where to get result files.
      \see SalomeLauncher::getJobResults
  */
  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 chosen - optional
  */
  string queue;
  
  //! Specifies if the job must run in exclusive mode (without sharing nodes with other jobs)
  boolean exclusive;

  //! Specifies the memory limit per cpu (exclusive with resource_required.mem_mb)
  unsigned long mem_per_cpu;

  //! Workload Characterization Key - mandatory on some clusters
  string wckey;

  //! String that is added to the job submission file - optional
  string extra_params;

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

  //! %Parameter for COORM
  string launcher_file;
  //! %Parameter for COORM
  string launcher_args;
};

struct JobDescription
{
  long job_id;
  Engines::JobParameters job_parameters;
};
typedef sequence<Engines::JobDescription> JobsList;

interface SalomeLauncherObserver
{
  void notify(in string event_name, in string event_data);
};

/*! \brief Interface of the %salomelauncher
    This interface is used for interaction with the unique instance
    of SalomeLauncher
*/
interface SalomeLauncher
{
  // Main methods
  /*! Create a job and set its parameters, without launching it.
      Its state becomes "CREATED".
      \return job id
  */
  long   createJob    (in Engines::JobParameters job_parameters) raises (SALOME::SALOME_Exception);

  /*! Launch an already created job (job's state should be "CREATED").
      Its state changes to "QUEUED".
  */
  void   launchJob    (in long job_id)                           raises (SALOME::SALOME_Exception);

  /*!
     \return "CREATED", "IN_PROCESS", "QUEUED", "RUNNING", "PAUSED",
             "FINISHED" or "FAILED"
     \see LIBBATCH/src/core/Constants.hxx
  */
  string getJobState  (in long job_id)                           raises (SALOME::SALOME_Exception);

  //! Get names or ids of hosts assigned to the job
  string getAssignedHostnames  (in long job_id)                  raises (SALOME::SALOME_Exception);

  /*!
     Copy the result files from the work directory of the job
     to a local directory.
     The list of result files is given by the "out_files" parameter.
     If a result "file" is a directory, the copy is recursive.
     The "logs" directory contains the standard and the error outputs of the job.
     \param job_id    Job id returned by createJob().
     \param directory Local directory where to copy the results.
                      If this value is an empty string (""), files will be
                      copied to the directory given by
                      JobParameters::result_directory.
     \see JobParameters
     \see createJob
  */
  void   getJobResults(in long job_id, in string directory)      raises (SALOME::SALOME_Exception);
  boolean getJobDumpState(in long job_id, in string directory)   raises (SALOME::SALOME_Exception);
  void   stopJob      (in long job_id)                           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();

  // Observer and introspection methods
  void addObserver(in Engines::SalomeLauncherObserver observer);
  void removeObserver(in Engines::SalomeLauncherObserver observer);
  Engines::JobsList getJobsList();
  Engines::JobParameters getJobParameters(in long job_id) raises (SALOME::SALOME_Exception);

  // Save and load methods
  void loadJobs(in string jobs_file) raises (SALOME::SALOME_Exception);
  void saveJobs(in string jobs_file) raises (SALOME::SALOME_Exception);

};

};
  
#endif