idl/SALOME_Component.idl

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