1 // Copyright (C) 2007-2008 CEA/DEN, EDF R&D, 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.
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
22 // File : SALOME_Component.idl
23 // Author : Paul RASCLE, EDF
26 #ifndef _SALOME_COMPONENT_IDL_
27 #define _SALOME_COMPONENT_IDL_
29 #include "SALOMEDS.idl"
30 #include "SALOME_Exception.idl"
33 This is a package of interfaces used for connecting new components to %SALOME
34 application. It also contains a set of interfaces used for management of %MED
35 component in %SALOME application.
40 A byte stream which is used for binary data transfer between different
43 typedef sequence<octet> TMPFile;
46 General Key Value Structure to set or get properties, for component
54 typedef sequence<KeyValuePair> FieldsDict;
58 interface fileTransfer ;
59 interface Salome_file;
61 /*! \brief Interface of the %Container.
62 This interface defines the process of loading and registration
63 of new components in %SALOME application
70 Loads a new component class (dynamic library).
71 \param componentName like COMPONENT, (Python or C++ implementation)
72 try to make a Python import of COMPONENT,
73 then a lib open of libCOMPONENTEngine.so
74 \return true if load successfull or already done, false otherwise
76 boolean load_component_Library(in string componentName);
79 Creates a new servant instance of a component.
80 Component library must be loaded.
81 \param componentName Name of the component which will be registered
82 in Registry and Name Service,
83 (instance number suffix added to the registered name)
84 \param studyId 0 if instance is not associated to a study,
85 >0 otherwise (== study id)
86 \return a loaded component
88 Engines::Component create_component_instance(in string componentName,
92 Finds a servant instance of a component
93 \param registeredName Name of the component in Registry or Name Service,
94 without instance suffix number
95 \param studyId 0 if instance is not associated to a study,
96 >0 otherwise (== study id)
97 \return the first instance found with same studyId
99 Component find_component_instance(in string registeredName,
103 Find a servant instance of a component, or create a new one.
104 Loads the component library if needed.
105 Only applicable to multiStudy components.
106 \param nameToRegister Name of the component which will be registered
107 in Registry (or Name Service)
108 \param componentName Name of the constructed library of the %component
109 (not used any more, give empty string)
110 \return a loaded component
112 Component load_impl(in string nameToRegister,
113 in string componentName);
116 Stops the component servant, and deletes all related objects
117 \param component_i Component to be removed
119 void remove_impl(in Component component_i);
122 Discharges all components from the container.
124 void finalize_removal() ;
127 Determines whether the server has been loaded or not.
132 Name of the %container
134 readonly attribute string name ;
137 working directory of the %container
139 readonly attribute string workingdir ;
142 name of the %container log file (this has been set by the launcher)
144 attribute string logfilename ;
147 Shutdown the Container process.
152 Returns the hostname of the container
154 string getHostName();
157 Returns the PID of the container
162 Returns True if the %container has been killed.
163 Kept for Superv compilation but can't work, unless oneway...
166 boolean Kill_impl() ;
169 returns a fileRef object if origFileName exists and is readable
170 else returns null object. Only one fileRef is created for a given
171 file name, so, several calls with the same file name returns the
174 fileRef createFileRef(in string origFileName);
177 returns a Salome_file object if origFileName exists and is readable
178 else returns null object.
180 \param origFileName name of the file to be managed (can contain the path).
182 \return Salome_file CORBA reference.
184 Salome_file createSalome_file(in string origFileName);
187 returns a fileTransfer object used to copy files from the container
188 machine to the clients machines. Only one fileTransfer instance is
189 created in a container.
191 fileTransfer getFileTransfer();
195 /*! \brief Interface of the %component.
196 This interface is used for interaction between the %container and the
197 %component and between the components inside the container.
202 The name of the instance of the %Component
204 readonly attribute string instanceName ;
207 The name of the interface of the %Component
209 readonly attribute string interfaceName ;
212 Determines whether the server has already been loaded or not.
217 // Set study associated to component instance
219 // (=0: multistudy component instance,
220 // >0: study id associated to this instance
221 // \return false if already set with a different value (change not possible)
223 // boolean setStudyId(in long studyId);
226 get study associated to component instance
227 \return -1: not initialised (Internal Error)
228 0: multistudy component instance
229 >0: study id associated to this instance
234 Deactivates the %Component.
235 -- TO BE USED BY CONTAINER ONLY (Container housekeeping) --
236 use remove_impl from Container instead !
241 Returns the container that the %Component refers to.
243 Container GetContainerRef() ;
246 Gives a sequence of (key=string,value=any) to the component.
247 Base class component stores the sequence in a map.
248 The map is cleared before.
249 This map is for use by derived classes.
251 void setProperties(in FieldsDict dico);
254 returns a previously stored map (key=string,value=any) as a sequence.
255 See setProperties(in FieldsDict dico).
257 FieldsDict getProperties();
260 This method is used by the %SUPERVISOR component. It sets the names of
261 the graph and of the node.
262 \param aGraphName Name of graph
263 \param aNodeName Name of node
265 void Names( in string aGraphName , in string aNodeName ) ;
268 Returns True if the %Component has been killed.
270 boolean Kill_impl() ;
273 Returns True if the activity of the %Component has been stopped.
274 (It's action can't be resumed)
276 boolean Stop_impl() ;
279 Returns True if the activity of the %Component has been suspended.
280 (It's action can be resumed)
282 boolean Suspend_impl() ;
285 Returns True if the activity of the %Component has been resumed.
287 boolean Resume_impl() ;
290 Returns the Cpu used (long does not run with python !...)
292 long CpuUsed_impl() ;
295 Returns a python script, which is being played back reproduces
296 the data model of component
298 TMPFile DumpPython(in Object theStudy,
299 in boolean isPublished,
300 out boolean isValidScript);
304 Returns a CORBA Ref of a input Salome_file managed by a service.
306 \param service_name service's name.
307 \param file_name name of the requested file.
309 \return CORBA Ref of the requested file.
311 \exception contains informations of what if the component cannot
312 sends the file's reference.
314 Engines::Salome_file getInputFileToService(in string service_name,
315 in string Salome_file_name) raises(SALOME::SALOME_Exception);
318 This method is used before the activation of the service. It calls
319 recvFiles() on all the input Salome_file files of the service.
321 Before each recvFiles(), it uses the callback method named configureSalome_file.
322 This method allows the user to configure the files managed by the Salome_file.
324 By default, there is no files managed when a Salome_file is created,
325 but the supervisor set some files managed by the Salome_file from the information contained
326 into the schema file.
328 \param service_name service's name.
330 \exception contains informations about files that are not in a good state.
332 void checkInputFilesToService(in string service_name) raises(SALOME::SALOME_Exception);
335 This method adds a input Salome_file to a service of the component.
337 \param service_name service's name.
338 \param Salome_file_name name of the Salome_file
340 \return a reference of the Salome_file
342 \exception raises an exception if there is already
343 a Salome_file with this name for the service.
345 Engines::Salome_file setInputFileToService(in string service_name,
346 in string Salome_file_name) raises(SALOME::SALOME_Exception);
349 Returns a CORBA Ref of a output Salome_file managed by a service.
351 \param service_name service's name.
352 \param file_name name of the requested file.
354 \return CORBA Ref of the requested file.
356 \exception contains informations of what if the component cannot
357 sends the file's reference.
359 Engines::Salome_file getOutputFileToService(in string service_name,
360 in string Salome_file_name) raises(SALOME::SALOME_Exception);
363 This method is used at the end of the service. It calls
364 recvFiles() on all the output Salome_file files of the service.
366 Before each recvFiles(), it uses the callback method named configureSalome_file.
367 This method allows the user to configure the files managed by the Salome_file.
369 By default, there is no files managed when a Salome_file is created,
370 but the supervisor set some files managed by the Salome_file from the information contained
371 into the schema file.
373 \param service_name service's name.
375 \exception contains informations about files that are not in a good state.
377 void checkOutputFilesToService(in string service_name) raises(SALOME::SALOME_Exception);
380 This method adds an output Salome_file to a service of the component.
382 \param service_name service's name.
383 \param Salome_file_name name of the Salome_file
385 \return a reference of the Salome_file
387 \exception raises an exception if there is already
388 a Salome_file with this name for the service.
390 Engines::Salome_file setOutputFileToService(in string service_name,
391 in string Salome_file_name) raises(SALOME::SALOME_Exception);
393 Returns true if the component provides custom information about its objects, false otherwise.
394 Should be redefined in the certain component to return true in case of this
395 component provides such information.
397 boolean hasObjectInfo();
400 This method is used to get the custom information about the given object.
401 Should be redefined in the certain component in case of this
402 component provides such information.
403 It is worth using this method only if hasObjectInfo() method returns true.
405 \param entry object's entry.
406 \param studyId study id
408 \return an information about the given object.
410 string getObjectInfo(in long studyId, in string entry);
413 interface Parallel_Component : Engines::Component {
414 void send_parallel_proxy_object(in Object proxy_ref);
418 A block of binary data used for file transfer. The maximum size of the
419 block is defined on server side.
421 typedef sequence<octet> fileBlock;
423 /*! \brief Interface of fileTransfer.
424 The fileTransfer and fileRef interfaces provide a file transfer service
425 between different computers.
427 interface fileTransfer
430 open method returns a key (fileId) that identifies the structure
431 (ex: C FILE), associated to the original file on the server.
432 The structure is created by a container for transfer of files availables
433 on the computer which runs the container.
434 Each open gives a unique fileId, to allow concurrent reads of the same
437 long open(in string fileName);
440 when the file transfer is finished, close method releases structures
441 created by open method, identified by fileId.
443 void close(in long fileId);
446 Get successive blocks of octets from the original file.
447 The last block is empty, and identifies the end of file.
449 fileBlock getBlock(in long fileId);
453 This is a file managed by a Salome_file. It contains file's name, path and status.
454 The status is : "present" or "notpresent".
460 string source_file_name;
463 Engines::Container container;
467 A sequence of Engines::file.
469 typedef sequence<Engines::file> files;
473 It is the state of a Salome_file. It contains the Salome_file's name, the name
474 of the hdf5 file where it can be saved, the number of files managed and the information
475 if all the files are received.
479 string hdf5_file_name;
480 long number_of_files;
484 /*! \brief Interface of a Salome_file managed
485 This file is independent of a Salome module. It can managed one or more
486 real files. It's useful for parallel files. Currently Salome_file cannot manage
487 two files that have the same name but not the same path.
489 interface Salome_file : Engines::fileTransfer
492 Load a Salome_file from a hdf5 file.
494 \param hdf5_file name (with path) of the hdf5_file.
496 \exception contains informations of errors if the loading doesn't succeed.
498 void load(in string hdf5_file) raises (SALOME::SALOME_Exception);
501 Save a Salome_file into a hdf5_file.
503 \param hdf5_file name (with path) of the hdf5_file.
505 \exception contains informations of errors if the save doesn't succeed.
508 void save(in string hdf5_file) raises (SALOME::SALOME_Exception);
511 Save a Salome_file into a hdf5_file. All files that are managed
512 are saved into the hdf5_file
514 \param hdf5_file name (with path) of the hdf5_file.
516 \exception contains informations of errors if the save doesn't succeed.
519 void save_all(in string hdf5_file) raises (SALOME::SALOME_Exception);
524 Add a Local file to the Salome_file.
526 \param file_name name of the file with the path.
528 \exception raised if the file is already added into the Salome_file.
530 void setLocalFile(in string comp_file_name) raises (SALOME::SALOME_Exception);
533 Add a Distributed file to the Salome_file.
535 \param comp_file_name name of the file with the path.
537 \exception raised if the file is already added into the Salome_file.
539 void setDistributedFile(in string comp_file_name) raises (SALOME::SALOME_Exception);
542 Connect a Salome_file with another Salome_file.
543 It works only if the Salome_file managed only one file
545 \param source_Salome_file Salome_file that managed the distributed version of the file.
547 \exception raised if there is more or less than one file.
549 void connect(in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
552 Connect the managed file file_name to a Salome_file.
554 \param file_name name of the file without the path.
555 \param source_Salome_file Salome_file that managed the distributed version of the file.
557 \exception raised if the file doesn't exist.
559 void connectDistributedFile(in string file_name,
560 in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
563 Connect the file_name with a Distributed file_name.
565 \param file_name name of the file without the path.
566 \param source_file_name It's the name of the file managed by the distributed source Salome_file.
568 \exception raised if the file doesn't exist.
570 void setDistributedSourceFile(in string file_name,
571 in string source_file_name) raises (SALOME::SALOME_Exception);
576 Get all the distributed files managed by the Salome_file and
577 check all the local files.
579 \exception raised if some of the files are not ok.
581 void recvFiles() raises (SALOME::SALOME_Exception) ;
586 Remove a file of the Salome_file.
588 \param file_name name of the file.
590 \exception raised if the file doesn't exist.
592 void removeFile(in string file_name) raises (SALOME::SALOME_Exception);
595 Remove all the files of the Salome_file.
602 Get the list of the files managed by the Salome_file.
603 The list can be empty.
605 Engines::files getFilesInfos();
608 Get a file managed by the Salome_file.
610 \param file_name the name of the file.
612 \return CORBA file reference.
614 \exception raised if the file doesn't exist.
616 Engines::file getFileInfos(in string file_name) raises (SALOME::SALOME_Exception);
619 Return the state of the Salome_file.
621 Engines::SfState getSalome_fileState();
625 Set the container where files are.
627 \param container container CORBA's reference.
629 void setContainer(in Engines::Container container);
632 /*! \brief Interface of fileRef.
633 The fileTransfer and fileRef interfaces provide a file transfer service
634 between different computers.
636 A fileRef object is associated to an original file (origFileName) on a
637 machine (refMachine).
638 It is created by a container (factoryServer) on refMachine,
639 with createFileRef(in string origFileName) method.
640 The fileRef object maintains a list of (machine,filename) for copies.
641 If a copy exists on myMachine, getRef(myMachine) returns the file name
642 of the copy on myMachine, else returns empy string.
643 If there is no copy on myMachine, method getFileTransfer() from container
644 factoryServer on refMachine provides a fileTransfer object dedicated to
646 After the copy, addRef(myMachine, localFileNameOnMyMachine) registers
647 the file name of the copy on myMachine.
651 readonly attribute string origFileName;
652 readonly attribute string refMachine;
654 Container getContainer();
656 boolean addRef(in string machine,
659 string getRef(in string machine);
662 /*! \brief Interface of a Parallel_Salome_file
663 This interface is used by parallel components and containers.
664 It adds methods to enable to choose on which node of the parallel component the file has to
667 interface Parallel_Salome_file : Engines::Salome_file {
670 Set a number of node for the file. Default is the node 0.
672 \param file_name name of the file.
673 \param node_nbr node number where the file is.
675 \exception raised if the file doesn't exist.
677 void setFileNode(in string file_name, in long node_nbr) raises (SALOME::SALOME_Exception);
680 Get the number of the node that actually managed the file.
682 \param file_name name of managed file.
684 \return node number of the file
686 \exception raised if the file doesn't exist.
688 long getFileNode(in string file_name) raises (SALOME::SALOME_Exception);
691 This method update the state of file for the Parallel_Salome_file.
693 \param new_file the new state of file.
695 Engines::Container updateFile(in Engines::file new_file);
698 This method is used by the parallel implementation of recvFiles.
700 \exception raised if the file cannot be ok.
702 void recvFiles_node() raises (SALOME::SALOME_Exception);