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