idl/SALOME_Component.idl

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