X-Git-Url: http://git.salome-platform.org/gitweb/?a=blobdiff_plain;f=idl%2FSALOME_Component.idl;h=9d55e154be208f748d5bf1ae95028f4479bf6f42;hb=bbac39ee34bd6a5e6fd051024209399b97b818b1;hp=f5fe50f56bef64f89622060c784d36b5f62271b8;hpb=4655b0b0eb5345da6a86852021014b0cbae2ad30;p=modules%2Fkernel.git diff --git a/idl/SALOME_Component.idl b/idl/SALOME_Component.idl index f5fe50f56..9d55e154b 100644 --- a/idl/SALOME_Component.idl +++ b/idl/SALOME_Component.idl @@ -1,117 +1,724 @@ -//============================================================================= -// File : SALOME_Component.idl -// Created : jeu jui 12 08:11:23 CEST 2001 -// Author : Paul RASCLE, EDF -// Project : SALOME -// Copyright : EDF 2001 -// $Header: /dn05/salome/CVS/SALOME_ROOT/idl/SALOME_Component.idl -//============================================================================= +// Copyright (C) 2007-2012 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 +// +// File : SALOME_Component.idl +// Author : Paul RASCLE, EDF #ifndef _SALOME_COMPONENT_IDL_ #define _SALOME_COMPONENT_IDL_ -/*! \ingroup Kernel -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. +#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 { - interface Component ; + /*! + A byte stream which is used for binary data transfer between different + components + */ + typedef sequence TMPFile; + + //! General Key Value Structure to set or get properties, for component + struct KeyValuePair + { + string key; + any value; + }; -/*! \brief Interface of the %Container + //! Structure data type to hold reference on data + struct dataref + { + string ref; + }; + + typedef sequence FieldsDict; + + interface EngineComponent ; + interface fileRef ; + interface fileTransfer ; + interface Salome_file; + + /*! \brief Interface of the %Container. + This interface defines the process of loading and registration + of new components in %SALOME application + */ - This interface defines the process of loading and registration - of new components in SALOME application -*/ interface Container { -/*! - Initializes the %container with a definite name. -*/ - Container start_impl( in string ContainerName ) ; -/*! - Loads into the container a new component, registers it and starts it's CORBA servant. - \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 -*/ - Component load_impl(in string nameToRegister, in string componentName); + /*! \brief Loads a new component class (dynamic library). -/*! - Stops the component servant, and deletes all related objects -*/ - void remove_impl(in Component component_i); + \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); -/*! - Discharges all components from the container. -*/ + //! 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. -*/ + //! Determines whether the server has been loaded or not. void ping(); -/*! - Name of the %container -*/ + + //! Name of the %container readonly attribute string name ; -/*! - Name of the machine containing this container (location of the container). -*/ - readonly attribute string machineName ; -/*! - Returns True if the %container has been killed -*/ + + //! 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 of the %component - This interface is used for interaction between the %container and the %component and between - the components inside the container. -*/ - interface Component + /*! \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 -*/ + //! The name of the instance of the %Component readonly attribute string instanceName ; -/*! - The name of the interface of the %Component -*/ + + //! The name of the interface of the %Component readonly attribute string interfaceName ; -/*! - Determines whether the server has already been loaded or not. -*/ + + //! Determines whether the server has already been loaded or not. void ping(); -/*! - Deactivates the %Component. -*/ + + //! 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. -*/ + + //! Returns the container that the %Component refers to. Container GetContainerRef() ; -/*! - This method is used by the %SUPERVISOR component. It sets the names of the graph and of the node. -*/ + + //! 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 ) ; -/*! - Returns True if the %Component has been killed. -*/ + + //! Kill the component (if you can) + /*! + Returns True if the %Component has been killed. + */ boolean Kill_impl() ; -/*! - Returns True if the activity of the %Component has been stopped. (It's action can't be resumed) -*/ + + //! 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() ; -/*! - Returns True if the activity of the %Component has been suspended. (It's action can be resumed) -*/ + + //! Suspend the component + /*! + Returns True if the activity of the %Component has been suspended. + (It's action can be resumed) + */ boolean Suspend_impl() ; -/*! - Returns True if the activity of the %Component has been resumed. -*/ + + //! 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); } ; -} ; + + /*! + \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 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 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