]> SALOME platform Git repositories - modules/kernel.git/blob - idl/SALOME_Component.idl
Salome HOME
#19007 [CEA][Windows] SALOME non regression tests on Windows: fix KERNEL_SALOME_COMMA...
[modules/kernel.git] / idl / SALOME_Component.idl
1 // Copyright (C) 2007-2020  CEA/DEN, EDF R&D, OPEN CASCADE
2 //
3 // Copyright (C) 2003-2007  OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN,
4 // CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS
5 //
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.
10 //
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.
15 //
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
19 //
20 // See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
21 //
22
23 //  File   : SALOME_Component.idl
24 //  Author : Paul RASCLE, EDF
25
26 #ifndef _SALOME_COMPONENT_IDL_
27 #define _SALOME_COMPONENT_IDL_
28
29 #include "SALOME_GenericObj.idl"
30 #include "SALOMEDS.idl"
31 #include "SALOME_Exception.idl"
32 #include "SALOME_PyNode.idl"
33
34 /*! \file SALOME_Component.idl \brief interfaces for EngineComponent and Container
35 */
36
37 /*! \brief
38 This is a package of interfaces used for connecting new components to %SALOME
39 application. It also contains a set of interfaces used for management of %FIELDS
40 component in %SALOME application.
41 */
42 module Engines
43 {
44   /*!
45     A byte stream which is used for binary data transfer between different
46     components
47   */
48   typedef sequence<octet> TMPFile;
49
50   //!  General Key Value Structure to set or get properties, for component
51   struct KeyValuePair
52   {
53     string key;
54     any value;
55   };
56
57   //!  Structure data type to hold reference on data
58   struct dataref
59   {
60     string ref;
61   };
62
63   typedef sequence<KeyValuePair> FieldsDict;
64
65   interface EngineComponent ;
66   interface fileRef ;
67   interface fileTransfer ;
68   interface Salome_file;
69
70   /*! \brief Interface of the %Container.
71   This interface defines the process of loading and registration
72   of new components in %SALOME application
73   */
74
75   interface Container
76   {
77
78     /*! \brief Loads a new component class (dynamic library).
79
80       \param componentName like COMPONENT, (Python or C++ implementation)
81                            try to make a Python import of COMPONENT,
82                            then a lib open of libCOMPONENTEngine.so
83       \param reason      in case of error (return false) a string explaining the error
84       \return true if load successful or already done, false otherwise
85     */
86     boolean load_component_Library(in string componentName, out string reason);
87
88     //! Create a new servant instance of a component.
89     /*!
90       Component library must be loaded.
91       \param componentName Name of the component which will be registered
92                            in Registry and Name Service,
93                          (instance number suffix added to the registered name)
94       \return a loaded component
95     */
96     Engines::EngineComponent create_component_instance(in string componentName);
97
98     //! Create a new Python servant instance of a generic service.
99         /*!
100           This simply loads the service in the current container by importing the
101           corresponding Python module.
102           Warning: no internal registration is done, so it is up to the caller to
103           manage the various instantiation.
104           \param serviceName Name of the service
105           \param reason  in case of error (return void string) a string explaining the error
106           \return the IOR of the loaded service.
107         */
108     string create_python_service_instance(in string serviceName,
109                                           out string reason);
110
111     //! Create a new servant instance of a component with environment variables specified.
112     /*!
113       Component library must be loaded.
114       \param componentName Name of the component which will be registered
115                            in Registry and Name Service,
116                          (instance number suffix added to the registered name)
117       \param env         a dict of env variables
118       \param reason      in case of error (return nil) a string explaining the error
119       \return a loaded component
120     */
121     Engines::EngineComponent create_component_instance_env(in string componentName,
122                                                            in FieldsDict env,
123                                                            out string reason);
124     //! Find a servant instance of a component
125     /*!
126       \param registeredName  Name of the component in Registry or Name Service,
127                              without instance suffix number
128       \return the first instance found
129     */
130     EngineComponent find_component_instance(in string registeredName);
131
132     //! Find a servant instance of a component, or create a new one.
133     /*!
134       Loads the component library if needed.
135       Only applicable to multiStudy components.
136       \param nameToRegister Name of the component which will be registered
137                             in Registry (or Name Service)
138       \param componentName  Name of the constructed library of the %component
139                             (not used any more, give empty string)
140       \return a loaded component
141     */
142     EngineComponent load_impl(in string nameToRegister,
143                               in string componentName);
144
145     //! Remove the component servant, and deletes all related objects
146     /*!
147       \param component_i     Component to be removed
148     */
149     void remove_impl(in EngineComponent component_i);
150
151     //!  Unload component libraries from the container.
152     void finalize_removal() ;
153
154     //!  Determines whether the server has been loaded or not.
155     void ping();
156
157     //!  Name of the %container
158     readonly attribute string name ;
159
160     //!  working directory of the %container
161     readonly attribute string workingdir ;
162
163     //!  name of the %container log file (this has been set by the launcher)
164     attribute string logfilename ;
165
166     //!  Shutdown the Container process.
167     void Shutdown();
168
169     //!  Returns the hostname of the container
170     string getHostName();
171
172     //!  Returns the PID of the container
173     long getPID();
174
175     //! Kill the container
176     /*!
177       Returns True if the %container has been killed.
178       Kept for Superv compilation but can't work, unless oneway...
179       TO REMOVE !
180     */
181     boolean Kill_impl() ;
182
183     //! Create a fileRef
184     /*!
185       returns a fileRef object if origFileName exists and is readable
186       else returns null object. Only one fileRef is created for a given
187       file name, so, several calls with the same file name returns the
188       same object.
189     */
190     fileRef createFileRef(in string origFileName);
191
192     //! Create a Salome_file
193     /*!
194       returns a Salome_file object if origFileName exists and is readable
195       else returns null object.
196
197       \param origFileName name of the file to be managed (can contain the path).
198
199       \return Salome_file CORBA reference.
200     */
201     Salome_file createSalome_file(in string origFileName);
202
203     //! Create a fileTransfer
204     /*!
205       returns a fileTransfer object used to copy files from the container
206       machine to the clients machines. Only one fileTransfer instance is
207       created in a container.
208     */
209     fileTransfer getFileTransfer();
210
211     //! Copy a file from a remote host (container) to a local file
212     /*!
213       \param contai the remote container
214       \param remoteFile the file on the remote host to copy
215       \param localFile the local file to create by copy
216      */
217     void copyFile(in Container contai, in string remoteFile, in string localFile);
218
219     //! Create a PyNode in the container
220     /*!
221       \param nodeName the name of the PyNode
222       \param code python code as text to load in the node
223      */
224     PyNode createPyNode(in string nodeName, in string code)  raises(SALOME::SALOME_Exception);
225
226     //! Retrieves the last created PyNode instance with createPyNode.
227     PyNode getDefaultPyNode(in string nodeName);
228
229     //! Create a PyScriptNode in the container
230     /*!
231       \param nodeName the name of the PyScriptNode
232       \param code python code as text to load in the node
233      */
234     PyScriptNode createPyScriptNode(in string nodeName, in string code)  raises(SALOME::SALOME_Exception);
235
236     void removePyScriptNode(in string nodeName) raises(SALOME::SALOME_Exception);
237
238     //! Retrieves the last created PyScriptNode instance with createPyScriptNode.
239     PyScriptNode getDefaultPyScriptNode(in string nodeName);
240
241     //! This method remove all refs of PyScriptNode servant objects stored in server.
242     /*!
243      * 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.
244      */
245     void cleanAllPyScripts();
246   };
247
248   /*! \brief Interface of the %component.
249   This interface is used for interaction between the %container and the
250   %component and between the components inside the container.
251   */
252   interface EngineComponent
253   {
254     //!  The name of the instance of the %Component
255     readonly attribute string instanceName ;
256
257     //!  The name of the interface of the %Component
258     readonly attribute string interfaceName ;
259
260     //!  Determines whether the server has already been loaded or not.
261     void ping();
262
263     //! Remove component instance from container
264     /*!
265       Deactivates the %Component.
266       -- TO BE USED BY CONTAINER ONLY (Container housekeeping) --
267       use remove_impl from Container instead !
268     */
269     void destroy() ;
270
271     //!  Returns the container that the %Component refers to.
272     Container GetContainerRef() ;
273
274     //! Set component instance properties
275     /*!
276       Gives a sequence of (key=string,value=any) to the component.
277       Base class component stores the sequence in a map.
278       The map is cleared before.
279       This map is for use by derived classes.
280     */
281     void setProperties(in FieldsDict dico);
282
283     //! Get component instance properties
284     /*!
285       returns a previously stored map (key=string,value=any) as a sequence.
286       See setProperties(in FieldsDict dico).
287     */
288     FieldsDict getProperties();
289
290     //! Set an option value
291     /*!
292       This method is to set an option specific to a certain EngineComponent.
293     */
294     void SetOption(in string optionName, in string value);
295
296     //! Return an option value
297     /*!
298       This method is to get value of an option specific to a certain EngineComponent.
299     */
300     string GetOption(in string optionName);
301
302     //! Set name of a node in a graph (for %SUPERVISOR use)
303     /*!
304       This method is used by the %SUPERVISOR component. It sets the names of
305       the graph and of the node.
306       \param aGraphName Name of graph
307       \param aNodeName  Name of node
308     */
309     void Names( in string aGraphName , in string aNodeName ) ;
310
311     //! Kill the component (if you can)
312     /*!
313       Returns True if the %Component has been killed.
314     */
315     boolean Kill_impl() ;
316
317     //! Stop the component (if you can)
318     /*!
319       Returns True if the activity of the %Component has been stopped.
320       (It's action can't be resumed)
321     */
322     boolean Stop_impl() ;
323
324     //! Suspend the component
325     /*!
326       Returns True if the activity of the %Component has been suspended.
327       (It's action can be resumed)
328     */
329     boolean Suspend_impl() ;
330
331     //! Resume the component
332     /*!
333       Returns True if the activity of the %Component has been resumed.
334     */
335     boolean Resume_impl() ;
336
337     //! Get the cpu used
338     /*!
339       Returns the Cpu used
340     */
341     long CpuUsed_impl() ;
342
343     //! Get a python dump
344     /*!
345       Returns a python script, which is being played back reproduces
346       the data model of component
347     */
348     TMPFile DumpPython(in boolean isPublished,
349                        in boolean isMultiFile,
350                        out boolean isValidScript);
351
352
353     //! Returns a CORBA Ref of a input Salome_file managed by a service.
354     /*!
355
356       \param service_name service's name.
357       \param file_name name of the requested file.
358
359       \return CORBA Ref of the requested file.
360
361       \exception contains information of what if the component cannot
362       sends the file's reference.
363     */
364     Engines::Salome_file getInputFileToService(in string service_name,
365                                                in string Salome_file_name) raises(SALOME::SALOME_Exception);
366
367     //! Check service input files (transfer them if needed)
368     /*!
369       This method is used before the activation of the service. It calls
370       recvFiles() on all the input Salome_file files of the service.
371
372       Before each recvFiles(), it uses the callback method named configureSalome_file.
373       This method allows the user to configure the files managed by the Salome_file.
374
375       By default, there is no files managed when a Salome_file is created,
376       but the supervisor set some files managed by the Salome_file from the information contained
377       into the schema file.
378
379       \param service_name service's name.
380
381       \exception contains information about files that are not in a good state.
382     */
383     void checkInputFilesToService(in string service_name)           raises(SALOME::SALOME_Exception);
384
385     //!  This method adds a input Salome_file to a service of the component.
386     /*!
387
388       \param service_name service's name.
389       \param Salome_file_name name of the Salome_file
390
391       \return a reference of the Salome_file
392
393       \exception raises an exception if there is already
394       a Salome_file with this name for the service.
395     */
396     Engines::Salome_file setInputFileToService(in string service_name,
397                                                in string Salome_file_name)   raises(SALOME::SALOME_Exception);
398
399     //!  Returns a CORBA Ref of a output Salome_file managed by a service.
400     /*!
401
402       \param service_name service's name.
403       \param file_name name of the requested file.
404
405       \return CORBA Ref of the requested file.
406
407       \exception contains information of what if the component cannot
408       sends the file's reference.
409     */
410     Engines::Salome_file getOutputFileToService(in string service_name,
411                                                 in string Salome_file_name) raises(SALOME::SALOME_Exception);
412
413     //! Check service output files (transfer them if needed)
414     /*!
415       This method is used at the end of the service. It calls
416       recvFiles() on all the output Salome_file files of the service.
417
418       Before each recvFiles(), it uses the callback method named configureSalome_file.
419       This method allows the user to configure the files managed by the Salome_file.
420
421       By default, there is no files managed when a Salome_file is created,
422       but the supervisor set some files managed by the Salome_file from the information contained
423       into the schema file.
424
425       \param service_name service's name.
426
427       \exception contains information about files that are not in a good state.
428     */
429     void checkOutputFilesToService(in string service_name)        raises(SALOME::SALOME_Exception);
430
431     //!  This method adds an output Salome_file to a service of the component.
432     /*!
433
434       \param service_name service's name.
435       \param Salome_file_name name of the Salome_file
436
437       \return a reference of the Salome_file
438
439       \exception raises an exception if there is already
440       a Salome_file with this name for the service.
441     */
442     Engines::Salome_file setOutputFileToService(in string service_name,
443                                                 in string Salome_file_name)  raises(SALOME::SALOME_Exception);
444
445     //! Indicate if the component instance provides custom information about its objects.
446     /*!
447       Returns true if the component provides custom information about its objects, false otherwise.
448       Should be redefined in the certain component to return true in case of this
449       component provides such information.
450     */
451     boolean hasObjectInfo();
452
453     //! Get custom information about the given object.
454     /*!
455       This method is used to get the custom information about the given object.
456       Should be redefined in the certain component in case of this
457       component provides such information.
458       It is worth using this method only if hasObjectInfo() method returns true.
459
460       \param entry object's entry.
461
462       \return an information about the given object.
463     */
464     string getObjectInfo(in string entry);
465
466     //! Get version of the component
467     /*!
468       This method is supposed to be implemented in all derived classes; default implementation
469       returns "unknown" string that means that no version information about the component is available.
470       \note The version of the component is stored to the study, as a part of general persistence
471       mechanism; once stored, version information in the study cannot be changed.
472
473       \return string containing component's version, e.g. "1.0"
474     */
475     string getVersion();
476   };
477
478   /*!
479     \brief Base interface of the %component that supports exporting data.
480   */
481   interface ImportableComponent
482   {
483     /*! \brief Get a list of supported formats */
484     SALOME::StringSeq GetImportableFormats();
485     boolean           ImportDataAs(in string format, in SALOME::GenericObj exporter);
486   };
487
488   //!  A block of binary data used for file transfer. The maximum size of the block is defined on server side.
489   typedef sequence<octet> fileBlock;
490
491   /*! \brief Interface of fileTransfer.
492      The fileTransfer and fileRef interfaces provide a file transfer service
493      between different computers.
494   */
495   interface fileTransfer : SALOME::GenericObj
496   {
497     //! Open the file transfer
498     /*!
499       open method returns a key (fileId) that identifies the structure
500       (ex: C FILE), associated to the original file on the server.
501       The structure is created by a container for transfer of files availables
502       on the computer which runs the container.
503       Each open gives a unique fileId, to allow concurrent reads of the same
504       File.
505     */
506     long open(in string fileName);
507     //! Open the file transfer in write mode for file fileName
508     /*!
509       \param fileName the file to copy into with putBlock
510       \return the id to use with putBlock
511     */
512     long openW(in string fileName);
513
514     //! Close the file transfer
515     /*!
516     when the file transfer is finished, close method releases structures
517     created by open method, identified by fileId.
518     */
519     void close(in long fileId);
520
521     //! Get a file data block
522     /*!
523       Get successive blocks of octets from the original file.
524       The last block is empty, and identifies the end of file.
525     */
526     fileBlock getBlock(in long fileId);
527
528     //! Put a file data block
529     /*!
530        \param fileId identification of the file obtained by openW
531        \param block a data block to copy into the file identified by fileId
532     */
533     void putBlock(in long fileId, in fileBlock block);
534
535   };
536
537   //!  A file managed by a Salome_file.
538   struct file {
539     //! file name
540     string file_name;
541     //! path name
542     string path;
543     string type;
544     string source_file_name;
545     //! status ("present" or "notpresent")
546     string status;
547     long   node;
548     Engines::Container container;
549   };
550
551   //!  A sequence of Engines::file.
552   typedef sequence<Engines::file> files;
553
554
555   //!  The state of a Salome_file.
556   struct SfState {
557     //! file name
558     string  name;
559     //! hdf5 file where the file can be saved
560     string  hdf5_file_name;
561     //! number of files managed
562     long    number_of_files;
563     //! information if all the files are received
564     boolean files_ok;
565
566   };
567
568   /*! \brief Interface of a Salome_file managed
569     This file is independent of a Salome module. It can managed one or more
570     real files. It's useful for parallel files. Currently Salome_file cannot manage
571     two files that have the same name but not the same path.
572   */
573   interface Salome_file : Engines::fileTransfer
574   {
575     //!  Load a Salome_file from a hdf5 file.
576     /*!
577
578       \param hdf5_file name (with path) of the hdf5_file.
579
580       \exception contains information of errors if the loading doesn't succeed.
581      */
582     void load(in string hdf5_file)                            raises (SALOME::SALOME_Exception);
583
584     //!  Save a Salome_file into a hdf5_file.
585     /*!
586
587       \param  hdf5_file name (with path) of the hdf5_file.
588
589       \exception contains information of errors if the save doesn't succeed.
590
591     */
592     void save(in string hdf5_file)                            raises (SALOME::SALOME_Exception);
593
594     //!  Save a Salome_file into a hdf5_file.
595     /*!
596       All files that are managed are saved into the hdf5_file
597
598       \param  hdf5_file name (with path) of the hdf5_file.
599
600       \exception contains information of errors if the save doesn't succeed.
601
602     */
603     void save_all(in string hdf5_file)                            raises (SALOME::SALOME_Exception);
604
605 /**************/
606
607     //!  Add a Local file to the Salome_file.
608     /*!
609
610       \param file_name name of the file with the path.
611
612       \exception raised if the file is already added into the Salome_file.
613     */
614     void setLocalFile(in string comp_file_name) raises (SALOME::SALOME_Exception);
615
616     //!  Add a Distributed file to the Salome_file.
617     /*!
618
619       \param comp_file_name name of the file with the path.
620
621       \exception raised if the file is already added into the Salome_file.
622     */
623     void setDistributedFile(in string comp_file_name) raises (SALOME::SALOME_Exception);
624
625     //!  Connect a Salome_file with another Salome_file.
626     /*!
627       It works only if the Salome_file managed only one file
628
629       \param source_Salome_file Salome_file that managed the distributed version of the file.
630
631       \exception raised if there is more or less than one file.
632     */
633     void connect(in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
634
635     //!  Connect the managed file file_name to a Salome_file.
636     /*!
637
638       \param file_name name of the file without the path.
639       \param source_Salome_file Salome_file that managed the distributed version of the file.
640
641       \exception raised if the file doesn't exist.
642     */
643     void connectDistributedFile(in string file_name,
644                                 in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
645
646     //!  Connect the file_name with a Distributed file_name.
647     /*!
648
649       \param file_name name of the file without the path.
650       \param source_file_name It's the name of the file managed by the distributed source Salome_file.
651
652       \exception raised if the file doesn't exist.
653     */
654     void setDistributedSourceFile(in string file_name,
655                                   in string source_file_name) raises (SALOME::SALOME_Exception);
656
657 /**************/
658
659     //! Get all the distributed files managed by the Salome_file and check all the local files.
660     /*!
661
662       \exception raised if some of the files are not ok.
663     */
664     void recvFiles()                                            raises (SALOME::SALOME_Exception) ;
665
666 /**************/
667
668     //!  Remove a file of the Salome_file.
669     /*!
670
671       \param file_name name of the file.
672
673       \exception raised if the file doesn't exist.
674     */
675     void removeFile(in string file_name)                    raises (SALOME::SALOME_Exception);
676
677     //!  Remove all the files of the Salome_file.
678     void removeFiles();
679
680 /**************/
681
682     //! Get the list of the files managed by the Salome_file.
683     /*!
684       The list can be empty.
685     */
686     Engines::files getFilesInfos();
687
688     //! Get a file managed by the Salome_file.
689     /*!
690
691       \param file_name the name of the file.
692
693       \return CORBA file reference.
694
695       \exception raised if the file doesn't exist.
696     */
697     Engines::file  getFileInfos(in string file_name) raises (SALOME::SALOME_Exception);
698
699     //!  Return the state of the Salome_file.
700     Engines::SfState getSalome_fileState();
701
702
703     //! Set the container where files are.
704     /*!
705
706       \param container container CORBA's reference.
707     */
708     void setContainer(in Engines::Container container);
709   };
710
711   /*! \brief Interface of fileRef.
712      The fileTransfer and fileRef interfaces provide a file transfer service
713      between different computers.
714
715      A fileRef object is associated to an original file (origFileName) on a
716      machine (refMachine).
717      It is created by a container (factoryServer) on refMachine,
718      with createFileRef(in string origFileName) method.
719      The fileRef object maintains a list of (machine,filename) for copies.
720      If a copy exists on myMachine, getRef(myMachine) returns the file name
721      of the copy on myMachine, else returns empty string.
722      If there is no copy on myMachine, method getFileTransfer() from container
723      factoryServer on refMachine provides a fileTransfer object dedicated to
724      CORBA file copy.
725      After the copy, addRef(myMachine, localFileNameOnMyMachine) registers
726      the file name of the copy on myMachine.
727   */
728   interface fileRef
729   {
730     //! the original file
731     readonly attribute string origFileName;
732     //! the machine of the original file
733     readonly attribute string refMachine;
734
735     Container getContainer();
736
737     boolean addRef(in string machine,
738                    in string fileName);
739
740     string getRef(in string machine);
741   };
742 };
743
744 #endif