<!doctype linuxdoc system>

<article>

<title>How to build a network for simulation in JNS
<author>Christian Nentwich (c.nentwich@cs.ucl.ac.uk)
<date>06/03/1999

<abstract>
This file describes how to build the static structure of a network (nodes,
links, etc.) from the classes available in JNS.
</abstract>

<toc>

<sect>Prerequisites
<p>

Before reading this document, you should ask yourself the following questions:
<itemize>
<item>Does the term "subnet" mean anything to you? Are you scared of the word
"netmask" ?
<item>Can you tell a "router" from a "host"? Is a "host" someone who provides
hospitality?
<item>Does the expression <tt>public static void main(String args[])</tt> look
meaningful?
<item>Does MTU mean "Military Telecommunications Unit"?
</itemize>

<p>
If the answer to any of those is "yes", you will probably have to do some
reading before you can use JNS. You will have to read up on the IP protocol,
especially subnetting, the Java programming language and/or basic networking
terms.


<sect>Introduction

<p>
This document will describe how you can build the network you want to
simulate in JNS. It is concerned with the static structure only, not with
dynamic things such as tracing or sending packets. Consequently, when
functions of several classes are described, those concerned with data 
transfer are left out.

<p>
The functions presented here are not recommended for "daily use". JNS was
designed with many options in mind, thus you have quite a bit of setup work
to do in order to build your network. If you want to just quickly build
a network without much customisation you are strongly advised to write some
code that will take away most details (For examples, a node together with an
interface could be built automatically and returned).

<p>
Again, this file describes how to build a network from the basic building
blocks:
<itemize>
<item>Nodes - think of this as computers. The box on your desk or under your
desk.
<item>Interfaces - the equivalent of network cards, modems, you name it.
<item>Links - the cable that runs out of your network card into the next
one, your phone-line, etc.. Note, however, that links are between two
interfaces, not like an Ethernet cable that can connect more than two
computers.
</itemize>

<p>
Each of these will be described in detail in the next sections. Nearly all
of them can be attached to each other. As a reminder from here on, JNS has
a uniform naming scheme for attaching elements to others, the function to
do this is always called <tt>'attach'</tt>, regardless of what is attached
to what.


<sect>Nodes
<p>

Nodes represent a computer. The class that implements a node is called..
<tt>Node</tt>. In JNS, a node contains a couple of essential components:
<itemize>
<item>Zero or more Interfaces - Any computer needs an interface to a network
to participate. You can have zero interfaces if you find a use for it.
<item>One IP Handler object - you will not see this object if you do not
look for it actively. It takes care of sending and receiving IP packets and
dispatching them to higher level protocols. There is only one of those in
each node and it is attached to every interface. It also contains the 
routing table.
<item>A name - be imaginative ;)
</itemize>

<p>
That's about all the elements a node contains. The functionality provided by
nodes includes:
<itemize>
<item>Attaching Interfaces - the most obvious functionality needed.
<item>Adding a routing table entry - you can add a route to a subnet.
<item>Adding a default route - the route to use if no other routes seem to
match.
</itemize>

<p>
It is worth pointing out that nodes are not particularly useful in any
simulation, there is nothing going in on inside that class. The only purpose
it has is to hold together its components, so the actual class looks pretty
boring.

<p>
The first thing you want to do when creating your network is create a couple
of <tt>Node</tt> objects to add interfaces to later.


<sect>Interfaces
<p>

An interface lets a node connect to a link, i.e. it is a bit like a network
card. The class <tt>Interface</tt> is actually an abstract class, so you 
cannot use it when building your network. Instead, you have to choose
between <tt>SimplexInterface</tt> and <tt>DuplexInterface</tt>

<p>
Those two classes share the important functionality you need, so it is
described here. An interface (regardless of whether it is simplex or duplex)
consists of:
<itemize>
<item>An IP address - a globally unique IP address by which this interface
can be identified.
<item>A bandwidth - the bandwidth is given in bps. Most of the time, you
will prefer to assign a bandwidth to a link and let all interfaces that
connect to the link inherit the bandwidth.
<item>A reference to an IP handler - this is invisible to you. The interface
knows which handler gets the packets that arrive.
<item>A queue - incoming and outgoing packets will be held in a queue until 
they can receive further treatment.
<item>A maximum transfer unit (MTU) - the maximum packet length in bytes of a
packet this interface can send. Defaults to 1500. Override if you want to see
some IP fragmentation.
</itemize>

<p>
There are several functions provided by all interfaces which are used almost
all of the time.
<itemize>
<item>Attaching a link - You will need this after creating a link when you
want to connect it to an interface. You can choose here whether the
interface will take its bandwidth from the link.
<item>Attaching a queue - An interface contains a queue for packets. You can
override the default queue here. The behaviour differs between
<tt>SimplexInterface</tt> and <tt>DuplexInterface</tt>, check in the
relevant sections.
</itemize>

<sect1>SimplexInterface
<p>
A <tt>SimplexInterface</tt> is a unidirectional interface, which means it
can either be a sender or a receiver, but not both. This class is used
heavily internally but it is generally not very useful for simulation.
Note that you can only attach a <tt>SimplexLink</tt> to a
<tt>SimplexInterface</tt>.

<p>
Simplex Interfaces contain a queue. By default, when a simplex interface is
created, a <it>drop-tail</it> queue is attached to it without any further
interaction from you. If you decide to attach your own queue (e.g. a RED
queue you implemented) this default queue will be overwritten.

<sect1>DuplexInterface
<p>
The <tt>DuplexInterface</tt> is much more like your network card. It really
consists of two simplex interfaces internally, but most of the time you can
ignore this. It is made of by a <it>sender</it> and a <it>receiver</it>
interface.

<p>
Note that attaching a queue to this interface works a bit differently. If
you choose to do this, the <tt>clone()</tt> method of the queue you are
attaching will be called and the two queues will be attach to the two
simplex interfaces.


<sect>Links
<p>
Setting up links is the last step in building a network. Similar to the
<tt>Interface</tt> class, the <tt>Link</tt> class is abstract so you cannot
instantiate it. You have to make a choice between <tt>SimplexLink</tt> and
<tt>DuplexLink</tt>.

<p>
Links in JNS have the following common characteristics:
<itemize>
<item>A Bandwidth - the bandwidth of a link is specified in bytes per second
(bps). You should know the bandwidth you want to use.
<item>A propagation delay - this value specifies how long it takes for one bit
to travel from one length of the link to the other. You will normally either
know the propagation delay or calculate it from 2/3 the speed of light (around
the speed of an electron going down a wire) and the length of the link.
<item>An error rate - This is a value between 0 and 1. 0 means error free
and 1 means "ruins everything". JNS will generate a random variable and if it
is smaller than this value, it will corrupt the CRC of the current packet the
link is sending.
</itemize>

<sect1>SimplexLink
<p>

Most of the time, you will not use simplex links, so they are not very 
interesting (although all processing is done internally using simplex links
anyway). If you do decide to use one, keep in mind that it can only attach
to a SimplexInterface.

<sect1>DuplexLink