1 // Copyright (C) 2007-2024 CEA, EDF, OPEN CASCADE
3 // Copyright (C) 2003-2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN,
4 // CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS
6 // This library is free software; you can redistribute it and/or
7 // modify it under the terms of the GNU Lesser General Public
8 // License as published by the Free Software Foundation; either
9 // version 2.1 of the License, or (at your option) any later version.
11 // This library is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 // Lesser General Public License for more details.
16 // You should have received a copy of the GNU Lesser General Public
17 // License along with this library; if not, write to the Free Software
18 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20 // See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
23 // File : SALOME_Component.idl
24 // Author : Paul RASCLE, EDF
26 #ifndef _SALOME_COMPONENT_IDL_
27 #define _SALOME_COMPONENT_IDL_
29 #include "SALOME_GenericObj.idl"
30 #include "SALOMEDS.idl"
31 #include "SALOME_Exception.idl"
32 #include "SALOME_PyNode.idl"
33 #include "SALOME_Embedded_NamingService.idl"
34 #include "SALOME_Comm.idl"
36 /*! \file SALOME_Component.idl \brief interfaces for EngineComponent and Container
40 This is a package of interfaces used for connecting new components to %SALOME
41 application. It also contains a set of interfaces used for management of %FIELDS
42 component in %SALOME application.
47 A byte stream which is used for binary data transfer between different
50 typedef sequence<octet> TMPFile;
52 //! General Key Value Structure to set or get properties, for component
59 //! Structure data type to hold reference on data
65 typedef sequence<KeyValuePair> FieldsDict;
66 typedef sequence<double> vectorOfDouble;
67 typedef sequence<string> vectorOfString;
68 typedef sequence<vectorOfString> vectorOfVectorOfString;
70 interface EngineComponent ;
72 interface fileTransfer ;
73 interface Salome_file;
75 /*! \brief Interface of the %Container.
76 This interface defines the process of loading and registration
77 of new components in %SALOME application
83 void override_environment( in FieldsDict env );
85 void override_environment_python( in FieldsDict env );
87 FieldsDict get_os_environment();
89 void set_big_obj_on_disk_threshold(in long thresholdInByte);
91 void set_big_obj_on_disk_directory(in string directory);
93 void set_directory_for_replay_files(in string directory);
95 void set_number_of_retry(in long nbRetry);
97 void set_current_directory(in string cwd);
99 void set_startup_code(in string codeAtStartUp);
101 string get_startup_code();
103 void addLogFileNameGroup(in vectorOfString groupOfLogFileNames);
105 vectorOfVectorOfString getAllLogFileNameGroups();
107 void execute_python_code( in string code ) raises(SALOME::SALOME_Exception);
109 /*! \brief Loads a new component class (dynamic library).
111 \param componentName like COMPONENT, (Python or C++ implementation)
112 try to make a Python import of COMPONENT,
113 then a lib open of libCOMPONENTEngine.so
114 \param reason in case of error (return false) a string explaining the error
115 \return true if load successful or already done, false otherwise
117 boolean load_component_Library(in string componentName, out string reason);
119 //! Create a new servant instance of a component.
121 Component library must be loaded.
122 \param componentName Name of the component which will be registered
123 in Registry and Name Service,
124 (instance number suffix added to the registered name)
125 \return a loaded component
127 Engines::EngineComponent create_component_instance(in string componentName);
129 //! Create a new Python servant instance of a generic service.
131 This simply loads the service in the current container by importing the
132 corresponding Python module.
133 Warning: no internal registration is done, so it is up to the caller to
134 manage the various instantiation.
135 \param serviceName Name of the service
136 \param reason in case of error (return void string) a string explaining the error
137 \return the IOR of the loaded service.
139 string create_python_service_instance(in string serviceName,
142 //! Create a new servant instance of a component with environment variables specified.
144 Component library must be loaded.
145 \param componentName Name of the component which will be registered
146 in Registry and Name Service,
147 (instance number suffix added to the registered name)
148 \param env a dict of env variables
149 \param reason in case of error (return nil) a string explaining the error
150 \return a loaded component
152 Engines::EngineComponent create_component_instance_env(in string componentName,
155 //! Find a servant instance of a component
157 \param registeredName Name of the component in Registry or Name Service,
158 without instance suffix number
159 \return the first instance found
161 EngineComponent find_component_instance(in string registeredName);
163 //! Find a servant instance of a component, or create a new one.
165 Loads the component library if needed.
166 Only applicable to multiStudy components.
167 \param nameToRegister Name of the component which will be registered
168 in Registry (or Name Service)
169 \param componentName Name of the constructed library of the %component
170 (not used any more, give empty string)
171 \return a loaded component
173 EngineComponent load_impl(in string nameToRegister,
174 in string componentName);
176 //! Remove the component servant, and deletes all related objects
178 \param component_i Component to be removed
180 void remove_impl(in EngineComponent component_i);
182 //! In case of SSL mode Returns entry to Embedded NS
183 EmbeddedNamingService get_embedded_NS_if_ssl();
185 boolean is_SSL_mode();
187 //! Unload component libraries from the container.
188 void finalize_removal() ;
190 //! Determines whether the server has been loaded or not.
193 //! Name of the %container
194 readonly attribute string name ;
196 //! working directory of the %container
197 readonly attribute string workingdir ;
199 //! name of the %container log file (this has been set by the launcher)
200 attribute string logfilename ;
202 //! name of the %container log file
203 attribute string locallogfilename ;
205 //! interval of time between two measures of CPU/time process container
206 attribute long monitoringtimeresms;
208 void verbosity(out boolean activated, out string level);
210 void setVerbosity(in boolean activated, in string level);
212 //! Shutdown the Container process. Shutdown is not immediate. It waits for all remaining invokation completion.
215 //! Shutdown the Container process. Shutdown is immediate for this method.
218 //! Returns the hostname of the container
219 string getHostName();
221 //! Returns the PID of the container
224 //! Kill the container
226 Returns True if the %container has been killed.
227 Kept for Superv compilation but can't work, unless oneway...
230 boolean Kill_impl() ;
234 returns a fileRef object if origFileName exists and is readable
235 else returns null object. Only one fileRef is created for a given
236 file name, so, several calls with the same file name returns the
239 fileRef createFileRef(in string origFileName);
241 //! Create a Salome_file
243 returns a Salome_file object if origFileName exists and is readable
244 else returns null object.
246 \param origFileName name of the file to be managed (can contain the path).
248 \return Salome_file CORBA reference.
250 Salome_file createSalome_file(in string origFileName);
252 //! Create a fileTransfer
254 returns a fileTransfer object used to copy files from the container
255 machine to the clients machines. Only one fileTransfer instance is
256 created in a container.
258 fileTransfer getFileTransfer();
260 //! Copy a file from a remote host (container) to a local file
262 \param contai the remote container
263 \param remoteFile the file on the remote host to copy
264 \param localFile the local file to create by copy
266 void copyFile(in Container contai, in string remoteFile, in string localFile);
268 //! Create a PyNode in the container
270 \param nodeName the name of the PyNode
271 \param code python code as text to load in the node
273 PyNode createPyNode(in string nodeName, in string code) raises(SALOME::SALOME_Exception);
275 //! Retrieves the last created PyNode instance with createPyNode.
276 PyNode getDefaultPyNode(in string nodeName);
278 //! Create a PyScriptNode in the container
280 \param nodeName the name of the PyScriptNode
281 \param code python code as text to load in the node
283 PyScriptNode createPyScriptNode(in string nodeName, in string code) raises(SALOME::SALOME_Exception);
285 void removePyScriptNode(in string nodeName) raises(SALOME::SALOME_Exception);
287 //! Retrieves the last created PyScriptNode instance with createPyScriptNode.
288 PyScriptNode getDefaultPyScriptNode(in string nodeName);
290 //! This method remove all refs of PyScriptNode servant objects stored in server.
292 * 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.
294 void cleanAllPyScripts();
296 //! Return number of CPU cores in the calculation node.
297 long getNumberOfCPUCores();
299 //! Return a load of each CPU core.
300 vectorOfDouble loadOfCPUCores() raises(SALOME::SALOME_Exception);
302 //! Set custom script to calculate a load of each CPU core.
304 \param script Python script to execute
306 void setPyScriptForCPULoad(in string script);
308 //! Nullify custom script to calculate each CPU core's load.
309 void resetScriptForCPULoad();
311 //! Get total physical memory of calculation node, in megabytes.
312 long getTotalPhysicalMemory();
314 //! Get used physical memory of calculation node, in megabytes.
315 long getTotalPhysicalMemoryInUse();
317 //! Obtain physical memory, used by the current process, in megabytes.
318 long getTotalPhysicalMemoryInUseByMe();
321 /*! \brief Interface of the %component.
322 This interface is used for interaction between the %container and the
323 %component and between the components inside the container.
325 interface EngineComponent
327 //! The name of the instance of the %Component
328 readonly attribute string instanceName ;
330 //! The name of the interface of the %Component
331 readonly attribute string interfaceName ;
333 //! Determines whether the server has already been loaded or not.
336 boolean isSSLMode() raises(SALOME::SALOME_Exception);
337 //! Remove component instance from container
339 Deactivates the %Component.
340 -- TO BE USED BY CONTAINER ONLY (Container housekeeping) --
341 use remove_impl from Container instead !
345 //! Returns the container that the %Component refers to.
346 Container GetContainerRef() ;
348 //! Set component instance properties
350 Gives a sequence of (key=string,value=any) to the component.
351 Base class component stores the sequence in a map.
352 The map is cleared before.
353 This map is for use by derived classes.
355 void setProperties(in FieldsDict dico);
357 //! Get component instance properties
359 returns a previously stored map (key=string,value=any) as a sequence.
360 See setProperties(in FieldsDict dico).
362 FieldsDict getProperties();
364 //! Set an option value
366 This method is to set an option specific to a certain EngineComponent.
368 void SetOption(in string optionName, in string value);
370 //! Return an option value
372 This method is to get value of an option specific to a certain EngineComponent.
374 string GetOption(in string optionName);
376 //! Set name of a node in a graph (for %SUPERVISOR use)
378 This method is used by the %SUPERVISOR component. It sets the names of
379 the graph and of the node.
380 \param aGraphName Name of graph
381 \param aNodeName Name of node
383 void Names( in string aGraphName , in string aNodeName ) ;
385 //! Kill the component (if you can)
387 Returns True if the %Component has been killed.
389 boolean Kill_impl() ;
391 //! Stop the component (if you can)
393 Returns True if the activity of the %Component has been stopped.
394 (It's action can't be resumed)
396 boolean Stop_impl() ;
398 //! Suspend the component
400 Returns True if the activity of the %Component has been suspended.
401 (It's action can be resumed)
403 boolean Suspend_impl() ;
405 //! Resume the component
407 Returns True if the activity of the %Component has been resumed.
409 boolean Resume_impl() ;
415 long CpuUsed_impl() ;
417 //! Get a python dump
419 Returns a python script, which is being played back reproduces
420 the data model of component
422 TMPFile DumpPython(in boolean isPublished,
423 in boolean isMultiFile,
424 out boolean isValidScript);
427 //! Returns a CORBA Ref of a input Salome_file managed by a service.
430 \param service_name service's name.
431 \param file_name name of the requested file.
433 \return CORBA Ref of the requested file.
435 \exception contains information of what if the component cannot
436 sends the file's reference.
438 Engines::Salome_file getInputFileToService(in string service_name,
439 in string Salome_file_name) raises(SALOME::SALOME_Exception);
441 //! Check service input files (transfer them if needed)
443 This method is used before the activation of the service. It calls
444 recvFiles() on all the input Salome_file files of the service.
446 Before each recvFiles(), it uses the callback method named configureSalome_file.
447 This method allows the user to configure the files managed by the Salome_file.
449 By default, there is no files managed when a Salome_file is created,
450 but the supervisor set some files managed by the Salome_file from the information contained
451 into the schema file.
453 \param service_name service's name.
455 \exception contains information about files that are not in a good state.
457 void checkInputFilesToService(in string service_name) raises(SALOME::SALOME_Exception);
459 //! This method adds a input Salome_file to a service of the component.
462 \param service_name service's name.
463 \param Salome_file_name name of the Salome_file
465 \return a reference of the Salome_file
467 \exception raises an exception if there is already
468 a Salome_file with this name for the service.
470 Engines::Salome_file setInputFileToService(in string service_name,
471 in string Salome_file_name) raises(SALOME::SALOME_Exception);
473 //! Returns a CORBA Ref of a output Salome_file managed by a service.
476 \param service_name service's name.
477 \param file_name name of the requested file.
479 \return CORBA Ref of the requested file.
481 \exception contains information of what if the component cannot
482 sends the file's reference.
484 Engines::Salome_file getOutputFileToService(in string service_name,
485 in string Salome_file_name) raises(SALOME::SALOME_Exception);
487 //! Check service output files (transfer them if needed)
489 This method is used at the end of the service. It calls
490 recvFiles() on all the output Salome_file files of the service.
492 Before each recvFiles(), it uses the callback method named configureSalome_file.
493 This method allows the user to configure the files managed by the Salome_file.
495 By default, there is no files managed when a Salome_file is created,
496 but the supervisor set some files managed by the Salome_file from the information contained
497 into the schema file.
499 \param service_name service's name.
501 \exception contains information about files that are not in a good state.
503 void checkOutputFilesToService(in string service_name) raises(SALOME::SALOME_Exception);
505 //! This method adds an output Salome_file to a service of the component.
508 \param service_name service's name.
509 \param Salome_file_name name of the Salome_file
511 \return a reference of the Salome_file
513 \exception raises an exception if there is already
514 a Salome_file with this name for the service.
516 Engines::Salome_file setOutputFileToService(in string service_name,
517 in string Salome_file_name) raises(SALOME::SALOME_Exception);
519 //! Indicate if the component instance provides custom information about its objects.
521 Returns true if the component provides custom information about its objects, false otherwise.
522 Should be redefined in the certain component to return true in case of this
523 component provides such information.
525 boolean hasObjectInfo();
527 //! Get custom information about the given object.
529 This method is used to get the custom information about the given object.
530 Should be redefined in the certain component in case of this
531 component provides such information.
532 It is worth using this method only if hasObjectInfo() method returns true.
534 \param entry object's entry.
536 \return an information about the given object.
538 string getObjectInfo(in string entry);
540 //! Get version of the component
542 This method is supposed to be implemented in all derived classes; default implementation
543 returns "unknown" string that means that no version information about the component is available.
544 \note The version of the component is stored to the study, as a part of general persistence
545 mechanism; once stored, version information in the study cannot be changed.
547 \return string containing component's version, e.g. "1.0"
553 \brief Base interface of the %component that supports exporting data.
555 interface ImportableComponent
557 /*! \brief Get a list of supported formats */
558 SALOME::StringSeq GetImportableFormats();
559 boolean ImportDataAs(in string format, in SALOME::GenericObj exporter);
562 //! A block of binary data used for file transfer. The maximum size of the block is defined on server side.
563 typedef sequence<octet> fileBlock;
565 /*! \brief Interface of fileTransfer.
566 The fileTransfer and fileRef interfaces provide a file transfer service
567 between different computers.
569 interface fileTransfer : SALOME::GenericObj
571 //! Open the file transfer
573 open method returns a key (fileId) that identifies the structure
574 (ex: C FILE), associated to the original file on the server.
575 The structure is created by a container for transfer of files availables
576 on the computer which runs the container.
577 Each open gives a unique fileId, to allow concurrent reads of the same
580 long open(in string fileName);
581 //! Open the file transfer in write mode for file fileName
583 \param fileName the file to copy into with putBlock
584 \return the id to use with putBlock
586 long openW(in string fileName);
588 //! Close the file transfer
590 when the file transfer is finished, close method releases structures
591 created by open method, identified by fileId.
593 void close(in long fileId);
595 //! Get a file data block
597 Get successive blocks of octets from the original file.
598 The last block is empty, and identifies the end of file.
600 fileBlock getBlock(in long fileId);
602 //! Put a file data block
604 \param fileId identification of the file obtained by openW
605 \param block a data block to copy into the file identified by fileId
607 void putBlock(in long fileId, in fileBlock block);
611 //! A file managed by a Salome_file.
618 string source_file_name;
619 //! status ("present" or "notpresent")
622 Engines::Container container;
625 //! A sequence of Engines::file.
626 typedef sequence<Engines::file> files;
629 //! The state of a Salome_file.
633 //! hdf5 file where the file can be saved
634 string hdf5_file_name;
635 //! number of files managed
636 long number_of_files;
637 //! information if all the files are received
642 /*! \brief Interface of a Salome_file managed
643 This file is independent of a Salome module. It can managed one or more
644 real files. It's useful for parallel files. Currently Salome_file cannot manage
645 two files that have the same name but not the same path.
647 interface Salome_file : Engines::fileTransfer
649 //! Load a Salome_file from a hdf5 file.
652 \param hdf5_file name (with path) of the hdf5_file.
654 \exception contains information of errors if the loading doesn't succeed.
656 void load(in string hdf5_file) raises (SALOME::SALOME_Exception);
658 //! Save a Salome_file into a hdf5_file.
661 \param hdf5_file name (with path) of the hdf5_file.
663 \exception contains information of errors if the save doesn't succeed.
666 void save(in string hdf5_file) raises (SALOME::SALOME_Exception);
668 //! Save a Salome_file into a hdf5_file.
670 All files that are managed are saved into the hdf5_file
672 \param hdf5_file name (with path) of the hdf5_file.
674 \exception contains information of errors if the save doesn't succeed.
677 void save_all(in string hdf5_file) raises (SALOME::SALOME_Exception);
681 //! Add a Local file to the Salome_file.
684 \param file_name name of the file with the path.
686 \exception raised if the file is already added into the Salome_file.
688 void setLocalFile(in string comp_file_name) raises (SALOME::SALOME_Exception);
690 //! Add a Distributed file to the Salome_file.
693 \param comp_file_name name of the file with the path.
695 \exception raised if the file is already added into the Salome_file.
697 void setDistributedFile(in string comp_file_name) raises (SALOME::SALOME_Exception);
699 //! Connect a Salome_file with another Salome_file.
701 It works only if the Salome_file managed only one file
703 \param source_Salome_file Salome_file that managed the distributed version of the file.
705 \exception raised if there is more or less than one file.
707 void connect(in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
709 //! Connect the managed file file_name to a Salome_file.
712 \param file_name name of the file without the path.
713 \param source_Salome_file Salome_file that managed the distributed version of the file.
715 \exception raised if the file doesn't exist.
717 void connectDistributedFile(in string file_name,
718 in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
720 //! Connect the file_name with a Distributed file_name.
723 \param file_name name of the file without the path.
724 \param source_file_name It's the name of the file managed by the distributed source Salome_file.
726 \exception raised if the file doesn't exist.
728 void setDistributedSourceFile(in string file_name,
729 in string source_file_name) raises (SALOME::SALOME_Exception);
733 //! Get all the distributed files managed by the Salome_file and check all the local files.
736 \exception raised if some of the files are not ok.
738 void recvFiles() raises (SALOME::SALOME_Exception) ;
742 //! Remove a file of the Salome_file.
745 \param file_name name of the file.
747 \exception raised if the file doesn't exist.
749 void removeFile(in string file_name) raises (SALOME::SALOME_Exception);
751 //! Remove all the files of the Salome_file.
756 //! Get the list of the files managed by the Salome_file.
758 The list can be empty.
760 Engines::files getFilesInfos();
762 //! Get a file managed by the Salome_file.
765 \param file_name the name of the file.
767 \return CORBA file reference.
769 \exception raised if the file doesn't exist.
771 Engines::file getFileInfos(in string file_name) raises (SALOME::SALOME_Exception);
773 //! Return the state of the Salome_file.
774 Engines::SfState getSalome_fileState();
777 //! Set the container where files are.
780 \param container container CORBA's reference.
782 void setContainer(in Engines::Container container);
785 /*! \brief Interface of fileRef.
786 The fileTransfer and fileRef interfaces provide a file transfer service
787 between different computers.
789 A fileRef object is associated to an original file (origFileName) on a
790 machine (refMachine).
791 It is created by a container (factoryServer) on refMachine,
792 with createFileRef(in string origFileName) method.
793 The fileRef object maintains a list of (machine,filename) for copies.
794 If a copy exists on myMachine, getRef(myMachine) returns the file name
795 of the copy on myMachine, else returns empty string.
796 If there is no copy on myMachine, method getFileTransfer() from container
797 factoryServer on refMachine provides a fileTransfer object dedicated to
799 After the copy, addRef(myMachine, localFileNameOnMyMachine) registers
800 the file name of the copy on myMachine.
804 //! the original file
805 readonly attribute string origFileName;
806 //! the machine of the original file
807 readonly attribute string refMachine;
809 Container getContainer();
811 boolean addRef(in string machine,
814 string getRef(in string machine);