1 // Copyright (C) 2007-2015 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, or (at your option) any later version.
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
25 #ifndef _SALOME_COMPONENT_IDL_
26 #define _SALOME_COMPONENT_IDL_
28 #include "SALOME_GenericObj.idl"
29 #include "SALOMEDS.idl"
30 #include "SALOME_Exception.idl"
31 #include "SALOME_PyNode.idl"
33 /*! \file SALOME_Component.idl \brief interfaces for EngineComponent and Container
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.
44 A byte stream which is used for binary data transfer between different
47 typedef sequence<octet> TMPFile;
49 //! General Key Value Structure to set or get properties, for component
56 //! Structure data type to hold reference on data
62 typedef sequence<KeyValuePair> FieldsDict;
63 typedef sequence<string> ListOfOptions;
64 typedef sequence<string> ListOfIdentifiers;
66 interface EngineComponent ;
68 interface fileTransfer ;
69 interface Salome_file;
70 interface DataContainer;
72 typedef sequence<DataContainer> ListOfData;
74 /*! \brief Interface of the %Container.
75 This interface defines the process of loading and registration
76 of new components in %SALOME application
82 /*! \brief Loads a new component class (dynamic library).
84 \param componentName like COMPONENT, (Python or C++ implementation)
85 try to make a Python import of COMPONENT,
86 then a lib open of libCOMPONENTEngine.so
87 \param reason in case of error (return false) a string explaining the error
88 \return true if load successfull or already done, false otherwise
90 boolean load_component_Library(in string componentName, out string reason);
92 //! Create a new servant instance of a component.
94 Component library must be loaded.
95 \param componentName Name of the component which will be registered
96 in Registry and Name Service,
97 (instance number suffix added to the registered name)
98 \param studyId 0 if instance is not associated to a study,
99 >0 otherwise (== study id)
100 \return a loaded component
102 Engines::EngineComponent create_component_instance(in string componentName,
105 //! Create a new Python servant instance of a generic service.
107 This simply loads the service in the current container by importing the
108 corresponding Python module.
109 Warning: no internal registration is done, so it is up to the caller to
110 manage the various instanciation.
111 \param serviceName Name of the service
113 >0 otherwise (== study id)
114 \param reason in case of error (return void string) a string explaining the error
115 \return the IOR of the loaded service.
117 string create_python_service_instance(in string serviceName,
120 //! Create a new servant instance of a component with environment variables specified.
122 Component library must be loaded.
123 \param componentName Name of the component which will be registered
124 in Registry and Name Service,
125 (instance number suffix added to the registered name)
126 \param studyId 0 if instance is not associated to a study,
127 >0 otherwise (== study id)
128 \param env a dict of env variables
129 \param reason in case of error (return nil) a string explaining the error
130 \return a loaded component
132 Engines::EngineComponent create_component_instance_env(in string componentName,
133 in long studyId, in FieldsDict env,
135 //! Find a servant instance of a component
137 \param registeredName Name of the component in Registry or Name Service,
138 without instance suffix number
139 \param studyId 0 if instance is not associated to a study,
140 >0 otherwise (== study id)
141 \return the first instance found with same studyId
143 EngineComponent find_component_instance(in string registeredName,
146 //! Find a servant instance of a component, or create a new one.
148 Loads the component library if needed.
149 Only applicable to multiStudy components.
150 \param nameToRegister Name of the component which will be registered
151 in Registry (or Name Service)
152 \param componentName Name of the constructed library of the %component
153 (not used any more, give empty string)
154 \return a loaded component
156 EngineComponent load_impl(in string nameToRegister,
157 in string componentName);
159 //! Remove the component servant, and deletes all related objects
161 \param component_i Component to be removed
163 void remove_impl(in EngineComponent component_i);
165 //! Unload component libraries from the container.
166 void finalize_removal() ;
168 //! Determines whether the server has been loaded or not.
171 //! Name of the %container
172 readonly attribute string name ;
174 //! working directory of the %container
175 readonly attribute string workingdir ;
177 //! name of the %container log file (this has been set by the launcher)
178 attribute string logfilename ;
180 //! Shutdown the Container process.
183 //! Returns the hostname of the container
184 string getHostName();
186 //! Returns the PID of the container
189 //! Kill the container
191 Returns True if the %container has been killed.
192 Kept for Superv compilation but can't work, unless oneway...
195 boolean Kill_impl() ;
199 returns a fileRef object if origFileName exists and is readable
200 else returns null object. Only one fileRef is created for a given
201 file name, so, several calls with the same file name returns the
204 fileRef createFileRef(in string origFileName);
206 //! Create a Salome_file
208 returns a Salome_file object if origFileName exists and is readable
209 else returns null object.
211 \param origFileName name of the file to be managed (can contain the path).
213 \return Salome_file CORBA reference.
215 Salome_file createSalome_file(in string origFileName);
217 //! Create a fileTransfer
219 returns a fileTransfer object used to copy files from the container
220 machine to the clients machines. Only one fileTransfer instance is
221 created in a container.
223 fileTransfer getFileTransfer();
225 //! Copy a file from a remote host (container) to a local file
227 \param contai the remote container
228 \param remoteFile the file on the remote host to copy
229 \param localFile the local file to create by copy
231 void copyFile(in Container contai, in string remoteFile, in string localFile);
233 //! Create a PyNode in the container
235 \param nodeName the name of the PyNode
236 \param code python code as text to load in the node
238 PyNode createPyNode(in string nodeName, in string code) raises(SALOME::SALOME_Exception);
240 //! Retrieves the last created PyNode instance with createPyNode.
241 PyNode getDefaultPyNode();
243 //! Create a PyScriptNode in the container
245 \param nodeName the name of the PyScriptNode
246 \param code python code as text to load in the node
248 PyScriptNode createPyScriptNode(in string nodeName, in string code) raises(SALOME::SALOME_Exception);
250 //! Retrieves the last created PyScriptNode instance with createPyScriptNode.
251 PyScriptNode getDefaultPyScriptNode();
254 /*! \brief Interface to pass data files from the client side to the SALOME Container.
255 Passes data from client side to the SALOME container (where component engine is running)
256 size via the CORBA bus as a stream of bytes.
259 interface DataContainer
261 //! This operation returns the stream with the data file content.
264 //! Returns the name of the document corresponding to this data container.
267 //! Returns the identifier of the document corresponding to this data container.
270 //! Returns the extension (type) of the document corresponding to this data container.
271 //! It is taked from the SIMAN URL.
274 //! Defines the extension. It is required is extension of the file is not
275 //! matched with a read extension: archived file, for example.
276 void setExtension(in string extension);
280 /*! \brief Interface of the %component.
281 This interface is used for interaction between the %container and the
282 %component and between the components inside the container.
284 interface EngineComponent
286 //! The name of the instance of the %Component
287 readonly attribute string instanceName ;
289 //! The name of the interface of the %Component
290 readonly attribute string interfaceName ;
292 //! Determines whether the server has already been loaded or not.
295 //! Get study associated to component instance
297 get study associated to component instance
298 \return -1: not initialised (Internal Error)
299 0: multistudy component instance
300 >0: study id associated to this instance
304 //! Remove component instance from container
306 Deactivates the %Component.
307 -- TO BE USED BY CONTAINER ONLY (Container housekeeping) --
308 use remove_impl from Container instead !
312 //! Returns the container that the %Component refers to.
313 Container GetContainerRef() ;
315 //! Set component instance properties
317 Gives a sequence of (key=string,value=any) to the component.
318 Base class component stores the sequence in a map.
319 The map is cleared before.
320 This map is for use by derived classes.
322 void setProperties(in FieldsDict dico);
324 //! Get component instance properties
326 returns a previously stored map (key=string,value=any) as a sequence.
327 See setProperties(in FieldsDict dico).
329 FieldsDict getProperties();
331 //! Set an option value
333 This method is to set an option specific to a certain EngineComponent.
335 void SetOption(in string optionName, in string value);
337 //! Return an option value
339 This method is to get value of an option specific to a certain EngineComponent.
341 string GetOption(in string optionName);
343 //! Set name of a node in a graph (for %SUPERVISOR use)
345 This method is used by the %SUPERVISOR component. It sets the names of
346 the graph and of the node.
347 \param aGraphName Name of graph
348 \param aNodeName Name of node
350 void Names( in string aGraphName , in string aNodeName ) ;
352 //! Kill the component (if you can)
354 Returns True if the %Component has been killed.
356 boolean Kill_impl() ;
358 //! Stop the component (if you can)
360 Returns True if the activity of the %Component has been stopped.
361 (It's action can't be resumed)
363 boolean Stop_impl() ;
365 //! Suspend the component
367 Returns True if the activity of the %Component has been suspended.
368 (It's action can be resumed)
370 boolean Suspend_impl() ;
372 //! Resume the component
374 Returns True if the activity of the %Component has been resumed.
376 boolean Resume_impl() ;
382 long CpuUsed_impl() ;
384 //! Get a python dump
386 Returns a python script, which is being played back reproduces
387 the data model of component
389 TMPFile DumpPython(in Object theStudy,
390 in boolean isPublished,
391 in boolean isMultiFile,
392 out boolean isValidScript);
395 //! Returns a CORBA Ref of a input Salome_file managed by a service.
398 \param service_name service's name.
399 \param file_name name of the requested file.
401 \return CORBA Ref of the requested file.
403 \exception contains informations of what if the component cannot
404 sends the file's reference.
406 Engines::Salome_file getInputFileToService(in string service_name,
407 in string Salome_file_name) raises(SALOME::SALOME_Exception);
409 //! Check service input files (transfer them if needed)
411 This method is used before the activation of the service. It calls
412 recvFiles() on all the input Salome_file files of the service.
414 Before each recvFiles(), it uses the callback method named configureSalome_file.
415 This method allows the user to configure the files managed by the Salome_file.
417 By default, there is no files managed when a Salome_file is created,
418 but the supervisor set some files managed by the Salome_file from the information contained
419 into the schema file.
421 \param service_name service's name.
423 \exception contains informations about files that are not in a good state.
425 void checkInputFilesToService(in string service_name) raises(SALOME::SALOME_Exception);
427 //! This method adds a input Salome_file to a service of the component.
430 \param service_name service's name.
431 \param Salome_file_name name of the Salome_file
433 \return a reference of the Salome_file
435 \exception raises an exception if there is already
436 a Salome_file with this name for the service.
438 Engines::Salome_file setInputFileToService(in string service_name,
439 in string Salome_file_name) raises(SALOME::SALOME_Exception);
441 //! Returns a CORBA Ref of a output Salome_file managed by a service.
444 \param service_name service's name.
445 \param file_name name of the requested file.
447 \return CORBA Ref of the requested file.
449 \exception contains informations of what if the component cannot
450 sends the file's reference.
452 Engines::Salome_file getOutputFileToService(in string service_name,
453 in string Salome_file_name) raises(SALOME::SALOME_Exception);
455 //! Check service output files (transfer them if needed)
457 This method is used at the end of the service. It calls
458 recvFiles() on all the output Salome_file files of the service.
460 Before each recvFiles(), it uses the callback method named configureSalome_file.
461 This method allows the user to configure the files managed by the Salome_file.
463 By default, there is no files managed when a Salome_file is created,
464 but the supervisor set some files managed by the Salome_file from the information contained
465 into the schema file.
467 \param service_name service's name.
469 \exception contains informations about files that are not in a good state.
471 void checkOutputFilesToService(in string service_name) raises(SALOME::SALOME_Exception);
473 //! This method adds an output Salome_file to a service of the component.
476 \param service_name service's name.
477 \param Salome_file_name name of the Salome_file
479 \return a reference of the Salome_file
481 \exception raises an exception if there is already
482 a Salome_file with this name for the service.
484 Engines::Salome_file setOutputFileToService(in string service_name,
485 in string Salome_file_name) raises(SALOME::SALOME_Exception);
487 //! Indicate if the component instance provides custom information about its objects.
489 Returns true if the component provides custom information about its objects, false otherwise.
490 Should be redefined in the certain component to return true in case of this
491 component provides such information.
493 boolean hasObjectInfo();
495 //! Get custom information about the given object.
497 This method is used to get the custom information about the given object.
498 Should be redefined in the certain component in case of this
499 component provides such information.
500 It is worth using this method only if hasObjectInfo() method returns true.
502 \param entry object's entry.
503 \param studyId study id
505 \return an information about the given object.
507 string getObjectInfo(in long studyId, in string entry);
509 //! Get version of the component
511 This method is supposed to be implemented in all derived classes; default implementation
512 returns "unknown" string that means that no version information about the component is available.
513 \note The version of the component is stored to the study, as a part of general persistence
514 mechanism; once stored, version information in the study cannot be changed.
516 \return string containing component's version, e.g. "1.0"
520 //! Generic Import operation to let the component to import data, corresponding to it.
522 \param studyId indentifier of the study where the data must be placed
523 \param data data for import: usually this is just imported file content
524 \param options additional options for Importat operation
525 \return the sequence of identifiers of the importedData in the component (to use later in the export function)
527 ListOfIdentifiers importData(in long studyId, in DataContainer data, in ListOfOptions options);
529 //! Generic Export operation to ket the component export all modified data corresponding to it.
531 \param studyId identifier of the study that contains the exported data
533 ListOfData getModifiedData(in long studyId);
537 \brief Base interface of the %component that supports exporting data.
539 interface ImportableComponent
541 /*! \brief Get a list of supported formats */
542 SALOME::StringSeq GetImportableFormats();
543 boolean ImportDataAs(in string format, in SALOME::GenericObj exporter);
546 //! A block of binary data used for file transfer. The maximum size of the block is defined on server side.
547 typedef sequence<octet> fileBlock;
549 /*! \brief Interface of fileTransfer.
550 The fileTransfer and fileRef interfaces provide a file transfer service
551 between different computers.
553 interface fileTransfer : SALOME::GenericObj
555 //! Open the file transfer
557 open method returns a key (fileId) that identifies the structure
558 (ex: C FILE), associated to the original file on the server.
559 The structure is created by a container for transfer of files availables
560 on the computer which runs the container.
561 Each open gives a unique fileId, to allow concurrent reads of the same
564 long open(in string fileName);
565 //! Open the file transfer in write mode for file fileName
567 \param fileName the file to copy into with putBlock
568 \return the id to use with putBlock
570 long openW(in string fileName);
572 //! Close the file transfer
574 when the file transfer is finished, close method releases structures
575 created by open method, identified by fileId.
577 void close(in long fileId);
579 //! Get a file data block
581 Get successive blocks of octets from the original file.
582 The last block is empty, and identifies the end of file.
584 fileBlock getBlock(in long fileId);
586 //! Put a file data block
588 \param fileId identification of the file obtained by openW
589 \param block a data block to copy into the file identified by fileId
591 void putBlock(in long fileId, in fileBlock block);
595 //! A file managed by a Salome_file.
602 string source_file_name;
603 //! status ("present" or "notpresent")
606 Engines::Container container;
609 //! A sequence of Engines::file.
610 typedef sequence<Engines::file> files;
613 //! The state of a Salome_file.
617 //! hdf5 file where the file can be saved
618 string hdf5_file_name;
619 //! number of files managed
620 long number_of_files;
621 //! information if all the files are received
626 /*! \brief Interface of a Salome_file managed
627 This file is independent of a Salome module. It can managed one or more
628 real files. It's useful for parallel files. Currently Salome_file cannot manage
629 two files that have the same name but not the same path.
631 interface Salome_file : Engines::fileTransfer
633 //! Load a Salome_file from a hdf5 file.
636 \param hdf5_file name (with path) of the hdf5_file.
638 \exception contains informations of errors if the loading doesn't succeed.
640 void load(in string hdf5_file) raises (SALOME::SALOME_Exception);
642 //! Save a Salome_file into a hdf5_file.
645 \param hdf5_file name (with path) of the hdf5_file.
647 \exception contains informations of errors if the save doesn't succeed.
650 void save(in string hdf5_file) raises (SALOME::SALOME_Exception);
652 //! Save a Salome_file into a hdf5_file.
654 All files that are managed are saved into the hdf5_file
656 \param hdf5_file name (with path) of the hdf5_file.
658 \exception contains informations of errors if the save doesn't succeed.
661 void save_all(in string hdf5_file) raises (SALOME::SALOME_Exception);
665 //! Add a Local file to the Salome_file.
668 \param file_name name of the file with the path.
670 \exception raised if the file is already added into the Salome_file.
672 void setLocalFile(in string comp_file_name) raises (SALOME::SALOME_Exception);
674 //! Add a Distributed file to the Salome_file.
677 \param comp_file_name name of the file with the path.
679 \exception raised if the file is already added into the Salome_file.
681 void setDistributedFile(in string comp_file_name) raises (SALOME::SALOME_Exception);
683 //! Connect a Salome_file with another Salome_file.
685 It works only if the Salome_file managed only one file
687 \param source_Salome_file Salome_file that managed the distributed version of the file.
689 \exception raised if there is more or less than one file.
691 void connect(in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
693 //! Connect the managed file file_name to a Salome_file.
696 \param file_name name of the file without the path.
697 \param source_Salome_file Salome_file that managed the distributed version of the file.
699 \exception raised if the file doesn't exist.
701 void connectDistributedFile(in string file_name,
702 in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
704 //! Connect the file_name with a Distributed file_name.
707 \param file_name name of the file without the path.
708 \param source_file_name It's the name of the file managed by the distributed source Salome_file.
710 \exception raised if the file doesn't exist.
712 void setDistributedSourceFile(in string file_name,
713 in string source_file_name) raises (SALOME::SALOME_Exception);
717 //! Get all the distributed files managed by the Salome_file and check all the local files.
720 \exception raised if some of the files are not ok.
722 void recvFiles() raises (SALOME::SALOME_Exception) ;
726 //! Remove a file of the Salome_file.
729 \param file_name name of the file.
731 \exception raised if the file doesn't exist.
733 void removeFile(in string file_name) raises (SALOME::SALOME_Exception);
735 //! Remove all the files of the Salome_file.
740 //! Get the list of the files managed by the Salome_file.
742 The list can be empty.
744 Engines::files getFilesInfos();
746 //! Get a file managed by the Salome_file.
749 \param file_name the name of the file.
751 \return CORBA file reference.
753 \exception raised if the file doesn't exist.
755 Engines::file getFileInfos(in string file_name) raises (SALOME::SALOME_Exception);
757 //! Return the state of the Salome_file.
758 Engines::SfState getSalome_fileState();
761 //! Set the container where files are.
764 \param container container CORBA's reference.
766 void setContainer(in Engines::Container container);
769 /*! \brief Interface of fileRef.
770 The fileTransfer and fileRef interfaces provide a file transfer service
771 between different computers.
773 A fileRef object is associated to an original file (origFileName) on a
774 machine (refMachine).
775 It is created by a container (factoryServer) on refMachine,
776 with createFileRef(in string origFileName) method.
777 The fileRef object maintains a list of (machine,filename) for copies.
778 If a copy exists on myMachine, getRef(myMachine) returns the file name
779 of the copy on myMachine, else returns empy string.
780 If there is no copy on myMachine, method getFileTransfer() from container
781 factoryServer on refMachine provides a fileTransfer object dedicated to
783 After the copy, addRef(myMachine, localFileNameOnMyMachine) registers
784 the file name of the copy on myMachine.
788 //! the original file
789 readonly attribute string origFileName;
790 //! the machine of the original file
791 readonly attribute string refMachine;
793 Container getContainer();
795 boolean addRef(in string machine,
798 string getRef(in string machine);