idl/SALOME_Component.idl

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