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