1 // Copyright (C) 2007 OPEN CASCADE, EADS/CCR, LIP6, CEA/DEN,
2 // CEDRAT, EDF R&D, LEG, PRINCIPIA R&D, BUREAU VERITAS
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.
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.
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
18 // See http://www.salome-platform.org/ or email : webmaster.salome@opencascade.com
20 // File : DSC_Engines.idl
21 // Author : Andre RIBES, EDF
24 #ifndef _DSC_ENGINES_IDL_
25 #define _DSC_ENGINES_IDL_
27 #include "SALOME_Component.idl"
28 #include "SALOME_Ports.idl"
31 This is a package that contains IDL interfaces that permits to add
32 a dynamic port model to the SALOME object model.
36 /*! \brief Interface of a DSC component.
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.
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".
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.
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.
59 interface DSC : Engines::Component {
61 /*--------------------------------------------------------------------------------------------*/
62 /*-------------------------------------- Types Part ------------------------------------------*/
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.
70 typedef sequence<Ports::Port> uses_port;
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.
76 enum Message {AddingConnection,
81 This exception is raised when a port's name is gived before
82 it is added to the component.
84 exception PortNotDefined {};
87 This exception is raised if you try to add a port with the same
88 name than a previous defined port.
90 exception PortAlreadyDefined {};
93 This exception is raised when you try to use a port that is not connected.
95 exception PortNotConnected {};
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.
102 exception BadPortType {
108 Port's reference is Nil !
110 exception NilPort {};
113 Port's reference is not the right reference.
115 exception BadPortReference {};
118 Object porperty is not good for the port
120 exception BadProperty {};
123 /*--------------------------------------------------------------------------------------------*/
124 /*-------------------------------------- Operation Part --------------------------------------*/
127 This operation adds a provides port to the component.
129 \param ref port's Corba reference.
130 \param provides_port_name port's name.
131 \param port_prop port's property object.
133 \exception PortAlreadyDefined
135 \exception BadProperty
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.
141 void add_provides_port(in Ports::Port ref,
142 in string provides_port_name,
143 in Ports::PortProperties port_prop) raises(PortAlreadyDefined,
148 This operation adds a uses port to the component.
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.
155 \exception PortAlreadyDefined
156 \exception BadProperty
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.
162 void add_uses_port(in string repository_id,
163 in string uses_port_name,
164 in Ports::PortProperties port_prop) raises(PortAlreadyDefined,
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.
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.
177 \param provides_port_name port's name.
178 \param connection_error true if you want to wait that the port is connected with
180 \return port's Corba reference.
182 \exception PortNotDefined
183 \exception PortNotConnected
184 \exception BadPortType
187 Ports::Port get_provides_port(in string provides_port_name,
188 in boolean connection_error) raises(PortNotDefined,
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.
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).
202 \param uses_port_name port's name.
203 \return uses port's sequence.
205 \exception PortNotDefined
206 \exception PortNotConnected
207 \exception BadPortType
211 uses_port get_uses_port(in string uses_port_name) raises(PortNotDefined,
217 This operation connects a provides port with a uses port.
219 \param provides_port_name provides port's name.
221 \exception PortNotDefined
223 \note Notice that the provides doesn't uses port names or component reference.
225 void connect_provides_port(in string provides_port_name) raises(PortNotDefined);
228 This operation connects a uses port with a provides port.
230 \param uses_port_name uses port's name.
231 \param provides_port_ref provides port's Corba reference.
233 \exception PortNotDefined
234 \exception BadPortType
237 void connect_uses_port(in string uses_port_name,
238 in Ports::Port provides_port_ref) raises(PortNotDefined,
242 This operation tests if a port is connected. You can test
243 a uses port or a provides port.
245 \param port_name port's name.
246 \return true if the uses port is connected.
248 \exception PortNotDefined
250 boolean is_connected(in string port_name) raises(PortNotDefined);
253 This operation disconnects a uses port to a provides port.
255 \param provides_port_name provides port's name.
256 \param message state associated with the disconnection.
258 \exception PortNotDefined
259 \exception PortNotConnected
261 void disconnect_provides_port(in string provides_port_name,
262 in Engines::DSC::Message message) raises(PortNotDefined,
266 This operation disconnects a provides port to a uses port.
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.
272 \exception PortNotDefined
273 \exception PortNotConnected
274 \exception BadPortReference
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,
282 This operation permits to get port's property object.
284 \param port_name port's name.
285 \return properties object's CORBA reference.
287 \exception PortNotDefined
289 Ports::PortProperties get_port_properties(in string port_name) raises(PortNotDefined);
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).
297 interface ConnectionManager {
300 The Id gived to the disconnect method is bad.
305 A connection Id. It's unique.
307 typedef short connectionId;
310 This operation connects a uses port with a provides port.
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.
317 \exception Engines::DSC::PortNotDefined
318 \exception Engines::DSC::BadPortType
319 \exception Engines::DSC::NilPort
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.
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);
333 This operation releases a connection that has been previously created by
334 the ConnectionManager.
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.
340 \exception Engines::ConnectionManager::BadId
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);
349 Shutdown the ConnectionManager process.
351 oneway void ShutdownWithExit();
354 Returns the PID of the connection manager
359 /*--------------------------------------------------------------------------------------------*/
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.
367 interface Superv_Component : Engines::DSC {
370 The SUPERV module call this method before starting the service. Thus the service
371 can add is dynamics ports before it is started.
373 \param service_name service's name.
374 \return true if the service is correctly initialised.
376 boolean init_service(in string service_name);
379 /*--------------------------------------------------------------------------------------------*/
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.
385 interface Parallel_DSC : Engines::Superv_Component, Engines::Parallel_Component {
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.
392 \param ref provides proxy port's reference.
393 \param provides_port_name provides port's name.
395 \see Engines_ParallelDSC_i::add_parallel_provides_proxy_port
397 void set_paco_proxy(in Object ref,
398 in string provides_port_name,
399 in Ports::PortProperties port_prop);