Base and Common Classes 
for Network Simulation in J-Sim

October 06, 2003

This page documents the drcl.net package in J-Sim. The package provides base and common classes for building different network architectures and scenarios. Specifically, it contains:

• base classes for writing packet subclasses, network modules, packet classifiers and address schemes,
• tool components such as a packet classifier, traffic monitors, a NAM trace base component and a generic receiving component, and
• traffic models and generators.

Table of Contents

• 1 Base Classes
  • 1.1 Address
  • 1.2 Module
  • 1.3 Packet
  • 1.4 PktClassifier
  • 1.5 FooPacket/PacketWrapper
• 2 Tool Components
  • 2.1 TrafficMonitor/TrafficMonitor2
  • 2.2 NamTrace
  • 2.3 Classifier
  • 2.4 Receiver
• 3 Traffic Models and Generators
  • 3.1 TrafficShaper, TrafficShaperComponent and TrafficSourceComponent
  • 3.2 Available Traffic Models, TrafficShaper and TrafficSourceComponent Classes
  • 3.3 TrafficAssistant
  • 3.4 TraceInput
  • 3.5 Examples
• 4 Examples

1 Base Classes

• 1.1 Address
• 1.2 Module
• 1.3 Packet
• 1.4 PktClassifier
• 1.5 FooPacket/PacketWrapper

1.1 Address

Address implements an address scheme. An address scheme divides the address space (in long) into unicast addresses, multicast addresses, broadcast addresses (any addresses), null addresses. Also it provides translation between an address and String representation of the address.

The class defines the following fields and methods:

static long	ANY_ADDR           The default broadcast address.
static Address	DEFAULT_ADDRESS           An instance of the default address scheme.
static long	MAX_ADDR           The maximum address value that can be used in any address scheme.
static long	NULL_ADDR           The default null address.
static boolean	_isAny(long addr_)           Returns true if the argument is the default broadcast address.
static boolean	_isNull(long addr_)           Returns true if the argument is the default null address.
boolean	isAny(long addr_)           Returns true if the argument is a broadcast address.
boolean	isMcast(long addr_)           Returns true if the argument is a multicast address.
boolean	isNull(long addr_)           Returns true if the argument is a null address.
boolean	isUnicast(long addr_)           Returns true if the argument is a unicast address.
java.lang.String	ltos(long addr_)           Returns the String representation of the address.
long	stol(java.lang.String addr_)           Returns the long representation of the address.

All the address schemes should follow the following rules:

• NULL_ADDR must be in the null address space.
• ANY_ADDR must be in the broadcast address space.
• The maximum value of an address must not exceed MAX_ADDR.

The default address scheme implemented by this class is as follows:

• Unicast address: [0, MAX_ADDR].
• Multicast address: [Long.MIN_VALUE, -1].
• Null address: {NULL_ADDR}.
• Broadcast address: {ANY_ADDR}.
• String representation: using Long.toString(long) and Long.valueOf(String) to convert between the long integer address and its String representation.

1.2 Module

A module is a component which implements a protocol. The ports of a module are categorized into "up" and "down" groups. "Up" and "down" indicate the direction of data flow in the protocol stack of a node. By default, it contains one "up" port (upPort, a port in the default port group with ID "up") and one "down" port (downPort, a port in the default port group with ID "down").

In addition, A module is equipped with one timer port (timerPort) and defines a set of methods to set up and cancel timeout events (setTimeout(Object event_, double interval_), setTimeoutAt(Object event_, double time_) and cancelTimeout(ACATimer).  The first two methods return a timer object (drcl.comp.ACATimer) which contains the event object (event_) and can be queried for the time when the timer expires with its getTime() method. Most importantly, it can be used to cancel the event with cancelTimeout(). A timeout event arrives at the timer port when the timeout occurs. The timeout event should be processed in the timeout(Object) handler (see below).

Incoming data is dispatched in process(Object, Port) to four handlers by the port at which data arrives: 

	dataArriveAtUpPort(Object, Port)
	dataArriveAtDownPort(Object, Port)
	timeout(Object)
	processOther(Object, Port)

A module is associated with an address scheme (address), which separates the dividing of address space from the functionality of the module.

The class defines the following fields and methods:

static java.lang.String	PortGroup_UP           The ID of the "up" port group.
static java.lang.String	PortGroup_DOWN           The ID of the "down" port group.
Port	upPort           The default "up" port.
Port	downPort           The default "down" port.
protected  Port	timerPort           The port at which the timeout events come.
protected  Address	address           The address scheme associated with this module.

protected  void	dataArriveAtUpPort(java.lang.Object data_, Port upPort_)           The handler is invoked when a packet arrives at an "up" port.
protected  void	dataArriveAtDownPort(java.lang.Object data_, Port downPort_)           The handler is invoked when a packet arrives at a "down" port.
protected  void	timeout(java.lang.Object data_)           The handler is invoked when a timeout event occurs at the timer port.
protected  void	processOther(java.lang.Object data_, Port inPort_)           The handler is invoked when a packet arrived at a port other than the "up", "down" and timer ports.
protected  boolean	deliver(java.lang.Object data_, java.lang.String portID_)           Delivers data_ at the (up) port specified.
drcl.comp.ACATimer	setTimeout(java.lang.Object evt_, double duration_)           Sets up a timer at relative time.
drcl.comp.ACATimer	setTimeoutAt(java.lang.Object evt_, double time_)           Sets up a timer at absolute time.
void	cancelTimeout(jdrcl.comp.ACATimer timer_)           Cancels a timer.
void	setAddress(Address address_)           Sets the address scheme associated with this module.
Address	getAddress()           Returns the address scheme associated with this module.

1.3 Packet

This class defines the base class for packets. A packet consists of a header and a body. The header structure should be further defined in subclasses. This class defines the interface a subclass should/would implement, and implements the setter/getter methods for the encapsulated body object, the packet size and the header size.

This class defines the following fields and methods:

1.4 PktClassifier

PktClassifier is an interface. It defines the following method:

1.5 FooPacket/PacketWrapper

FooPacket is a generic implementation of Packet.  It contains only the packet count and byte count information.

PacketWrapper is an interface for an object that can wrap up a packet. Packet itself is a packet wrapper by wrapping up another packet as the packet body.  The class defines the following methods:

PacketWrapper is particularly useful in making the traffic components generic enough to fit in different framework or network architectures.  See the section of Traffic Models and Generators for details.

2 Tool Components

• 2.1 TrafficMonitor/TrafficMonitor2
• 2.2 NamTrace
• 2.3 Classifier
• 2.4 Receiver

2.1 TrafficMonitor/TrafficMonitor2

This component can operate in either "byte" mode, "packet" mode or both. If the "byte" mode is enabled, the component exports the throughput, in the unit of bit/second, or bps, at the bytecount@ port. If the "packet" mode is enabled, it exports the throughput, in packet/second, at the pktcount@ port. 

The first exported event is in the following format (drcl.comp.contract.EventMsg):

• Event name: "Throughput" ("byte" mode, see BYTE_COUNT_EVENT) or "Throughput (packet count)" ("packet" mode, see PKT_COUNT_EVENT).
• Event object: the calculated throughput in Double.
• Event description: null.

The class defines the following fields and methods:

TrafficMonitor2 works the same as TrafficMonitor except that it also exports the events of packet loss rate. To make it work with packet loss rate, the incoming packets must contain correct ordering information. TrafficMonitor2 calculates the packet loss rate by summing up the "gaps" found between the ordering information in the packets in the current window. The calculation may not be correct if packets may arrive out of order in different windows.

Same as TrafficMonitor, TrafficMonitor2 is configured by two parameters: the window size and the output interval. It can operate in the "byte" mode, the "packet" mode, or both. The throughput events are exported at either the bytecount@ port or the pktcount@ port, and the loss rate exported at either the byteloss@ port or the pktloss@ port, both in percentage(%).

2.2 NamTrace

The NamTrace component is an instrument class that probes appropriate components to collect interested events and produce trace outputs in the NAM (VINT/UCB Network Animator) trace format.  Currently, NamTrace supports the following NAM events/configurations: node, link, queue, color and packet. The first four events are usually used in the initial/configuration part of a trace that defines the network topology and the color index. Packet events are collected from probing appropriate components in the system. In all cases, the traces are produced at the output@ port of the NamTrace component.  To save the output in a file, one must connect a file component (e.g., drcl.comp.io.FileComponent) to the output@ port of the NamTrace component.

In what follows, we describe the format of each event type, commonly used values for each field of an event and the methods to produce the event. For details, please refer to the formal NAM documentation. 

Node Event

The format of a node event in a NAM trace is as follows:

n -t <time> -s <source> -d <destination> -S <state> -v <shape> -c <color> -o <previous_color> -A <label>

The destination field is only used for "interface event". State can be one of 

A node event can be added using one of the following methods in NamTrace:

public void addNode(double time_, long source_, long dest_, String state_, String shape_,

	String color_, String prevColor_, String label_)

public void addNode(double time_, long source_, String state_, String shape_,

	String color_, String prevColor_, String label_)

public void addNode(long source_, String state_, String shape_, String color_, String label_)

public void addNode(double time_, long source_, String state_, String color_)

The first method contains the most complete set of arguments for a node event. The other three use subsets of the arguments to specify a node event.  In particular, the third method is useful in describing a node in a network topology at the beginning of a NAM trace. The last one is useful in marking a node state change with a specified color. The state of a node may be "up" or "down". Simple shapes, such as "circle", "square" and so on, are recognized.

Link Event

The format of a link event in a NAM trace is as follows:

l -t <time> -s <source> -d <destination> -S <state> -c <color> -r <bandwidth> -D <propagation_delay> -o <orientation>

A link event can be added using one of the following methods in NamTrace:

public void addLink(double time_, long source_, long dest_, String state_, String color_,

	String bandwidth_, String propagationDelay_, String orientation_)

public void addLink(long source_, long dest_, String state_, String bandwidth_,

	String propagationDelay_, String orientation_)

public void addLink(double time_, long source_, long dest_, String state_, String color_)

The first method contains the most complete set of arguments for a link event. The second one is useful in describing a link in a network topology at the beginning of a NAM trace. The last one is useful in marking a link state change with a specified color. The source and destination are the two ends of the link. The state of a link may be "up" or "down". The examples of the orientation of the link are "left", "right", "up", "down", or null for automatic layout.

Queue Event

The format of a queue event in a NAM trace is as follows:

q -t <time> -s <source> -d <destination> -a <attribute>

A queue event can be added using one of the following methods in NamTrace:

public void addQueue(double time_, long source_, long dest_, String attribute_)

public void addQueue(long source_, long dest_, String attribute_)

The first method contains the most complete set of arguments for a queue event. The second one is useful in describing a queue in a network topology at the beginning of a NAM trace. A link can be associated with two queues, one for each end.  The source and destination (of the link) specifies the queue at the source end of the link. The attribute is the angle between the line along which the queue packets are displayed and the horizontal line. For example, 90 degrees may be represented by "0.5" or "90deg".

Color Index

A color index can be added using one of the following methods in NamTrace:

public void addColor(double time_, int colorid_, String colorName_)
public void addColor(int colorid_, String colorName_)
public void addColors(String[] colorNames_)
public void addColors()

The last three methods without the time argument are useful in specifying a color index at the beginning of a NAM trace. The last method adds the default color indices to the NAM trace. NAM recognizes all the X11 color names.

Packet Event

NamTrace collects packet events by probing appropriate components in the system, and then produces corresponding traces at the output port. Listed below are all the fields in a packet event and how NamTrace produces them:

1. Event type: NAM defines five types of packet events:
   1. enqueue: when a packet is enqueued to the buffer before transmitted over a link;
   2. dequeue: when a packet is removed from the buffer before transmitted over a link;
   3. drop: when a packet is dropped from the buffer due to buffer overflow;
   4. hop: when a link starts transmitting a packet;
   5. receive: when a packet is completely received at the other end of a link.
   These five events fully describe a packet's whereabouts over a link. As this information cannot be identified from a packet, it is put as part of the ID of the port where the probed packet comes (see example below).
2. Source: The source of the "link", that is, the one end where the packet is originated. As this information cannot be identified from a packet, it is put as part of the ID of the port where the probed packet comes (see example below).
3. Destination: Same as source, this is the other end of the link. It is put as part of the ID of the port where the probed packet comes (see example below).
4. Time of the event: Obtained from the component API (Component.getTime()).
5. Packet Type: Obtained from the getPacketType(Packet) method. By default, drcl.net.tool.NamTrace obtains this information from the packet itself (Packet.getPacketType()). A NamTrace subclass may override this method to interpret the packets for the interests of the simulation.
6. Extent: Is the packet size in bytes; obtained from the probed packet.
7. ID: The ID of the packets being transmitted over the link; must be unique for each packet transmitted over the link. This is automatically maintained and produced by NamTrace.
8. Conversation ID: Obtained from the getConversationID(Packet) method. By default, drcl.net.tool.NamTrace returns nothing for this field.
9. Attribute: Is the color index; obtained from getColorID(Packet) method. By default, drcl.net.tool.NamTrace always returns 0.

To collect packet events over a link, one must connect a NamTrace component to five places, each for a type of packet events, for one direction. Fig.11 illustrates how this is done for one direction of a link in the INET framework.

Figure 11:	Example of attaching a NamTrace component to collect packet events for the link from node 3 to node 7. Note how the first three fields (event type, source and destination) are directly put in the ID of the ports.

 It is tedious to hook up a NamTrace component to every interested link even for a small network. As the task is repetitive in nature, a utility method is possible for a specific framework.  For example, the utility method setNamTraceOn() in drcl.inet.InetUtil automates the task for a network that consists of INET nodes.

2.3 Classifier

The component classifies the incoming packets and pass them on at corresponding ports.  Specifically, this component uses the PktClassifier to obtain an integer key for an incoming packet and then retrieves the corresponding port from its key-port map. 

The class defines the following methods, in particular, the add() and remove() methods for configuring the key-port map:

2.4 Receiver

This generic receiving component uses the getPacketCount() and getByteCount() methods of Packet to record the packet and byte "gaps" (unreceived packets and bytes) of the connection. One can use the info() method of the component to print out the gaps.

3 Traffic Models and Generators

• 3.1 TrafficShaper, TrafficShaperComponent and TrafficSourceComponent
• 3.2 Available Traffic Models, TrafficShaper and TrafficSourceComponent Classes
• 3.3 TrafficAssistant
• 3.4 TraceInput

The drcl.net.traffic package provides several traffic model classes and corresponding traffic source/shaping components.  The classes are made generic enough to be used in different frameworks or network architectures.  Two base classes are defined for this purpose: TrafficModel and TrafficComponent.  TrafficModel holds the parameters that describe the model while TrafficComponent is the component who actually sends out packets based on some TrafficModel.

TrafficModel defines the following methods which a subclass must implement:

TrafficComponent defines the following methods:

By default, a TrafficComponent outputs FooPackets if it is a source, or whatever comes in if it is a traffic shaping component (termed as shaper).  One can change this behavior by installing a PacketWrapper in a TrafficComponent.  With the PacketWrapper installed, every time a packet goes out, the TrafficComponent outputs a clone of the PacketWrapper that wraps up the packet. This facility is the key to make a TrafficComponent usable in different frameworks or network architectures.

3.1 TrafficShaper, TrafficShaperComponent and TrafficSourceComponent

TrafficSourceComponent and TrafficShaperComponent are derived from TrafficComponent.  A TrafficSourceComponent originates packets based on the associated traffic model, while a TrafficShaperComponent regulates incoming packets according to the associated traffic model.  

TrafficShaperComponent defines the following methods:

In the core of a TrafficShaperComponent is the associated TrafficShaper instance.  To create different traffic shaper components, one simply installs different TrafficShaper classes to the TrafficShaperComponent.  The TrafficShaper class (is not a Component!) defines the following methods:

To embed this class in a component (e.g., TrafficShaperComponent), adjust(drcl.net.Packet, double) for each packet to be regulated. The method returns the amount of time that must be delayed for outputting the packet in order to conform to the associated traffic model. If the time is greater than zero, then the packet is held in the buffer until dequeue() is called to release the packet. One can use nextOutputTime() to get the absolute time when the next packet in the buffer can be released.

A TrafficShaper subclass must override adjust(double currentTime_, int packetSize_) to implement the regulation logic. Subclasses do not need to be concerned about the buffer as it is taken care of in adjust(drcl.net.Packet, double).  The current time passed to this method is maintained relatively to the time when this shaper instance starts.  A subclass also needs to override duplicate(Object), info(String) and reset().

TrafficSourceComponent is the base class to implement different traffic source components.  It defines the following fields and methods:

A subclass must override setNextPacket(FooPacket) to set the size of the packet and return the birth time of the packet to conform to the associated traffic model  In addition, a subclass should override info(String) to print out the content of the source component.  Buffer operations are taken care of in the base class.

One may add a TrafficShaper at the output of a TrafficSourceComponent to create a traffic source that conforms to the traffic model of the shaper.  For example, a toke buck source may be created by a uniformly random source with a token bucket shaper installed.  This allows creation of various traffic sources from a small set of TrafficShaper and TrafficSourceComponent classes.

One may enable timestamping generated packets.  In this case, generated packets are in the TimestampedFooPacket class which is a subclass of FooPacket.  One may retrieve the time stamp information (double) from the packets via the getTimestamp() method.

3.2 Available Traffic Models, Traffic Shaper and TrafficSourceComponent Classes

3.3 TrafficAssistant

TrafficAssistant is a utility class which helps to get the corresponding TrafficShaper or TrafficSourceComponent from a TrafficModel.  It defines the following static methods:

To ease the task, TrafficAssistant expects:

1. The name of a traffic model class starts with "traffic_".  For example, traffic_TokenBucket.
2. The name of a TrafficShaper class or a TrafficSourceComponent class starts with "ts".  For example, tsTokenBucket.

3.4 TraceInput

TraceInput is a TrafficSourceComponent which reads a trace file and outputs packets (FooPacket) according to the trace file. To use the class, one must assigned to it a java.io.Reader which is associated with the opened trace file.

As a TrafficSourceComponent, a subclass must override the setNextPacket(drcl.net.FooPacket) method to set the size of next packet and return its birth time based on the trace file.  In addition, a subclass also needs to implement the looping (rewind) operation. When the looping flag is enabled, the trace file is repeated every loopPeriod second.  The associated traffic model is made up by the load, burst and MTU properties.

TraceInput defines the following fields and methods:

SimpleTrace is a subclass of TraceInput.  It recognizes the following trace format:

<time>  <packet_size>

And it ignores any line starting with "#".

4 Examples

4.1 TrafficSourceComponent and TrafficShaperComponent

Connect a peak rate source component and a token bucket shaper component. The outputs of both components are monitored by TrafficMonitors, and the results are sent to a plotter component (drcl.comp.tool.Plotter).

We use the following Tcl script to create the scenario:

cd [mkdir drcl.comp.Component /test]

# set up traffic source
set src_model [java::new drcl.net.traffic.traffic_PeakRate 100 150 .01 .04]
mkdir [java::call drcl.net.traffic.TrafficAssistant getTrafficComponent $src_model] source

# set up token bucket shaper
set token_model [java::new drcl.net.traffic.traffic_TokenBucket 600 600 40000 8000000 600]
	# bucketSize, initBucketSize, tokenGenRate, outRate, MTU
mkdir [java::call drcl.net.traffic.TrafficAssistant getTrafficComponent $token_model] token_bucket
! token_bucket setBufferSize 600

# connect generator to shaper
connect source/down@ -to token_bucket/up@

# Traffic monitors and plotter
mkdir drcl.net.tool.TrafficMonitor2 .source
mkdir drcl.net.tool.TrafficMonitor2 .token
mkdir drcl.comp.tool.Plotter .plot

# connect monitors
connect -c source/down@ -to .source/in@
connect -c token_bucket/down@ -to .token/in@

# connect monitors to plotter
connect -c .source/bytecount@ -to .plot/0@0
connect -c .token/bytecount@ -to .plot/1@0
connect -c .token/byteloss@ -to .plot/1@1

# set up simulator
attach_simulator .

puts "Simulation running..."
run . 
rt . stop 100

For attaching a simulation runtime and controlling a simulation, please refer to the sections of Runtime, Simulation Engine and Simulation Control and rt, run/stop/resume, reset, reboot in the INET document.  For using drcl.comp.tool.Plotter, please refer to the section of xy Plot - drcl.comp.tool.Plotter in the INET document.

The result should look like:

4.2 TrafficSourceComponent and TrafficShaper

Examine a peak rate source component with a token bucket shaper installed. Both unshaped traffic (thru .timer@) and shaped traffic (thru down@) are monitored by TrafficMonitors, and the results are sent to a plotter component (drcl.comp.tool.Plotter).

We use the following Tcl script to create the scenario:

cd [mkdir drcl.comp.Component /test]

set src_model [java::new drcl.net.traffic.traffic_PeakRate 100 150 .01 .04]
set token_model [java::new drcl.net.traffic.traffic_TokenBucket 600 600 40000 8000000 600]
mkdir [java::call drcl.net.traffic.TrafficAssistant getTrafficSource $src_model $token_model] source

! source setBufferSize 600; # for the shaper
! source setSendUnshapedTrafficEnabled true

# Traffic monitors and plotter
mkdir drcl.net.tool.TrafficMonitor2 .unshaped
mkdir drcl.net.tool.TrafficMonitor2 .shaped
mkdir drcl.comp.tool.Plotter .plot

# connect monitors
connect -c source/.timer@ -to .unshaped/in@
connect -c source/down@ -to .shaped/in@

# connect monitors to plotter
connect -c .unshaped/bytecount@ -to .plot/0@0
connect -c .shaped/bytecount@ -to .plot/1@0
connect -c .shaped/byteloss@ -to .plot/1@1

# set up simulator
attach_simulator .

puts "Simulation running..."
run .
rt . stop 100

The result of this example is exactly the same as that of Example 4.1.

4.3 TraceInput/SimpleTrace

Create a trace and examine a TraceInput component with the trace. The output is monitored by TrafficMonitor, and the results are sent to a plotter component (drcl.comp.tool.Plotter).

We use the following Tcl script to create the scenario:

cd [mkdir drcl.comp.Component /test]

# set up source
mkdir drcl.net.traffic.SimpleTrace source

! source setReader [java::new java.io.StringReader {
	0.0 1000
	0.1 1000
	0.2 1000
	0.3 1000
	0.4 1000
	5.0 1000
}]

! source setLoopEnabled true
! source setLoopPeriod 10.0

# Traffic monitors and plotter
mkdir drcl.net.tool.TrafficMonitor .source
mkdir drcl.comp.tool.Plotter .plot

# configure TrafficMonitor: window size, output interval
! .source configure .2 .2
connect -c source/down@ -to .source/in@
connect -c .source/bytecount@ -to .plot/0@0

# set up simulator
attach_simulator .

puts "Simulation running..."
run .
rt . stop 100

The monitor keeps a window of 0.2 second, so for packets outputted before 0.4 each loop period, the throughput is 1000 * 8 * 2 / 0.2 = 8.0e4 (bit/second); and for the packet outputted at 5.0, the throughput is 1000 * 8 / 0.2 = 4.0e4 (bit/second). The result should look like:

One may adjust the window size and output interval of TrafficMonitor to get different averaged results.

~ END ~