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 /*! \brief
  30 This is a package of interfaces used for connecting new components to %SALOME
  31 application. It also contains a set of interfaces used for management of %MED
  32 component in %SALOME application.
  33 */
  34 module Engines
  35 {
  36   /*!
  37     A byte stream which is used for binary data transfer between different
  38     components
  39   */
  40   typedef sequence<octet> TMPFile;
  41
  42   /*!
  43     General Key Value Structure to set or get properties, for component
  44   */
  45   struct KeyValuePair
  46   {
  47     string key;
  48     any value;
  49   };
  50
  51   typedef sequence<KeyValuePair> FieldsDict;
  52
  53   interface Component ;
  54   interface fileRef ;
  55   interface fileTransfer ;
  56
  57   /*! \brief Interface of the %Container.
  58   This interface defines the process of loading and registration
  59   of new components in %SALOME application
  60   */
  61
  62   interface Container
  63   {
  64
  65     /*!
  66       Loads a new component class (dynamic library).
  67       \param componentName like COMPONENT, (Python or C++ implementation)
  68                            try to make a Python import of COMPONENT,
  69                            then a lib open of libCOMPONENTEngine.so
  70       \return true if load successfull or already done, false otherwise
  71     */
  72     boolean load_component_Library(in string componentName);
  73
  74     /*!
  75       Creates a new servant instance of a component.
  76       Component library must be loaded.
  77       \param componentName Name of the component which will be registered
  78                            in Registry and Name Service,
  79                          (instance number suffix added to the registered name)
  80       \param studyId        0 if instance is not associated to a study,
  81                             >0 otherwise (== study id)
  82       \return a loaded component
  83     */
  84     Component create_component_instance(in string componentName,
  85                                         in long studyId);
  86
  87     /*!
  88       Finds a servant instance of a component
  89       \param registeredName  Name of the component in Registry or Name Service,
  90                              without instance suffix number
  91       \param studyId        0 if instance is not associated to a study,
  92                             >0 otherwise (== study id)
  93       \return the first instance found with same studyId
  94     */
  95     Component find_component_instance(in string registeredName,
  96                                       in long studyId);
  97
  98     /*!
  99       Find a servant instance of a component, or create a new one.
 100       Loads the component library if needed.
 101       Only applicable to multiStudy components.
 102       \param nameToRegister Name of the component which will be registered
 103                             in Registry (or Name Service)
 104       \param componentName  Name of the constructed library of the %component
 105                             (not used any more, give empty string)
 106       \return a loaded component
 107     */
 108     Component load_impl(in string nameToRegister,
 109                         in string componentName);
 110
 111     /*!
 112       Stops the component servant, and deletes all related objects
 113       \param component_i     Component to be removed
 114     */
 115     void remove_impl(in Component component_i);
 116
 117     /*!
 118       Discharges all components from the container.
 119     */
 120     void finalize_removal() ;
 121
 122     /*!
 123       Determines whether the server has been loaded or not.
 124     */
 125     void ping();
 126
 127     /*!
 128       Name of the %container
 129     */
 130     readonly attribute string name ;
 131
 132     /*!
 133       Shutdown the Container process.
 134     */
 135     oneway void Shutdown();
 136
 137     /*!
 138       Returns the hostname of the container
 139     */
 140     string getHostName();
 141
 142     /*!
 143       Returns the PID of the container
 144     */
 145     long getPID();
 146
 147     /*!
 148       Returns True if the %container has been killed.
 149       Kept for Superv compilation but can't work, unless oneway...
 150       TO REMOVE !
 151     */
 152     boolean Kill_impl() ;
 153
 154     /*!
 155       returns a fileRef object if origFileName exists and is readable
 156       else returns null object. Only one fileRef is created for a given
 157       file name, so, several calls with the same file name returns the
 158       same object.
 159     */
 160     fileRef createFileRef(in string origFileName);
 161
 162     /*!
 163       returns a fileTransfer object used to copy files from the container
 164       machine to the clients machines. Only one fileTransfer instance is
 165       created in a container.
 166     */
 167     fileTransfer getFileTransfer();
 168
 169   };
 170
 171
 172
 173   /*! \brief Interface of the %component.
 174   This interface is used for interaction between the %container and the
 175   %component and between the components inside the container.
 176   */
 177   interface Component
 178   {
 179     /*!
 180       The name of the instance of the %Component
 181     */
 182     readonly attribute string instanceName ;
 183
 184     /*!
 185       The name of the interface of the %Component
 186     */
 187     readonly attribute string interfaceName ;
 188
 189     /*!
 190       Determines whether the server has already been loaded or not.
 191     */
 192     void ping();
 193
 194 //     /*!
 195 //       Set study associated to component instance
 196 //       \param studyId
 197 //       (=0:  multistudy component instance,
 198 //        >0: study id associated to this instance
 199 //       \return false if already set with a different value (change not possible)
 200 //     */
 201 //     boolean setStudyId(in long studyId);
 202
 203     /*!
 204       get study associated to component instance
 205       \return -1: not initialised (Internal Error)
 206                0: multistudy component instance
 207               >0: study id associated to this instance
 208     */
 209     long getStudyId();
 210
 211     /*!
 212       Deactivates the %Component.
 213       -- TO BE USED BY CONTAINER ONLY (Container housekeeping) --
 214       use remove_impl from Container instead !
 215     */
 216     void destroy() ;
 217
 218     /*!
 219       Returns the container that the %Component refers to.
 220     */
 221     Container GetContainerRef() ;
 222
 223     /*!
 224       Gives a sequence of (key=string,value=any) to the component.
 225       Base class component stores the sequence in a map.
 226       The map is cleared before.
 227       This map is for use by derived classes.
 228     */
 229     void setProperties(in FieldsDict dico);
 230
 231     /*!
 232       returns a previously stored map (key=string,value=any) as a sequence.
 233       See setProperties(in FieldsDict dico).
 234     */
 235     FieldsDict getProperties();
 236
 237     /*!
 238       This method is used by the %SUPERVISOR component. It sets the names of
 239       the graph and of the node.
 240       \param aGraphName Name of graph
 241       \param aNodeName  Name of node
 242     */
 243     void Names( in string aGraphName , in string aNodeName ) ;
 244
 245     /*!
 246       Returns True if the %Component has been killed.
 247     */
 248     boolean Kill_impl() ;
 249
 250     /*!
 251       Returns True if the activity of the %Component has been stopped.
 252       (It's action can't be resumed)
 253     */
 254     boolean Stop_impl() ;
 255
 256     /*!
 257       Returns True if the activity of the %Component has been suspended.
 258       (It's action can be resumed)
 259     */
 260     boolean Suspend_impl() ;
 261
 262     /*!
 263       Returns True if the activity of the %Component has been resumed.
 264     */
 265     boolean Resume_impl() ;
 266
 267     /*!
 268       Returns the Cpu used (long does not run with python !...)
 269     */
 270     long CpuUsed_impl() ;
 271
 272     /*!
 273       Returns a python script, which is being played back reproduces
 274       the data model of component
 275     */
 276     TMPFile DumpPython(in Object theStudy,
 277                        in boolean isPublished,
 278                        out boolean isValidScript);
 279
 280   } ;
 281
 282   /*!
 283     A block of binary data used for file transfer. The maximum size of the
 284     block is defined on server side.
 285    */
 286   typedef sequence<octet> fileBlock;
 287
 288   /*! \brief Interface of fileTransfer.
 289      The fileTransfer and fileRef interfaces provide a file transfer service
 290      between different computers.
 291   */
 292   interface fileTransfer
 293   {
 294     /*!
 295       open method returns a key (fileId) that identifies the structure
 296       (ex: C FILE), associated to the original file on the server.
 297       The structure is created by a container for transfer of files availables
 298       on the computer which runs the container.
 299       Each open gives a unique fileId, to allow concurrent reads of the same
 300       File.
 301     */
 302     long open(in string fileName);
 303
 304     /*!
 305     when the file transfer is finished, close method releases structures
 306     created by open method, identified by fileId.
 307     */
 308     void close(in long fileId);
 309
 310     /*!
 311       Get successive blocks of octets from the original file.
 312       The last block is empty, and identifies the end of file.
 313     */
 314     fileBlock getBlock(in long fileId);
 315   };
 316
 317   /*! \brief Interface of fileTransfer.
 318      The fileTransfer and fileRef interfaces provide a file transfer service
 319      between different computers.
 320
 321      A fileRef object is associated to an original file (origFileName) on a
 322      machine (refMachine).
 323      It is created by a container (factoryServer) on refMachine,
 324      with createFileRef(in string origFileName) method.
 325      The fileRef object maintains a list of (machine,filename) for copies.
 326      If a copy exists on myMachine, getRef(myMachine) returns the file name
 327      of the copy on myMachine, else returns empy string.
 328      If there is no copy on myMachine, method getFileTransfer() from container
 329      factoryServer on refMachine provides a fileTransfer object dedicated to
 330      CORBA file copy.
 331      After the copy, addRef(myMachine, localFileNameOnMyMachine) registers
 332      the file name of the copy on myMachine.
 333   */
 334   interface fileRef
 335   {
 336     readonly attribute string origFileName;
 337     readonly attribute string refMachine;
 338
 339     Container getContainer();
 340
 341     boolean addRef(in string machine,
 342                 in string fileName);
 343
 344     string getRef(in string machine);
 345   };
 346
 347 } ;
 348
 349 #endif