idl/SALOME_Component.idl

   1 // Copyright (C) 2007-2019  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, or (at your option) any later version.
  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
  26 #ifndef _SALOME_COMPONENT_IDL_
  27 #define _SALOME_COMPONENT_IDL_
  28
  29 #include "SALOME_GenericObj.idl"
  30 #include "SALOMEDS.idl"
  31 #include "SALOME_Exception.idl"
  32 #include "SALOME_PyNode.idl"
  33
  34 /*! \file SALOME_Component.idl \brief interfaces for EngineComponent 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 %FIELDS
  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 EngineComponent ;
  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 successful 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       \return a loaded component
  95     */
  96     Engines::EngineComponent create_component_instance(in string componentName);
  97
  98     //! Create a new Python servant instance of a generic service.
  99         /*!
 100           This simply loads the service in the current container by importing the
 101           corresponding Python module.
 102           Warning: no internal registration is done, so it is up to the caller to
 103           manage the various instantiation.
 104           \param serviceName Name of the service
 105           \param reason  in case of error (return void string) a string explaining the error
 106           \return the IOR of the loaded service.
 107         */
 108     string create_python_service_instance(in string serviceName,
 109                                           out string reason);
 110
 111     //! Create a new servant instance of a component with environment variables specified.
 112     /*!
 113       Component library must be loaded.
 114       \param componentName Name of the component which will be registered
 115                            in Registry and Name Service,
 116                          (instance number suffix added to the registered name)
 117       \param env         a dict of env variables
 118       \param reason      in case of error (return nil) a string explaining the error
 119       \return a loaded component
 120     */
 121     Engines::EngineComponent create_component_instance_env(in string componentName,
 122                                                            in FieldsDict env,
 123                                                            out string reason);
 124     //! Find a servant instance of a component
 125     /*!
 126       \param registeredName  Name of the component in Registry or Name Service,
 127                              without instance suffix number
 128       \return the first instance found
 129     */
 130     EngineComponent find_component_instance(in string registeredName);
 131
 132     //! Find a servant instance of a component, or create a new one.
 133     /*!
 134       Loads the component library if needed.
 135       Only applicable to multiStudy components.
 136       \param nameToRegister Name of the component which will be registered
 137                             in Registry (or Name Service)
 138       \param componentName  Name of the constructed library of the %component
 139                             (not used any more, give empty string)
 140       \return a loaded component
 141     */
 142     EngineComponent load_impl(in string nameToRegister,
 143                               in string componentName);
 144
 145     //! Remove the component servant, and deletes all related objects
 146     /*!
 147       \param component_i     Component to be removed
 148     */
 149     void remove_impl(in EngineComponent component_i);
 150
 151     //!  Unload component libraries from the container.
 152     void finalize_removal() ;
 153
 154     //!  Determines whether the server has been loaded or not.
 155     void ping();
 156
 157     //!  Name of the %container
 158     readonly attribute string name ;
 159
 160     //!  working directory of the %container
 161     readonly attribute string workingdir ;
 162
 163     //!  name of the %container log file (this has been set by the launcher)
 164     attribute string logfilename ;
 165
 166     //!  Shutdown the Container process.
 167     void Shutdown();
 168
 169     //!  Returns the hostname of the container
 170     string getHostName();
 171
 172     //!  Returns the PID of the container
 173     long getPID();
 174
 175     //! Kill the container
 176     /*!
 177       Returns True if the %container has been killed.
 178       Kept for Superv compilation but can't work, unless oneway...
 179       TO REMOVE !
 180     */
 181     boolean Kill_impl() ;
 182
 183     //! Create a fileRef
 184     /*!
 185       returns a fileRef object if origFileName exists and is readable
 186       else returns null object. Only one fileRef is created for a given
 187       file name, so, several calls with the same file name returns the
 188       same object.
 189     */
 190     fileRef createFileRef(in string origFileName);
 191
 192     //! Create a Salome_file
 193     /*!
 194       returns a Salome_file object if origFileName exists and is readable
 195       else returns null object.
 196
 197       \param origFileName name of the file to be managed (can contain the path).
 198
 199       \return Salome_file CORBA reference.
 200     */
 201     Salome_file createSalome_file(in string origFileName);
 202
 203     //! Create a fileTransfer
 204     /*!
 205       returns a fileTransfer object used to copy files from the container
 206       machine to the clients machines. Only one fileTransfer instance is
 207       created in a container.
 208     */
 209     fileTransfer getFileTransfer();
 210
 211     //! Copy a file from a remote host (container) to a local file
 212     /*!
 213       \param contai the remote container
 214       \param remoteFile the file on the remote host to copy
 215       \param localFile the local file to create by copy
 216      */
 217     void copyFile(in Container contai, in string remoteFile, in string localFile);
 218
 219     //! Create a PyNode in the container
 220     /*!
 221       \param nodeName the name of the PyNode
 222       \param code python code as text to load in the node
 223      */
 224     PyNode createPyNode(in string nodeName, in string code)  raises(SALOME::SALOME_Exception);
 225
 226     //! Retrieves the last created PyNode instance with createPyNode.
 227     PyNode getDefaultPyNode(in string nodeName);
 228
 229     //! Create a PyScriptNode in the container
 230     /*!
 231       \param nodeName the name of the PyScriptNode
 232       \param code python code as text to load in the node
 233      */
 234     PyScriptNode createPyScriptNode(in string nodeName, in string code)  raises(SALOME::SALOME_Exception);
 235
 236     //! Retrieves the last created PyScriptNode instance with createPyScriptNode.
 237     PyScriptNode getDefaultPyScriptNode(in string nodeName);
 238   };
 239
 240   /*! \brief Interface of the %component.
 241   This interface is used for interaction between the %container and the
 242   %component and between the components inside the container.
 243   */
 244   interface EngineComponent
 245   {
 246     //!  The name of the instance of the %Component
 247     readonly attribute string instanceName ;
 248
 249     //!  The name of the interface of the %Component
 250     readonly attribute string interfaceName ;
 251
 252     //!  Determines whether the server has already been loaded or not.
 253     void ping();
 254
 255     //! Remove component instance from container
 256     /*!
 257       Deactivates the %Component.
 258       -- TO BE USED BY CONTAINER ONLY (Container housekeeping) --
 259       use remove_impl from Container instead !
 260     */
 261     void destroy() ;
 262
 263     //!  Returns the container that the %Component refers to.
 264     Container GetContainerRef() ;
 265
 266     //! Set component instance properties
 267     /*!
 268       Gives a sequence of (key=string,value=any) to the component.
 269       Base class component stores the sequence in a map.
 270       The map is cleared before.
 271       This map is for use by derived classes.
 272     */
 273     void setProperties(in FieldsDict dico);
 274
 275     //! Get component instance properties
 276     /*!
 277       returns a previously stored map (key=string,value=any) as a sequence.
 278       See setProperties(in FieldsDict dico).
 279     */
 280     FieldsDict getProperties();
 281
 282     //! Set an option value
 283     /*!
 284       This method is to set an option specific to a certain EngineComponent.
 285     */
 286     void SetOption(in string optionName, in string value);
 287
 288     //! Return an option value
 289     /*!
 290       This method is to get value of an option specific to a certain EngineComponent.
 291     */
 292     string GetOption(in string optionName);
 293
 294     //! Set name of a node in a graph (for %SUPERVISOR use)
 295     /*!
 296       This method is used by the %SUPERVISOR component. It sets the names of
 297       the graph and of the node.
 298       \param aGraphName Name of graph
 299       \param aNodeName  Name of node
 300     */
 301     void Names( in string aGraphName , in string aNodeName ) ;
 302
 303     //! Kill the component (if you can)
 304     /*!
 305       Returns True if the %Component has been killed.
 306     */
 307     boolean Kill_impl() ;
 308
 309     //! Stop the component (if you can)
 310     /*!
 311       Returns True if the activity of the %Component has been stopped.
 312       (It's action can't be resumed)
 313     */
 314     boolean Stop_impl() ;
 315
 316     //! Suspend the component
 317     /*!
 318       Returns True if the activity of the %Component has been suspended.
 319       (It's action can be resumed)
 320     */
 321     boolean Suspend_impl() ;
 322
 323     //! Resume the component
 324     /*!
 325       Returns True if the activity of the %Component has been resumed.
 326     */
 327     boolean Resume_impl() ;
 328
 329     //! Get the cpu used
 330     /*!
 331       Returns the Cpu used
 332     */
 333     long CpuUsed_impl() ;
 334
 335     //! Get a python dump
 336     /*!
 337       Returns a python script, which is being played back reproduces
 338       the data model of component
 339     */
 340     TMPFile DumpPython(in boolean isPublished,
 341                        in boolean isMultiFile,
 342                        out boolean isValidScript);
 343
 344
 345     //! Returns a CORBA Ref of a input 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 information of what if the component cannot
 354       sends the file's reference.
 355     */
 356     Engines::Salome_file getInputFileToService(in string service_name,
 357                                                in string Salome_file_name) raises(SALOME::SALOME_Exception);
 358
 359     //! Check service input files (transfer them if needed)
 360     /*!
 361       This method is used before the activation of the service. It calls
 362       recvFiles() on all the input 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 information about files that are not in a good state.
 374     */
 375     void checkInputFilesToService(in string service_name)           raises(SALOME::SALOME_Exception);
 376
 377     //!  This method adds a input 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 setInputFileToService(in string service_name,
 389                                                in string Salome_file_name)   raises(SALOME::SALOME_Exception);
 390
 391     //!  Returns a CORBA Ref of a output Salome_file managed by a service.
 392     /*!
 393
 394       \param service_name service's name.
 395       \param file_name name of the requested file.
 396
 397       \return CORBA Ref of the requested file.
 398
 399       \exception contains information of what if the component cannot
 400       sends the file's reference.
 401     */
 402     Engines::Salome_file getOutputFileToService(in string service_name,
 403                                                 in string Salome_file_name) raises(SALOME::SALOME_Exception);
 404
 405     //! Check service output files (transfer them if needed)
 406     /*!
 407       This method is used at the end of the service. It calls
 408       recvFiles() on all the output Salome_file files of the service.
 409
 410       Before each recvFiles(), it uses the callback method named configureSalome_file.
 411       This method allows the user to configure the files managed by the Salome_file.
 412
 413       By default, there is no files managed when a Salome_file is created,
 414       but the supervisor set some files managed by the Salome_file from the information contained
 415       into the schema file.
 416
 417       \param service_name service's name.
 418
 419       \exception contains information about files that are not in a good state.
 420     */
 421     void checkOutputFilesToService(in string service_name)        raises(SALOME::SALOME_Exception);
 422
 423     //!  This method adds an output Salome_file to a service of the component.
 424     /*!
 425
 426       \param service_name service's name.
 427       \param Salome_file_name name of the Salome_file
 428
 429       \return a reference of the Salome_file
 430
 431       \exception raises an exception if there is already
 432       a Salome_file with this name for the service.
 433     */
 434     Engines::Salome_file setOutputFileToService(in string service_name,
 435                                                 in string Salome_file_name)  raises(SALOME::SALOME_Exception);
 436
 437     //! Indicate if the component instance provides custom information about its objects.
 438     /*!
 439       Returns true if the component provides custom information about its objects, false otherwise.
 440       Should be redefined in the certain component to return true in case of this
 441       component provides such information.
 442     */
 443     boolean hasObjectInfo();
 444
 445     //! Get custom information about the given object.
 446     /*!
 447       This method is used to get the custom information about the given object.
 448       Should be redefined in the certain component in case of this
 449       component provides such information.
 450       It is worth using this method only if hasObjectInfo() method returns true.
 451
 452       \param entry object's entry.
 453
 454       \return an information about the given object.
 455     */
 456     string getObjectInfo(in string entry);
 457
 458     //! Get version of the component
 459     /*!
 460       This method is supposed to be implemented in all derived classes; default implementation
 461       returns "unknown" string that means that no version information about the component is available.
 462       \note The version of the component is stored to the study, as a part of general persistence
 463       mechanism; once stored, version information in the study cannot be changed.
 464
 465       \return string containing component's version, e.g. "1.0"
 466     */
 467     string getVersion();
 468   };
 469
 470   /*!
 471     \brief Base interface of the %component that supports exporting data.
 472   */
 473   interface ImportableComponent
 474   {
 475     /*! \brief Get a list of supported formats */
 476     SALOME::StringSeq GetImportableFormats();
 477     boolean           ImportDataAs(in string format, in SALOME::GenericObj exporter);
 478   };
 479
 480   //!  A block of binary data used for file transfer. The maximum size of the block is defined on server side.
 481   typedef sequence<octet> fileBlock;
 482
 483   /*! \brief Interface of fileTransfer.
 484      The fileTransfer and fileRef interfaces provide a file transfer service
 485      between different computers.
 486   */
 487   interface fileTransfer : SALOME::GenericObj
 488   {
 489     //! Open the file transfer
 490     /*!
 491       open method returns a key (fileId) that identifies the structure
 492       (ex: C FILE), associated to the original file on the server.
 493       The structure is created by a container for transfer of files availables
 494       on the computer which runs the container.
 495       Each open gives a unique fileId, to allow concurrent reads of the same
 496       File.
 497     */
 498     long open(in string fileName);
 499     //! Open the file transfer in write mode for file fileName
 500     /*!
 501       \param fileName the file to copy into with putBlock
 502       \return the id to use with putBlock
 503     */
 504     long openW(in string fileName);
 505
 506     //! Close the file transfer
 507     /*!
 508     when the file transfer is finished, close method releases structures
 509     created by open method, identified by fileId.
 510     */
 511     void close(in long fileId);
 512
 513     //! Get a file data block
 514     /*!
 515       Get successive blocks of octets from the original file.
 516       The last block is empty, and identifies the end of file.
 517     */
 518     fileBlock getBlock(in long fileId);
 519
 520     //! Put a file data block
 521     /*!
 522        \param fileId identification of the file obtained by openW
 523        \param block a data block to copy into the file identified by fileId
 524     */
 525     void putBlock(in long fileId, in fileBlock block);
 526
 527   };
 528
 529   //!  A file managed by a Salome_file.
 530   struct file {
 531     //! file name
 532     string file_name;
 533     //! path name
 534     string path;
 535     string type;
 536     string source_file_name;
 537     //! status ("present" or "notpresent")
 538     string status;
 539     long   node;
 540     Engines::Container container;
 541   };
 542
 543   //!  A sequence of Engines::file.
 544   typedef sequence<Engines::file> files;
 545
 546
 547   //!  The state of a Salome_file.
 548   struct SfState {
 549     //! file name
 550     string  name;
 551     //! hdf5 file where the file can be saved
 552     string  hdf5_file_name;
 553     //! number of files managed
 554     long    number_of_files;
 555     //! information if all the files are received
 556     boolean files_ok;
 557
 558   };
 559
 560   /*! \brief Interface of a Salome_file managed
 561     This file is independent of a Salome module. It can managed one or more
 562     real files. It's useful for parallel files. Currently Salome_file cannot manage
 563     two files that have the same name but not the same path.
 564   */
 565   interface Salome_file : Engines::fileTransfer
 566   {
 567     //!  Load a Salome_file from a hdf5 file.
 568     /*!
 569
 570       \param hdf5_file name (with path) of the hdf5_file.
 571
 572       \exception contains information of errors if the loading doesn't succeed.
 573      */
 574     void load(in string hdf5_file)                            raises (SALOME::SALOME_Exception);
 575
 576     //!  Save a Salome_file into a hdf5_file.
 577     /*!
 578
 579       \param  hdf5_file name (with path) of the hdf5_file.
 580
 581       \exception contains information of errors if the save doesn't succeed.
 582
 583     */
 584     void save(in string hdf5_file)                            raises (SALOME::SALOME_Exception);
 585
 586     //!  Save a Salome_file into a hdf5_file.
 587     /*!
 588       All files that are managed are saved into the hdf5_file
 589
 590       \param  hdf5_file name (with path) of the hdf5_file.
 591
 592       \exception contains information of errors if the save doesn't succeed.
 593
 594     */
 595     void save_all(in string hdf5_file)                            raises (SALOME::SALOME_Exception);
 596
 597 /**************/
 598
 599     //!  Add a Local file to the Salome_file.
 600     /*!
 601
 602       \param file_name name of the file with the path.
 603
 604       \exception raised if the file is already added into the Salome_file.
 605     */
 606     void setLocalFile(in string comp_file_name) raises (SALOME::SALOME_Exception);
 607
 608     //!  Add a Distributed file to the Salome_file.
 609     /*!
 610
 611       \param comp_file_name name of the file with the path.
 612
 613       \exception raised if the file is already added into the Salome_file.
 614     */
 615     void setDistributedFile(in string comp_file_name) raises (SALOME::SALOME_Exception);
 616
 617     //!  Connect a Salome_file with another Salome_file.
 618     /*!
 619       It works only if the Salome_file managed only one file
 620
 621       \param source_Salome_file Salome_file that managed the distributed version of the file.
 622
 623       \exception raised if there is more or less than one file.
 624     */
 625     void connect(in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
 626
 627     //!  Connect the managed file file_name to a Salome_file.
 628     /*!
 629
 630       \param file_name name of the file without the path.
 631       \param source_Salome_file Salome_file that managed the distributed version of the file.
 632
 633       \exception raised if the file doesn't exist.
 634     */
 635     void connectDistributedFile(in string file_name,
 636                                 in Engines::Salome_file source_Salome_file) raises (SALOME::SALOME_Exception);
 637
 638     //!  Connect the file_name with a Distributed file_name.
 639     /*!
 640
 641       \param file_name name of the file without the path.
 642       \param source_file_name It's the name of the file managed by the distributed source Salome_file.
 643
 644       \exception raised if the file doesn't exist.
 645     */
 646     void setDistributedSourceFile(in string file_name,
 647                                   in string source_file_name) raises (SALOME::SALOME_Exception);
 648
 649 /**************/
 650
 651     //! Get all the distributed files managed by the Salome_file and check all the local files.
 652     /*!
 653
 654       \exception raised if some of the files are not ok.
 655     */
 656     void recvFiles()                                            raises (SALOME::SALOME_Exception) ;
 657
 658 /**************/
 659
 660     //!  Remove a file of the Salome_file.
 661     /*!
 662
 663       \param file_name name of the file.
 664
 665       \exception raised if the file doesn't exist.
 666     */
 667     void removeFile(in string file_name)                    raises (SALOME::SALOME_Exception);
 668
 669     //!  Remove all the files of the Salome_file.
 670     void removeFiles();
 671
 672 /**************/
 673
 674     //! Get the list of the files managed by the Salome_file.
 675     /*!
 676       The list can be empty.
 677     */
 678     Engines::files getFilesInfos();
 679
 680     //! Get a file managed by the Salome_file.
 681     /*!
 682
 683       \param file_name the name of the file.
 684
 685       \return CORBA file reference.
 686
 687       \exception raised if the file doesn't exist.
 688     */
 689     Engines::file  getFileInfos(in string file_name) raises (SALOME::SALOME_Exception);
 690
 691     //!  Return the state of the Salome_file.
 692     Engines::SfState getSalome_fileState();
 693
 694
 695     //! Set the container where files are.
 696     /*!
 697
 698       \param container container CORBA's reference.
 699     */
 700     void setContainer(in Engines::Container container);
 701   };
 702
 703   /*! \brief Interface of fileRef.
 704      The fileTransfer and fileRef interfaces provide a file transfer service
 705      between different computers.
 706
 707      A fileRef object is associated to an original file (origFileName) on a
 708      machine (refMachine).
 709      It is created by a container (factoryServer) on refMachine,
 710      with createFileRef(in string origFileName) method.
 711      The fileRef object maintains a list of (machine,filename) for copies.
 712      If a copy exists on myMachine, getRef(myMachine) returns the file name
 713      of the copy on myMachine, else returns empty string.
 714      If there is no copy on myMachine, method getFileTransfer() from container
 715      factoryServer on refMachine provides a fileTransfer object dedicated to
 716      CORBA file copy.
 717      After the copy, addRef(myMachine, localFileNameOnMyMachine) registers
 718      the file name of the copy on myMachine.
 719   */
 720   interface fileRef
 721   {
 722     //! the original file
 723     readonly attribute string origFileName;
 724     //! the machine of the original file
 725     readonly attribute string refMachine;
 726
 727     Container getContainer();
 728
 729     boolean addRef(in string machine,
 730                    in string fileName);
 731
 732     string getRef(in string machine);
 733   };
 734 };
 735
 736 #endif