1 // Copyright (C) 2007-2010 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
23 // File : SALOME_Component.idl
24 // Author : Paul RASCLE, EDF
27 #ifndef _SALOME_COMPONENT_IDL_
28 #define _SALOME_COMPONENT_IDL_
30 #include "SALOMEDS.idl"
31 #include "SALOME_Exception.idl"
32 #include "SALOME_PyNode.idl"
34 /*! \file SALOME_Component.idl \brief interfaces for Component and Container
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 %MED
40 component in %SALOME application.
45 A byte stream which is used for binary data transfer between different
48 typedef sequence<octet> TMPFile;
50 //! General Key Value Structure to set or get properties, for component
57 //! Structure data type to hold reference on data
63 typedef sequence<KeyValuePair> FieldsDict;
67 interface fileTransfer ;
68 interface Salome_file;
70 /*! \brief Interface of the %Container.
71 This interface defines the process of loading and registration
72 of new components in %SALOME application
78 /*! \brief Loads a new component class (dynamic library).
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 successfull or already done, false otherwise
86 boolean load_component_Library(in string componentName, out string reason);
88 //! Create a new servant instance of a component.
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 \param studyId 0 if instance is not associated to a study,
95 >0 otherwise (== study id)
96 \return a loaded component
98 Engines::Component create_component_instance(in string componentName,
101 //! Create a new servant instance of a component with environment variables specified.
103 Component library must be loaded.
104 \param componentName Name of the component which will be registered
105 in Registry and Name Service,
106 (instance number suffix added to the registered name)
107 \param studyId 0 if instance is not associated to a study,
108 >0 otherwise (== study id)
109 \param env a dict of env variables
110 \param reason in case of error (return nil) a string explaining the error
111 \return a loaded component
113 Engines::Component create_component_instance_env(in string componentName,
114 in long studyId, in FieldsDict env,
116 //! Find a servant instance of a component
118 \param registeredName Name of the component in Registry or Name Service,
119 without instance suffix number
120 \param studyId 0 if instance is not associated to a study,
121 >0 otherwise (== study id)
122 \return the first instance found with same studyId
124 Component find_component_instance(in string registeredName,
127 //! Find a servant instance of a component, or create a new one.
129 Loads the component library if needed.
130 Only applicable to multiStudy components.
131 \param nameToRegister Name of the component which will be registered
132 in Registry (or Name Service)
133 \param componentName Name of the constructed library of the %component
134 (not used any more, give empty string)
135 \return a loaded component
137 Component load_impl(in string nameToRegister,
138 in string componentName);
140 //! Remove the component servant, and deletes all related objects
142 \param component_i Component to be removed
144 void remove_impl(in Component component_i);
146 //! Unload component libraries from the container.
147 void finalize_removal() ;
149 //! Determines whether the server has been loaded or not.
152 //! Name of the %container
153 readonly attribute string name ;
155 //! working directory of the %container
156 readonly attribute string workingdir ;
158 //! name of the %container log file (this has been set by the launcher)
159 attribute string logfilename ;
161 //! Shutdown the Container process.
164 //! Returns the hostname of the container
165 string getHostName();
167 //! Returns the PID of the container
170 //! Kill the container
172 Returns True if the %container has been killed.
173 Kept for Superv compilation but can't work, unless oneway...
176 boolean Kill_impl() ;
180 returns a fileRef object if origFileName exists and is readable
181 else returns null object. Only one fileRef is created for a given
182 file name, so, several calls with the same file name returns the
185 fileRef createFileRef(in string origFileName);
187 //! Create a Salome_file
189 returns a Salome_file object if origFileName exists and is readable
190 else returns null object.
192 \param origFileName name of the file to be managed (can contain the path).
194 \return Salome_file CORBA reference.
196 Salome_file createSalome_file(in string origFileName);
198 //! Create a fileTransfer
200 returns a fileTransfer object used to copy files from the container
201 machine to the clients machines. Only one fileTransfer instance is
202 created in a container.
204 fileTransfer getFileTransfer();
206 //! Copy a file from a remote host (container) to a local file
208 \param contai the remote container
209 \param remoteFile the file on the remote host to copy
210 \param localFile the local file to create by copy
212 void copyFile(in Container contai, in string remoteFile, in string localFile);
214 //! Create a PyNode in the container
216 \param nodeName the name of the PyNode
217 \param code python code as text to load in the node
219 PyNode createPyNode(in string nodeName, in string code) raises(SALOME::SALOME_Exception);
222 /*! \brief Interface of the %component.
223 This interface is used for interaction between the %container and the
224 %component and between the components inside the container.
228 //! The name of the instance of the %Component
229 readonly attribute string instanceName ;
231 //! The name of the interface of the %Component
232 readonly attribute string interfaceName ;
234 //! Determines whether the server has already been loaded or not.
237 //! Get study associated to component instance
239 get study associated to component instance
240 \return -1: not initialised (Internal Error)
241 0: multistudy component instance
242 >0: study id associated to this instance
246 //! Remove component instance from container
248 Deactivates the %Component.
249 -- TO BE USED BY CONTAINER ONLY (Container housekeeping) --
250 use remove_impl from Container instead !
254 //! Returns the container that the %Component refers to.
255 Container GetContainerRef() ;
257 //! Set component instance properties
259 Gives a sequence of (key=string,value=any) to the component.
260 Base class component stores the sequence in a map.
261 The map is cleared before.
262 This map is for use by derived classes.
264 void setProperties(in FieldsDict dico);
266 //! Get component instance properties
268 returns a previously stored map (key=string,value=any) as a sequence.
269 See setProperties(in FieldsDict dico).
271 FieldsDict getProperties();
273 //! Set name of a node in a graph (for %SUPERVISOR use)
275 This method is used by the %SUPERVISOR component. It sets the names of
276 the graph and of the node.
277 \param aGraphName Name of graph
278 \param aNodeName Name of node
280 void Names( in string aGraphName , in string aNodeName ) ;
282 //! Kill the component (if you can)
284 Returns True if the %Component has been killed.
286 boolean Kill_impl() ;
288 //! Stop the component (if you can)
290 Returns True if the activity of the %Component has been stopped.
291 (It's action can't be resumed)
293 boolean Stop_impl() ;
295 //! Suspend the component
297 Returns True if the activity of the %Component has been suspended.
298 (It's action can be resumed)
300 boolean Suspend_impl() ;
302 //! Resume the component
304 Returns True if the activity of the %Component has been resumed.
306 boolean Resume_impl() ;
312 long CpuUsed_impl() ;
314 //! Get a python dump
316 Returns a python script, which is being played back reproduces
317 the data model of component
319 TMPFile DumpPython(in Object theStudy,
320 in boolean isPublished,
321 out boolean isValidScript);
324 //! Returns a CORBA Ref of a input Salome_file managed by a service.
327 \param service_name service's name.
328 \param file_name name of the requested file.
330 \return CORBA Ref of the requested file.
332 \exception contains informations of what if the component cannot
333 sends the file's reference.
335 Engines::Salome_file getInputFileToService(in string service_name,
336 in string Salome_file_name) raises(SALOME::SALOME_Exception);
338 //! Check service input files (transfer them if needed)
340 This method is used before the activation of the service. It calls
341 recvFiles() on all the input Salome_file files of the service.
343 Before each recvFiles(), it uses the callback method named configureSalome_file.
344 This method allows the user to configure the files managed by the Salome_file.
346 By default, there is no files managed when a Salome_file is created,
347 but the supervisor set some files managed by the Salome_file from the information contained
348 into the schema file.
350 \param service_name service's name.
352 \exception contains informations about files that are not in a good state.
354 void checkInputFilesToService(in string service_name) raises(SALOME::SALOME_Exception);
356 //! This method adds a input Salome_file to a service of the component.
359 \param service_name service's name.
360 \param Salome_file_name name of the Salome_file
362 \return a reference of the Salome_file
364 \exception raises an exception if there is already
365 a Salome_file with this name for the service.
367 Engines::Salome_file setInputFileToService(in string service_name,
368 in string Salome_file_name) raises(SALOME::SALOME_Exception);
370 //! Returns a CORBA Ref of a output Salome_file managed by a service.
373 \param service_name service's name.
374 \param file_name name of the requested file.
376 \return CORBA Ref of the requested file.
378 \exception contains informations of what if the component cannot
379 sends the file's reference.
381 Engines::Salome_file getOutputFileToService(in string service_name,
382 in string Salome_file_name) raises(SALOME::SALOME_Exception);
384 //! Check service output files (transfer them if needed)
386 This method is used at the end of the service. It calls
387 recvFiles() on all the output Salome_file files of the service.
389 Before each recvFiles(), it uses the callback method named configureSalome_file.
390 This method allows the user to configure the files managed by the Salome_file.
392 By default, there is no files managed when a Salome_file is created,
393 but the supervisor set some files managed by the Salome_file from the information contained
394 into the schema file.
396 \param service_name service's name.
398 \exception contains informations about files that are not in a good state.
400 void checkOutputFilesToService(in string service_name) raises(SALOME::SALOME_Exception);
402 //! This method adds an output Salome_file to a service of the component.
405 \param service_name service's name.
406 \param Salome_file_name name of the Salome_file
408 \return a reference of the Salome_file
410 \exception raises an exception if there is already
411 a Salome_file with this name for the service.
413 Engines::Salome_file setOutputFileToService(in string service_name,
414 in string Salome_file_name) raises(SALOME::SALOME_Exception);
416 //! Indicate if the component instance provides custom information about its objects.
418 Returns true if the component provides custom information about its objects, false otherwise.
419 Should be redefined in the certain component to return true in case of this
420 component provides such information.
422 boolean hasObjectInfo();
424 //! Get custom information about the given object.
426 This method is used to get the custom information about the given object.
427 Should be redefined in the certain component in case of this
428 component provides such information.
429 It is worth using this method only if hasObjectInfo() method returns true.
431 \param entry object's entry.
432 \param studyId study id
434 \return an information about the given object.
436 string getObjectInfo(in long studyId, in string entry);
439 //! A block of binary data used for file transfer. The maximum size of the block is defined on server side.
440 typedef sequence<octet> fileBlock;
442 /*! \brief Interface of fileTransfer.
443 The fileTransfer and fileRef interfaces provide a file transfer service
444 between different computers.
446 interface fileTransfer
448 //! Open the file transfer
450 open method returns a key (fileId) that identifies the structure
451 (ex: C FILE), associated to the original file on the server.
452 The structure is created by a container for transfer of files availables
453 on the computer which runs the container.
454 Each open gives a unique fileId, to allow concurrent reads of the same
457 long open(in string fileName);
458 //! Open the file transfer in write mode for file fileName
460 \param fileName the file to copy into with putBlock
461 \return the id to use with putBlock
463 long openW(in string fileName);
465 //! Close the file transfer
467 when the file transfer is finished, close method releases structures
468 created by open method, identified by fileId.
470 void close(in long fileId);
472 //! Get a file data block
474 Get successive blocks of octets from the original file.
475 The last block is empty, and identifies the end of file.
477 fileBlock getBlock(in long fileId);
479 //! Put a file data block
481 \param fileId identification of the file obtained by openW
482 \param block a data block to copy into the file identified by fileId
484 void putBlock(in long fileId, in fileBlock block);
488 //! A file managed by a Salome_file.
495 string source_file_name;
496 //! status ("present" or "notpresent")
499 Engines::Container container;
502 //! A sequence of Engines::file.
503 typedef sequence<Engines::file> files;
506 //! The state of a Salome_file.
510 //! hdf5 file where the file can be saved
511 string hdf5_file_name;
512 //! number of files managed
513 long number_of_files;
514 //! information if all the files are received
519 /*! \brief Interface of a Salome_file managed
520 This file is independent of a Salome module. It can managed one or more
521 real files. It's useful for parallel files. Currently Salome_file cannot manage
522 two files that have the same name but not the same path.
524 interface Salome_file : Engines::fileTransfer
526 //! Load a Salome_file from a hdf5 file.
529 \param hdf5_file name (with path) of the hdf5_file.
531 \exception contains informations of errors if the loading doesn't succeed.
533 void load(in string hdf5_file) raises (SALOME::SALOME_Exception);
535 //! Save a Salome_file into a hdf5_file.
538 \param hdf5_file name (with path) of the hdf5_file.
540 \exception contains informations of errors if the save doesn't succeed.
543 void save(in string hdf5_file) raises (SALOME::SALOME_Exception);
545 //! Save a Salome_file into a hdf5_file.
547 All files that are managed are saved into the hdf5_file
549 \param hdf5_file name (with path) of the hdf5_file.
551 \exception contains informations of errors if the save doesn't succeed.
554 void save_all(in string hdf5_file) raises (SALOME::SALOME_Exception);
558 //! Add a Local file to the Salome_file.
561 \param file_name name of the file with the path.
563 \exception raised if the file is already added into the Salome_file.
565 void setLocalFile(in string comp_file_name) raises (SALOME::SALOME_Exception);
567 //! Add a Distributed file to the Salome_file.
570 \param comp_file_name name of the file with the path.
572 \exception raised if the file is already added into the Salome_file.
574 void setDistributedFile(in string comp_file_name) raises (SALOME::SALOME_Exception);
576 //! Connect a Salome_file with another Salome_file.
578 It works only if the Salome_file managed only one file
580 \param source_Salome_file Salome_file that managed the distributed version of the file.
582 \exception raised if there is more or less than one file.
584 void connect(in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
586 //! Connect the managed file file_name to a Salome_file.
589 \param file_name name of the file without the path.
590 \param source_Salome_file Salome_file that managed the distributed version of the file.
592 \exception raised if the file doesn't exist.
594 void connectDistributedFile(in string file_name,
595 in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
597 //! Connect the file_name with a Distributed file_name.
600 \param file_name name of the file without the path.
601 \param source_file_name It's the name of the file managed by the distributed source Salome_file.
603 \exception raised if the file doesn't exist.
605 void setDistributedSourceFile(in string file_name,
606 in string source_file_name) raises (SALOME::SALOME_Exception);
610 //! Get all the distributed files managed by the Salome_file and check all the local files.
613 \exception raised if some of the files are not ok.
615 void recvFiles() raises (SALOME::SALOME_Exception) ;
619 //! Remove a file of the Salome_file.
622 \param file_name name of the file.
624 \exception raised if the file doesn't exist.
626 void removeFile(in string file_name) raises (SALOME::SALOME_Exception);
628 //! Remove all the files of the Salome_file.
633 //! Get the list of the files managed by the Salome_file.
635 The list can be empty.
637 Engines::files getFilesInfos();
639 //! Get a file managed by the Salome_file.
642 \param file_name the name of the file.
644 \return CORBA file reference.
646 \exception raised if the file doesn't exist.
648 Engines::file getFileInfos(in string file_name) raises (SALOME::SALOME_Exception);
650 //! Return the state of the Salome_file.
651 Engines::SfState getSalome_fileState();
654 //! Set the container where files are.
657 \param container container CORBA's reference.
659 void setContainer(in Engines::Container container);
662 /*! \brief Interface of fileRef.
663 The fileTransfer and fileRef interfaces provide a file transfer service
664 between different computers.
666 A fileRef object is associated to an original file (origFileName) on a
667 machine (refMachine).
668 It is created by a container (factoryServer) on refMachine,
669 with createFileRef(in string origFileName) method.
670 The fileRef object maintains a list of (machine,filename) for copies.
671 If a copy exists on myMachine, getRef(myMachine) returns the file name
672 of the copy on myMachine, else returns empy string.
673 If there is no copy on myMachine, method getFileTransfer() from container
674 factoryServer on refMachine provides a fileTransfer object dedicated to
676 After the copy, addRef(myMachine, localFileNameOnMyMachine) registers
677 the file name of the copy on myMachine.
681 //! the original file
682 readonly attribute string origFileName;
683 //! the machine of the original file
684 readonly attribute string refMachine;
686 Container getContainer();
688 boolean addRef(in string machine,
691 string getRef(in string machine);