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