source: source/ariba/Node.h@ 12771

Last change on this file since 12771 was 12769, checked in by hock@…, 11 years ago

made message_not_sent exception accessible from applications (and services)
File size: 13.3 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#ifndef NODE_H_
40#define NODE_H_
41
42// forward declarations
43namespace ariba {
44 class Node;
45 namespace communication {
46 class BaseCommunication;
47 }
48 namespace overlay {
49 class BaseOverlay;
50 }
51}
52
53#include <vector>
54#include <iostream>
55#include <exception>
56
57#include "Module.h"
58#include "Identifiers.h"
59#include "SpoVNetProperties.h"
60#include "NodeListener.h"
61#include "Name.h"
62//#include "AribaModule.h"
63#include "CommunicationListener.h"
64#include "DataMessage.h"
65#include "SideportListener.h"
66#include "ariba/overlay/SequenceNumber.h"
67#include "ariba/utility/logging/Logging.h"
68#include "ariba/overlay/PublicExceptions.h"
69
70// reboost messages
71#include "ariba/utility/transport/messages/message.hpp"
72
73#include <boost/property_tree/ptree.hpp>
74
75using std::vector;
76using ariba::overlay::BaseOverlay;
77
78namespace ariba {
79
80typedef overlay::message_not_sent message_not_sent;
81// typedef ariba::overlay::SequenceNumber SequenceNumber; // XXX see CommunicationListener
82
83using boost::property_tree::ptree;
84
85// sendMessage-Priorities
86struct send_priority
87{
88 enum SEND_PRIORITY
89 {
90 HIGHEST = 2,
91 HIGHER = 3,
92 NORMAL = 4,
93 LOWER = 5,
94 LOWEST = 6
95 };
96};
97
98
99
100/**
101 * \addtogroup public
102 * @{
103 *
104 * This class should implement all ariba node functionality.
105 *
106 * @author Sebastian Mies <mies@tm.uka.de>
107 * @author Christoph Mayer <mayer@tm.uka.de>
108 */
109// TODO do we really want to inherit from Module.. ?
110class Node: public Module {
111 use_logging_h(Node);
112public:
113
114 /**
115 * Constructs a new node using a given ariba module
116 *
117 * @param ariba_mod The ariba module
118 * @param name The canonical node name of the new node. When NULL a
119 * randomly chosen name is created.
120 * @param len The length of the canonical node name or -1, if the name
121 * is a zero-terminated char-string.
122 */
123// Node(AribaModule& ariba_mod, const Name& node_name = Name::UNSPECIFIED);
124
125 // XXX EXPERIMENTAL
126 Node();
127
128 /**
129 * Destroys the node. Before destruction some pre-conditions
130 * must be met:<br />
131 *
132 * 1. The node is not part of any SpoVNet <br />
133 * 2. All listeners must be unbound from this node <br />
134 * 3. The module has been stopped<br />
135 */
136 virtual ~Node();
137
138 //--- node control ---
139
140 /**
141 * XXX EXPERIMENTAL
142 *
143 * Replaces initialte & join
144 */
145 void connect(const ptree& config);
146
147 // XXX DEPRECATED
148 /**
149 * This method instructs the node to join a particular spovnet.
150 * Callees may bind with a NodeListener to receive events, when
151 * a node has been successfully joined.
152 *
153 * @param vnetId The SpoVNet name
154 */
155// void join(const Name& name);
156
157 /**
158 * This method initiates a new SpoVNet with the given SpoVNetID and
159 * parameters.
160 *
161 * @param name The SpoVNet name
162 * @param param The SpoVNet properties
163 */
164// void initiate(const Name& name, const SpoVNetProperties& parm =
165// SpoVNetProperties::DEFAULT);
166
167 /**
168 * This method initiates the leave procedure of this node.
169 */
170 void leave();
171
172 /**
173 * This method is used to bind a node listener to this node.
174 *
175 * @param listener The node listener
176 * @return boolean indicating success of failure
177 */
178 bool bind(NodeListener* listener);
179
180 /**
181 * This method is used to unbind a node listener to this node.
182 *
183 * @param listener The node listener
184 * @return boolean indicating success of failure
185 */
186 bool unbind(NodeListener* listener);
187
188 //--- spovnet properties ---
189
190 /**
191 * Returns the properties of the spovnet the node has joined.
192 *
193 * @return The properties of the spovnet the node has joined
194 */
195 const SpoVNetProperties& getSpoVNetProperties() const;
196
197 /**
198 * Returns the spovnet identifier
199 *
200 * @return The spovnet idenfifier
201 */
202 const SpoVNetID& getSpoVNetId() const;
203
204 /**
205 * Returns true, if the node is part of a spovnet.
206 *
207 * @return True, if the node is part of a spovnet
208 */
209 bool isJoined() const;
210
211 //--- addressing ---
212
213 /**
214 * Returns the node id of this node if the link id is unspecified or
215 * the node id of the remote node.
216 *
217 * @return The local or the remote node identifier
218 */
219 const NodeID& getNodeId(const LinkID& lid = LinkID::UNSPECIFIED) const;
220
221 /**
222 * Returns the node id to a node name according to the currently joined
223 * spovnet (usually derives a node identifier by hashing the name).
224 *
225 * @return The node identifier to the given name
226 */
227 NodeID generateNodeId(const Name& name) const;
228
229 /**
230 * Returns the name of this node if the link id is unspecified or
231 * the node name of the remote node, if known -- otherwise it returns
232 * an unspecified name.
233 *
234 * @return A node's name or an unspecified name, if unknown
235 */
236 const Name getNodeName(const LinkID& lid = LinkID::UNSPECIFIED) const;
237
238 /**
239 * Get a list of neighboring nodes in the overlay structure.
240 * The number and identities of nodes depends highly on the
241 * used overlay structure.
242 *
243 * @return a list of NodeIDs that are neighbors in the overlay structure
244 * @see sendBroadcastMessage
245 */
246 vector<NodeID> getNeighborNodes() const;
247
248 //--- communication ---
249
250 /**
251 * Establishes a new link to another node and service with the given
252 * link properties. An optional message could be sent with the request.
253 *
254 * @param nid The remote node identifier
255 * @param sid The remote service identifier
256 * @param req The required link properties
257 * @param msg An optional message that is sent with the request
258 * @return A new link id
259 */
260 LinkID establishLink(const NodeID& nid, const ServiceID& sid);
261
262 /**
263 * This method drops an established link.
264 *
265 * @param lnk The link identifier of an active link
266 */
267 void dropLink(const LinkID& lnk);
268
269 /**
270 * Returns whether a link is direct or relayed over other nodes
271 * @param lnk LinkID of the link
272 * @return true if link is direct; false otherwise
273 */
274 bool isLinkDirect(const ariba::LinkID& lnk) const;
275
276 /**
277 * Returns the latest measured hop count on this link.
278 * NOTE: This is not guaranteed to be up to date.
279 *
280 * @param lnk LinkID of the link
281 * @return overlay hop count on this link
282 */
283 int getHopCount(const ariba::LinkID& lnk) const;
284
285
286 /* +++++ Message sending +++++ */
287
288
289 /**
290 * Sends a message via an established link. If reliable transport was
291 * selected, the method returns a sequence number and a communication event
292 * is triggered on message delivery or loss.
293 *
294 * +++ New interface, using efficient zero-copy reboost messages. +++
295 *
296 * @param msg The message to be sent
297 * @param lnk The link to be used for sending the message
298 */
299 const SequenceNumber& sendMessage(reboost::message_t msg, const LinkID& lnk, uint8_t priority=send_priority::NORMAL);
300
301 /**
302 * +++ Legacy interface, converts old ariba messages into new reboost messages. +++
303 */
304 seqnum_t sendMessage(const DataMessage& msg, const LinkID& lnk);
305
306
307 /**
308 * Sends a one-shot message to a service. If link properties are specified,
309 * the node tries to fulfill those requirements. This may cause the node
310 * to first establish a temporary link, second sending the message and last
311 * dropping the link. This would result in a small amount of extra latency
312 * until the message is delivered. If reliable transport was selected,
313 * the method returns a sequence number and a communication event is
314 * triggered on message delivery or loss.
315 *
316 * +++ New interface, using efficient zero-copy reboost messages. +++
317 *
318 * @param msg The message to be sent
319 * @param nid The remote node identifier
320 * @param sid The remote service identifier
321 * @param req The requirements associated with the message
322 * @return A sequence number
323 */
324 const SequenceNumber& sendMessage(reboost::message_t msg, const NodeID& nid, const ServiceID& sid,
325 uint8_t priority=send_priority::NORMAL, const LinkProperties& req = LinkProperties::DEFAULT);
326
327 /**
328 * +++ Legacy interface, converts old ariba messages into new reboost messages. +++
329 */
330 seqnum_t sendMessage(const DataMessage& msg, const NodeID& nid, const ServiceID& sid,
331 const LinkProperties& req = LinkProperties::DEFAULT);
332
333
334 /**
335 * like the above function, but sends the message to the closest directly known node
336 * to the specified address
337 *
338 * +++ New interface, using efficient zero-copy reboost messages. +++
339 *
340 */
341 NodeID sendMessageCloserToNodeID(reboost::message_t msg, const NodeID& nid, const ServiceID& sid,
342 uint8_t priority=send_priority::NORMAL, const LinkProperties& req = LinkProperties::DEFAULT);
343
344 /**
345 * +++ Legacy interface, converts old ariba messages into new reboost messages. +++
346 */
347 NodeID sendMessageCloserToNodeID(const DataMessage& msg, const NodeID& nid, const ServiceID& sid,
348 const LinkProperties& req = LinkProperties::DEFAULT);
349
350
351 /**
352 * Sends a message to all known hosts in the overlay structure
353 * the nodes that are reached here depend on the overlay structure.
354 *
355 * +++ New interface, using efficient zero-copy reboost messages. +++
356 *
357 * @param msg The message to be send
358 * @param sid The id of the service that should receive the message
359 * @see getNeighborNodes
360 */
361 void sendBroadcastMessage(reboost::message_t msg, const ServiceID& sid, uint8_t priority=send_priority::NORMAL);
362
363 /**
364 * +++ Legacy interface, converts old ariba messages into new reboost messages. +++
365 */
366 void sendBroadcastMessage(const DataMessage& msg, const ServiceID& sid);
367
368
369 /* +++++ [Message sending] +++++ */
370
371
372
373 // --- communication listeners ---
374
375 /**
376 * Binds a listener to a specifed service identifier.
377 * Whenever a link is established/dropped or messages are received the
378 * events inside the interface are called.
379 *
380 * @param listener The listener to be registered
381 * @param sid The service identifier
382 * @return boolean indicating success of failure
383 */
384 bool bind(CommunicationListener* listener, const ServiceID& sid);
385
386 /**
387 * Un-binds a listener from this node.
388 *
389 * @param The listener to be unbound
390 * @return boolean indicating success of failure
391 */
392 bool unbind(CommunicationListener* listener, const ServiceID& sid);
393
394 //-------------------------------------------------------------------------
395 //
396 // --- optimization proposal: allow direct endpoint descriptor exchange ---
397 // main-idea: directly allow exchanging endpoint descriptors to establish
398 // links. Depending on the overlay structure used in the base overlay, this
399 // allows a node to directly establish links between two nodes when an
400 // endpoint descriptor is known.
401 //
402 //const EndpointDescriptor& getEndpointDescriptor( const LinkID& lid );
403 //void sendMessage( EndpointDescriptor& epd, Message* msg );
404 //LinkID setupLink( const EndpointDescriptor& endpointDesc,
405 // const LinkProperties& req = LinkProperties::UNSPECIFIED,
406 // const Message* msg = NULL );
407 //
408 //-------------------------------------------------------------------------
409
410 // --- module implementation ---
411 //
412 // main-idea: use module properties to configure nodeid, spovnetid etc. and
413 // select start/stop procedures. This allows simulations to start a
414 // node without manually calling join etc.
415
416 /** @see Module.h */
417 string getName() const;
418
419
420private:
421 inline void check_send_priority(uint8_t priority);
422
423
424protected:
425 // friends
426 friend class AribaModule;
427
428 // member variables
429 Name name; //< node name
430// AribaModule* ariba_mod; //< ariba module
431 SpoVNetID spovnetId; //< current spovnet id
432 NodeID nodeId; //< current node id
433 communication::BaseCommunication* base_communication;
434 overlay::BaseOverlay* base_overlay; //< the base overlay
435
436};
437
438} // namespace ariba
439
440/** @} */
441
442#endif /* NODE_H_ */
Note: See TracBrowser for help on using the repository browser.