================================================================================
Test... Are you using 80 columns of text?
12345678901234567890123456789012345678901234567890123456789012345678901234567890
================================================================================
CSC 442F: SOFTWARE ENGINEERING
==============================
Course Project: Part 1
Program Design Documentation Version 1.0
By: Joveria Asif
Khalid Mufti
David Tam
DESIGN NOTES
============
1.0 INTRODUCTION
================
This design document is intended to supplement the application-level protocol
defined in the PROTOCOL document. The internal design of the program is
described in this document.
An object-oriented approach was used to design the server program. The first
component of the server is the main object. It continously listens to a specified
TCP socket for new client connects. Once a new client connects, it transfers the
connection to a new port, forks off the connection, and passes the file
descriptor for this new port to a newly instantiaed socket object. The main
object then returns back to listening for new connections. Each new client
connection is handled by a new socket object.
Once the socket object has created, it instantiates a parser object to parse all
incoming data. When the parser is instantiated, it creates a login, admin,
request, and schedule object to handle each class of requests. The parser
receives text commands from the socket connection, parsers the data, and calls
the appropriate class and its associated member function with correct parameters
to execute the transaction.
Each of the login, admin, request, and schedule objects instantiate their own
copies of the filesystem class to handle data transfer between the server and
disk(s). The filesystem class also handles atomicity, concurrency, and logging
requirments.
This object-oriented break-down of the program easily allowed for parallel development
of code. The only major central component in the program (in which almost all
other objects must interactive with) was the parser. Objects such as the
request, login, admin, and scheduler class did not depend on each other. While
the parser object was the central source of control, a filesystem object
instantiated for each the other objects to provide basic file support services.
The scheduling data was kept in flat data files (in ASCII format) and basic file
locking was provided through unix facilities. An off-the-shelf SQL database was
not used because the data files were relatively simple. Also, the time
required to learn about available SQL databases, find a open-source version,
install it on the workstations, and learn the query language would have consumed
more time than using flat data files. Since a basic file locking module was
made available to the project, using flat files was decided.
2.0 HOW EACH EVENT IS IDENTIFIED
================================
This protocol uses the following structure to uniquely identify each event:
Username.Year.Month.Day.StartHour
This structure is what is needed whenever a function asks for an EventId
parameter. Not only does this structure allow each user to identify his/her
meetings uniquely, but it also allows group meetings to be easily referenced and
modified by matching the last four parts of the structure
(Year.Month.Day.StartHour).
Each part of the structure has the following format:
Username: When a username is created, the server assigns each username a unique
ID for internal server use. Each username (8 chars max) is
dereferenced to that number. The unique ID is an unsigned long int.
Year: The year of the event in 4 digits (Y2K compatible). (unsigned int)
Month: The month of the event in 2 digits. (unsigned int)
Day: The day of the event in 2 digits. (unsigned int)
StartHour: The start hour of the event in 2 digits. (unsigned int)
3.0 FILE FORMAT (STORING ALL THE DATA)
======================================
This section examines the files and file formats used to store data on the
server.
3.1 Main Registry
-----------------
The main registry is stored in the primary directory, under the file
"registry.dat". This file contains each username and password.
Thus, each entry in the file has the following format:
3.2 Directory Structure
-----------------------
Each user has directory that contains a file for each day that an event is
scheduled, a notification file, a notes and todo list for each applicable day,
and a prefs file for saving client state information. The following is an
example of the contents that may be found in the user's directory.
//...events.dat
//...notes.dat
//...todo.dat
//prefs.dat
//userinfo.dat
//notify.dat
3.3 Files
---------
The notify.dat, todo.dat, notes.dat, prefs.dat, and userinfo.dat files are
described in more detail below.
3.3.1 Notifications
-------------------
All notification messages for each user are stored in the
following location:
//notify.dat
New events are added to this file. Basically, this is the user's mailbox. The
following is a typical entry:
||
All notifications are automatically placed in the appropriate user notification
boxes by the server on behalf of other users. The first field contains the
username of the person who created the notification. The second field, an
unsigned int, numerically classifies the type of notification. The numbers in
this field have the following meaning:
0 = it is a request sent by the creator of the meeting
1 = it is an acceptance sent from an invitee
2 = it is a rejection sent from an invitee
3 = it is a deletion sent by the creator of the meeting
4 = it is a an acceptance but with shortened attendance (invitee's reponse)
5 = it is a change in room location of the meeting
The EventId structure is used to identify new events in order to increase
efficiency. The notification description field is 256 chars, and it identifies
the content of the notification. In this document, the pipe symbols | are used
so that a field value may contain spaces.
An Example
----------
When Bill schedules a 2 hour meeting with Monica on Saturday, Sept. 26, 1998 at
9 pm (21:00 hrs), the following entry will appear in Monica's notify.dat file:
bill 0 bill.1998.09.26.21 |We need to talk|
If Monica reads this notification and accepts the invitation, the following
will automatically appear in Bill's notify.dat file:
monica 1 bill.1998.09.26.21 |I'll be there|
However, if Monica reads this notification and rejects the invitation, the
following will appear in Bill's notify.dat file instead:
monica 2 bill.1998.09.26.21 |Sorry. No can do|
On the other hand, if Monica reads the notification and can't make up her mind,
no entry will appear in Bill's notify.dat file.
If Monica decides to compromise and meet for only 1 hour, the following will
appear in Bill’s notify.dat file:
monica 4 bill.1998.09.26.21 |Ok. But only from 9 pm to 10 pm. I'm very busy|
If Bill has second thoughts about the meeting and decides to cancel it, the
following will appear in Monica's notify.dat file:
bill 3 bill.1998.09.26.21 |Forget I even mentioned it.|
3.3.2 To Do List
----------------
Each To Do List is associated with a particular day and is stored in the
following location:
//...todo.dat
Each To Do List can contain a maximum of 256 characters. Thus, this list can be
considered a big block of text.
3.3.3 Notes List
----------------
Each Notes list is is associated with a particular day and stored in the
following location:
//...notes.dat
Each Notes List can contain a maximum of 256 characters. Thus, this list can be
considered a big block of text.
3.3.4 Prefs
-----------
All client preferences and state information is kept in the following location:
//pref.dat
This storage space is initially empty. The data stored here is completely
client-definable, giving the client flexibility on the content, type of data,
and format. For example, a possible structure of this file might look as
follows:
client layout, client view, viewing year, viewing month, viewing day,
viewing hour, colour of background, size of main window, size of
notification window, etc...
It is up to the client to manage the information stored here. E.g. parsing,
keeping it consistent, etc...
3.3.5 Userinfo
--------------
Each user has a file that contains user information. It is kept in the following
location
//userinfo.dat
It contains 7 seven lines, with the following meanings:
Line Number #1: First name. (max of 25 chars)
Line Number #2: Last name. (max of 25 chars)
Line Number #3: Address. (max of 128 chars)
Line Number #4: Phone #. (max of 15 chars)
Line Number #5: Fax #. (max of 15 chars)
Line Number #6: Email. (max of 50 chars)
Line Number #7: Comment. (max of 256 chars)
3.3.6 Events (Meetings, etc)
----------------------------
All events, such as meetings, are stored in the following location:
//...events.dat
Every events.dat file contains 24 entries, 1 entry for each hour. Each entry is
broken up into several parts, as shown below:
|| ||
<# of Users> ...
The first field identifies the length of the meeting. The second field provides
a quick event description in a maximum of 50 chars. The third field provides a
more detailed event description with 256 maximum numbers of characters. The
fourth field identifies the room for the meeting. The fifth field identifies
the room of the meeting. The sixth field the username who created the
meeting. The seventh field identifies the number of internal users attending
the event. Remaining pairs of fields give the username and attendance status of
those involved in the event. The attendance status can have the following
values:
0 = username has not responded or decided yet
1 = Ok, username will attend
2 = No, username will not attend
4 = username will attend but will shorten his/her attendance and make an
early departure / late entrance.
If the event is not a meeting, then the # of Users field is set to 0 and all
subsequent fields are empty. If a meeting does not require a room to take
place, the string "NO_ROOM" is used. Finally, if no event exists, then a single
minus sign "-" is inserted on the line. This allows random access file search
to be implemented.
If an event occupies more than 1 hour consecutively (e.g. a 2 hour event),
the event entry is copied to the subsequent hours as well. The only
difference is the ".hour" part of the EventId. It is changed to the new
hour's value. E.g. Monica has scheduled a 2 hour event from 10am to 12pm
on Sunday, September 27, 1998. The following entries will appear in the
/monica/1998/09/27/events.dat file:
Line 10: 2 |A two hour meeting w/ managers| |I want to talk to Bill and Al
about my raise.| whitehouse monica 2 bill 0 al 0
Line 11: 2 |A two hour meeting w/ managers| |I want to talk to Bill and Al
about my raise.| whitehouse monica 2 bill 0 al 0
4.0 TESTING PROCESS
===================
Each class, and each member function of a class was united tested with the help
of test scripts.
Within a class, as each new member function was written it was tested
immediately with a test script. Because the scripts also included tests for
member functions written earlier, these past tests were reconfirmed along with
the inclusion of the newly written member function. Due to this process, it can
be seen that a minor form of regression testing was performed.
The unit test scripts used include the following:
RequestTest
LoginAdminTest
Login
testcl
testserv
Integration testing was performed as soon as two separate units had successfully
passed unit tests. For instance, the request class and filesystem class were
tested for integration early in the development. These two classes were then
integration tested with the socket class.
Once these components performed fairly satisfactorly, the login and admin
classes were integrated and tested with the previous configuration.
(
geocities.com/siliconvalley/campus/9640) (
geocities.com/siliconvalley/campus) (
geocities.com/siliconvalley)