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