An Overlay-based
Virtual Network Substrate
SpoVNet

source: source/ariba/Node.h @ 3037

Last change on this file since 3037 was 3037, checked in by Christoph Mayer, 15 years ago

-jede Menge fixes und Umstellungen
-angefangen ariba/interface los zu werden, erste dateien sind weg

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 {
44class Node;
45}
46
47#include <vector>
48#include "Module.h"
49#include "Identifiers.h"
50#include "SpoVNetProperties.h"
51#include "NodeListener.h"
52#include "Name.h"
53#include "AribaModule.h"
54#include "CommunicationListener.h"
55#include "DataMessage.h"
56
57using std::vector;
58
59namespace ariba {
60
61// forward declaration
62namespace interface {
63class ServiceInterface;
64}
65
66namespace overlay {
67class BaseOverlay;
68}
69
70/**
71 * This class should implement all ariba node functionality.
72 *
73 * @author Sebastian Mies <mies@tm.uka.de>
74 * @author Christoph Mayer <mayer@tm.uka.de>
75 */
76class Node: public Module {
77public:
78        /**
79         * Constructs a new node using a given ariba module
80         *
81         * @param ariba_mod The ariba module
82         * @param name The canonical node name of the new node. When NULL a
83         *   randomly chosen name is created.
84         * @param len The length of the canonical node name or -1, if the name
85         *   is a zero-terminated char-string.
86         */
87        Node(AribaModule& ariba_mod, const Name& node_name = Name::UNSPECIFIED);
88
89        /**
90         * Destroys the node. Before destruction some pre-conditions
91         * must be met:<br />
92         *
93         * 1. The node is not part of any SpoVNet <br />
94         * 2. All listeners must be unbound from this node <br />
95         * 3. The module has been stopped<br />
96         */
97        ~Node();
98
99        //--- node control ---
100
101        /**
102         * This method instructs the node to join a particular spovnet.
103         * Callees may bind with a NodeListener to receive events, when
104         * a node has been successfully joined.
105         *
106         * @param vnetId The SpoVNet name
107         */
108        void join(const Name& name);
109
110        /**
111         * This method initiates a new SpoVNet with the given SpoVNetID and
112         * parameters.
113         *
114         * @param name The SpoVNet name
115         * @param param The SpoVNet properties
116         */
117        void initiate(const Name& name, const SpoVNetProperties& parm =
118                        SpoVNetProperties::DEFAULT);
119
120        /**
121         * This method initiates the leave procedure of this node.
122         */
123        void leave();
124
125        /**
126         * This method is used to bind a node listener to this node.
127         *
128         * @param listener The node listener
129         */
130        void bind(NodeListener* listener);
131
132        /**
133         * This method is used to unbind a node listener to this node.
134         *
135         * @param listener The node listener
136         */
137        void 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                        const LinkProperties& req = LinkProperties::DEFAULT,
215                        const DataMessage& msg = DataMessage::UNSPECIFIED);
216
217        /**
218         * This method drops an established link.
219         *
220         * @param lnk The link identifier of an active link
221         */
222        void dropLink(const LinkID& lnk);
223
224        // message sending
225
226        /**
227         * Sends a one-shot message to a service. If link properties are specified,
228         * the node tries to fulfill those requirements. This may cause the node
229         * to first establish a temporary link, second sending the message and last
230         * dropping the link. This would result in a small amount of extra latency
231         * until the message is delivered. If reliable transport was selected,
232         * the method returns a sequence number and a communication event is
233         * triggered on message delivery or loss.
234         *
235         * @param msg The message to be sent
236         * @param nid The remote node identifier
237         * @param sid The remote service identifier
238         * @param req The requirements associated with the message
239         * @return A sequence number
240         */
241        seqnum_t sendMessage(const DataMessage& msg, const NodeID& nid, const ServiceID& sid,
242                        const LinkProperties& req = LinkProperties::DEFAULT);
243
244        /**
245         * Sends a message via an established link. If reliable transport was
246         * selected, the method returns a sequence number and a communication event
247         * is triggered on message delivery or loss.
248         *
249         * @param msg The message to be sent
250         * @param lnk The link to be used for sending the message
251         */
252        seqnum_t sendMessage(const DataMessage& msg, const LinkID& lnk);
253
254        /**
255         * Sends a message to all known hosts in the overlay structure
256         * the nodes that are reached here depend on the overlay structure.
257         *
258         * @param msg The message to be send
259         * @param sid The id of the service that should receive the message
260         * @see getNeighborNodes
261         */
262        void sendBroadcastMessage(const DataMessage& msg, const ServiceID& sid);
263
264        // --- communication listeners ---
265
266        /**
267         * Binds a listener to a specifed service identifier.
268         * Whenever a link is established/dropped or messages are received the
269         * events inside the interface are called.
270         *
271         * @param listener The listener to be registered
272         * @param sid The service identifier
273         */
274        void 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         */
281        void unbind(CommunicationListener* listener, const ServiceID& sid);
282
283        // --- extension proposal: service directory -- TODO
284        // main-idea: use this methods to register groups/rendevous points inside
285        // the base overlay via a distributed storage service.
286        //
287        //void put(const KeyID& key, Message* value);
288        //void get(const KeyID& key);
289        //-------------------------------------------------------------------------
290        //
291        // --- optimization proposal: allow direct endpoint descriptor exchange ---
292        // main-idea: directly allow exchanging endpoint descriptors to establish
293        // links. Depending on the overlay structure used in the base overlay, this
294        // allows a node to directly establish links between two nodes when an
295        // endpoint descriptor is known.
296        //
297        //const EndpointDescriptor& getEndpointDescriptor( const LinkID& lid );
298        //void sendMessage( EndpointDescriptor& epd, Message* msg );
299        //LinkID setupLink( const EndpointDescriptor& endpointDesc,
300        //              const LinkProperties& req = LinkProperties::UNSPECIFIED,
301        //              const Message* msg = NULL );
302        //
303        //-------------------------------------------------------------------------
304
305        // --- module implementation ---
306        //
307        // main-idea: use module properties to configure nodeid, spovnetid etc. and
308        // select start/stop procedures. This allows simulations to start a
309        // node without manually calling join etc.
310
311        /** @see Module.h */
312        void initialize();
313
314        /** @see Module.h */
315        void start();
316
317        /** @see Module.h */
318        void stop();
319
320        /** @see Module.h */
321        string getName() const;
322
323        /** @see Module.h */
324        void setProperty(string key, string value);
325
326        /** @see Module.h */
327        const string getProperty(string key) const;
328
329        /** @see Module.h */
330        const vector<string> getProperties() const;
331
332protected:
333        // friends
334        friend class AribaModule;
335
336        // member variables
337        Name name;                             //< node name
338        AribaModule& ariba_mod;                //< ariba module
339        SpoVNetID spovnetId;                   //< current spovnet id
340        NodeID nodeId;                             //< current node id
341        overlay::BaseOverlay* base_overlay;    //< the base overlay
342
343        // delegates
344        static ServiceID anonymousService;
345};
346
347} // namespace ariba
348
349#endif /* NODE_H_ */
Note: See TracBrowser for help on using the repository browser.