idl/DSC_Engines.idl

   1 //  Copyright (C) 2007-2008  CEA/DEN, EDF R&D, OPEN CASCADE
   2 //
   3 //  Copyright (C) 2003-2007  OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN,
   4 //  CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS
   5 //
   6 //  This library is free software; you can redistribute it and/or
   7 //  modify it under the terms of the GNU Lesser General Public
   8 //  License as published by the Free Software Foundation; either
   9 //  version 2.1 of the License.
  10 //
  11 //  This library is distributed in the hope that it will be useful,
  12 //  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 //  Lesser General Public License for more details.
  15 //
  16 //  You should have received a copy of the GNU Lesser General Public
  17 //  License along with this library; if not, write to the Free Software
  18 //  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
  19 //
  20 //  See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
  21 //
  22 //  File   : DSC_Engines.idl
  23 //  Author : Andre RIBES, EDF
  24 //  $Header:
  25 //
  26 #ifndef _DSC_ENGINES_IDL_
  27 #define _DSC_ENGINES_IDL_
  28
  29 #include "SALOME_Component.idl"
  30 #include "SALOME_Ports.idl"
  31
  32 /*! \file
  33   This is a package that contains IDL interfaces that permits to add
  34   a dynamic port model to the SALOME object model.
  35  */
  36 module Engines {
  37
  38   /*! \brief Interface of a DSC component.
  39
  40     This interface defines the operations needed to add a component model with dynamic port
  41     declaration to the SALOME object model. A component is a black box that interacts with
  42     other components only by his ports. A port represents a connection point for the component.
  43     In this model, a port is a CORBA interface, so a CORBA object.
  44
  45     There is two ways for a component to interact with a port type :
  46     - It implements the port : it means "the component provides an implementation of the
  47     interface of the port". We design this kind of port as "provides ports". It provides an
  48     interface to other components.
  49     - It needs to use an object that provides the port interface. We say that the component uses this
  50     port type. It is represented by a "uses" port. A uses port can be connected with a provides port
  51     of the same interface type. When the connection is done, a component can use the "uses port" to use the
  52     interface provided by the "provides port".
  53
  54     The interface DSC implements the component interface that containes the operations that are needed
  55     to manage declarations into a component and connections between ports.
  56
  57     These operations are logicaly divided in two parts :
  58     - First part permits to add an get ports of a component.
  59     - Second part permits to connect/disconnect ports.
  60   */
  61   interface DSC : Engines::Component {
  62
  63 /*--------------------------------------------------------------------------------------------*/
  64 /*-------------------------------------- Types Part ------------------------------------------*/
  65
  66     /*!
  67       This sequence is a uses port. It's a sequence since a uses port can be
  68       connected with x provides port. Sometimes this kind of uses port is called multiple port.
  69       At this programming level, the user has to deal with the sequence. In the DSC_user
  70       layer, the user only deals with one pointer.
  71     */
  72     typedef sequence<Ports::Port> uses_port;
  73
  74     /*!
  75       This enumeration is used when the connection of a port (uses or provides)
  76       is changed. This information is for the component's user code.
  77     */
  78     enum Message {AddingConnection,
  79                   RemovingConnection,
  80                   ApplicationError};
  81
  82     /*!
  83       This exception is raised when a port's name is gived before
  84       it is added to the component.
  85     */
  86     exception PortNotDefined {};
  87
  88     /*!
  89       This exception is raised if you try to add a port with the same
  90       name than a previous defined port.
  91     */
  92     exception PortAlreadyDefined {};
  93
  94     /*!
  95       This exception is raised when you try to use a port that is not connected.
  96     */
  97     exception PortNotConnected {};
  98
  99     /*!
 100       This exception is raised if the type of the provides port is bad.
 101       This exception contains a string that gives what type is expected
 102       and the type that the operation received.
 103     */
 104     exception BadPortType {
 105       string expected;
 106       string received;
 107     };
 108
 109     /*!
 110       Port's reference is Nil !
 111     */
 112     exception NilPort {};
 113
 114     /*!
 115       Port's reference is not the right reference.
 116     */
 117     exception BadPortReference {};
 118
 119     /*!
 120       Object porperty is not good for the port
 121     */
 122     exception BadProperty {};
 123
 124
 125 /*--------------------------------------------------------------------------------------------*/
 126 /*-------------------------------------- Operation Part --------------------------------------*/
 127
 128     /*!
 129       This operation adds a provides port to the component.
 130
 131       \param ref  port's Corba reference.
 132       \param provides_port_name port's name.
 133       \param port_prop port's property object.
 134
 135       \exception PortAlreadyDefined
 136       \exception NilPort
 137       \exception BadProperty
 138
 139       \note Notice that the name of the port is unique on a component. So if there is
 140       a uses port that has the same name, the PortAlreadyDefined exception will be throw.
 141       Also notice that each port as an object property that is associated with.
 142     */
 143     void add_provides_port(in Ports::Port ref,
 144                            in string provides_port_name,
 145                            in Ports::PortProperties port_prop) raises(PortAlreadyDefined,
 146                                                                       NilPort,
 147                                                                       BadProperty);
 148
 149     /*!
 150       This operation adds a uses port to the component.
 151
 152       \param repository_id  port's Corba repository id.
 153              Eg : IDL:toto.tata/MODULE/INTERFACE_NAME:1.0
 154       \param uses_port_name port's name.
 155       \param port_prop port's property object.
 156
 157       \exception PortAlreadyDefined
 158       \exception BadProperty
 159
 160       \note Notice that the name of the port is unique on the component. So if there is
 161       a provides port that has the same name, the PortAlreadyDefined exception will be throw.
 162       Also notice that each port as an object property that is associated with.
 163     */
 164     void add_uses_port(in string repository_id,
 165                        in string uses_port_name,
 166                        in Ports::PortProperties port_prop) raises(PortAlreadyDefined,
 167                                                                   BadProperty);
 168
 169     /*!
 170       This operation is used to get a provides port of the component.
 171       It can be used by the framework or the component himself.
 172
 173       If it's the framework that wants the port, the reference has to be gived
 174       even if the port is not connected (boolean connection_error to false).
 175       Contrary, if it's the component that wants the port, the port is given
 176       in most of cases only if it is connected (boolean connection_error to true).
 177       Notice that you can choose the behaviour that you want.
 178
 179       \param provides_port_name port's name.
 180       \param connection_error true if you want to wait that the port is connected with
 181       an another port.
 182       \return port's Corba reference.
 183
 184       \exception PortNotDefined
 185       \exception PortNotConnected
 186       \exception BadPortType
 187
 188     */
 189     Ports::Port get_provides_port(in string provides_port_name,
 190                                   in boolean connection_error) raises(PortNotDefined,
 191                                                                       PortNotConnected,
 192                                                                       BadPortType);
 193
 194     /*!
 195       This operation is used to get a uses port of the component.
 196       It can be used by the framework or the component himself.
 197       Actually, only the user layer of the component will use this operation.
 198       A uses port could be obtained if and only if the uses port is connected. The sequence
 199       contains all the connections since a uses port can have multiple connections.
 200
 201       There is a system of callbacks to prevent the user code that there is a new
 202       (or a deletion) of a connection (see DSC_Callbacks class).
 203
 204       \param uses_port_name port's name.
 205       \return uses port's sequence.
 206
 207       \exception PortNotDefined
 208       \exception PortNotConnected
 209       \exception BadPortType
 210
 211       \see DSC_Callbacks
 212     */
 213     uses_port get_uses_port(in string uses_port_name) raises(PortNotDefined,
 214                                                              PortNotConnected,
 215                                                              BadPortType);
 216
 217
 218     /*!
 219       This operation connects a provides port with a uses port.
 220
 221       \param provides_port_name provides port's name.
 222
 223       \exception PortNotDefined
 224
 225       \note Notice that the provides doesn't uses port names or component reference.
 226     */
 227     void connect_provides_port(in string provides_port_name) raises(PortNotDefined);
 228
 229     /*!
 230       This operation connects a uses port with a provides port.
 231
 232       \param uses_port_name uses port's name.
 233       \param provides_port_ref provides port's Corba reference.
 234
 235       \exception PortNotDefined
 236       \exception BadPortType
 237       \exception NilPort
 238     */
 239     void connect_uses_port(in string uses_port_name,
 240                            in Ports::Port provides_port_ref) raises(PortNotDefined,
 241                                                                     BadPortType,
 242                                                                     NilPort);
 243     /*!
 244       This operation tests if a port is connected. You can test
 245       a uses port or a provides port.
 246
 247       \param port_name port's name.
 248       \return true if the uses port is connected.
 249
 250       \exception PortNotDefined
 251     */
 252     boolean is_connected(in string port_name) raises(PortNotDefined);
 253
 254     /*!
 255       This operation disconnects a uses port to a provides port.
 256
 257       \param provides_port_name provides port's name.
 258       \param message state associated with the disconnection.
 259
 260       \exception PortNotDefined
 261       \exception PortNotConnected
 262     */
 263     void disconnect_provides_port(in string provides_port_name,
 264                                   in Engines::DSC::Message message) raises(PortNotDefined,
 265                                                                            PortNotConnected);
 266
 267     /*!
 268       This operation disconnects a provides port to a uses port.
 269
 270       \param uses_port_name uses port's name.
 271       \param provides_port_ref CORBA reference of the provides port.
 272       \param message state associated with the disconnection.
 273
 274       \exception PortNotDefined
 275       \exception PortNotConnected
 276       \exception BadPortReference
 277     */
 278     void disconnect_uses_port(in string uses_port_name,
 279                               in Ports::Port provides_port_ref,
 280                               in Engines::DSC::Message message) raises(PortNotDefined,
 281                                                                        PortNotConnected,
 282                                                                        BadPortReference);
 283     /*!
 284       This operation permits to get port's property object.
 285
 286       \param port_name port's name.
 287       \return properties object's CORBA reference.
 288
 289       \exception PortNotDefined
 290     */
 291     Ports::PortProperties get_port_properties(in string port_name) raises(PortNotDefined);
 292
 293   };
 294
 295   /*! \brief Interface of the ConnectionManager.
 296     It is a helper object for connection operations.
 297     The ConnectionManager is used like other services of SALOME (e.g ContainerManager).
 298   */
 299   interface ConnectionManager {
 300
 301     /*!
 302       The Id gived to the disconnect method is bad.
 303     */
 304     exception BadId {};
 305
 306     /*!
 307       A connection Id. It's unique.
 308     */
 309     typedef short connectionId;
 310
 311     /*!
 312       This operation connects a uses port with a provides port.
 313
 314       \param uses_component The component that have the uses port.
 315       \param uses_port_name uses port's name.
 316       \param provides_component The component that have the provides port.
 317       \param provides_port_name provides port's name.
 318
 319       \exception Engines::DSC::PortNotDefined
 320       \exception Engines::DSC::BadPortType
 321       \exception Engines::DSC::NilPort
 322
 323       \return the id of the connection that the ConnectionManager will use
 324       to release this connection when the framework (or a user script, ...)
 325       will call ConnectionManager::disconnect.
 326     */
 327     connectionId connect(in Engines::DSC uses_component,
 328                          in string uses_port_name,
 329                          in Engines::DSC provides_component,
 330                          in string provides_port_name) raises(Engines::DSC::PortNotDefined,
 331                                                               Engines::DSC::BadPortType,
 332                                                               Engines::DSC::NilPort);
 333
 334     /*!
 335       This operation releases a connection that has been previously created by
 336       the ConnectionManager.
 337
 338       \param id The id of the connection previously gived by the connect operation
 339       of the ConnectionManager.
 340       \param message state associated with the disconnection.
 341
 342       \exception Engines::ConnectionManager::BadId
 343     */
 344     void disconnect(in connectionId id,
 345                     in Engines::DSC::Message message) raises(Engines::ConnectionManager::BadId,
 346                                                  Engines::DSC::PortNotDefined,
 347                                                  Engines::DSC::PortNotConnected,
 348                                                                                            Engines::DSC::BadPortReference);
 349
 350     /*!
 351       Shutdown the ConnectionManager process.
 352     */
 353     oneway void ShutdownWithExit();
 354
 355     /*!
 356       Returns the PID of the connection manager
 357     */
 358     long getPID();
 359   };
 360
 361 /*--------------------------------------------------------------------------------------------*/
 362
 363   /*! \brief Interface of the Superv_Component.
 364     This interface is a DSC component that contains services for the SALOME module SUPERV.
 365     This interface contains methods that are only in local (so they are described
 366     and explained in the implementation class Superv_Component_i). These methods give access
 367     to data-oriented ports provided by default by SALOME's kernel.
 368   */
 369   interface Superv_Component : Engines::DSC {
 370
 371     /*!
 372       The SUPERV module call this method before starting the service. Thus the service
 373       can add is dynamics ports before it is started.
 374
 375       \param service_name service's name.
 376       \return true if the service is correctly initialised.
 377      */
 378     boolean init_service(in string service_name);
 379   };
 380
 381 /*--------------------------------------------------------------------------------------------*/
 382
 383   /*! \brief Interface of a Parallel_DSC component.
 384     This interface defines the operations needed to add a paco++ port
 385     into a parallel DSC component.
 386   */
 387   interface Parallel_DSC : Engines::Superv_Component, Engines::Parallel_Component {
 388
 389     /*!
 390       This operation gives the proxy node of a paco++ port to all the nodes.
 391       Only a node of the parallel component is going to add a proxy object
 392       with an internal method.
 393
 394       \param ref provides proxy port's reference.
 395       \param provides_port_name provides port's name.
 396
 397       \see Engines_ParallelDSC_i::add_parallel_provides_proxy_port
 398      */
 399     void set_paco_proxy(in Object ref,
 400                         in string provides_port_name,
 401                         in Ports::PortProperties port_prop);
 402
 403   };
 404 };
 405
 406 #endif