Product Information System: Design Document Version 2.0 XYZZY Software July 2016   Revision History Version Date Author Comments 1.0 01/07/16 D. Jarvis Initial draft: Phase 1 2.0 05/07/16 D. Jarvis Initial Draft: Phase 2 Please email [email protected] with any corrections / requests for clarification.   Table of Contents Revision History 2 1. Introduction 4 2. Requirements 5 3. Architecture 7 4. Database / Data Access Design 8 5. GUI Design 9 6. Class Diagram 13 7. Sequence Diagrams 14 8. Acceptance Test Plan 15 Acknowledgements 16   1. Introduction XYZZY Software has been approached by liquor distributor CQU to develop a product information system to assist customers who are interested in the purchase of fine wines and spirits. It has been decided that in keeping with industry best practice, a 3-layered architecture will be employed. Two candidate architectures have been identified - MVP (Model View Presenter) and MVC (Model View Controller). Your initial tasks are to prototype these architectures. In terms of product, the scope of these prototypes will be limited to a small subset of malt whiskies. MVP implementation is designated as Phase 1; MVC implementation as Phase 2. This document represents the current state of the design for the Phase 2 system. Note that the system must be developed using Java Technologies, in particular NetBeans, Swing and Java DB. The code that is produced must also be appropriately documented and a standard coding / layout convention used. JavaDoc is not required, but all public methods must be suitably documented.  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 provide information about products to a potential purchaser. 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: 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 products 4. Display all products for a specified region 5. Display the number of products within a specified age range 6. Update the price of a specified product 7. The software architecture is to conform to the MVP (Model View Presenter) pattern. In Phase 2, Requirement 7 is to be changed to conformance to the MVC (Model View Controller) pattern. Also after using the Phase 1 system, the client has requested the following changes / additions: 1. Requirement 5 is to be changed so that all products within a specified age range are to be displayed 2. Browsing of query results is to be supported In addition, the XYZZY design team has determined that a clear button is required to clear both the GUI and the model state required by the MVC implementation. Thus the Phase 2 requirements are the following: 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. Browse all products 4. Browse all products for a specified region 5. Browse all products within a specified age range 6. Update the price of a specified product 7. Clear GUI and model state 8. The software architecture is to conform to the MVC (Model View Presenter) pattern. As before, products (ie malt whiskies) are specified by a distillery and an age - 10 year old Laphroaig and 15 year old Laphroaig are distinct products. The required browsing functionality is described in Section 5. 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 2, consisting of a 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 SINGLEMALTS; CREATE TABLE SINGLEMALTS ( DISTILLERY VARCHAR (32) NOT NULL, AGE INT NOT NULL, REGION VARCHAR (16) NOT NULL, PRICE INT NOT NULL, PRIMARY KEY (DISTILLERY, AGE) ); INSERT INTO SINGLEMALTS(DISTILLERY,AGE,REGION,PRICE) VALUES ('Laphroaig',10,'Islay',100), ('Laphroaig',15,'Islay',150), ('Laphroaig',30,'Islay',500), ('Lagavulin',16,'Islay',100), ('Oban',14,'Highland',120), ('Tomatin',12,'Highland',90), ('Tomatin',14,'Highland',110); 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 SingleMaltQueries 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 Figures 2 and Table 1. Figure 2a. Start screen / screen after Clear clicked. Note that Previous and Next buttons are disabled. Figure 2b. Display After All Malts clicked. Note that "Record x of y" is displayed in the Message area. This message is to be modified to reflect the record displayed by the Next / Previous buttons. Figure 2c. Display after price has been updated Functionality Swing Components Output JTextArea Input JLabel, JTextField Operations JButton Table 1. Mapping of GUI functionality to Swing component types. Feel free to use this design as is or to do things differently, for example using menus for data entry and tables for output. However, browsing behaviour similar to that intimated in Figures 2 must be provided. In particular 1. The fields for the current record are to be displayed in separate controls 2. Browsing is to be circular. If the last record is displayed, Next will result in the first record being displayed. If the first record is displayed, Previous will result in the last record being displayed. 3. The browsing buttons are to be disabled at start up, when Clear is clicked and when Update Price is clicked. 4. "Record x of y" is to be displayed and updated appropriately for each record that is browsed. 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, the required actions are summarised in Table 2. Requirement Button Inputs Required 1 n/a n/a 2 Exit None 3 All Malts None 4 Malts From Region Region 5 Malts in Age Range Age range – see below 6 Update Price Distillery, Age, Price 7 Clear none 8 n/a n/a Table 2. Mapping of requirements to actions If required inputs are not present, then an appropriate message is to be displayed in the message area. For requirement 5, note that clicking of the Malts in Age 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, the left input is to be set to 0. If only the left input that is specified, then the right input is set to 100.   6. Class Diagram The class diagram for the application is illustrated in Figure 3. Figure 3. Class diagram 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 Products class. Note that UML syntax is not strictly followed. In particular, we feel 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. Also note that unlike the Phase 1 class diagram, key private members are only shown for the SingleMaltQueries class.  7. Sequence Diagrams Omitted. Normally, each use case/requirement would have a corresponding sequence diagram.   8. Acceptance Test Plan The following tests will be performed by the customer: 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 incomplete field entry 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 incomplete field entry 7 Operation performs correctly 8 Implementation conforms to the specification provided in this document Browsing Browsing behaves as detailed in Section 5 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/ )