Changeset 3690 for source/ariba/overlay/modules/OverlayInterface.h

Timestamp:

May 26, 2009, 1:40:23 AM (14 years ago)

Author:

mies

Message:

Merged 20090512-mies-connectors changes r3472:r3689 into trunk.

File:

• source/ariba/overlay/modules/OverlayInterface.h (modified) (3 diffs)

source/ariba/overlay/modules/OverlayInterface.h

@@ -1 @@
-// [Licence]
+// [License]
 // The Ariba-Underlay Copyright
 //
@@ -35 +35 @@
 // official policies, either expressed or implied, of the Institute of
 // Telematics.
-// [Licence]
+// [License]
 
 #ifndef __OVERLAY_INTERFACE_H
@@ -57 +57 @@
 class BaseOverlay;
 
-class OverlayInterface : public CommunicationListener {
+/**
+ * This class declares an interface for an structured overlay.
+ */
+class OverlayInterface: public CommunicationListener {
         friend class BaseOverlay;
+
 public:
+        /**
+         * A node list
+         */
+        typedef vector<NodeID> NodeList;
+
+        /**
+         * Constructs a new overlay.
+         */
         OverlayInterface(
-                BaseOverlay& _baseoverlay,
-                const NodeID& _nodeid,
-                OverlayStructureEvents* _eventsReceiver
-        );
+                        BaseOverlay& _baseoverlay,
+                        const NodeID& _nodeid,
+                        OverlayStructureEvents* _eventsReceiver );
 
+        /**
+         * Destrcuts the overlay.
+         */
         virtual ~OverlayInterface();
 
-        typedef vector<NodeID> NodeList;
+        /**
+         * Creates the overlay.
+         */
+        virtual void createOverlay() = 0;
 
-        virtual void createOverlay() = 0;
+        /**
+         * Destroys the overlay.
+         */
         virtual void deleteOverlay() = 0;
 
-        virtual void joinOverlay( const EndpointDescriptor& bootstrapEp = EndpointDescriptor::UNSPECIFIED) = 0;
+        /**
+         * Joins the overlay. Starts integration and stabilization of the overlay
+         * Node.
+         *
+         * @param bootstrap The bootstrap end-point descriptor or the default
+         *    end-point, if this node is the initiator
+         */
+        virtual void joinOverlay(const EndpointDescriptor& bootstrap =
+                EndpointDescriptor::UNSPECIFIED ) = 0;
+
+        /**
+         * Leaves the overlay gracefully.
+         */
         virtual void leaveOverlay() = 0;
 
-        virtual const EndpointDescriptor& resolveNode( const NodeID& node ) = 0;
-        virtual void routeMessage( const NodeID& destnode, Message* msg ) = 0;
+        /**
+         * Resolves a overlay neighbor.
+         *
+         * @param node The node to resolve
+         * @return Endpoint descriptor of local neighbor or UNSPECIFIED
+         */
+        virtual const EndpointDescriptor& resolveNode(const NodeID& node) = 0;
 
+        /**
+         * Routes a message to a given node by using overlay routing.
+         *
+         * @param destnode The destination node.
+         * @param msg The message to be routed.
+         */
+        virtual void routeMessage(const NodeID& destnode, Message* msg) = 0;
+
+        /**
+         * Returns the nodes known to this overlay.
+         *
+         * Usually this are the direct neighbors in the overlay structure.
+         * For instance, Chord would return his predecessor, successor and finger
+         * nodes. On the other hand OneHop would likely return all participating
+         * nodes in the overlay.
+         *
+         * @return The list of all known nodes
+         */
         virtual NodeList getKnownNodes() const = 0;
 
-        // functions from CommunicationListener that we _can_ use as overlay
+        //--- functions from CommunicationListener that we _can_ use as overlay ---
+
+        /// @see CommunicationListener
         virtual void onLinkUp(const LinkID& lnk, const NodeID& remote);
+        /// @see CommunicationListener
         virtual void onLinkDown(const LinkID& lnk, const NodeID& remote);
+        /// @see CommunicationListener
         virtual void onLinkChanged(const LinkID& lnk, const NodeID& remote);
+        /// @see CommunicationListener
         virtual void onLinkFail(const LinkID& lnk, const NodeID& remote);
-        virtual void onLinkQoSChanged(const LinkID& lnk, const NodeID& remote, const LinkProperties& prop);
+        /// @see CommunicationListener
+        virtual void onLinkQoSChanged(const LinkID& lnk, const NodeID& remote,
+                        const LinkProperties& prop);
+        /// @see CommunicationListener
         virtual bool onLinkRequest(const NodeID& remote, const DataMessage& msg);
-        virtual void onMessage(const DataMessage& msg, const NodeID& remote, const LinkID& lnk = LinkID::UNSPECIFIED);
+        /// @see CommunicationListener
+        virtual void onMessage(const DataMessage& msg, const NodeID& remote,
+                        const LinkID& lnk = LinkID::UNSPECIFIED);
 
 protected:
+
+        /// Reference to an active base overlay
         BaseOverlay& baseoverlay;
+
+        /// The node identifier to use with this overlay
         const NodeID& nodeid;
+
+        /// The listener used to inform about overlay structure changes
         OverlayStructureEvents* eventsReceiver;
+
+        /// The service identifer of this overlay
         static ServiceID OVERLAY_SERVICE_ID;
 };