idl/DSC_Engines.idl

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