[modules/kernel.git] / idl / SALOME_Component.idl

// 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
//
//  File   : SALOME_Component.idl
//  Author : Paul RASCLE, EDF

#ifndef _SALOME_COMPONENT_IDL_
#define _SALOME_COMPONENT_IDL_

#include "SALOME_GenericObj.idl"
#include "SALOMEDS.idl"
#include "SALOME_Exception.idl"
#include "SALOME_PyNode.idl"

/*! \file SALOME_Component.idl \brief interfaces for EngineComponent and Container
*/

/*! \brief
This is a package of interfaces used for connecting new components to %SALOME
application. It also contains a set of interfaces used for management of %MED
component in %SALOME application.
*/
module Engines
{
  /*! 
    A byte stream which is used for binary data transfer between different
    components
  */
  typedef sequence<octet> TMPFile;  
  
  //!  General Key Value Structure to set or get properties, for component
  struct KeyValuePair
  {
    string key;
    any value;
  };

  //!  Structure data type to hold reference on data 
  struct dataref
  {
    string ref;
  };

  typedef sequence<KeyValuePair> FieldsDict;
  typedef sequence<string> ListOfOptions;
  typedef sequence<string> ListOfIdentifiers;

  interface EngineComponent ;
  interface fileRef ;
  interface fileTransfer ;
  interface Salome_file;
  interface DataContainer;

  typedef sequence<DataContainer> ListOfData;
  
  /*! \brief Interface of the %Container.
  This interface defines the process of loading and registration
  of new components in %SALOME application
  */

  interface Container
  {

    /*! \brief Loads a new component class (dynamic library).

      \param componentName like COMPONENT, (Python or C++ implementation)
                           try to make a Python import of COMPONENT,
                           then a lib open of libCOMPONENTEngine.so
      \param reason      in case of error (return false) a string explaining the error
      \return true if load successfull or already done, false otherwise
    */
    boolean load_component_Library(in string componentName, out string reason);

    //! Create a new servant instance of a component.
    /*!
      Component library must be loaded.
      \param componentName Name of the component which will be registered
                           in Registry and Name Service,
                         (instance number suffix added to the registered name)
      \param studyId        0 if instance is not associated to a study, 
                            >0 otherwise (== study id)
      \return a loaded component
    */
    Engines::EngineComponent create_component_instance(in string componentName,
                                                       in long studyId);

    //! Create a new servant instance of a component with environment variables specified.
    /*!
      Component library must be loaded.
      \param componentName Name of the component which will be registered
                           in Registry and Name Service,
                         (instance number suffix added to the registered name)
      \param studyId        0 if instance is not associated to a study, 
                            >0 otherwise (== study id)
      \param env         a dict of env variables
      \param reason      in case of error (return nil) a string explaining the error
      \return a loaded component
    */
    Engines::EngineComponent create_component_instance_env(in string componentName,
                                                           in long studyId, in FieldsDict env,
                                                           out string reason);
    //! Find a servant instance of a component
    /*!
      \param registeredName  Name of the component in Registry or Name Service,
                             without instance suffix number
      \param studyId        0 if instance is not associated to a study, 
                            >0 otherwise (== study id)
      \return the first instance found with same studyId
    */
    EngineComponent find_component_instance(in string registeredName,
                                            in long studyId);

    //! Find a servant instance of a component, or create a new one.
    /*!
      Loads the component library if needed.
      Only applicable to multiStudy components.
      \param nameToRegister Name of the component which will be registered
                            in Registry (or Name Service)
      \param componentName  Name of the constructed library of the %component
                            (not used any more, give empty string)
      \return a loaded component
    */
    EngineComponent load_impl(in string nameToRegister,
                              in string componentName);

    //! Remove the component servant, and deletes all related objects
    /*!
      \param component_i     Component to be removed
    */
    void remove_impl(in EngineComponent component_i);

    //!  Unload component libraries from the container. 
    void finalize_removal() ;

    //!  Determines whether the server has been loaded or not.
    void ping();

    //!  Name of the %container
    readonly attribute string name ;

    //!  working directory of the %container
    readonly attribute string workingdir ;

    //!  name of the %container log file (this has been set by the launcher)
    attribute string logfilename ;

    //!  Shutdown the Container process.
    void Shutdown();

    //!  Returns the hostname of the container
    string getHostName();

    //!  Returns the PID of the container
    long getPID();

    //! Kill the container 
    /*!
      Returns True if the %container has been killed.
      Kept for Superv compilation but can't work, unless oneway...
      TO REMOVE !
    */
    boolean Kill_impl() ;

    //! Create a fileRef
    /*!
      returns a fileRef object if origFileName exists and is readable
      else returns null object. Only one fileRef is created for a given
      file name, so, several calls with the same file name returns the 
      same object.
    */
    fileRef createFileRef(in string origFileName);

    //! Create a Salome_file
    /*!
      returns a Salome_file object if origFileName exists and is readable
      else returns null object. 

      \param origFileName name of the file to be managed (can contain the path).

      \return Salome_file CORBA reference.
    */
    Salome_file createSalome_file(in string origFileName);

    //! Create a fileTransfer
    /*!
      returns a fileTransfer object used to copy files from the container
      machine to the clients machines. Only one fileTransfer instance is
      created in a container.
    */
    fileTransfer getFileTransfer();

    //! Copy a file from a remote host (container) to a local file
    /*!
      \param contai the remote container
      \param remoteFile the file on the remote host to copy
      \param localFile the local file to create by copy
     */
    void copyFile(in Container contai, in string remoteFile, in string localFile);

    //! Create a PyNode in the container
    /*!
      \param nodeName the name of the PyNode
      \param code python code as text to load in the node
     */
    PyNode createPyNode(in string nodeName, in string code)  raises(SALOME::SALOME_Exception);

    //! Create a PyScriptNode in the container
    /*!
      \param nodeName the name of the PyScriptNode
      \param code python code as text to load in the node
     */
    PyScriptNode createPyScriptNode(in string nodeName, in string code)  raises(SALOME::SALOME_Exception);
  };

  /*! \brief Interface to pass data files from the client side to the SALOME Container.
    Passes data from client side to the SALOME container (where component engine is running)
    size via the CORBA bus as a stream of bytes.
  */

  interface DataContainer
  {
    //! This operation returns the stream with the data file content.
    TMPFile get();
    
    //! Returns the name of the document corresponding to this data container.                                                                                  
    string name();
    
    //! Returns the identifier of the document corresponding to this data container.
    string identifier();

    //! Returns the extension (type) of the document corresponding to this data container.
    //! It is taked from the SIMAN URL.
    string extension();

    //! Defines the extension. It is required is extension of the file is not
    //! matched with a read extension: archived file, for example.
    void setExtension(in string extension);
  };
                                      

  /*! \brief Interface of the %component.
  This interface is used for interaction between the %container and the
  %component and between the components inside the container.
  */
  interface EngineComponent
  {
    //!  The name of the instance of the %Component
    readonly attribute string instanceName ;

    //!  The name of the interface of the %Component
    readonly attribute string interfaceName ;

    //!  Determines whether the server has already been loaded or not.
    void ping();

    //!  Get study associated to component instance
    /*!
      get study associated to component instance
      \return -1: not initialised (Internal Error)
               0: multistudy component instance
              >0: study id associated to this instance
    */
    long getStudyId();

    //! Remove component instance from container
    /*!
      Deactivates the %Component.
      -- TO BE USED BY CONTAINER ONLY (Container housekeeping) --
      use remove_impl from Container instead !
    */
    void destroy() ;

    //!  Returns the container that the %Component refers to.
    Container GetContainerRef() ;

    //! Set component instance properties
    /*!
      Gives a sequence of (key=string,value=any) to the component. 
      Base class component stores the sequence in a map.
      The map is cleared before.
      This map is for use by derived classes. 
    */
    void setProperties(in FieldsDict dico);

    //! Get component instance properties
    /*!
      returns a previously stored map (key=string,value=any) as a sequence.
      See setProperties(in FieldsDict dico).
    */
    FieldsDict getProperties();

    //! Set an option value
    /*!
      This method is to set an option specific to a certain EngineComponent.
    */
    void SetOption(in string optionName, in string value);

    //! Return an option value
    /*!
      This method is to get value of an option specific to a certain EngineComponent.
    */
    string GetOption(in string optionName);

    //! Set name of a node in a graph (for %SUPERVISOR use)
    /*!
      This method is used by the %SUPERVISOR component. It sets the names of
      the graph and of the node.
      \param aGraphName Name of graph
      \param aNodeName  Name of node
    */
    void Names( in string aGraphName , in string aNodeName ) ;

    //! Kill the component (if you can)
    /*!
      Returns True if the %Component has been killed.
    */
    boolean Kill_impl() ;

    //! Stop the component (if you can)
    /*!
      Returns True if the activity of the %Component has been stopped.
      (It's action can't be resumed)
    */
    boolean Stop_impl() ;

    //! Suspend the component
    /*!
      Returns True if the activity of the %Component has been suspended.
      (It's action can be resumed)
    */
    boolean Suspend_impl() ;

    //! Resume the component
    /*!
      Returns True if the activity of the %Component has been resumed.
    */
    boolean Resume_impl() ;

    //! Get the cpu used
    /*!
      Returns the Cpu used 
    */
    long CpuUsed_impl() ;
    
    //! Get a python dump
    /*!
      Returns a python script, which is being played back reproduces
      the data model of component
    */    
    TMPFile DumpPython(in Object theStudy,
                       in boolean isPublished,
                       in boolean isMultiFile,
                       out boolean isValidScript);

    
    //! Returns a CORBA Ref of a input Salome_file managed by a service.
    /*!

      \param service_name service's name.
      \param file_name name of the requested file.

      \return CORBA Ref of the requested file.

      \exception contains informations of what if the component cannot 
      sends the file's reference.
    */
    Engines::Salome_file getInputFileToService(in string service_name, 
                                               in string Salome_file_name) raises(SALOME::SALOME_Exception);

    //! Check service input files (transfer them if needed) 
    /*!
      This method is used before the activation of the service. It calls
      recvFiles() on all the input Salome_file files of the service. 
      
      Before each recvFiles(), it uses the callback method named configureSalome_file.
      This method allows the user to configure the files managed by the Salome_file.

      By default, there is no files managed when a Salome_file is created, 
      but the supervisor set some files managed by the Salome_file from the information contained
      into the schema file.

      \param service_name service's name.

      \exception contains informations about files that are not in a good state.
    */
    void checkInputFilesToService(in string service_name)           raises(SALOME::SALOME_Exception);

    //!  This method adds a input Salome_file to a service of the component.
    /*!

      \param service_name service's name.
      \param Salome_file_name name of the Salome_file

      \return a reference of the Salome_file

      \exception raises an exception if there is already
      a Salome_file with this name for the service.
    */
    Engines::Salome_file setInputFileToService(in string service_name,
                                               in string Salome_file_name)   raises(SALOME::SALOME_Exception);

    //!  Returns a CORBA Ref of a output Salome_file managed by a service.
    /*!

      \param service_name service's name.
      \param file_name name of the requested file.

      \return CORBA Ref of the requested file.

      \exception contains informations of what if the component cannot 
      sends the file's reference.
    */
    Engines::Salome_file getOutputFileToService(in string service_name, 
                                                in string Salome_file_name) raises(SALOME::SALOME_Exception);

    //! Check service output files (transfer them if needed) 
    /*!
      This method is used at the end of the service. It calls
      recvFiles() on all the output Salome_file files of the service. 
      
      Before each recvFiles(), it uses the callback method named configureSalome_file.
      This method allows the user to configure the files managed by the Salome_file.

      By default, there is no files managed when a Salome_file is created, 
      but the supervisor set some files managed by the Salome_file from the information contained
      into the schema file.

      \param service_name service's name.

      \exception contains informations about files that are not in a good state.
    */
    void checkOutputFilesToService(in string service_name)        raises(SALOME::SALOME_Exception);

    //!  This method adds an output Salome_file to a service of the component.
    /*!

      \param service_name service's name.
      \param Salome_file_name name of the Salome_file

      \return a reference of the Salome_file

      \exception raises an exception if there is already
      a Salome_file with this name for the service.
    */
    Engines::Salome_file setOutputFileToService(in string service_name,
                                                in string Salome_file_name)  raises(SALOME::SALOME_Exception);

    //! Indicate if the component instance provides custom information about its objects.
    /*!
      Returns true if the component provides custom information about its objects, false otherwise.
      Should be redefined in the certain component to return true in case of this
      component provides such information.
    */
    boolean hasObjectInfo();
    
    //! Get custom information about the given object.
    /*!
      This method is used to get the custom information about the given object.
      Should be redefined in the certain component in case of this
      component provides such information.
      It is worth using this method only if hasObjectInfo() method returns true.
      
      \param entry object's entry.
      \param studyId study id

      \return an information about the given object.
    */
    string getObjectInfo(in long studyId, in string entry);

    //! Get version of the component
    /*!
      This method is supposed to be implemented in all derived classes; default implementation
      returns "unknown" string that means that no version information about the component is available.
      \note The version of the component is stored to the study, as a part of general persistence
      mechanism; once stored, version information in the study cannot be changed.

      \return string containing component's version, e.g. "1.0"
    */
    string getVersion();

    //! Generic Import operation to let the component to import data, corresponding to it.
    /*!
      \param studyId indentifier of the study where the data must be placed
      \param data data for import: usually this is just imported file content
      \param options additional options for Importat operation
      \return the sequence of identifiers of the importedData in the component (to use later in the export function)
    */
    ListOfIdentifiers importData(in long studyId, in DataContainer data, in ListOfOptions options);
    
    //! Generic Export operation to ket the component export all modified data corresponding to it.
    /*!
      \param studyId identifier of the study that contains the exported data
     */
    ListOfData getModifiedData(in long studyId);
  };

  /*!
    \brief Base interface of the %component that supports exporting data.
  */
  interface ImportableComponent
  {
    /*! \brief Get a list of supported formats */
    SALOME::StringSeq GetImportableFormats();
    boolean           ImportDataAs(in string format, in SALOME::GenericObj exporter);
  };

  //!  A block of binary data used for file transfer. The maximum size of the block is defined on server side.
  typedef sequence<octet> fileBlock;

  /*! \brief Interface of fileTransfer.
     The fileTransfer and fileRef interfaces provide a file transfer service
     between different computers.
  */
  interface fileTransfer : SALOME::GenericObj
  {
    //! Open the file transfer
    /*!
      open method returns a key (fileId) that identifies the structure
      (ex: C FILE), associated to the original file on the server.
      The structure is created by a container for transfer of files availables
      on the computer which runs the container.
      Each open gives a unique fileId, to allow concurrent reads of the same
      File.
    */
    long open(in string fileName);
    //! Open the file transfer in write mode for file fileName
    /*!
      \param fileName the file to copy into with putBlock
      \return the id to use with putBlock
    */
    long openW(in string fileName);

    //! Close the file transfer
    /*!
    when the file transfer is finished, close method releases structures 
    created by open method, identified by fileId.
    */
    void close(in long fileId);

    //! Get a file data block
    /*!
      Get successive blocks of octets from the original file.
      The last block is empty, and identifies the end of file.
    */
    fileBlock getBlock(in long fileId);

    //! Put a file data block
    /*!
       \param fileId identification of the file obtained by openW
       \param block a data block to copy into the file identified by fileId
    */
    void putBlock(in long fileId, in fileBlock block);

  };

  //!  A file managed by a Salome_file. 
  struct file {
    //! file name
    string file_name;
    //! path name
    string path; 
    string type;
    string source_file_name;
    //! status ("present" or "notpresent")
    string status; 
    long   node;
    Engines::Container container;
  };

  //!  A sequence of Engines::file.
  typedef sequence<Engines::file> files;


  //!  The state of a Salome_file. 
  struct SfState {
    //! file name
    string  name; 
    //! hdf5 file where the file can be saved
    string  hdf5_file_name; 
    //! number of files managed
    long    number_of_files; 
    //! information if all the files are received
    boolean files_ok; 

  };

  /*! \brief Interface of a Salome_file managed
    This file is independent of a Salome module. It can managed one or more
    real files. It's useful for parallel files. Currently Salome_file cannot manage
    two files that have the same name but not the same path.
  */
  interface Salome_file : Engines::fileTransfer
  {
    //!  Load a Salome_file from a hdf5 file.
    /*!

      \param hdf5_file name (with path) of the hdf5_file.

      \exception contains informations of errors if the loading doesn't succeed.
     */
    void load(in string hdf5_file)                            raises (SALOME::SALOME_Exception);

    //!  Save a Salome_file into a hdf5_file.
    /*!

      \param  hdf5_file name (with path) of the hdf5_file.

      \exception contains informations of errors if the save doesn't succeed.

    */
    void save(in string hdf5_file)                            raises (SALOME::SALOME_Exception);

    //!  Save a Salome_file into a hdf5_file. 
    /*!
      All files that are managed are saved into the hdf5_file

      \param  hdf5_file name (with path) of the hdf5_file.

      \exception contains informations of errors if the save doesn't succeed.

    */
    void save_all(in string hdf5_file)                            raises (SALOME::SALOME_Exception);

/**************/

    //!  Add a Local file to the Salome_file.
    /*!

      \param file_name name of the file with the path.

      \exception raised if the file is already added into the Salome_file.
    */
    void setLocalFile(in string comp_file_name) raises (SALOME::SALOME_Exception);

    //!  Add a Distributed file to the Salome_file.
    /*!

      \param comp_file_name name of the file with the path.

      \exception raised if the file is already added into the Salome_file.
    */
    void setDistributedFile(in string comp_file_name) raises (SALOME::SALOME_Exception);

    //!  Connect a Salome_file with another Salome_file.
    /*!
      It works only if the Salome_file managed only one file

      \param source_Salome_file Salome_file that managed the distributed version of the file.

      \exception raised if there is more or less than one file.
    */
    void connect(in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);

    //!  Connect the managed file file_name to a Salome_file.
    /*!

      \param file_name name of the file without the path.
      \param source_Salome_file Salome_file that managed the distributed version of the file.

      \exception raised if the file doesn't exist.
    */
    void connectDistributedFile(in string file_name,
                                in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
    
    //!  Connect the file_name with a Distributed file_name.
    /*!

      \param file_name name of the file without the path.
      \param source_file_name It's the name of the file managed by the distributed source Salome_file.

      \exception raised if the file doesn't exist.
    */
    void setDistributedSourceFile(in string file_name,
                                  in string source_file_name) raises (SALOME::SALOME_Exception);

/**************/

    //! Get all the distributed files managed by the Salome_file and check all the local files.
    /*!

      \exception raised if some of the files are not ok.
    */
    void recvFiles()                                            raises (SALOME::SALOME_Exception) ;

/**************/

    //!  Remove a file of the Salome_file.
    /*!

      \param file_name name of the file.

      \exception raised if the file doesn't exist.
    */
    void removeFile(in string file_name)                    raises (SALOME::SALOME_Exception);

    //!  Remove all the files of the Salome_file.
    void removeFiles();

/**************/

    //! Get the list of the files managed by the Salome_file.
    /*!
      The list can be empty.
    */
    Engines::files getFilesInfos();

    //! Get a file managed by the Salome_file.
    /*!

      \param file_name the name of the file.

      \return CORBA file reference.

      \exception raised if the file doesn't exist.
    */
    Engines::file  getFileInfos(in string file_name) raises (SALOME::SALOME_Exception);

    //!  Return the state of the Salome_file.
    Engines::SfState getSalome_fileState();


    //! Set the container where files are.
    /*!

      \param container container CORBA's reference.
    */
    void setContainer(in Engines::Container container);
  };

  /*! \brief Interface of fileRef.
     The fileTransfer and fileRef interfaces provide a file transfer service
     between different computers.

     A fileRef object is associated to an original file (origFileName) on a
     machine (refMachine).
     It is created by a container (factoryServer) on refMachine,
     with createFileRef(in string origFileName) method.
     The fileRef object maintains a list of (machine,filename) for copies. 
     If a copy exists on myMachine, getRef(myMachine) returns the file name
     of the copy on myMachine, else returns empy string.
     If there is no copy on myMachine, method getFileTransfer() from container
     factoryServer on refMachine provides a fileTransfer object dedicated to
     CORBA file copy.
     After the copy, addRef(myMachine, localFileNameOnMyMachine) registers
     the file name of the copy on myMachine.
  */
  interface fileRef
  {
    //! the original file
    readonly attribute string origFileName;
    //! the machine of the original file
    readonly attribute string refMachine;

    Container getContainer();

    boolean addRef(in string machine,
                   in string fileName);

    string getRef(in string machine);
  };
};

#endif