An Overlay-based
Virtual Network Substrate
SpoVNet

source: source/ariba/Node.h @ 12438

Last change on this file since 12438 was 12350, checked in by s_taenzer@…, 9 years ago

Logging: Properly enable logging with Log4Cxx in Node

File size: 13.2 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 communication {
46        class BaseCommunication;
47    }
48    namespace overlay {
49        class BaseOverlay;
50    }
51}
52
53#include <vector>
54#include <iostream>
55#include <exception>
56
57#include "Module.h"
58#include "Identifiers.h"
59#include "SpoVNetProperties.h"
60#include "NodeListener.h"
61#include "Name.h"
62//#include "AribaModule.h"
63#include "CommunicationListener.h"
64#include "DataMessage.h"
65#include "SideportListener.h"
66#include "ariba/overlay/SequenceNumber.h"
67#include "ariba/utility/logging/Logging.h"
68
69// reboost messages
70#include "ariba/utility/transport/messages/message.hpp"
71
72#include <boost/property_tree/ptree.hpp>
73
74using std::vector;
75using ariba::overlay::BaseOverlay;
76
77namespace ariba {
78
79// typedef ariba::overlay::SequenceNumber SequenceNumber; // XXX see CommunicationListener
80
81using boost::property_tree::ptree;
82
83// sendMessage-Priorities
84struct send_priority
85{
86    enum SEND_PRIORITY
87    {
88        HIGHEST = 2,
89        HIGHER = 3,
90        NORMAL = 4,
91        LOWER = 5,
92        LOWEST = 6
93    };
94};
95
96
97
98/**
99 * \addtogroup public
100 * @{
101 *
102 * This class should implement all ariba node functionality.
103 *
104 * @author Sebastian Mies <mies@tm.uka.de>
105 * @author Christoph Mayer <mayer@tm.uka.de>
106 */
107// TODO do we really want to inherit from Module.. ?
108class Node: public Module {
109        use_logging_h(Node);
110public:
111   
112        /**
113         * Constructs a new node using a given ariba module
114         *
115         * @param ariba_mod The ariba module
116         * @param name The canonical node name of the new node. When NULL a
117         *   randomly chosen name is created.
118         * @param len The length of the canonical node name or -1, if the name
119         *   is a zero-terminated char-string.
120         */
121//      Node(AribaModule& ariba_mod, const Name& node_name = Name::UNSPECIFIED);
122       
123        // XXX EXPERIMENTAL
124        Node();
125
126        /**
127         * Destroys the node. Before destruction some pre-conditions
128         * must be met:<br />
129         *
130         * 1. The node is not part of any SpoVNet <br />
131         * 2. All listeners must be unbound from this node <br />
132         * 3. The module has been stopped<br />
133         */
134        virtual ~Node();
135
136        //--- node control ---
137
138    /**
139     * XXX EXPERIMENTAL
140     *
141     * Replaces initialte & join
142     */
143    void connect(const ptree& config);
144
145    // XXX DEPRECATED
146        /**
147         * This method instructs the node to join a particular spovnet.
148         * Callees may bind with a NodeListener to receive events, when
149         * a node has been successfully joined.
150         *
151         * @param vnetId The SpoVNet name
152         */
153//      void join(const Name& name);
154
155        /**
156         * This method initiates a new SpoVNet with the given SpoVNetID and
157         * parameters.
158         *
159         * @param name The SpoVNet name
160         * @param param The SpoVNet properties
161         */
162//      void initiate(const Name& name, const SpoVNetProperties& parm =
163//                      SpoVNetProperties::DEFAULT);
164
165        /**
166         * This method initiates the leave procedure of this node.
167         */
168        void leave();
169
170        /**
171         * This method is used to bind a node listener to this node.
172         *
173         * @param listener The node listener
174         * @return boolean indicating success of failure
175         */
176        bool bind(NodeListener* listener);
177
178        /**
179         * This method is used to unbind a node listener to this node.
180         *
181         * @param listener The node listener
182         * @return boolean indicating success of failure
183         */
184        bool unbind(NodeListener* listener);
185
186        //--- spovnet properties ---
187
188        /**
189         * Returns the properties of the spovnet the node has joined.
190         *
191         * @return The properties of the spovnet the node has joined
192         */
193        const SpoVNetProperties& getSpoVNetProperties() const;
194
195        /**
196         * Returns the spovnet identifier
197         *
198         * @return The spovnet idenfifier
199         */
200        const SpoVNetID& getSpoVNetId() const;
201
202        /**
203         * Returns true, if the node is part of a spovnet.
204         *
205         * @return True, if the node is part of a spovnet
206         */
207        bool isJoined() const;
208
209        //--- addressing ---
210
211        /**
212         * Returns the node id of this node if the link id is unspecified or
213         * the node id of the remote node.
214         *
215         * @return The local or the remote node identifier
216         */
217        const NodeID& getNodeId(const LinkID& lid = LinkID::UNSPECIFIED) const;
218
219        /**
220         * Returns the node id to a node name according to the currently joined
221         * spovnet (usually derives a node identifier by hashing the name).
222         *
223         * @return The node identifier to the given name
224         */
225        NodeID generateNodeId(const Name& name) const;
226
227        /**
228         * Returns the name of this node if the link id is unspecified or
229         * the node name of the remote node, if known -- otherwise it returns
230         * an unspecified name.
231         *
232         * @return A node's name or an unspecified name, if unknown
233         */
234        const Name getNodeName(const LinkID& lid = LinkID::UNSPECIFIED) const;
235
236        /**
237         * Get a list of neighboring nodes in the overlay structure.
238         * The number and identities of nodes depends highly on the
239         * used overlay structure.
240         *
241         * @return a list of NodeIDs that are neighbors in the overlay structure
242         * @see sendBroadcastMessage
243         */
244        vector<NodeID> getNeighborNodes() const;
245
246        //--- communication ---
247
248        /**
249         * Establishes a new link to another node and service with the given
250         * link properties. An optional message could be sent with the request.
251         *
252         * @param nid The remote node identifier
253         * @param sid The remote service identifier
254         * @param req The required link properties
255         * @param msg An optional message that is sent with the request
256         * @return A new link id
257         */
258        LinkID establishLink(const NodeID& nid, const ServiceID& sid);
259
260        /**
261         * This method drops an established link.
262         *
263         * @param lnk The link identifier of an active link
264         */
265        void dropLink(const LinkID& lnk);
266
267        /**
268         * Returns whether a link is direct or relayed over other nodes
269         * @param lnk LinkID of the link
270         * @return true if link is direct; false otherwise
271         */
272        bool isLinkDirect(const ariba::LinkID& lnk) const;
273       
274        /**
275         * Returns the latest measured hop count on this link.
276         * NOTE: This is not guaranteed to be up to date.
277         *
278         * @param lnk LinkID of the link
279         * @return overlay hop count on this link
280         */
281        int getHopCount(const ariba::LinkID& lnk) const;
282       
283       
284        /* +++++ Message sending +++++ */
285
286       
287    /**
288     * Sends a message via an established link. If reliable transport was
289     * selected, the method returns a sequence number and a communication event
290     * is triggered on message delivery or loss.
291     *
292     * +++ New interface, using efficient zero-copy reboost messages. +++
293     *
294     * @param msg The message to be sent
295     * @param lnk The link to be used for sending the message
296     */
297    const SequenceNumber& sendMessage(reboost::message_t msg, const LinkID& lnk, uint8_t priority=send_priority::NORMAL);
298
299    /**
300     * +++ Legacy interface, converts old ariba messages into new reboost messages. +++
301     */   
302    seqnum_t sendMessage(const DataMessage& msg, const LinkID& lnk);
303
304   
305    /**
306     * Sends a one-shot message to a service. If link properties are specified,
307     * the node tries to fulfill those requirements. This may cause the node
308     * to first establish a temporary link, second sending the message and last
309     * dropping the link. This would result in a small amount of extra latency
310     * until the message is delivered. If reliable transport was selected,
311     * the method returns a sequence number and a communication event is
312     * triggered on message delivery or loss.
313     *
314     * +++ New interface, using efficient zero-copy reboost messages. +++
315     *
316     * @param msg The message to be sent
317     * @param nid The remote node identifier
318     * @param sid The remote service identifier
319     * @param req The requirements associated with the message
320     * @return A sequence number
321     */
322    const SequenceNumber& sendMessage(reboost::message_t msg, const NodeID& nid, const ServiceID& sid,
323            uint8_t priority=send_priority::NORMAL, const LinkProperties& req = LinkProperties::DEFAULT);
324
325    /**
326     * +++ Legacy interface, converts old ariba messages into new reboost messages. +++
327     */
328        seqnum_t sendMessage(const DataMessage& msg, const NodeID& nid, const ServiceID& sid,
329                        const LinkProperties& req = LinkProperties::DEFAULT);
330
331   
332    /**
333     * like the above function, but sends the message to the closest directly known node
334     * to the specified address
335     *
336     * +++ New interface, using efficient zero-copy reboost messages. +++
337     *
338     */
339    NodeID sendMessageCloserToNodeID(reboost::message_t msg, const NodeID& nid, const ServiceID& sid,
340            uint8_t priority=send_priority::NORMAL, const LinkProperties& req = LinkProperties::DEFAULT);
341
342    /**
343     * +++ Legacy interface, converts old ariba messages into new reboost messages. +++
344     */
345    NodeID sendMessageCloserToNodeID(const DataMessage& msg, const NodeID& nid, const ServiceID& sid,
346            const LinkProperties& req = LinkProperties::DEFAULT);
347
348       
349    /**
350     * Sends a message to all known hosts in the overlay structure
351     * the nodes that are reached here depend on the overlay structure.
352     *
353     * +++ New interface, using efficient zero-copy reboost messages. +++
354     *
355     * @param msg The message to be send
356     * @param sid The id of the service that should receive the message
357     * @see getNeighborNodes
358     */
359        void sendBroadcastMessage(reboost::message_t msg, const ServiceID& sid, uint8_t priority=send_priority::NORMAL);
360
361    /**
362     * +++ Legacy interface, converts old ariba messages into new reboost messages. +++
363     */
364        void sendBroadcastMessage(const DataMessage& msg, const ServiceID& sid);
365
366       
367        /* +++++ [Message sending] +++++ */
368       
369       
370       
371        // --- communication listeners ---
372
373        /**
374         * Binds a listener to a specifed service identifier.
375         * Whenever a link is established/dropped or messages are received the
376         * events inside the interface are called.
377         *
378         * @param listener The listener to be registered
379         * @param sid The service identifier
380         * @return boolean indicating success of failure
381         */
382        bool bind(CommunicationListener* listener, const ServiceID& sid);
383
384        /**
385         * Un-binds a listener from this node.
386         *
387         * @param The listener to be unbound
388         * @return boolean indicating success of failure
389         */
390        bool unbind(CommunicationListener* listener, const ServiceID& sid);
391
392        //-------------------------------------------------------------------------
393        //
394        // --- optimization proposal: allow direct endpoint descriptor exchange ---
395        // main-idea: directly allow exchanging endpoint descriptors to establish
396        // links. Depending on the overlay structure used in the base overlay, this
397        // allows a node to directly establish links between two nodes when an
398        // endpoint descriptor is known.
399        //
400        //const EndpointDescriptor& getEndpointDescriptor( const LinkID& lid );
401        //void sendMessage( EndpointDescriptor& epd, Message* msg );
402        //LinkID setupLink( const EndpointDescriptor& endpointDesc,
403        //              const LinkProperties& req = LinkProperties::UNSPECIFIED,
404        //              const Message* msg = NULL );
405        //
406        //-------------------------------------------------------------------------
407
408        // --- module implementation ---
409        //
410        // main-idea: use module properties to configure nodeid, spovnetid etc. and
411        // select start/stop procedures. This allows simulations to start a
412        // node without manually calling join etc.
413
414        /** @see Module.h */
415        string getName() const;
416       
417       
418private:
419        inline void check_send_priority(uint8_t priority);
420
421       
422protected:
423        // friends
424        friend class AribaModule;
425
426        // member variables
427        Name name;                             //< node name
428//      AribaModule* ariba_mod;                //< ariba module
429        SpoVNetID spovnetId;                   //< current spovnet id
430        NodeID nodeId;                             //< current node id
431        communication::BaseCommunication* base_communication;
432        overlay::BaseOverlay* base_overlay;    //< the base overlay
433
434};
435
436} // namespace ariba
437
438/** @} */
439
440#endif /* NODE_H_ */
Note: See TracBrowser for help on using the repository browser.