X-Git-Url: http://git.salome-platform.org/gitweb/?a=blobdiff_plain;f=idl%2FSALOME_Component.idl;h=2e3b662f49efe032a164fd8ed4369463e88bfd7c;hb=f9ed7d1e82753ef572fcb1179e370e11e807a883;hp=5503ed3f200b3cd034bb3ab091c644795e46a428;hpb=e6bfea36374791cd31c274a2f97df90dc60ddaf3;p=modules%2Fkernel.git diff --git a/idl/SALOME_Component.idl b/idl/SALOME_Component.idl index 5503ed3f2..2e3b662f4 100644 --- a/idl/SALOME_Component.idl +++ b/idl/SALOME_Component.idl @@ -1,58 +1,74 @@ -// Copyright (C) 2003 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 +// Copyright (C) 2007-2023 CEA, EDF, 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 -// $Header: #ifndef _SALOME_COMPONENT_IDL_ #define _SALOME_COMPONENT_IDL_ +#include "SALOME_GenericObj.idl" +#include "SALOMEDS.idl" +#include "SALOME_Exception.idl" +#include "SALOME_PyNode.idl" +#include "SALOME_Embedded_NamingService.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 +application. It also contains a set of interfaces used for management of %FIELDS component in %SALOME application. */ module Engines { - /*! + /*! 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 - */ + typedef sequence 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 FieldsDict; + typedef sequence vectorOfDouble; + typedef sequence vectorOfString; - interface Component ; + interface EngineComponent ; interface fileRef ; interface fileTransfer ; + interface Salome_file; /*! \brief Interface of the %Container. This interface defines the process of loading and registration @@ -62,41 +78,70 @@ module Engines interface Container { - /*! - Loads a new component class (dynamic library). + void override_environment( in FieldsDict env ); + + void override_environment_python( in FieldsDict env ); + + FieldsDict get_os_environment(); + + void execute_python_code( in string code ) raises(SALOME::SALOME_Exception); + + /*! \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 - \return true if load successfull or already done, false otherwise + \param reason in case of error (return false) a string explaining the error + \return true if load successful or already done, false otherwise */ - boolean load_component_Library(in string componentName); + boolean load_component_Library(in string componentName, out string reason); + //! Create a new servant instance of a component. /*! - Creates 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 */ - Component create_component_instance(in string componentName, - in long studyId); - + Engines::EngineComponent create_component_instance(in string componentName); + + //! Create a new Python servant instance of a generic service. + /*! + This simply loads the service in the current container by importing the + corresponding Python module. + Warning: no internal registration is done, so it is up to the caller to + manage the various instantiation. + \param serviceName Name of the service + \param reason in case of error (return void string) a string explaining the error + \return the IOR of the loaded service. + */ + string create_python_service_instance(in string serviceName, + out string reason); + + //! 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 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 FieldsDict env, + out string reason); + //! Find a servant instance of a component /*! - Finds 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 + \return the first instance found */ - Component find_component_instance(in string registeredName, - in long studyId); + EngineComponent find_component_instance(in string registeredName); + //! Find a servant instance of a component, or create a new one. /*! - 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 @@ -105,45 +150,45 @@ module Engines (not used any more, give empty string) \return a loaded component */ - Component load_impl(in string nameToRegister, - in string componentName); + EngineComponent load_impl(in string nameToRegister, + in string componentName); + //! Remove the component servant, and deletes all related objects /*! - Stops the component servant, and deletes all related objects \param component_i Component to be removed */ - void remove_impl(in Component component_i); + void remove_impl(in EngineComponent component_i); + + //! In case of SSL mode Returns entry to Embedded NS + EmbeddedNamingService get_embedded_NS_if_ssl(); + + boolean is_SSL_mode(); - /*! - Discharges all components from the container. - */ + //! 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 ; - /*! - Shutdown the Container process. - */ - oneway void Shutdown(); + //! working directory of the %container + readonly attribute string workingdir ; - /*! - Returns the hostname of the container - */ + //! 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 - */ + //! 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... @@ -151,14 +196,27 @@ module Engines */ 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 + 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 @@ -166,48 +224,84 @@ module Engines */ 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); + //! Retrieves the last created PyNode instance with createPyNode. + PyNode getDefaultPyNode(in string nodeName); + //! 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); + + void removePyScriptNode(in string nodeName) raises(SALOME::SALOME_Exception); + + //! Retrieves the last created PyScriptNode instance with createPyScriptNode. + PyScriptNode getDefaultPyScriptNode(in string nodeName); + + //! This method remove all refs of PyScriptNode servant objects stored in server. + /*! + * Previous scripts created on container may have been stored in a map. This method removes them. It then clean all the contexts dict attached to them. + */ + void cleanAllPyScripts(); + + //! Return number of CPU cores in the calculation node. + long getNumberOfCPUCores(); + + //! Return a load of each CPU core. + vectorOfDouble loadOfCPUCores() raises(SALOME::SALOME_Exception); + + //! Set custom script to calculate a load of each CPU core. + /*! + \param script Python script to execute + */ + void setPyScriptForCPULoad(in string script); + + //! Nullify custom script to calculate each CPU core's load. + void resetScriptForCPULoad(); + + //! Get total physical memory of calculation node, in megabytes. + long getTotalPhysicalMemory(); + + //! Get used physical memory of calculation node, in megabytes. + long getTotalPhysicalMemoryInUse(); + + //! Obtain physical memory, used by the current process, in megabytes. + long getTotalPhysicalMemoryInUseByMe(); + }; /*! \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 + 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(); -// /*! -// Set study associated to component instance -// \param studyId -// (=0: multistudy component instance, -// >0: study id associated to this instance -// \return false if already set with a different value (change not possible) -// */ -// boolean setStudyId(in long studyId); - - /*! - 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(); - + boolean isSSLMode() raises(SALOME::SALOME_Exception); + //! Remove component instance from container /*! Deactivates the %Component. -- TO BE USED BY CONTAINER ONLY (Container housekeeping) -- @@ -215,25 +309,38 @@ module Engines */ void destroy() ; - /*! - Returns the container that the %Component refers to. - */ + //! 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. + 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. + 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. @@ -242,55 +349,193 @@ module Engines */ 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 does not run with python !...) + 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, - out boolean isValidScript); + */ + TMPFile DumpPython(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 information 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 information 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 information 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 information 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. + + \return an information about the given object. + */ + string getObjectInfo(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(); + }; /*! - A block of binary data used for file transfer. The maximum size of the - block is defined on server side. - */ + \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 + 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. @@ -300,21 +545,211 @@ module Engines 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 + 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); + }; - /*! \brief Interface of fileTransfer. + //! 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 information 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 information 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 information 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. @@ -322,9 +757,9 @@ module Engines 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. + 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. + of the copy on myMachine, else returns empty string. If there is no copy on myMachine, method getFileTransfer() from container factoryServer on refMachine provides a fileTransfer object dedicated to CORBA file copy. @@ -333,17 +768,18 @@ module Engines */ 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); + in string fileName); string getRef(in string machine); }; - -} ; +}; #endif