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