Final Project Information

Revision 1.1 November 19, 2004

Revision History

Rev 1.1: Correct project due date

Overview.

You will build a layer 4 transport protocol service that implements most of the TCP protocol mechanisms:

• three-way handshake to connect
• credit-based flow control during data transfer
• three-way handshake to disconnect.

Moreover, your protocol will handle the effects of packet loss and corruption that result from use of an unreliable IP network layer 3.

Programming Language.

The framework that you will work with is written in JAVA. You will be given some JAVA source to which you have to add methods. The simulation software itself is also written in JAVA. You will receive the class files for these.

Phased Development.

Like most 'big' problems, it is best to partition the big task into a set of smaller tasks. A suggested approach follows:

You should develop your layer 3 entities in four phases:

1. Implement the Open 3-way handshake and Close the 3-way handshake to work in an error-free simulation.
2. Implement Data Transfer (the Established state) in an error-free simulation
3. Modify the your phase 1 and 2 code to handle network errors (packet loss and corruption).

Rules for Working on the Project.

You may work individually or you may work in a team of 2 (and ONLY 2). If you work as a pair, then you will have to do a little more work than those who work alone. Details are provided later. Both students will receive the same grade.

If you decide to work as a pair, you MUST declare your intention and identify your partner no later than November 30. Once you declare that you are working as a team, you are committed to work with your partner to the very end, so BE SURE that this the way you want to go!

Academic Honesty.

1. You MUST NOT share your code or your solutions (ideas) with any other student UNLESS he/she is your partner.

2. You MUST NOT copy ANY source code from ANY source to use in this project, unless I give it to you.

3. You MUST NOT decompile ANY class files I give you. If I find that you have, you will receive a grade of F for the course.

The Simulated Environment

The simulated environment consists a network (layer 3), applications (layer 5), and transport protocol entities (layer 4). The simulated applications run on two imaginary computers, Node_A and Node_B, each of which has its own transport protocol (layer 4).

The application on Node_A will try to establish a TCP connection (as a client) to a server on Node_B. The application (layer 5 entity) on Node_A will then try to send a number of messages to Node_B. After the required number of messages has been sent, layer 5 on Node_A will try to close the connection.

The simulator is a JAVA program and set of supporting classes. The simulator main program is PNSimulator. All of the classes you need to develop and run the simulator are included in the files source.zip, doc.zip, and pns.java.

The source files that you should use are in the zip file source.zip. Documentation for all of the classes in the project is provided in JAVADOC (html format) doc.zip, and class files that comprise the simulator, Node_B, and supporting classes are located in pns.jar.

You do not need to (and should not) extract ANYTHING from pns.jar. Use it as given in your classpath

To extract the source files and documentation on Windows, use WinZip.

To extract the source and documentation files on Unix, use the unzip command:

unzip source.zip

unzip doc.zip

This command will extract two directories from the jar file, one with source code (java files) and the other with JAVADOC files for the project (html files). You will only modify ONE of the source files that you extract: Node_A.java. The other source files are there for you to use for REFERENCE ONLY. YOU SHOULD NOT COMPILE THEM!

The abstract class layer4Entity.java defines some parameters that you MUST use in your solution. They are also implemented by Node_B.

To avoid any conflicts when you compile your code, you should move ALL of the java source files OTHER than Node_A.java to some other directory, leaving only Node_A.java and pns.jar in your development directory.

To compile your Node_A and any other java files that YOU develop, use this command:

javac -classpath .:./pns.jar *.java (Solaris, Linux, etc)

or

javac -classpath .;./pns.jar *.java (Windows)

NOTE: pay attention to syntax of classpath argument!

To run the Packet Network Simulator, use this command:

java -classpath .:./pns.jar PNSimulator [arguments] (Solaris)

or

java -cp .;./pns.jar PNSimulator [arguments] (Windows)

NOTE: pay attention to syntax of classpath argument!

The PNSimulator program EXPECTS to find a class named Node_A and a class named Node_B. Since Node_A and Node_B are instances of a layer4Entity, PNSimulator knows the methods that they provide, and will use them to run the simulation. You can run the "skeleton" Node_A as is. Although Node_A does nothing, the simulator will still run.

There is a complete working implementation of Node_B in the pns.jar file.

The source.zip file is HERE

The doc.zip file is HERE

The pns.jar file is HERE

Controlling the Simulator

The simulated network layer (layer 3) is capable of corrupting and losing packets. It will not reorder packets. When you compile your class and run the simulator, you will specify values in a property file that specify parameters for the simulated network environment:

• NumberOfMessages. The simulator (and your methods) will stop as soon as this number of messages has been passed down from layer 5 AND all of the subsequent packets required to execute a close have been sent, regardless of whether or not all of the messages have been correctly delivered. You can run the simulator with NumberOfMessages=0 to test the open and close processes: no data will be sent between the open and close.
• ProbabilityOfLoss. You are asked to specify a packet loss probability. A value of 0.1 would mean that one in ten packets (on average) are lost.
• ProbabilityOfCorruption. Y ou are asked to specify a packet corruption probability. A value of 0.2 would mean that one in five packets (on average) are corrupted. Note that the contents of payload, sequence, ack, or checksum fields can be corrupted. Your checksum should thus include the data, sequence, and ack fields.
• TraceLevel.  Setting a tracing value of 1 or 2 will print out useful information about what is going on inside the simulation (e.g., what's happening to packets and timers). A tracing value of 0 will turn this off. A tracing value of 3 will display packet data as packets pass through critical stages of the simulator. A tracing value higher than 3 will include internal information about the simulator operation, but may not be too helpful to you in debugging your code.
• TimeBetweenMessages. This property gives the average time in simulated time units (you can think of them as milliseconds) between application messages. Thus, this is the average rate that at which the application layer will attempt to send messages to the application layer in the other node. You can set this property to any non-zero, positive value. Note that the smaller the value you choose, the faster packets will be arriving to your sender. You should test your code using a value of 20 time units, since this is the smallest value that I will use when I test your project.
• BiDirectional. This property is boolean (true/false). Normally, Node_A executes an active open and is a sender, while Node_B executes a passive open (listen) and is a receiver. Apart from packets exchanged during the connection open and close, the only packets that Node_B sends toNode_A are ACK packets. Setting the property BiDirectional=true will force the simulator to generate messages from layer 5 for both Node_A and Node_B In this mode, approximately half of the messages sent by layer 5 will be sent through Node_A, and the other half are sent through Node_B. For example, if NumberOfMessages=100, then about 50 will be sent by Node_A and about 50 will be sent by Node_B.

I suggest that you develop your solution so that at first your Node_A is a sender only. You can test by running the simulator with BiDiectional=false. Once you are confident that your sending code is working you can try to add the code to be a receiver. To test your receiving code, you will run the simulator and set BiDiectional=true.

Here is the format for property file for the simulator:

NumberOfMessages=n <n is number of messages> [default is 0]

TimeBetweenMessages=t <t s average time between messages from layer5> [default is 0]

ProbabilityOfLoss=l <l is probability of packet loss> [default is 0.0]

ProbabilityOfCorruption=c <c is probability of packet corruption> [default is 0.0]

TraceLevel=TL <TL is trace level (0|1|2|3)> [default is 0 (no tracing)]

BiDirectional=true|false [default is false (one direction, A -> B)]

Simulator Output

When the simulator has finished, it will display a number of statistics to help you evaluate the success of your project. Here is an example:

Simulator terminated at time 29808.73 after sending 1000 msgs from layer5

Bytes given to A: 32949

Bytes recvd by B: 32949

Bytes given to B: 32109

Bytes recvd by A: 32109

Packets sent [A]: 1175

Packets sent [B]: 1229

Packets lost: 500

Packets corrupt: 97

1. Bytes given to (A or B) is the count of all of the bytes in all of the messages sent by layer 5 (A or B) to its layer 4.
2. Bytes recvd by (A or B) is the count of all of the bytes taken in recv() calls by layer 5 (A or B) from its layer 4.
3. Packets sent (A or B) is a count of all of the packets presented by layer 4 (A or B) to layer 3. This count includes packets that have been corrupted or dropped by layer 3.
4. Packets lost is the total number of packets dropped by layer 3
5. Packets corrupt is the total number of packets corrupted by layer 3

Your goal is to write a program that correctly delivers ALL of the bytes given to it by layer 5 to the remote layer 5, and to deliver ALL of the bytes that you receive from the network TO your layer 5. So, the number of bytes recvd by B should equal the number of bytes given to A. Similarly, the number of bytes recvd by A should equal the number of bytes given to B.

The Software Interface

Layer 3 provides service to you for send and receiving network packets, starting and stopping timers, getting system time, and tracing. The methods that provide these services are accessible from the layer3Entity object passed to your Node_A constructor. The services are:

toLayer3() // send a packet into the network

startTimer() // start a timer

stopTimer() // stop a timer

getTime() // get current system time

trace() // display your own debugging information

Layer 5 provides just one service that your Node_A is required to use ONLY if you support bi-directional data transfer. You must notify layer 5 that thee is data in your receive buffer available for reading. This alerts layer5 that it should execute your recv() method to remove data from the receive buffer. The notify service is accessible from the layer5Entity object passed to your Node_A constructor:

Notify() // notify layer 5 that there is new data in the receive buffer

Layer 4 (Node_A)

As a layer 4 entity, you (Node_A) provide typical TCP services to layer 5 AND receive packets and timer interrupts from layer 3. You have to write the following methods for the Node_A class:

Init()

Open()

Close()

Send()

Recv()

FromLayer3()

TimerInterrupt()

These methods are documented in layer4Entity.java "Stubs" for these methods have been provided in Node_A.java.

Note: if you are working as a pair and are also developing Node_B, then Node_B will declare a Listen() method rather than an Open() method.

All of these methods are documented in the JAVADOCs.

The packet and message classes.

Layer 5 will provide data to transmit using the message object, passed on calls to the send method. The message class is documented in the JAVADOCs

The packet class is an approximation of a real TCP packet. You create new packets to send to Node_B, and you receive packets from Node_B through layer 3. The packet class is fairly powerful in that it provides a complete checksum mechanism as well as control flag test, set, and reset.

The packet and message classes are documented in the JAVADOCs.

Protocol Specification

The protocol specification describes the behavior that is expected from your program. This specification is based upon RFC 793 and the text

User (layer 5) Functions.

Your must implement the following methods (see layer4Entity.java)

• open
• close
• send
• recv

You DO NOT have to implement listen() unless you are working as a pair.

Connection establishment

• You must implement the 3-way handshake connection establishment process described in the text.

• You DO NOT have to support RST, Urgent data, PUSH, or the user ABORT command.

Flow Control.

• You must implement the credit based flow control described in the text in Chapter 3.

• You must implement the parameters TRANSMISSION_ INTERVAL and RETRY_COUNT defined in layer4Entity.java for timing and retry

• Your maximum window size is 1024.

• Your initial send sequence number (ISS) is 1.

• You DO NOT have to support RST, Urgent data, Security, Precedence, or PUSH mentioned in the RFC.

Connection Termination

• You must implement the 3-way handshake connection termination process described in the text.

• You DO NOT have to support receipt of segments in the FIN_WAIT1 or FIN_WAIT2 states as described in the RFC.

• You DO NOT have to support RST, Urgent data, Security, Precedence, PUSH, or the user ABORT command.

• RFC 793 says that TCP (your layer 4) will signal a user (layer 5) when the remote end of the connection has closed (indicated by receipt of a FIN segment). YOU DO NOT HAVE TO IMPLEMENT THIS. In this simulation, layer 5 will call your close() method indicating that it wants you to begin the close connection sequence (by sending a FIN segment to Node B).

You should pay attention to the timer values given in layer4Entity.java. These are the values that Node B is using. The TIME_WAIT value is the value that you SHOULD use when you enter the TIME-WAIT state (you leave this state when the timer expires).

Implementation Policies

Send:

Send ONLY when the send window allows, and queue messages for later transmission when the send window opens. Do NOT support PUSH

Deliver:

- Use Notify() to alert Layer 5.

- Give data to layer 5 when layer 5 executes your recv() method.

- Pass ONLY data that has been received in correct sequence order.

Accept:

You are free to choose, but beware that the In-Order policy generates excess network traffic (see Performance Requirements).

Retransmit:

First-Only

Acknowledge:

Your are free to choose, but beware that the Immediate policy generates excess network traffic (see Performance Requirements).

The TCP Packet (packet class)

The maximum payload (data) field in a packet is 128 octets (See packetProperies.java)

You are NOT required to provide support for the RST flag.

User Data

The maximum size message that a user will pass to layer 4 on a send call is 128 octets (see message.java).

Performance Requirements

Your program must be able to handle both packet loss and packet corruption. It should be possible for your program to successfully connect, send all messages, and disconnect when the sum of the packet loss and packet corruption probabilities are 0.25 or less.

I will run your program several times, specifying corruption and loss in varying combinations, up to the limit of 25% packet failure. Remember that packet loss/corruption is a random event and simply because you can execute the simulator once or twice with 25% packet loss and pass does not necessarily prove that your program is correct.

For example, you should verify that you could complete the 3-way handshake when packets are lost/corrupted in BOTH directions. The same requirement applies to the 3-way disconnect sequence.

Since you are required to support bi-directional data transfer you should pay careful attention to your Accept and Acknowledge policies so that:

1. You require as few retransmissions as possible
2. Send as few ACK packets as possible yet avoid unnecessary window closing.

NOTE: You should test that your program works for at least 1000 messages. It is possible that your program may work for 50 or even 100 messages, but fail for longer streams of messages. I will test by using 1000 messages.

What to Submit

You must submit a zip file containing ALL of your source code:

• DO NOT INCLUDE CLASS FILES
• DO NOT INCLUDE pns.jar
• DO NOT ATTEMPT TO MAKE A PACKAGE
• DO USE A FLAT FILE STRUCTURE.

The zip file must be emailed to me no later than 11:59 PM on Thursday, December 16. Please name the file <first>_<last>.zip where <first> is your first name and <last> is your last name. For example, were I to submit a zip file, I would name it joseph_conron.zip.

PAY ATTENTION TO THIS: you must save a copy of the email WITH THE ATTACHEMENT that you submit. If there is some problem such that I do not receive your project before the due date, you can prove to me that you did in fact send it on time by producing the SAVED email.

How the project will be graded

The project, including answers to questions, is worth either 94 or 100 points, depending whether you work alone or in a pair.

• Students who are working alone are only required to pass test items (1) through (5). Top score = 90
• Students who work as a pair must pass test items (1) through (6). Top score = 100.

Test Item	Value
(1) Program handles connect and disconnect correctly at 0% loss/corruption	20 points
(2) Program handles sending at 0% loss/corruption	20 points
(3) Program handles receiving correctly at 0% loss/corruption	20 points
(4) Program handles connect, data transfer, and disconnect correctly at 25% loss/corruption	20 points.
(5) Performance Case 1	10 points
(6) Performance Case 2	10 points

How I will grade performance:

I will examine the behavior of your program in two areas:

(1) Send efficiency with no packet loss (A sends only) [10 points]

• The number of packets sent by A should not be greater than 1004 when the number of messages is 1000. [5 points]
• The total time to run the simulation should not exceed 22000 when the time between messages is 20 (-t 20) and then number of messages is 1000. [5 points]

(2) ACK efficiency with no packet loss (A and B send) [10 points]

• The number of packets send by A should be less or equal to 0.8 times the number of messages selected from the command line (the value of the -n option) when the number of messages is 100 or greater.

Case (1) is easy. If you cannot do meet these requirements then you may have a problem in your design.

Case (2) is a test of your ACK policy and the extent to which you piggy-back ACKs in your data segments that you send to B.

I will run your program twice for each case. If it fails to meet the requirements for the case BOTH times, then you do not get the points. (Sorry, "works sometimes" is not good enough!)