idl/SALOME_Component.idl

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