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"
32 /*! \file SALOME_Component.idl \brief interfaces for Component and Container
36 This is a package of interfaces used for connecting new components to %SALOME
37 application. It also contains a set of interfaces used for management of %MED
38 component in %SALOME application.
43 A byte stream which is used for binary data transfer between different
46 typedef sequence<octet> TMPFile;
48 //! General Key Value Structure to set or get properties, for component
55 typedef sequence<KeyValuePair> FieldsDict;
59 interface fileTransfer ;
60 interface Salome_file;
62 /*! \brief Interface of the %Container.
63 This interface defines the process of loading and registration
64 of new components in %SALOME application
70 /*! \brief Loads a new component class (dynamic library).
72 \param componentName like COMPONENT, (Python or C++ implementation)
73 try to make a Python import of COMPONENT,
74 then a lib open of libCOMPONENTEngine.so
75 \return true if load successfull or already done, false otherwise
77 boolean load_component_Library(in string componentName);
79 //! Create a new servant instance of a component.
81 Component library must be loaded.
82 \param componentName Name of the component which will be registered
83 in Registry and Name Service,
84 (instance number suffix added to the registered name)
85 \param studyId 0 if instance is not associated to a study,
86 >0 otherwise (== study id)
87 \return a loaded component
89 Engines::Component create_component_instance(in string componentName,
92 //! Find a servant instance of a component
94 \param registeredName Name of the component in Registry or Name Service,
95 without instance suffix number
96 \param studyId 0 if instance is not associated to a study,
97 >0 otherwise (== study id)
98 \return the first instance found with same studyId
100 Component find_component_instance(in string registeredName,
103 //! Find a servant instance of a component, or create a new one.
105 Loads the component library if needed.
106 Only applicable to multiStudy components.
107 \param nameToRegister Name of the component which will be registered
108 in Registry (or Name Service)
109 \param componentName Name of the constructed library of the %component
110 (not used any more, give empty string)
111 \return a loaded component
113 Component load_impl(in string nameToRegister,
114 in string componentName);
116 //! Remove the component servant, and deletes all related objects
118 \param component_i Component to be removed
120 void remove_impl(in Component component_i);
122 //! Unload component libraries from the container.
123 void finalize_removal() ;
125 //! Determines whether the server has been loaded or not.
128 //! Name of the %container
129 readonly attribute string name ;
131 //! working directory of the %container
132 readonly attribute string workingdir ;
134 //! name of the %container log file (this has been set by the launcher)
135 attribute string logfilename ;
137 //! Shutdown the Container process.
140 //! Returns the hostname of the container
141 string getHostName();
143 //! Returns the PID of the container
146 //! Kill the container
148 Returns True if the %container has been killed.
149 Kept for Superv compilation but can't work, unless oneway...
152 boolean Kill_impl() ;
156 returns a fileRef object if origFileName exists and is readable
157 else returns null object. Only one fileRef is created for a given
158 file name, so, several calls with the same file name returns the
161 fileRef createFileRef(in string origFileName);
163 //! Create a Salome_file
165 returns a Salome_file object if origFileName exists and is readable
166 else returns null object.
168 \param origFileName name of the file to be managed (can contain the path).
170 \return Salome_file CORBA reference.
172 Salome_file createSalome_file(in string origFileName);
174 //! Create a fileTransfer
176 returns a fileTransfer object used to copy files from the container
177 machine to the clients machines. Only one fileTransfer instance is
178 created in a container.
180 fileTransfer getFileTransfer();
184 /*! \brief Interface of the %component.
185 This interface is used for interaction between the %container and the
186 %component and between the components inside the container.
190 //! The name of the instance of the %Component
191 readonly attribute string instanceName ;
193 //! The name of the interface of the %Component
194 readonly attribute string interfaceName ;
196 //! Determines whether the server has already been loaded or not.
200 // Set study associated to component instance
202 // (=0: multistudy component instance,
203 // >0: study id associated to this instance
204 // \return false if already set with a different value (change not possible)
206 // boolean setStudyId(in long studyId);
208 //! Get study associated to component instance
210 get study associated to component instance
211 \return -1: not initialised (Internal Error)
212 0: multistudy component instance
213 >0: study id associated to this instance
217 //! Remove component instance from container
219 Deactivates the %Component.
220 -- TO BE USED BY CONTAINER ONLY (Container housekeeping) --
221 use remove_impl from Container instead !
225 //! Returns the container that the %Component refers to.
226 Container GetContainerRef() ;
228 //! Set component instance properties
230 Gives a sequence of (key=string,value=any) to the component.
231 Base class component stores the sequence in a map.
232 The map is cleared before.
233 This map is for use by derived classes.
235 void setProperties(in FieldsDict dico);
237 //! Get component instance properties
239 returns a previously stored map (key=string,value=any) as a sequence.
240 See setProperties(in FieldsDict dico).
242 FieldsDict getProperties();
244 //! Set name of a node in a graph (for %SUPERVISOR use)
246 This method is used by the %SUPERVISOR component. It sets the names of
247 the graph and of the node.
248 \param aGraphName Name of graph
249 \param aNodeName Name of node
251 void Names( in string aGraphName , in string aNodeName ) ;
253 //! Kill the component (if you can)
255 Returns True if the %Component has been killed.
257 boolean Kill_impl() ;
259 //! Stop the component (if you can)
261 Returns True if the activity of the %Component has been stopped.
262 (It's action can't be resumed)
264 boolean Stop_impl() ;
266 //! Suspend the component
268 Returns True if the activity of the %Component has been suspended.
269 (It's action can be resumed)
271 boolean Suspend_impl() ;
273 //! Resume the component
275 Returns True if the activity of the %Component has been resumed.
277 boolean Resume_impl() ;
283 long CpuUsed_impl() ;
285 //! Get a python dump
287 Returns a python script, which is being played back reproduces
288 the data model of component
290 TMPFile DumpPython(in Object theStudy,
291 in boolean isPublished,
292 out boolean isValidScript);
295 //! Returns a CORBA Ref of a input Salome_file managed by a service.
298 \param service_name service's name.
299 \param file_name name of the requested file.
301 \return CORBA Ref of the requested file.
303 \exception contains informations of what if the component cannot
304 sends the file's reference.
306 Engines::Salome_file getInputFileToService(in string service_name,
307 in string Salome_file_name) raises(SALOME::SALOME_Exception);
309 //! Check service input files (transfer them if needed)
311 This method is used before the activation of the service. It calls
312 recvFiles() on all the input Salome_file files of the service.
314 Before each recvFiles(), it uses the callback method named configureSalome_file.
315 This method allows the user to configure the files managed by the Salome_file.
317 By default, there is no files managed when a Salome_file is created,
318 but the supervisor set some files managed by the Salome_file from the information contained
319 into the schema file.
321 \param service_name service's name.
323 \exception contains informations about files that are not in a good state.
325 void checkInputFilesToService(in string service_name) raises(SALOME::SALOME_Exception);
327 //! This method adds a input Salome_file to a service of the component.
330 \param service_name service's name.
331 \param Salome_file_name name of the Salome_file
333 \return a reference of the Salome_file
335 \exception raises an exception if there is already
336 a Salome_file with this name for the service.
338 Engines::Salome_file setInputFileToService(in string service_name,
339 in string Salome_file_name) raises(SALOME::SALOME_Exception);
341 //! Returns a CORBA Ref of a output Salome_file managed by a service.
344 \param service_name service's name.
345 \param file_name name of the requested file.
347 \return CORBA Ref of the requested file.
349 \exception contains informations of what if the component cannot
350 sends the file's reference.
352 Engines::Salome_file getOutputFileToService(in string service_name,
353 in string Salome_file_name) raises(SALOME::SALOME_Exception);
355 //! Check service output files (transfer them if needed)
357 This method is used at the end of the service. It calls
358 recvFiles() on all the output Salome_file files of the service.
360 Before each recvFiles(), it uses the callback method named configureSalome_file.
361 This method allows the user to configure the files managed by the Salome_file.
363 By default, there is no files managed when a Salome_file is created,
364 but the supervisor set some files managed by the Salome_file from the information contained
365 into the schema file.
367 \param service_name service's name.
369 \exception contains informations about files that are not in a good state.
371 void checkOutputFilesToService(in string service_name) raises(SALOME::SALOME_Exception);
373 //! This method adds an output Salome_file to a service of the component.
376 \param service_name service's name.
377 \param Salome_file_name name of the Salome_file
379 \return a reference of the Salome_file
381 \exception raises an exception if there is already
382 a Salome_file with this name for the service.
384 Engines::Salome_file setOutputFileToService(in string service_name,
385 in string Salome_file_name) raises(SALOME::SALOME_Exception);
387 //! Indicate if the component instance provides custom information about its objects.
389 Returns true if the component provides custom information about its objects, false otherwise.
390 Should be redefined in the certain component to return true in case of this
391 component provides such information.
393 boolean hasObjectInfo();
395 //! Get custom information about the given object.
397 This method is used to get the custom information about the given object.
398 Should be redefined in the certain component in case of this
399 component provides such information.
400 It is worth using this method only if hasObjectInfo() method returns true.
402 \param entry object's entry.
403 \param studyId study id
405 \return an information about the given object.
407 string getObjectInfo(in long studyId, in string entry);
410 interface Parallel_Component : Engines::Component {
411 void send_parallel_proxy_object(in Object proxy_ref);
414 //! A block of binary data used for file transfer. The maximum size of the block is defined on server side.
415 typedef sequence<octet> fileBlock;
417 /*! \brief Interface of fileTransfer.
418 The fileTransfer and fileRef interfaces provide a file transfer service
419 between different computers.
421 interface fileTransfer
423 //! Open the file transfer
425 open method returns a key (fileId) that identifies the structure
426 (ex: C FILE), associated to the original file on the server.
427 The structure is created by a container for transfer of files availables
428 on the computer which runs the container.
429 Each open gives a unique fileId, to allow concurrent reads of the same
432 long open(in string fileName);
434 //! Close the file transfer
436 when the file transfer is finished, close method releases structures
437 created by open method, identified by fileId.
439 void close(in long fileId);
441 //! Get a file data block
443 Get successive blocks of octets from the original file.
444 The last block is empty, and identifies the end of file.
446 fileBlock getBlock(in long fileId);
449 //! A file managed by a Salome_file.
456 string source_file_name;
457 //! status ("present" or "notpresent")
460 Engines::Container container;
463 //! A sequence of Engines::file.
464 typedef sequence<Engines::file> files;
467 //! The state of a Salome_file.
471 //! hdf5 file where the file can be saved
472 string hdf5_file_name;
473 //! number of files managed
474 long number_of_files;
475 //! information if all the files are received
480 /*! \brief Interface of a Salome_file managed
481 This file is independent of a Salome module. It can managed one or more
482 real files. It's useful for parallel files. Currently Salome_file cannot manage
483 two files that have the same name but not the same path.
485 interface Salome_file : Engines::fileTransfer
487 //! Load a Salome_file from a hdf5 file.
490 \param hdf5_file name (with path) of the hdf5_file.
492 \exception contains informations of errors if the loading doesn't succeed.
494 void load(in string hdf5_file) raises (SALOME::SALOME_Exception);
496 //! Save a Salome_file into a hdf5_file.
499 \param hdf5_file name (with path) of the hdf5_file.
501 \exception contains informations of errors if the save doesn't succeed.
504 void save(in string hdf5_file) raises (SALOME::SALOME_Exception);
506 //! Save a Salome_file into a hdf5_file.
508 All files that are managed are saved into the hdf5_file
510 \param hdf5_file name (with path) of the hdf5_file.
512 \exception contains informations of errors if the save doesn't succeed.
515 void save_all(in string hdf5_file) raises (SALOME::SALOME_Exception);
519 //! Add a Local file to the Salome_file.
522 \param file_name name of the file with the path.
524 \exception raised if the file is already added into the Salome_file.
526 void setLocalFile(in string comp_file_name) raises (SALOME::SALOME_Exception);
528 //! Add a Distributed file to the Salome_file.
531 \param comp_file_name name of the file with the path.
533 \exception raised if the file is already added into the Salome_file.
535 void setDistributedFile(in string comp_file_name) raises (SALOME::SALOME_Exception);
537 //! Connect a Salome_file with another Salome_file.
539 It works only if the Salome_file managed only one file
541 \param source_Salome_file Salome_file that managed the distributed version of the file.
543 \exception raised if there is more or less than one file.
545 void connect(in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
547 //! Connect the managed file file_name to a Salome_file.
550 \param file_name name of the file without the path.
551 \param source_Salome_file Salome_file that managed the distributed version of the file.
553 \exception raised if the file doesn't exist.
555 void connectDistributedFile(in string file_name,
556 in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
558 //! Connect the file_name with a Distributed file_name.
561 \param file_name name of the file without the path.
562 \param source_file_name It's the name of the file managed by the distributed source Salome_file.
564 \exception raised if the file doesn't exist.
566 void setDistributedSourceFile(in string file_name,
567 in string source_file_name) raises (SALOME::SALOME_Exception);
571 //! Get all the distributed files managed by the Salome_file and check all the local files.
574 \exception raised if some of the files are not ok.
576 void recvFiles() raises (SALOME::SALOME_Exception) ;
580 //! Remove a file of the Salome_file.
583 \param file_name name of the file.
585 \exception raised if the file doesn't exist.
587 void removeFile(in string file_name) raises (SALOME::SALOME_Exception);
589 //! Remove all the files of the Salome_file.
594 //! Get the list of the files managed by the Salome_file.
596 The list can be empty.
598 Engines::files getFilesInfos();
600 //! Get a file managed by the Salome_file.
603 \param file_name the name of the file.
605 \return CORBA file reference.
607 \exception raised if the file doesn't exist.
609 Engines::file getFileInfos(in string file_name) raises (SALOME::SALOME_Exception);
611 //! Return the state of the Salome_file.
612 Engines::SfState getSalome_fileState();
615 //! Set the container where files are.
618 \param container container CORBA's reference.
620 void setContainer(in Engines::Container container);
623 /*! \brief Interface of fileRef.
624 The fileTransfer and fileRef interfaces provide a file transfer service
625 between different computers.
627 A fileRef object is associated to an original file (origFileName) on a
628 machine (refMachine).
629 It is created by a container (factoryServer) on refMachine,
630 with createFileRef(in string origFileName) method.
631 The fileRef object maintains a list of (machine,filename) for copies.
632 If a copy exists on myMachine, getRef(myMachine) returns the file name
633 of the copy on myMachine, else returns empy string.
634 If there is no copy on myMachine, method getFileTransfer() from container
635 factoryServer on refMachine provides a fileTransfer object dedicated to
637 After the copy, addRef(myMachine, localFileNameOnMyMachine) registers
638 the file name of the copy on myMachine.
642 //! the original file
643 readonly attribute string origFileName;
644 //! the machine of the original file
645 readonly attribute string refMachine;
647 Container getContainer();
649 boolean addRef(in string machine,
652 string getRef(in string machine);
655 /*! \brief Interface of a Parallel_Salome_file
656 This interface is used by parallel components and containers.
657 It adds methods to enable to choose on which node of the parallel component the file has to
660 interface Parallel_Salome_file : Engines::Salome_file {
663 Set a number of node for the file. Default is the node 0.
665 \param file_name name of the file.
666 \param node_nbr node number where the file is.
668 \exception raised if the file doesn't exist.
670 void setFileNode(in string file_name, in long node_nbr) raises (SALOME::SALOME_Exception);
673 Get the number of the node that actually managed the file.
675 \param file_name name of managed file.
677 \return node number of the file
679 \exception raised if the file doesn't exist.
681 long getFileNode(in string file_name) raises (SALOME::SALOME_Exception);
684 This method update the state of file for the Parallel_Salome_file.
686 \param new_file the new state of file.
688 Engines::Container updateFile(in Engines::file new_file);
691 This method is used by the parallel implementation of recvFiles.
693 \exception raised if the file cannot be ok.
695 void recvFiles_node() raises (SALOME::SALOME_Exception);