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