source: source/ariba/Node.h@ 10002

Last change on this file since 10002 was 9684, checked in by mies, 14 years ago

almost forgot to commit: doxygen modules :)

File size: 10.5 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 overlay {
46 class BaseOverlay;
47 }
48}
49
50#include <vector>
51#include <iostream>
52#include <boost/foreach.hpp>
53#include "Module.h"
54#include "Identifiers.h"
55#include "SpoVNetProperties.h"
56#include "NodeListener.h"
57#include "Name.h"
58#include "AribaModule.h"
59#include "CommunicationListener.h"
60#include "DataMessage.h"
61#include "SideportListener.h"
62
63using std::vector;
64using ariba::overlay::BaseOverlay;
65
66namespace ariba {
67
68/**
69 * \addtogroup public
70 * @{
71 *
72 * This class should implement all ariba node functionality.
73 *
74 * @author Sebastian Mies <mies@tm.uka.de>
75 * @author Christoph Mayer <mayer@tm.uka.de>
76 */
77class Node: public Module {
78public:
79 /**
80 * Constructs a new node using a given ariba module
81 *
82 * @param ariba_mod The ariba module
83 * @param name The canonical node name of the new node. When NULL a
84 * randomly chosen name is created.
85 * @param len The length of the canonical node name or -1, if the name
86 * is a zero-terminated char-string.
87 */
88 Node(AribaModule& ariba_mod, const Name& node_name = Name::UNSPECIFIED);
89
90 /**
91 * Destroys the node. Before destruction some pre-conditions
92 * must be met:<br />
93 *
94 * 1. The node is not part of any SpoVNet <br />
95 * 2. All listeners must be unbound from this node <br />
96 * 3. The module has been stopped<br />
97 */
98 virtual ~Node();
99
100 //--- node control ---
101
102 /**
103 * This method instructs the node to join a particular spovnet.
104 * Callees may bind with a NodeListener to receive events, when
105 * a node has been successfully joined.
106 *
107 * @param vnetId The SpoVNet name
108 */
109 void join(const Name& name);
110
111 /**
112 * This method initiates a new SpoVNet with the given SpoVNetID and
113 * parameters.
114 *
115 * @param name The SpoVNet name
116 * @param param The SpoVNet properties
117 */
118 void initiate(const Name& name, const SpoVNetProperties& parm =
119 SpoVNetProperties::DEFAULT);
120
121 /**
122 * This method initiates the leave procedure of this node.
123 */
124 void leave();
125
126 /**
127 * This method is used to bind a node listener to this node.
128 *
129 * @param listener The node listener
130 * @return boolean indicating success of failure
131 */
132 bool bind(NodeListener* listener);
133
134 /**
135 * This method is used to unbind a node listener to this node.
136 *
137 * @param listener The node listener
138 * @return boolean indicating success of failure
139 */
140 bool unbind(NodeListener* listener);
141
142 //--- spovnet properties ---
143
144 /**
145 * Returns the properties of the spovnet the node has joined.
146 *
147 * @return The properties of the spovnet the node has joined
148 */
149 const SpoVNetProperties& getSpoVNetProperties() const;
150
151 /**
152 * Returns the spovnet identifier
153 *
154 * @return The spovnet idenfifier
155 */
156 const SpoVNetID& getSpoVNetId() const;
157
158 /**
159 * Returns true, if the node is part of a spovnet.
160 *
161 * @return True, if the node is part of a spovnet
162 */
163 bool isJoined() const;
164
165 //--- addressing ---
166
167 /**
168 * Returns the node id of this node if the link id is unspecified or
169 * the node id of the remote node.
170 *
171 * @return The local or the remote node identifier
172 */
173 const NodeID& getNodeId(const LinkID& lid = LinkID::UNSPECIFIED) const;
174
175 /**
176 * Returns the node id to a node name according to the currently joined
177 * spovnet (usually derives a node identifier by hashing the name).
178 *
179 * @return The node identifier to the given name
180 */
181 NodeID generateNodeId(const Name& name) const;
182
183 /**
184 * Returns the name of this node if the link id is unspecified or
185 * the node name of the remote node, if known -- otherwise it returns
186 * an unspecified name.
187 *
188 * @return A node's name or an unspecified name, if unknown
189 */
190 const Name getNodeName(const LinkID& lid = LinkID::UNSPECIFIED) const;
191
192 /**
193 * Get a list of neighboring nodes in the overlay structure.
194 * The number and identities of nodes depends highly on the
195 * used overlay structure.
196 *
197 * @return a list of NodeIDs that are neighbors in the overlay structure
198 * @see sendBroadcastMessage
199 */
200 vector<NodeID> getNeighborNodes() const;
201
202 //--- communication ---
203
204 /**
205 * Establishes a new link to another node and service with the given
206 * link properties. An optional message could be sent with the request.
207 *
208 * @param nid The remote node identifier
209 * @param sid The remote service identifier
210 * @param req The required link properties
211 * @param msg An optional message that is sent with the request
212 * @return A new link id
213 */
214 LinkID establishLink(const NodeID& nid, const ServiceID& sid);
215
216 /**
217 * This method drops an established link.
218 *
219 * @param lnk The link identifier of an active link
220 */
221 void dropLink(const LinkID& lnk);
222
223 // message sending
224
225 /**
226 * Sends a one-shot message to a service. If link properties are specified,
227 * the node tries to fulfill those requirements. This may cause the node
228 * to first establish a temporary link, second sending the message and last
229 * dropping the link. This would result in a small amount of extra latency
230 * until the message is delivered. If reliable transport was selected,
231 * the method returns a sequence number and a communication event is
232 * triggered on message delivery or loss.
233 *
234 * @param msg The message to be sent
235 * @param nid The remote node identifier
236 * @param sid The remote service identifier
237 * @param req The requirements associated with the message
238 * @return A sequence number
239 */
240 seqnum_t sendMessage(const DataMessage& msg, const NodeID& nid, const ServiceID& sid,
241 const LinkProperties& req = LinkProperties::DEFAULT);
242
243 /**
244 * Sends a message via an established link. If reliable transport was
245 * selected, the method returns a sequence number and a communication event
246 * is triggered on message delivery or loss.
247 *
248 * @param msg The message to be sent
249 * @param lnk The link to be used for sending the message
250 */
251 seqnum_t sendMessage(const DataMessage& msg, const LinkID& lnk);
252
253 /**
254 * Sends a message to all known hosts in the overlay structure
255 * the nodes that are reached here depend on the overlay structure.
256 *
257 * @param msg The message to be send
258 * @param sid The id of the service that should receive the message
259 * @see getNeighborNodes
260 */
261 void sendBroadcastMessage(const DataMessage& msg, const ServiceID& sid);
262
263 // --- communication listeners ---
264
265 /**
266 * Binds a listener to a specifed service identifier.
267 * Whenever a link is established/dropped or messages are received the
268 * events inside the interface are called.
269 *
270 * @param listener The listener to be registered
271 * @param sid The service identifier
272 * @return boolean indicating success of failure
273 */
274 bool bind(CommunicationListener* listener, const ServiceID& sid);
275
276 /**
277 * Un-binds a listener from this node.
278 *
279 * @param The listener to be unbound
280 * @return boolean indicating success of failure
281 */
282 bool unbind(CommunicationListener* listener, const ServiceID& sid);
283
284 /**
285 * Adds a key value pair to the DHT
286 *
287 * @param key The key data
288 * @param value The value data
289 * @param ttl The time to live in seconds
290 */
291 void put( const Data& key, const Data& value, uint16_t ttl, bool replace = false);
292
293 /**
294 * Queries for values stored in the DHT. Fires an communication event when
295 * values arrive.
296 *
297 * @param key The key data
298 * @param sid The service that is requesting the values
299 */
300 void get( const Data& key, const ServiceID& sid );
301
302
303 //-------------------------------------------------------------------------
304 //
305 // --- optimization proposal: allow direct endpoint descriptor exchange ---
306 // main-idea: directly allow exchanging endpoint descriptors to establish
307 // links. Depending on the overlay structure used in the base overlay, this
308 // allows a node to directly establish links between two nodes when an
309 // endpoint descriptor is known.
310 //
311 //const EndpointDescriptor& getEndpointDescriptor( const LinkID& lid );
312 //void sendMessage( EndpointDescriptor& epd, Message* msg );
313 //LinkID setupLink( const EndpointDescriptor& endpointDesc,
314 // const LinkProperties& req = LinkProperties::UNSPECIFIED,
315 // const Message* msg = NULL );
316 //
317 //-------------------------------------------------------------------------
318
319 // --- module implementation ---
320 //
321 // main-idea: use module properties to configure nodeid, spovnetid etc. and
322 // select start/stop procedures. This allows simulations to start a
323 // node without manually calling join etc.
324
325 /** @see Module.h */
326 string getName() const;
327
328protected:
329 // friends
330 friend class AribaModule;
331
332 // member variables
333 Name name; //< node name
334 AribaModule& ariba_mod; //< ariba module
335 SpoVNetID spovnetId; //< current spovnet id
336 NodeID nodeId; //< current node id
337 overlay::BaseOverlay* base_overlay; //< the base overlay
338
339};
340
341} // namespace ariba
342
343/** @} */
344
345#endif /* NODE_H_ */
Note: See TracBrowser for help on using the repository browser.