idl/SALOME_Component.idl

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