idl/SALOME_Component.idl

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