Marks Management System: Design Document
Version 2.0
XYZZY Software
July 2017

Revision History
Version Date Author Comments
2.0 08/07/17 D. Jarvis Initial draft
Please email d.jarvis@cqu.edu.au with any corrections / requests for clarification.

Table of Contents
Revision History 2
1. Introduction 4
2. Requirements 5
3. Architecture 6
4. Database / Data Access Design 7
5. GUI Design 9
6. Class Diagram 14
7. Sequence Diagrams 17
8. Test Plan 18
Acknowledgements 19

1. Introduction
XYZZY Software has been approached by CQU to develop a system to assist unit coordinators in the management of marks. The system will be initially trialled for COIT20258 and a phased implementation strategy will be adopted. This document reflects the current state of the design for the Phase 2 system.
2. Requirements
Because of the simplicity of the user requirements, the corresponding use cases are not duplicated here, as would be the case in a normal XYZZY design document.
The purpose of the system is to assist a course coordinator in the management of student results. A Java desktop application is to be developed, driven by a simple Swing GUI. Interaction between the database and the application is to be via JDBC. The NetBeans IDE is to be used for development. Java DB must be used as the database.
The Phase 1 user requirements were as follows:
1. Start the application and connect to the database. If a connection cannot be established, the application must exit.
2. Close the database connection and stop the application
3. Display all records
4. Display the record for a specified student
5. Display all records where the total mark is within a specified range
6. Update the exam mark and total mark for a specified student.
7. Clear the display
In addition, it was decided that the architecture of the application was to conform to MVP (Model View Presenter).
For Phase 2, it has been decided to change the architecture to conform to MVC (Model View Controller). Also, browsing of query results is to be provided, as is the provision of a grade calculation capability. Thus, the functional requirements are as follows:
1. Start the application and connect to the database. If a connection cannot be established, the application must exit.
2. Close the database connection and stop the application
3. Display all records
4. Display the record for a specified student
5. Display all records where the total mark is within a specified range
6. Update the exam mark and total mark for a specified student.
7. Clear the display
8. Browse query results
9. Calculate grades for all students
As with the Phase 1 design, a class diagram is provided in Section 6 which must be followed.
The database design and sample data are provided in Section 4. Data validation is not required at this stage. However, basic preconditions must be satisfied for each requirement and if these are not satisfied, an appropriate message is to be displayed. These preconditions are specified in Section 8.

3. Architecture
A three-layered architecture will be employed in Phase 1, consisting of view, presenter and model layers. Given the simplicity of the architecture, an architecture diagram is not provided.
Layers are to be modelled as packages – the package structure for the application is illustrated in Figure 1.
Figure 1. Package structure
4. Database / Data Access Design
The SQL script that will be used to test the application is given below.
DROP TABLE MARKS;
CREATE TABLE MARKS
(
STUDENTID VARCHAR (8) NOT NULL,
ASSIGNMENT1 INT NOT NULL,
ASSIGNMENT2 INT NOT NULL,
EXAM INT NOT NULL,
TOTAL INT NOT NULL,
GRADE VARCHAR (4) NOT NULL,
PRIMARY KEY (STUDENTID)
);
INSERT INTO MARKS(STUDENTID,ASSIGNMENT1,ASSIGNMENT2,EXAM,TOTAL,GRADE)
VALUES
('S01',20,0,25,45,'?'),
('S02',0,0,0,0,'?'),
('S03',15,0,0,15,'?'),
('S04',15,15,19,49,'?'),
('S05',25,20,39,84,'?'),
('S06',0,0,45,45,'?'),
('S07',25,25,0,50,'?'),
('S08',20,20,25,65,'?'),
('S09',20,20,24,64,'?'),
('S10',17,19,39,75,'?');
As there is only one table, an ERD is not provided.
Data access will be via JDBC using prepared statements. Java DB must be used as the database.
Normally, in an XYZZY design document, we would specify the queries in this section and relate them to the methods exposed by the ResultsQueries class described in Section 6. However, for this project, we have decided to leave query formulation to the implementers.

5. GUI Design
Developers are free to use the NetBeans GUI Builder or alternatively, they can hand code the complete GUI. An indicative GUI is presented in Figure 2 and Table 1. Developers are free to use this design as is or to do things differently, for example using menus for data entry. Note that because of the simplicity of the GUI in Figure 2, screen shots for the realisation of each requirement are not shown as would normally occur in an XYZZY design document. Rather, selected screen shots are shown and the required actions are summarised in Table 2.
Figure 2. Indicative GUI

Functionality Swing Components
Output JTextArea
Input JLabel, JTextField
Operations JButton
Table 1. Mapping of GUI functionality to Swing component types.
Requirement Button
Inputs Required
1 n/a n/a
2 Exit None
3 All Students None
4 Specified Student Student #
5 All Students in Range Range of Marks – see below
6 Update Exam and Total
Student #, Exam, Total
7 Clear
None
8 Previous, Next None
9 Update Grades None
Table 2. Mapping of requirements to actions
Some indicative screenshots are shown below:

Figure 3. Update Grades selected

Figure 4. All Students selected

Figure 5. Previous selected
Note that
• in this phase, browsing is required and the text fields are to be used to both display the current record and it input query data. The text area is to be used only to display messages.
• the IView interface no longer contains a display() method, as record and message updating is now initiated by ResultsModel. Instead, it contains methods to clear the display and to enable/disable the Previous and Next buttons. ResultsController will initiate this functionality.
• with exceptions, there is no need to display a message, as the expectation is that when a query throws an exception, the application will exit. However, do print a stack trace to standard output.
For requirement 5, note that clicking of the Total Marks in Range button will result in the invocation of a single method. If two numbers are specified as input, then they are to be treated as the lower bound (left) and upper bound (right) of an inclusive range. Having the upper bound less than the lower bound is to be treated as an error. Having both numbers the same is not an error – they are the endpoints of a range of length zero. If one number is specified, then if it is the right input, it is an error. If it is the left input that is specified, then the right input is set to the value of the left input.
When browsing,
• when the end of the list is reached, next is to display the first record
• when the start of the list is reached, previous is to display the final record
For requirement 9, the rules to be applied are as follows:
Grade Rule
HD 85 = total = 100
D 75 = total 85
C 65 = total 75
P 50 = total 65
AF Marks for all assessment items of 0
NS Total 50 and exam mark = 0
SE 45 = total 50 and only one assessment item (the exam) failed. All assessment items must have been attempted (ie marks 0)
SA 45 = total 50 and only one assessment item (an assignment) failed. . All assessment items must have been attempted (ie all marks 0)
F Total 50 and not awarded an AF, SA or SE
6. Class Diagram
The class diagram for the application is illustrated in Figure 3.
Figure 3. Class diagram
Note the following:
• Data validation and any associated type conversion is to be performed in ResultsView
• GUI startup (setVisible() invocation) is to be performed in Results, as is observer registration
• ResultsModel will need to catch exceptions thrown by the ResultsQueries methods. However, once caught, just print a stack trace and exit the application
• There is only one main() method – in Results.
• Model state information is to be captured in Update objects. This information is to be made available to ResultsView via notifyObservers()
• All IModel methods are of type void – no values are returned to ResultsController
The mapping to packages/layers is provided in Section 3. Note that Figure 3 represents a refactoring of the class structure favoured by the NetBeans GUI Builder. Rather than having GUI creation in the GUI class definition (through the provision of a main() method, we have chosen to place GUI creation in a separate main class. If you are using the NetBeans GUI builder, all that this means is that the main() method that the Builder generates is moved into the Results class. Also note that interaction between the ResultsQueries class and the JBC library classes is not shown. This is normal for class diagrams. Finally, formal UML syntax is not strictly followed. In particular, we feel felt that method signatures as employed in NetBeans are clearer than their UML counterparts. In this regard, note that if no return type for a method is specified, void is assumed.
7. Sequence Diagrams
Omitted.

8. Test Plan
The following tests will be performed prior to acceptance:
Requirement Test
Comment
1 Operation performs correctly given correct preconditions
1 Handles no database/incorrect database Application is to exit
2 Operation performs correctly
3 Operation performs correctly
4 Operation performs correctly given correct preconditions No data validation checks required.
4 Handles incomplete field entry

5 Operation performs correctly given correct preconditions No data validation checks required.
5 Handles missing preconditions

5 Input variants as specified in Section 5 are handled correctly
6 Operation performs correctly given correct preconditions No data validation checks required.
6 Handles missing preconditions

7 Operation performs correctly
8 Previous and next buttons cycle

8 Previous and Next buttons disabled/enabled
9 Grades upgraded correctly

Table 3. Acceptance tests
Note:
1. By preconditions, we mean that the required values are available.
2. Acceptance tests coincide with class unit tests, so no separate unit testing is required.
3. Testing will be conducted by the markers with the database specified in Section 4.

Acknowledgements
The UML diagrams were created using Violet ( http://horstmann.com/violet/ )