source: source/ariba/Node.h@ 3056

Last change on this file since 3056 was 3055, checked in by Christoph Mayer, 16 years ago

-temporärer commit, sorry kompiliert nicht :( muss aber die änderungen auf die andere maschine kriegen, ist in ca1h gefixt.

File size: 10.4 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 "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
60using ariba::overlay::BaseOverlay;
61using std::vector;
62
63namespace 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 */
71class Node: public Module {
72public:
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
327protected:
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_ */
Note: See TracBrowser for help on using the repository browser.