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