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