wns::node Namespace Reference

Basic building blocks for a simulation : The Node. More...

Classes
class	Interface
	Interface of Node. More...
class	Node
	Contains various Components to form a network element in a simulation. More...
class	NodeSimulationModel
Namespaces
namespace	component
namespace	tests
Typedefs
typedef wns::container::Registry < std::string, node::Interface * >	Registry

---

Detailed Description

A simulation consists of a number of Nodes (Node), which are communicating with each other. As a simple example consider two Nodes (Node), a Server (WebServer) and a Client (WebBrowser):

Each node contains several components that enable communication. In this example components are WiMAX, IP, TCP, Webserver, WebBrowser. Before we continue we will define what we mean when talking about nodes and components:

Node

• A Node contains components.
• A Node is responsible of creating, destroying and managing its components.
• A Node enables components to connect to each other.
• A Node has a unique name within a simulation.

Component

The component semantics have been borrowed from UML 2.0. In "The Unified Modeling Language Reference Manual, Second Edition" Rumbaugh et.al. state that a component is

"A modular part of a system design that hides its implementation behind a set of external interfaces. Within a a system, components satisfying the same interfaces may be substituted freely."

This is in accordance with our understanding of a component. In particular we have the following specializations:

• All Components have one parent node.
• All Components have a unique name within the context of their parent node.
• Specific components realize and/or uses services.
• Specific components know how to connect to other specific components that realize required services.

A node is only little more than a container for components. The minimal (but very useless) component only has a parent node and a name. It does not offer or require any services. However, a component that does not do anything is not very usefull. Therefore components realize services. These services are realized by depending on other services that are offered by other components (remember ISO/OSI?). How these services look like is out of scope of the component concept. The only requirement on all components is that they implement the component::findOtherComponents method which is called after all components within a node have been created. Here the component needs to find its required services (details see below). But now back to the interesting stuff:

The nodes (Node) are communicating via TCP/IP over WiMAX (802.16). Packets will be generated in either WebBrowser or WebServer Component and will travel down the node through the TCP, IP and WiMAX Component in order to be sent to the other Node where they travel the Node up again. The question is now: How to achieve such a setup? What do the config files look like and what are the respective classes in the C++ world?

To simplify the example a little further we're going to focus on TCP and IP only. First of all let's have a look how the TCP and the IP Component are going to exchange information/data.

For our example the TCP and IP are going to form a Node. How can we do that? Have a look at the following code snippet:

node::Interface* node = new Node(registry, nodeConfig);
component::Interface* ci = new component::tests::ComponentStub(node, "component");
component::tests::TCPInterface* tcp =
    new component::tests::TCP(ci, tcpConfig);
component::tests::IPInterface* ip =
    new component::tests::IP(ci, ipConfig);

node->addService(tcp->getName(), tcp);
node->addService(ip->getName(), ip);

First we're creating a Node (node) and two components (tcp, ip). After that we're putting the two components into the Node. The node contains now the two components (tcp and ip). The three variables nodeConfig, tcpConfig and ipConfig contain the configuration (see wns::pyconfig) for these classes.

Let's explore how the Node and those Components work together. The Node has the following interface:

• Node::getName() const
• Node::addComponent(component::Interface*)
• Node::getComponentByName(const std::string&) const
• Node::getComponentByOthersComponentsName(COMPONENTTYPE) const
• Node::getProbeIDProviderRegistry() const

If we take a closer look at the method Node::addComponent(component::Interface*) we can observe that it takes a pointer to a component::Interface as argument. The code detective inside us suggests that TCP and IP must be of type component::Interface. Bingo! So the class hierachy looks something like this:

What does the component::Interface look like?

• component::Interface::getName() const
• component::Interface::getNode() const
• component::Interface::onNodeCreated()
• component::Interface::onWorldCreated()

However this is only half the truth, because as we can see from the code snippet above the TCP instancs is assigned to a pointer of type TCPInterface. This means there is not only a component::Interface but also a TCPInterface. TCPInterface must be derived from component::Interface otherwise Node::addComponent can't be called with this type.Further, TCP must be derived from TCPInterface otherwise the assignment to TCPInterface would not be possible. Hence, our hierachy looks now like this:

The "Interfaces" (IPInterface, TCPInterface, component::Interface) are abstract (which means they contain only definitions of the methods but no implementation). What is the benefit of these Interfaces? Consider the following: TCP will very likely use an IP instance. But it should not rely on one specific implementation. So it will use the IPInterface instead of IP direct:

And we can have more than one IP implementation. As long as it conforms to the IPInterface everything is fine:

Still with me? Good! We still have room for optimization! The classes TCP, IPv4 and IPv6 are derived from component::Interface (through TCPInterface and IPInterface). Since the component::Interface is abstract we have to implement all the methods required by component::Interface (see above which methods are required by component::Interface). They are very similar for all three classes (TCP, IPv4, IPv6). To be exact: they are the same. Lucky as we are, we don't need to implement these methods. There is a default implementation available: Component. To get the implementation from Component we derive TCP, IPv4 and IPv6 from Component:

Et voila! We've a way to define interfaces for different types of Components and they can be stored in a Node. Now, how does all this look like in C++? We're going to examine only the TCP class. Let's look a the class hierachy again:

A simple TCPInterface
Assume the following interface has been defined for an TCP component:

// Define a new Interface
class TCPInterface :
    virtual public service::Service
{
public:
    virtual int
    getFreePort() = 0;

    virtual std::string
    getAddressOfIPInstance() = 0;

    virtual std::string
    getName() = 0;
};

Note how we derive from component::Interface here and compare this to the class diagram above. Note further the two new methods that have been defined in the TCPInterface:

• TCPInterface::getFreePort()
• TCPInterface::getAddressOfIPInstance()

These methods are again abstract and need to be implemented.

An TCP implementation
The implementation of TCP might then look like this:

// Implementation of TCPInterface
class TCP :
    virtual public TCPInterface
{
public:
    TCP(component::Interface* ci, const pyconfig::View& _pyco) :
        pyco(_pyco),
        ip(NULL),
        componentInterface(ci),
        name(_pyco.get<std::string>("name"))
    {
    }

    // TCPInterface
    int getFreePort()
    {
        // Return always 31337 (only for tests)
        return 31337;
    }

    // TCPInterface
    std::string
    getAddressOfIPInstance()
    {
        return ip->getAddress();
    }

    // ComponentInterface
    void onNodeCreated()
    {
        ip = componentInterface->getService<IPInterface*>(pyco.get<std::string>("ipInstance"));
    }

    void onWorldCreated()
    {
        // No inter-node dependecies.
    }

    virtual std::string
    getName()
    {
        return name;
    }

private:
    wns::pyconfig::View pyco;
    // The IP instance below this TCP instance
    IPInterface* ip;
    component::Interface* componentInterface;
    std::string name;
};

Note how we derive from Component additionally here in order to "implement" the component::Interface. The only thing left is the implementation of TCP::getFreePort(), TCP::getAddressOfIPInstance(), TCP::onNodeCreated() and TCP::onWorldCreated from the component::Interface.

Let's see what we can learn from the three methods that have been implemented here:

TCP::getFreePort():
This one is easy. For testing purpose we return an integer. Nothing special.

TCP::getAddressOfIPInstance():
This one is a little bit more difficult. From the name we can guess that we need an instance of something conforming to the IPInterface since we need to ask this instance for its address.

The question is now: How do we find such an instance? We know that the instance must be part of the same Node that the instance of TCP is currently being part of.

At this point the method TCP::onNodeCreated() comes into play. Normally components are not added from outside to a Node but the Node creates all necessary components in its constructor. After all components have been created the method component::Interface::onNodeCreated() of each component is called. Hence, this is the point where a component can try to find other components within its parent Node. You resolve inter Node dependencies only after all Nodes have been constructed and all components have executed their onNodeCreated method. This is the time instance when the onWorldCreated() method is called.

The Node provides special methods to retrieve components from itself.

Retrieve a Component from a Node
A Component can be retrieved from a Node by its name (like a IP instance):

// retrieve TCP instance from Node
component::tests::TCPInterface* tcp =
    node->getService<component::tests::TCPInterface*>("TCP");

Note how the method is informed about the type to be retrieved from the Node. This is necessary since the Node has no idea of the type (it stores component::Interfaces). This is mostly used in component::Interface::onNodeCreated(), i.e. if one component tries to find another component with another type in the same Node.

---

Typedef Documentation

typedef wns::container::Registry<std::string, node::Interface*> wns::node::Registry

Definition at line 35 of file Registry.hpp.