LAB-JAVA_BASH-MAYNOOTH_CS380/lab8_protocols/jasper/docs/index.html

535 lines
19 KiB
HTML
Raw Permalink Normal View History

2020-12-08 21:10:13 +01:00
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- index.html K. J. Turner 28/09/15 -->
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>
Jasper Protocol Simulator (Java Simulation of Protocols for Education and Research)
</title>
<link rev="made" href="mailto:kjt@cs.stir.ac.uk"/>
<meta name="keywords"
content="communication communications protocol network interactive graphical visual visualisation simulation simulator ABP Alternating Bit Protocol ABRA Abracadabra Protocol BOOTP Boot Protocol HTTP HyperText Transfer Protocol IP Internet Protocol SMTP Simple Mail Transfer Protocol SWP Sliding Window Protocol TCP Transmission Control Protocol TFTP Trivial File Transfer Protocol UDP User Datagram Protocol"/>
</head>
<body>
<div style="text-align: center">
<h1>
Jasper Protocol Simulator
<br/>
(Java Simulation of Protocols for Education and Research)
</h1>
</div>
<!-- =================== Description =================== -->
<h2>Description</h2>
<p>
This protocol simulator provides:
</p>
<ul>
<li>
the capability for interactively and graphically simulating a wide
variety of communications protocols
</li>
<li>a framework for creating new protocol simulations</li>
<li>
pre-defined simulations of various well-known protocols:
</li>
<ul>
<li>ABP (Alternating Bit Protocol)</li>
<li>ABRA (Abracadabra Protocol)</li>
<li>BOOTP (Boot Protocol)</li>
<li>HTTP (HyperText Transfer Protocol)</li>
<li>IP (Internet Protocol)</li>
<li>SMTP (Simple Mail Transfer Protocol)</li>
<li>SWP (Sliding Window Protocol, 3 and 5 column layout)</li>
<li>TCP (Transmission Control Protocol)</li>
<li>TFTP (Trivial File Transfer Protocol)</li>
<li>UDP (User Datagram Protocol)</li>
</ul>
</ul>
<p>
The simulator is written in Java, and so can be used on many platforms with
a web browser (subject to applet security) and/or a Java environment. To
compile or extend the simulator requires a Java development environment such
as the Oracle JDK (and ideally also Apache Ant). To run simulations requires
a Java runtime environment such as the Oracle JRE. The code has been
pre-built using JDK 1.8. However, it should compile and run using Java 5
onwards.
</p>
<p>
(A <a
href="http://science.webhostinggeeks.com/jasper-java-simulacija">Serbo-Croat
version</a> of this page was produced by Anja Skrba.)
</p>
<!-- =================== Installation =================== -->
<h2>Installation</h2>
<p>
The simulator is provided as a <var>Zip</var> archive. The simulator unpacks
to a directory called <var>jasper-N.N</var> according to version number. You
might rename this to <var>jasper</var> for simplicity. The distribution
contains:
</p>
<dl>
<dt><strong>build.xml</strong></dt>
<dd><var>Ant</var> build file to manage the code</dd>
<dt><strong>docs</strong></dt>
<dd>basic documentation</dd>
<dt><strong>html</strong></dt>
<dd>directory for protocol simulation pages and simulator JAR archive</dd>
<dt><strong>scenarios</strong></dt>
<dd>example scenario files</dd>
<dt><strong>source</strong></dt>
<dd>directories for Java code (protocol, simulator, support)</dd>
</dl>
<!-- =================== Applet Simulation =================== -->
<h2>Simulation as an Applet</h2>
<p>
The simulator can be used on various protocols by opening
<var>html/index.html</var> in a web browser. This assumes you renamed the
distribution folder as <var>jasper</var>. This will bring up the main page,
with general instructions and a list of protocols that can be simulated.
Your web browser will need to be configured to run Java applets and
(ideally) JavaScript. Due to Java security restrictions you must authorise
running of the pre-compiled code created by the University of Stirling.
Alternatively, use an applet viewer on the files (though the JavaScript to
set protocol parameters will not work).
</p>
<p>
Most simulations are in three-column format: two protocol entities
(sender/receiver or A/B) and a communications medium (link or network). A
few simulations add the sending and receiving users (applications) in outer
columns. This format is useful for showing what the user sees; typically
this is only part of what is happening in the protocol.
</p>
<p>
In a web browser, select an action by clicking on the list at the bottom
right of the diagram. Actions are things like a user sending a data message
or the medium delivering a protocol message. You are completely in control
of the simulation. For example you may decide when to send messages, whether
to acknowledge messages, and whether to deliver or lose messages in the
medium. Since the simulation does not run in real-time, a timeout is
possible as soon as a message has been sent.
</p>
<p>
The last action in the diagram is shown in red. Various protocol comments
may also be noted in green the diagram, e.g. that a timeout occurred or that
a message was ignored.
</p>
<p>
If you make a mistake, or just want to backtrack in the simulation, then
click <em>Undo</em>. You can undo as many steps as you like, right up to the
beginning of the simulation. Clicking on <em>Redo</em> will perform again
the last undone step. <em>Clear</em> will restart the simulation with the
current protocol parameters. If you click on <em>Run</em> the simulator will
run automatically, making random choices for you. If you are not sure what
to experiment with, this is an easy way of seeing the protocol in action.
While this is happening, the <em>Run</em> button changes to <em>Stop</em>.
Click on <em>Stop</em> to return the simulator to user control. You can
continue at this point as if you had made all the automatic choices
yourself.
</p>
<p>
The <em>Print</em>, <em>Load</em> and <em>Save</em> buttons are disabled
since the simulations are running as applets. If you wish hard copy of the
simulation, position the scroll bar in the simulation pane at an interesting
point and print out the whole web page.
</p>
<p>
Some simulations have associated protocol parameters. To change the defaults
that are shown, enter new values and click <em>Change Values</em>. In some
cases, this will force the simulation to restart. The following is a
screen-shot of a TCP client-server simulation, showing the protocol
parameters and the main simulation controls.
</p>
<!-- for SourceForge
<div style="text-align: center">
<img
src="https://a.fsdn.com/con/app/proj/jaspersimulator/screenshots/tcp-simulation.gif"
alt="TCP Simulation"/>
</div>
-->
<!-- for local file -->
<div style="text-align: center">
<img src="tcp-simulation.gif" alt="TCP Simulation"/>
</div>
<!-- =================== Application Simulation =================== -->
<h2>Simulation as an Application</h2>
<p>
Running a protocol simulation as an application gives access to the
<em>Print</em>, <em>Load</em> and <em>Save</em> buttons.
</p>
<p>
<em>Print</em> produces a hard copy of the whole simulation scenario.
Note that individual pages cannot be selected for printing. The width of the
printout is determined by the width of the on-screen window. Constants
<var>winWidth</var> and <var>winHeight</var> in
<var>ProtocolSimulator</var> define the initial window size. Constant
<var>maxHeight</var> in <var>TimeSequenceDiagram</var> defines the
vertical size of printed pages. The current sizes are appropriate for A4
paper. If necessary, change them for (say) US letter.
</p>
<p>
<em>Load</em> loads a simulation scenario file (with a name ending in
<em>.scn</em>); this must be for the same protocol as you are currently
simulating. It replaces the current simulation scenario (if any).
<em>Save</em> saves the current simulation as a scenario file (with a
name ending in <em>.scn</em>). If you are adventurous, you can create and
edit your own scenarios using a text editor.
</p>
<p>
When the simulator is run as an application, a mandatory protocol name
follows the main simulator class. Protocol parameters may then be given if
required; protocols have defaults for these. Assume that the simulator has
been built and is to be started from the top level of Jasper. The following
(split here across two lines) will run TCP in client-server mode, with
message window sizes other than the default:
</p>
<pre>
java -cp html/ProtocolSimulator.jar simulator.ProtocolSimulator
TCP/cs windowSizeA=500 windowSizeB=300
</pre>
<!-- =================== Development =================== -->
<h2>Development</h2>
<p>
The complete source of the simulator is provided. (Most files have Unix
end-of-line.) The code should preferably be rebuilt using the Ant
<var>build.xml</var> build file. <var>ant -p</var> will print help
information about build targets.
<var>ant&nbsp;simulator</var> will rebuild <var>ProtocolSimulator.jar</var>
in the <var>html</var> directory. <var>ant&nbsp;clean</var> will remove all
compiled class files and backup files, but preserving the JAR file.
<var>ant&nbsp;spotless</var> will remove even this.
</p>
<p>
If you do not have Ant you will need to compile the Java source files
manually and create a JAR file from the result.
</p>
<p>
To modify an existing protocol simulation or to write a new one will need a
knowledge of the simulation framework. See the article <a
href="http://www.cs.stir.ac.uk/~kjt/research/pdf/prot-sim.pdf"
target="_blank">An Interactive Visual Protocol Simulator</a> for details of
this and an extended example of how to develop a simulation. Once the
framework is understood, a simple simulation can be developed in a day;
complex protocols could take a week or two to develop.
</p>
<p>
Suppose that you want to develop a new simulation of the protocol
<var>EXP</var> (&#39;Example Protocol&#39;). You would need to write
<var>EXP.java</var> to instantiate the various entities in the protocol.
For a simple protocol, you would then write <var>EXPSender.java</var> and
<var>EXPReceiver.java</var> to define the behaviour of a sending or
receiving protocol entity. More complex protocols could involve defining
separate entities to handle the service interface and the protocol entity.
It might also be necessary to define the formats of protocol messages and a
variation on the underlying <var>Medium</var> to match these.
</p>
<p>
Due to increased Java security, applets need to be signed by a proper
certificate. This has been done for the pre-compiled code. If you need to
rebuild the code you will need your own keystore and digital certificate.
See the Ant build file for how to use these.
</p>
<p>
Bear in mind that much of the development work was undertaken by
students, so the level of comments in the code is somewhat limited in
places. The ABP simulation is the simplest of the protocols and is a good
place to start. The TFTP simulation is the best commented and best
explained of the protocols. It illustrates nearly all the key points in
simulation development.
</p>
<!-- =================== Licence =================== -->
<h2>Licence</h2>
<p>
This program is free software. You can redistribute it and/or modify it
under the terms of the <a href="http://www.gnu.org/copyleft/gpl.html"
target="_blank">GNU General Public License</a> as published by the Free
Software Foundation - either version 3 of the License, or (at your option)
any later version.
</p>
<p>
This program is distributed in the hope that it will be useful but
<strong>without any warranty</strong>, without even the implied warranty
of <strong>merchantability</strong> or <strong>fitness for a particular
purpose</strong>. See the GNU General Public License for more details.
</p>
<!-- =================== Acknowledgements =================== -->
<h2>Acknowledgements</h2>
<p>
The protocol simulator was developed by <a href="http://www.cs.stir.ac.uk/"
target="_blank">Computing Science and Mathematics</a> at the <a
href="http://www.stir.ac.uk/" target="_blank">University of Stirling</a>.
Iain A. Robin undertook most of the development for his Master's project
under Ken Turner&#39;s supervision. Paul Johnson and Kenneth A. Whyte
contributed to the development of some of the simulations for their Master's
projects. Dr. Peter J. B. King, Heriot-Watt University, provided helpful
ideas and suggestions.
</p>
<!-- =================== History =================== -->
<h2>History</h2>
<ul>
<li>
<p>
Version 1.0: Private internal version, Iain Robin, 1st September 1999
</p>
</li>
<li>
<p>
Version 1.1: Private internal version, Ken Turner, 22nd December 2000
</p>
</li>
<li>
<p>
Version 1.2: Private internal version, Ken Turner, 5th March 2001
</p>
</li>
<li>
<p>
Version 1.3: First public release, Ken Turner 6th June 2001
</p>
</li>
<li>
<p>
Version 1.4: General updating, Ken Turner, 9th March 2006:
</p>
</li>
<ul>
<li>HTML files updated to be XHTML-compliant.</li>
<li>
Source updated for JDK 1.5, and Swing graphics used. Note that JDK 1.5
or later is now required to re-compile the source or to run the code.
</li>
<li>
Top-level directory structure revised to have <var>source</var>,
<var>build</var> and <var>docs</var> directories.
</li>
<li>
<var>Makefile</var> replaced by Ant <var>build</var> file. Only
<var>build</var> and <var>clean</var> batch files retained. (Thanks
to Dr. Peter J. B. King, Heriot-Watt University, for contributing to
this.)
</li>
<li>
Blank lines ignored in scenario files.
</li>
<li>
<var>ABP</var> and <var>SWP3</var> medium control is now
offered through a parameter (delivery/loss, delivery only, automatic).
It would be possible in principle use this with other protocols, but
makes sense in only some cases. (Thanks to Dr. Peter J. B. King,
Heriot-Watt University, for contributing to this.)
</li>
<li>
<var>SMTP</var> protocol messages have been slightly renamed for
consistency with the RFC.
</li>
<li>
<var>TCP</var> default window size restored on restart.
Acknowledgements now sent on receipt of data, and not when
receiving window becomes full. Some complex changes caused by this.
Data pending delivery now sent to user prior to Closed. Open while
still Closing now leads to Closed when fully closed rather than
immediately. Duplicate SYN plus ACK now cancels any retransmissions
while Established.
</li>
</ul>
<li>
<p>
Version 1.5: Extensions for new protocols, Ken Turner, 11th February
2011
</p>
</li>
<ul>
<li>
Major new work has been undertaken for Pearson Education on new
simulations (CSMA/CD, Multicast, Multiplexing, Protocol Stack, TCP Slow
Start) to accompany the ninth edition of "Data and Computer
Communications" by William Stallings.
</li>
<li>
More comments, particularly JavaDoc, have been added to many files
(which have also been reformatted).
</li>
<li>
More thorough checks of values have been added to the JavaScript in HTML
files. In addition, the HTML files have been revised and reformatted.
</li>
<li>
The <var>TimeSequenceDiagram</var> class has been modified. Vertical
space is now added before a DELIVER protocol event, and also before a
COMMENT (even if it is not the first). A TRAVERSE protocol event has
been added to deal with the situation that a dashed arrow crosses
multiple columns. A corresponding <var>TraverseTransmission</var> class
has been added.
</li>
<li>
The <var>Medium</var> class has been extended with two
<var>isEmpty</var> methods: one to check if the medium is completely
empty of messages, and one to check if the medium is empty of messages
from a particular source.
</li>
<li>
All <var>TCP</var> classes have been extended to support the slow-start
variant (<var>TCP/ss</var>). In addition, some problems with TCP have
been corrected (obscure situations in which the protocol did not recover
when trying to close). The <var>TIME_WAIT</var> state is now used to
cope with these situations, including more abrupt termination when FIN
is received in unusual situations.
</li>
<li>
A <var>Protocol</var> can now now implement the methods
<var>getRandNumbers</var> and <var>setRandomNumbers</var> (by default
these do nothing useful). If these methods are implemented, a list of
the random numbers is appended to the scenario header line when the
scenario is saved, and is restored when the scenario is loaded. This is
for protocols such as CSMA that generate their own random numbers (as
opposed to media that do so as per previous releases). The header line
is now in a format such as "Jasper CSMA 0.3,0.01,0.891". If no random
numbers are present following the protocol type (as is the case with
previous scenario files) then no action is taken.
</li>
</ul>
<li>
<p>
Version 1.6: Distribution via SourceForge, Ken Turner, 18th December
2014
</p>
</li>
<ul>
<li>
The simulator has been packaged and made available via SourceForge.
</li>
</ul>
<li>
<p>
Version 1.7: Update for Java 7u51 onwards, Ken Turner, 28th September
2015
</p>
</li>
<ul>
<li>
The build file now sets the "Caller-Allowable-Codebase" attribute in the
simulator JAR manifest. This is so that more recent Java versions will
allow JavaScript access to the simulator applet. The user will be asked
to grant access to the applet from any file URL.
</li>
<li>
The pre-built simulator JAR has been signed with a later University of
Stirling certificate valid up to August 2018.
</li>
</ul>
</ul>
</body>
</html>