source: source/ariba/tidy/Node.h@ 2393

Last change on this file since 2393 was 2393, checked in by mies, 16 years ago

added MessageData wrapper

File size: 9.6 KB
Line 
1// [License]
2// The Ariba-Underlay Copyright
3//
4// Copyright (c) 2008-2009, Institute of Telematics, UniversitÀt Karlsruhe (TH)
5//
6// Institute of Telematics
7// UniversitÀt Karlsruhe (TH)
8// Zirkel 2, 76128 Karlsruhe
9// Germany
10//
11// Redistribution and use in source and binary forms, with or without
12// modification, are permitted provided that the following conditions are
13// met:
14//
15// 1. Redistributions of source code must retain the above copyright
16// notice, this list of conditions and the following disclaimer.
17// 2. Redistributions in binary form must reproduce the above copyright
18// notice, this list of conditions and the following disclaimer in the
19// documentation and/or other materials provided with the distribution.
20//
21// THIS SOFTWARE IS PROVIDED BY THE INSTITUTE OF TELEMATICS ``AS IS'' AND
22// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
24// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OF TELEMATICS OR
25// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
26// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
27// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
28// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
29// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
30// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
31// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32//
33// The views and conclusions contained in the software and documentation
34// are those of the authors and should not be interpreted as representing
35// official policies, either expressed or implied, of the Institute of
36// Telematics.
37// [License]
38
39
40#ifndef NODE_H_
41#define NODE_H_
42
43// forward declarations
44namespace ariba {
45class Node;
46}
47
48#include "Module.h"
49#include "Identifiers.h"
50#include "SpoVNetProperties.h"
51#include "NodeListener.h"
52#include "Name.h"
53#include "AribaModule.h"
54#include "TidyCommunicationListener.h"
55#include "DataMessage.h"
56
57namespace ariba {
58
59// forward declaration
60namespace interface {
61class AribaContext;
62class ServiceInterface;
63}
64
65/**
66 * This class should implement all ariba node functionality.
67 *
68 * @author Sebastian Mies <mies@tm.uka.de>
69 */
70class Node: public Module {
71public:
72 /**
73 * Constructs a new node using a given ariba module
74 *
75 * @param ariba_mod The ariba module
76 * @param name The canonical node name of the new node. When NULL a
77 * randomly chosen name is created.
78 * @param len The length of the canonical node name or -1, if the name
79 * is a zero-terminated char-string.
80 */
81 Node(AribaModule& ariba_mod, const Name& name = Name::UNSPECIFIED);
82
83 /**
84 * Destroys the node. Before destruction some pre-conditions
85 * must be met:<br />
86 *
87 * 1. The node is not part of any SpoVNet <br />
88 * 2. All listeners must be unbound from this node <br />
89 * 3. The module has been stopped<br />
90 */
91 ~Node();
92
93 //--- node control ---
94
95 /**
96 * This method instructs the node to join a particular spovnet.
97 * Callees may bind with a NodeListener to receive events, when
98 * a node has been successfully joined.
99 *
100 * @param vnetId The SpoVNet name
101 */
102 void join(const Name& name);
103
104 /**
105 * This method initiates a new SpoVNet with the given SpoVNetID and
106 * parameters.
107 *
108 * @param name The SpoVNet name
109 * @param param The SpoVNet properties
110 */
111 void initiate(const Name& name, const SpoVNetProperties& parm =
112 SpoVNetProperties::DEFAULT);
113
114 /**
115 * This method initiates the leave procedure of this node.
116 */
117 void leave();
118
119 /**
120 * This method is used to bind a node listener to this node.
121 *
122 * @param listener The node listener
123 */
124 void bind(NodeListener* listener);
125
126 /**
127 * This method is used to unbind a node listener to this node.
128 *
129 * @param listener The node listener
130 */
131 void unbind(NodeListener* listener);
132
133 //--- spovnet properties ---
134
135 /**
136 * Returns the properties of the spovnet the node has joined.
137 *
138 * @return The properties of the spovnet the node has joined
139 */
140 const SpoVNetProperties& getSpoVNetProperties() const;
141
142 /**
143 * Returns the spovnet identifier
144 *
145 * @return The spovnet idenfifier
146 */
147 const SpoVNetID& getSpoVNetId() const;
148
149 /**
150 * Returns true, if the node is part of a spovnet.
151 *
152 * @return True, if the node is part of a spovnet
153 */
154 bool isJoined() const;
155
156 //--- addressing ---
157
158 /**
159 * Returns the node id of this node if the link id is unspecified or
160 * the node id of the remote node.
161 *
162 * @return The local or the remote node identifier
163 */
164 const NodeID& getNodeId(const LinkID& lid = LinkID::UNSPECIFIED) const;
165
166 /**
167 * Returns the node id to a node name according to the currently joined
168 * spovnet (usually derives a node identifier by hashing the name).
169 *
170 * @return The node identifier to the given name
171 */
172 NodeID generateNodeId(const Name& name) const;
173
174 /**
175 * Returns the name of this node if the link id is unspecified or
176 * the node name of the remote node, if known -- otherwise it returns
177 * an unspecified name.
178 *
179 * TODO: RFE -- send request to remote node and inform service.
180 *
181 * @return A node's name or an unspecified name, if unknown
182 */
183 const Name getNodeName(const LinkID& lid = LinkID::UNSPECIFIED) const;
184
185 //--- communication ---
186
187 /**
188 * Establishes a new link to another node and service with the given
189 * link properties. An optional message could be sent with the request.
190 *
191 * @param nid The remote node identifier
192 * @param sid The remote service identifier
193 * @param req The required link properties
194 * @param msg An optional message that is sent with the request
195 * @return A new link id
196 */
197 LinkID establishLink(const NodeID& nid, const ServiceID& sid,
198 const LinkProperties& req = LinkProperties::DEFAULT,
199 const DataMessage& msg = DataMessage::UNSPECIFIED);
200
201 /**
202 * This method drops an established link.
203 *
204 * @param lnk The link identifier of an active link
205 */
206 void dropLink(const LinkID& lnk);
207
208 // message sending
209
210 /**
211 * Sends a one-shot message to a service. If link properties are specified,
212 * the node tries to fulfill those requirements. This may cause the node
213 * to first establish a temporary link, second sending the message and last
214 * dropping the link. This would result in a small amount of extra latency
215 * until the message is delivered. If reliable transport was selected,
216 * the method returns a sequence number and a communication event is
217 * triggered on message delivery or loss.
218 *
219 * @param msg The message to be sent
220 * @param nid The remote node identifier
221 * @param sid The remote service identifier
222 * @param req The requirements associated with the message
223 * @return A sequence number
224 */
225 seqnum_t sendMessage(const DataMessage& msg, const NodeID& nid, const ServiceID& sid,
226 const LinkProperties& req = LinkProperties::DEFAULT);
227
228 /**
229 * Sends a message via an established link. If reliable transport was
230 * selected, the method returns a sequence number and a communication event
231 * is triggered on message delivery or loss.
232 *
233 * @param msg The message to be sent
234 * @param lnk The link to be used for sending the message
235 */
236 seqnum_t sendMessage(const DataMessage& msg, const LinkID& lnk);
237
238 // --- communication listeners ---
239
240 /**
241 * Binds a listener to a specifed service identifier.
242 * Whenever a link is established/dropped or messages are received the
243 * events inside the interface are called.
244 *
245 * @param listener The listener to be registered
246 * @param sid The service identifier
247 */
248 void bind(CommunicationListener* listener, const ServiceID& sid);
249
250 /**
251 * Un-binds a listener from this node.
252 *
253 * @param The listener to be unbound
254 */
255 void unbind(CommunicationListener* listener, const ServiceID& sid);
256
257 // --- extension proposal: service directory -- TODO
258 // main-idea: use this methods to register groups/rendevous points inside
259 // the base overlay via a distributed storage service.
260 //
261 //void put(const KeyID& key, Message* value);
262 //void get(const KeyID& key);
263 //-------------------------------------------------------------------------
264 //
265 // --- optimization proposal: allow direct endpoint descriptor exchange ---
266 // main-idea: directly allow exchanging endpoint descriptors to establish
267 // links. Depending on the overlay structure used in the base overlay, this
268 // allows a node to directly establish links between two nodes when an
269 // endpoint descriptor is known.
270 //
271 //const EndpointDescriptor& getEndpointDescriptor( const LinkID& lid );
272 //void sendMessage( EndpointDescriptor& epd, Message* msg );
273 //LinkID setupLink( const EndpointDescriptor& endpointDesc,
274 // const LinkProperties& req = LinkProperties::UNSPECIFIED,
275 // const Message* msg = NULL );
276 //
277 //-------------------------------------------------------------------------
278
279 // --- module implementation ---
280 //
281 // main-idea: use module properties to configure nodeid, spovnetid etc. and
282 // select start/stop procedures. This allows simulations to start a
283 // node without manually calling join etc.
284
285 /** @see Module.h */
286 void initialize();
287
288 /** @see Module.h */
289 void start();
290
291 /** @see Module.h */
292 void stop();
293
294 /** @see Module.h */
295 string getName() const;
296
297 /** @see Module.h */
298 void setProperty(string key, string value);
299
300 /** @see Module.h */
301 const string getProperty(string key) const;
302
303 /** @see Module.h */
304 const vector<string> getProperties() const;
305
306protected:
307 // friends
308 friend class AribaModule;
309
310 // member variables
311 Name name; //< node name
312 AribaModule& ariba_mod; //< ariba module
313 SpoVNetID spovnetId; //< current spovnet id
314 NodeID nodeId; //< current node id
315
316 // delegates
317 interface::AribaContext* context;
318 static const ServiceID anonymousService;
319};
320
321} // namespace ariba
322
323#endif /* NODE_H_ */
Note: See TracBrowser for help on using the repository browser.