9.2 SAM

This section describes the behaviour of SAM and the interaction between its modules using use cases.

Figure 34: Shows the actors and use cases for SAM

9.2.1 Loading SAM

Description:

This scenario describes how SAM is loaded and what happens on startup.

Trigger:

The user decides to open the SAM program.

SRS References:

3.2

1. The user runs SAM.
2. A new Controller class is created, which in turn creates the MainWindow class.
3. In creating the MainWindow class the only instances of AnalysisPluginsClass and the OutputPluginsClass, AnalysisPlugins and OutputPlugins, are also created.
4. The AnalysisPlugins.loadPlugins() function is called which imports all the files ending in .py in the analysis directory which causes all analysis plugins to register themselves giving their title and function name, e.g. AnalysisPluginsClass.registerPlugin( "Example Analysis", analysis).
5. The OutputPlugins.loadPlugins() function is also called thus importing all the output plugins, causing them to register themselves, e.g. OutputPlugins.registerPlugin("Example output", output).
6. Controller class then calls the MainWindow.show() function.
7. MainWindow.show() then requests the list of all the analysis plugins AnalysisPlugins.listPlugins() and displays them on screen, they are then disabled so that the user can't click on them.
8. MainWindow.show() requests the list of all the output plugins OutputPlugins.listPlugins() and displays them on screen, these are also disabled so the user can't click on them.
9. MainWindow.show() then grays out the 'graph' button making it unavailable to be selected, since no log file has been loaded and no data selected.
10. MainWindow is now ready to accept user input.

9.2.2 Performing a packet dump

Description:

This scenario describes how a packet dump is made by the user using a separate user interface to the rest of SAM.

Trigger:

The user clicks on the ``Create log'' button or selects ``Create log'' from the file menu.

SRS References:

3.2.1.9a, 3.2.1.9b, 3.2.1.9c, 3.2.1.9d, 3.2.1.9e

1. MainWindow.loadLog() creates a new instance of the Logger class and then calls the Logger.show() function which brings up the Packet dump options GUI.
2. The user then has the option to:
   1. Select the network interface to log : the user left this as the default value
   2. Select the packet fields to log : the user selected TCP Window
   3. Select the logging interval : the user left this as the default value
   4. Select the logging duration : the user left this as the default value
   5. Select the file to dump to : the user selected browse and created a file called 'fred'
   The user then clicks on the ``Begin Logging'' button.
3. The Logger.begin() method is triggered which reads in the options selected and creates a Logging object and calls its Logging.show() function.
4. The Logging.show() function adds ``time'' and ``stream'' fields to those selected and calls the NetLogger.beginLog() function which starts logging.
5. The Logging.show() function then creates the MonitorLogging class and calls the MonitorLogging.start() function which updates the progressbar as packets are logged.
6. Once the specified duration has expired, the user is notified of this and may continue (perform another log or return to the main window of SAM).

9.2.3 Opening a log file

Description:

This scenario describes how a log file is selected.

Trigger:

The user decides to select a log file to perform an analysis on.

SRS References:

3.2.1.1

1. The user selects the ``Open File'' button or selects ``File'', then ``Open File'' from the menu.
2. An ``Open File'' dialog box pops up, providing the user with a directory listing from the current directory and a line to input a filename by typing it in. The dialog box is modal, ie, the user cannot interact with Mainwindow while this is open.
3. The user selects or enters a log file name, and either clicks ``Ok'' or presses the enter key.
4. MainWindow creates Model class with the selected file name.
5. Model then creates an instance of NetLogInput class and extracts the available data (fields) from the file using the NetLogInput.getFields() function, which either raises a exception or parses the files header returning all available fields.
6. If a streams field is present, Model then creates a StreamsLogInput class and parses the corresponding STREAMSLOG file with StreamsLogInput.parse() which either raises a exception or returns all the available streams.
7. MainWindow then calls Model.getAvailableFields() which returns a list of all the available fields.
8. MainWindow calls Model.getStreams() which returns a list of all the available streams.
9. MainWindow then catches any IOError or CustomError exceptions that may have been raised and by calling ErrorHandler class with a error string, displays them in a separate error box. The ``Open File'' dialog box will remain open until a valid file is selected or the user clicks the ``cancel'' button.
10. If an error occurs the user can acknowledge an error by clicking ``Ok'' or pressing the enter key.
11. If no error occurs the ``Open File'' dialog box is closed and the outputplugins and analysis plugins are enabled ready for the user to select them.

9.2.4 Selecting streams, data, output and analysis types

Description:

This scenario describes how streams, data, output type and a particular analysis are selected.

Trigger:

A log file has just been successfully loaded.

SRS References:

3.2.1.2, 3.2.1.3, 3.2.1.5, 3.2.1.6

1. A list of streams and list of data types from the loaded network log has been produced and displayed on screen already, this enables the analysis and output to also be selected.
2. The user can select in any order:
   1. One or more streams and/or stream combinations
   2. One data type
   3. One analysis type
   4. One output type
3. The user can then and only then click the ``Run'' button which becomes available to be selected, i.e., is no longer greyed out.

9.2.5 Performing an analysis

Description:

This scenario describes how an analysis is performed on a data table and how it is output to the user.

Trigger:

The data, stream set, analysis type and output type have all been selected by the user, who then clicks ``Run''.

SRS References:

3.2.1.4, 3.2.1.7, 3.2.1.8

1. The MainWindow.handleAnalysis() is called which calls the Model.generateTable(fields,streams) with the selected fields and streams.
2. Model.generateTable() calls NetLogInput.parse which either raises an exception (if file is of incorrect format) or returns a Table class containing all the data on the selected fields and streams, which is then passed back up to MainWindow.
3. MainWindow.handleAnalysis() then calls AnalysisPlugins.runPlugin(table) passing it the Table class.
4. AnalysisPlugins.runPlugin(table) will initialise and run the selected analysis which may include opening a window which allows the user to select further options specific to the analysis.
5. AnalysisPlugins.runPlugin(table) then performs its analysis on the Table class and returns another Table class.
6. MainWindow.handleAnalysis() then calls OutputPlugins.runPlugin(table) passing it the analysed data.
7. OutputPlugins.runPlugin(table) may open its own window allowing the user to select further options.
8. OutputPlugins.runPlugin(table) then outputs the analysed data as the user selected.

9.2.6 Getting Help

Description:

This scenario describes how a user can get help at any stage of the program.

Trigger:

The user wishes to get help on a topic.

SRS References:

4.3.4.5, 5.2.3

1. The user clicks on the ``Help'' menu item.
2. The MainWindow.startHelp() is called.
3. MainWindow.startHelp() checks that the there are user documents then compiles the user documentation from the .tex files if they haven't been already.
4. It then spawns a new thread and calls a web browser to handle the viewing of the document which displays the table of contents.
5. The user can then select a topic from the table of contents by clicking on the link the user can then read the information and close the window, all at the same time as using sam.

9.2.7 Exiting SAM

Description:

This scenario describes how a user exits the program.

Trigger:

The user wishes to exit SAM.

SRS References:

3.2.1.10

1. The user clicks on ``File'' then ``Exit'' from the File menu.
2. SAM shuts down.