97

The simu API

The simu API is a collection of Java packages that, together with networked computers, comprise the Simulated Network Environment. The Simulated Network Environment is shown in the diagram below.

Each networked computer may have several processes running in it, including those processes that are part of the Simulated Network Environment, which include Simulated Network Elements (SNEs), the Simulator Control Program (SCP), one or more Network Managers (NMs), and possibly other remote objects. Most processes running in the environment are Java Virtual machines (JVMs), which run Java programs as threads within. Any of the processes could potentially be non-JVM processes, however. For example, the Network Manager could be written in C++ and could run as a standard UNIX process, as long as it uses the accepted communication protocols to communicate with other elements in the environment.

The simu API is composed of the following Java packages:

package simu.net
package simu.scp
package simu.sned
package simu.test
package simu.util

Each package is described in more detail in the table below.

Package Description

simu.net Contains classes used for communication between elements in the Simulated Network Environment. Each class adheres to an established protocol.

simu.scp Contains the Simulator Control Program (SCP), which is the program used to control the Simulated Network Environment, specifically by managing SNEs and by responding to requests for information from remote objects.
Since the SCP is a standalone program and is not designed to be imported into other Java programs, it is not considered to be strictly part of the API. It is included in a package so that the Javadoc documentation generation tool can include its documentation along with the other packages in the API. This will allow SCP documented methods and classes to be chosen from a common package index.

simu.sned Contains the classes that define the SNE Database (SNED). These classes are used by the SCP and some communication classes in the simu.net package.

simu.test Contains test harnesses for various components of the API. Again, these test harnesses are not strictly part of the API, since no Java programs will import them, but they are included in the package for the same reason that the SCP is included.

simu.util Contains utility classes that are used by other classes in the Package.

Each package is described in more detail in the sections below. Information about the classes in the packages, as well as how and when to use them, is provided.

The simu.net Package

The simu.net package contains classes used for communication between elements in the Simulated Network Environment. Each class adheres to an established protocol, which is composed of simple SEND and RECEIVE commands, followed by data values. The following table shows a description of the classes in the simu.net package.

Class Description

Dispatcher The Dispatcher class is spawned as a daemon thread by the Simulator Control Program (SCP) which listens for communication connection requests from remote objects on the network.
Once a request is received, it's passed to a SCPCommunicator. This allows the dispatcher to listen for future communication requests while another thread (the SCPCommunicator in this case) processes pending requests.

Communicator The Communicator class is used by objects running in the simulated network environment to communicate with the Simulator Control Program (SCP). In most cases, the objects would be Simulated Network Elements (SNEs) which simulate the behaviour of real network elements, such as printers and routers. The communication with the Simulator Control Program is accomplished using TCP socket connections.
The Communicator class may be use in one of three ways:

Spawned to interact with a dispatcher and obtain the anonymous port number to use when subsequently connecting to the SCPCommunicator.
Spawned by an object (such as a SNE) to be permanently listening (as a daemon) for communication.
Spawned by an object (such as a SNE) to communicate with the SCP, after which the Communicator thread terminates.

SCPCommunicator The SCPCommunicator class is used by the Simulator Control program (SCP) to communicate with remote objects on the simulated network environment. The communication with the remote objects (usually SNEs) is accomplished using TCP socket connections.
The SCPCommunicator class may be use in one of three ways:

Spawned by the SCP to be permanently listening (as a daemon) for communication.
Spawned by the Dispatcher to listen for one and only one incoming message, after which the SCPCommunicator thread terminates.
Spawned by the SCP to communicate with a remote object, such as a SNE, after which the SCPCommunicator thread terminates.

Both the Communicator and SCPCommunicator classes communicate with other elements on the network using an established protocol. Any incoming messages that do not adhere to the protocol are not processed. The protocol is shown in the table below:

Valid protocol messages that the SCPCommunicator class can receive and the Communicator class can send.

"RECEIVE LOCAL <SNEid> <key>"
This message tells the SCPCommunicator to return the local SNE value corresponding to the specified key across the communication link to the initiator.

"RECEIVE LINKS <fromSNEid> <toSNEid>"
This message tells the SCPCommunicator to return the link status corresponding to the specified SNEs across the communication link to the initiator.

"SHIP LINKS <fromSNEid> <toSNEid> <linkStatus>"
This message tells the SCPCommunicator to modify the link status corresponding to the specified SNEs to the specified value.

Valid protocol messages that the SCPCommunicator class can send and the Communicator class can receive.

"SHIP <key> <value>"
This message tells the Communicator to modify the attribute (or add it, if it doesn't exist) in its local database corresponding to the specified key to the specified value.

"SHIP REMOVE <key>"
This message tells the Communicator to delete the attribute corresponding to the specified key from its local database.

"RECEIVE <key>"
This message tells the Communicator to return the value from its local database corresponding to the specified key across the communication link to the initiator.

"RECEIVE REMOTE ALL"
This message tells the Communicator to return all values in its local database across the communication link to the initiator.

This defines the minimum protocol set that is required to allow the SCP to communicate with SNEs, and for other objects, such as a network manager, to query the SCP and/or SNEs for information.

The simu.scp Package

The simu.scp package contains the Simulator Control Program (SCP), which is the program used to control the Simulated Network Environment, specifically by managing SNEs and by responding to requests for information from remote objects.

The SCP is responsible for creating, linking, destroying and modifying data within these SNEs. Multiple SNEs can be created on a single workstation, or on many workstations. Currently a user must run the SNE on a workstation and then manually "register" it with the SCP. This process of registration tells the SCP where to find the SNE on the network, so that it can read or write data to it over the network.

The simu.sned Package

The sned class is a database for SNEs used by the Simulator Control Program (SCP) and some communication classes in the simu.net package. It is an abbreviation for Simulated Network Element Database (SNED). It is composed of Java primitive types, such as Hashtables, and a sne class object. The sne class object contains all pertinent information about a particular SNE, such as IP address and port where it can be reached on the network, and including links to other SNEs.

All of the sned class methods are synchronized, which will offer mutual exclusion protection on the database. This means that only one thread can be accessing or mutating data in the SNED at a time.

The simu.test Package

The simu.test package contains test harnesses for the SCPCommunicator and Communicator classes in the simu.net package. The TestSCPCommunicator class tests the SCPCommunicator class, and the TestCommunicator class tests the Communicator class. The two classes were designed to be run in conjunction with each other to test the concurrent operation of both the Communicator and SCPCommunicator classes.

The simu.util Package

Currently, the simu.util package contains only one class; the Semaphore class. The Semaphore class implements a simple counting semaphore, which is used to synchronize threads. Currently, only the SCPCommunicator class in the simu.net package uses it.

Package	Description
`simu.net`	Contains classes used for communication between elements in the Simulated Network Environment. Each class adheres to an established protocol.
`simu.scp`	Contains the Simulator Control Program (SCP), which is the program used to control the Simulated Network Environment, specifically by managing SNEs and by responding to requests for information from remote objects. Since the SCP is a standalone program and is not designed to be imported into other Java programs, it is not considered to be strictly part of the API. It is included in a package so that the Javadoc documentation generation tool can include its documentation along with the other packages in the API. This will allow SCP documented methods and classes to be chosen from a common package index.
`simu.sned`	Contains the classes that define the SNE Database (SNED). These classes are used by the SCP and some communication classes in the `simu.net` package.
`simu.test`	Contains test harnesses for various components of the API. Again, these test harnesses are not strictly part of the API, since no Java programs will import them, but they are included in the package for the same reason that the SCP is included.
`simu.util`	Contains utility classes that are used by other classes in the Package.

Class	Description
Dispatcher	The Dispatcher class is spawned as a daemon thread by the Simulator Control Program (SCP) which listens for communication connection requests from remote objects on the network. Once a request is received, it's passed to a SCPCommunicator. This allows the dispatcher to listen for future communication requests while another thread (the SCPCommunicator in this case) processes pending requests.
Communicator	The Communicator class is used by objects running in the simulated network environment to communicate with the Simulator Control Program (SCP). In most cases, the objects would be Simulated Network Elements (SNEs) which simulate the behaviour of real network elements, such as printers and routers. The communication with the Simulator Control Program is accomplished using TCP socket connections. The Communicator class may be use in one of three ways: Spawned to interact with a dispatcher and obtain the anonymous port number to use when subsequently connecting to the SCPCommunicator. Spawned by an object (such as a SNE) to be permanently listening (as a daemon) for communication. Spawned by an object (such as a SNE) to communicate with the SCP, after which the Communicator thread terminates.
SCPCommunicator	The SCPCommunicator class is used by the Simulator Control program (SCP) to communicate with remote objects on the simulated network environment. The communication with the remote objects (usually SNEs) is accomplished using TCP socket connections. The SCPCommunicator class may be use in one of three ways: Spawned by the SCP to be permanently listening (as a daemon) for communication. Spawned by the Dispatcher to listen for one and only one incoming message, after which the SCPCommunicator thread terminates. Spawned by the SCP to communicate with a remote object, such as a SNE, after which the SCPCommunicator thread terminates.