1 // Copyright (C) 2007-2008 CEA/DEN, EDF R&D, OPEN CASCADE
3 // Copyright (C) 2003-2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN,
4 // CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS
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.
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.
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
20 // See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
22 // File : DSC_Engines.idl
23 // Author : Andre RIBES, EDF
26 #ifndef _DSC_ENGINES_IDL_
27 #define _DSC_ENGINES_IDL_
29 #include "SALOME_Component.idl"
30 #include "SALOME_Ports.idl"
32 /*! \file DSC_Engines.idl
33 \brief interfaces that permits to add a dynamic port model to the SALOME object model.
37 /*! \brief Interface of a DSC component.
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.
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".
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.
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.
60 interface DSC : Engines::Component {
62 /*--------------------------------------------------------------------------------------------*/
63 /*-------------------------------------- Types Part ------------------------------------------*/
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.
72 typedef sequence<Ports::Port> uses_port;
74 //! This enumeration is used when the connection of a port (uses or provides) is changed.
76 This information is for the component's user code.
78 enum Message {AddingConnection,
82 //! This exception is raised when a port is used before it is added to the component.
83 exception PortNotDefined {};
85 //! This exception is raised if you try to add a port with the same name than a previous defined port.
86 exception PortAlreadyDefined {};
88 //! This exception is raised when you try to use a port that is not connected.
89 exception PortNotConnected {};
91 //! This exception is raised if the type of the provides port is bad.
93 This exception contains a string that gives what type is expected
94 and the type that the operation received.
96 exception BadPortType {
101 //! Port's reference is Nil !
102 exception NilPort {};
104 //! Port's reference is not the right reference.
105 exception BadPortReference {};
107 //! Object property is not good for the port
108 exception BadProperty {};
111 /*--------------------------------------------------------------------------------------------*/
112 /*-------------------------------------- Operation Part --------------------------------------*/
114 //! This operation adds a provides port to the component.
117 \param ref port's Corba reference.
118 \param provides_port_name port's name.
119 \param port_prop port's property object.
121 \exception PortAlreadyDefined
123 \exception BadProperty
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.
129 void add_provides_port(in Ports::Port ref,
130 in string provides_port_name,
131 in Ports::PortProperties port_prop) raises(PortAlreadyDefined,
135 //! This operation adds a uses port to the component.
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.
143 \exception PortAlreadyDefined
144 \exception BadProperty
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.
150 void add_uses_port(in string repository_id,
151 in string uses_port_name,
152 in Ports::PortProperties port_prop) raises(PortAlreadyDefined,
155 //! Get a provides port of the component.
157 It can be used by the framework or the component himself.
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.
165 \param provides_port_name port's name.
166 \param connection_error true if you want to wait that the port is connected with
168 \return port's Corba reference.
170 \exception PortNotDefined
171 \exception PortNotConnected
172 \exception BadPortType
175 Ports::Port get_provides_port(in string provides_port_name,
176 in boolean connection_error) raises(PortNotDefined,
180 //! Get a uses port of the component.
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.
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).
190 \param uses_port_name port's name.
191 \return uses port's sequence.
193 \exception PortNotDefined
194 \exception PortNotConnected
195 \exception BadPortType
199 uses_port get_uses_port(in string uses_port_name) raises(PortNotDefined,
204 //! Connect a provides port with a uses port.
207 \param provides_port_name provides port's name.
209 \exception PortNotDefined
211 \note Notice that the provides doesn't uses port names or component reference.
213 void connect_provides_port(in string provides_port_name) raises(PortNotDefined);
215 //! Connect a uses port with a provides port.
218 \param uses_port_name uses port's name.
219 \param provides_port_ref provides port's Corba reference.
221 \exception PortNotDefined
222 \exception BadPortType
225 void connect_uses_port(in string uses_port_name,
226 in Ports::Port provides_port_ref) raises(PortNotDefined,
230 //! Check if a port is connected.
232 You can test a uses port or a provides port.
234 \param port_name port's name.
235 \return true if the uses port is connected.
237 \exception PortNotDefined
239 boolean is_connected(in string port_name) raises(PortNotDefined);
241 //! Disconnect a uses port from a provides port.
244 \param provides_port_name provides port's name.
245 \param message state associated with the disconnection.
247 \exception PortNotDefined
248 \exception PortNotConnected
250 void disconnect_provides_port(in string provides_port_name,
251 in Engines::DSC::Message message) raises(PortNotDefined,
254 //! Disconnect a provides port from a uses port.
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.
261 \exception PortNotDefined
262 \exception PortNotConnected
263 \exception BadPortReference
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,
270 //! Get port's property object.
273 \param port_name port's name.
274 \return properties object's CORBA reference.
276 \exception PortNotDefined
278 Ports::PortProperties get_port_properties(in string port_name) raises(PortNotDefined);
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).
286 interface ConnectionManager {
288 //! The Id given to the disconnect method is bad.
291 //! A connection Id. It's unique.
292 typedef short connectionId;
294 //! Connect a uses port with a provides port.
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.
302 \exception Engines::DSC::PortNotDefined
303 \exception Engines::DSC::BadPortType
304 \exception Engines::DSC::NilPort
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.
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);
317 //! Release a connection that has been previously created by the ConnectionManager.
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.
324 \exception Engines::ConnectionManager::BadId
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);
332 //! Shutdown the ConnectionManager process.
333 oneway void ShutdownWithExit();
335 //! Return the PID of the connection manager
339 /*--------------------------------------------------------------------------------------------*/
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.
347 interface Superv_Component : Engines::DSC {
349 //! Operation to create the service ports before it is executed
351 The SUPERV module call this method before starting the service. Thus the service
352 can add its dynamics ports before it is started.
354 \param service_name service's name.
355 \return true if the service is correctly initialised.
357 boolean init_service(in string service_name);