idl/DSC_Engines.idl

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