Simple Client Management (SCM)

Detailed software specifications

Table of contents
Table of contents ....................................................................................................................................................2 1. 2. 3. Introduction ....................................................................................................................................................3 Scope ...............................................................................................................................................................3 User level use cases ........................................................................................................................................4 3.1. 3.2. 3.3. 3.4. 3.5. 3.6. 4. Show info use case .............................................................................................................................4 enter/modify data use case ...............................................................................................................5 Add client use case .............................................................................................................................6 Update client use case .......................................................................................................................6 Delete client use case .........................................................................................................................7 Fill database use case .........................................................................................................................7

Implementation details ...................................................................................................................................8 4.1. 4.2. 4.3. 4.3.1. 4.3.2. 4.4. 4.5. 4.6. Introduction ........................................................................................................................................... 8 System architecture ...............................................................................................................................8 System level use cases ...........................................................................................................................9 Show info use case .........................................................................................................................9 enter/modify data use case ...........................................................................................................9 Class diagram .......................................................................................................................................10 Database structure ..............................................................................................................................10 User interface ......................................................................................................................................11

5.

Test plan ........................................................................................................................................................12 5.1. 5.2. 5.3. Unit tests ............................................................................................................................................. 12 Integration tests ..................................................................................................................................12 Functional tests ...................................................................................................................................12

6.

Final thoughts ...............................................................................................................................................12 6.1. 6.2. 6.3. Performance aspects ...........................................................................................................................12 Security concerns ................................................................................................................................13 Functional enhancements ...................................................................................................................13

1. Introduction
SCM is a simple demo system, with the declared intent of showing off our system analysis and software development capabilities. High level requirements are specified in the HLR.pdf document, provided by the client.

2. Scope
SCM will provide, trough a simple WEB page, a table filled with the information available for each client in the database. No pagination or filtering should be implemented. Basic actions should be available to the user: add, edit and delete client. The fields needed for the add and edit actions should be presented to the user on the same page, without reloading (AJAX). All actions should be available with no restrictions to all users (no authentication required). We assume that the users browser has Javascript enabled and is Ajax aware. No fallback methods are provided in case those requirements arent met. Also, no performance constraints are enforced.

3. User level use cases

The user-level class diagrams are shown in the figure below :

Show info

add client

uses

User uses update client

enter/modify data

delete client

fill database Admin

Use case narratives are provided in the following chapters. For the most important use cases an activity diagram is included.

3.1. Show info use case

This use case begins when the user access the applications main URL. The system responds by returning a HTML table with the client data and a set of action buttons (delete, edit) for each client. The use case ends when the HTML page is rendered in the users browser.

The user enter the application's main url in the browser

The system queries the database and return the client list

[Non-empty client list]

[Empty client list]

The system renders the client table on the page

"No clients in the DB" message provided

3.2. enter/modify data use case

This use case begins when another use case call it. The system renders the edit form on the right of the clients table. The edit form contains the following fields : name (text box), email (text box), birth date (calendar control), company (drop down). The user fills the name and email fields. When the user clicks on the birth date field, the system renders a calendar control over the field. The user selects a year and a month and clicks on a day. The system closes the calendar control and displays the selected date in the birth date field. The user selects a company from the company drop-down. When the user clicks on the reset button, the system empties all the fields contained by the edit form. When the user clicks on the update button, the system validates the data entered in the above mentioned fields. If all the fields are non-empty, the data is saved in the database and the edit form is hidden and the page is reloaded. If something goes wrong when the data is saved in the database, the system displays an error alert box. If at least one of the fields is empty, the system displays an error alert box. The use case ends when the new page is rendered in the users browser.

The system renders the "edit form"

The system clears the editable fields

New client or edit existing one ?

[existing client] Initialize fields with existing client data

[new client]

The user fills the "name" field

The user clicks on the "birth date" field

The user fills the "email" field

The system renders the "calendar control"

The user selects a company from the "company drop-down The user selects the year, month and day

[Yes] User clicked on "Reset" [No] [No] All fields are non-empty [Yes] Show error message

User clicked on "Update"

Save info in DB

Errors when saving in DB ?

[Yes] Show error message

[No]

Reload page

3.3. Add client use case

This use case begins when the user left-clicks on the Add client button. This use case uses enter/modify data use case to manage data entry. The use case ends when the new page is rendered in the users browser.

3.4. Update client use case

This use case begins when the user left-clicks on the Edit icon next to a clients data. This use case uses enter/modify data use case to manage data entry. The system fills the edit form fields with the edited clients data.

The use case ends when the new page is rendered in the users browser.

3.5. Delete client use case

This use case begins when the user left-clicks on the delete icon next to a clients data. The system deletes the client from the database and reloads the page. The use case ends when the new page is rendered in the users browser or when it is an error working with the database.

3.6. Fill database use case

The use case begins when the system admin want to populate the companies table. This operation is done using the MySql admin tools. The use-case ends when the admin has finished populating the companies table.

4. Implementation details
4.1. Introduction
The proposed implementation uses Java MVC three-tier architecture. This is definitely overkill for such a simple application, but this provides a higher degree of extensibility for future enhancements and a better reusability factor of the existing code base. On the other hand, the purpose of this application is to demonstrate our programming skills, so a more advanced architecture could be appropriate. We will use the following infrastructure components/frameworks: Struts - for implementing the MVC controller Hibernate for database mapping of our domain model DWR for AJAX calls to the business logic YUI for building the Javascript client part

The client part will be valid XHTML code for markup, cross-browser CSS (in a separate file) for layout and positioning and Javascript for actions and gluing together all the required functionality. The client page will render and behave correctly in IE6/7, Mozilla 2.x and Opera 9.x The edit form is implemented as a hidden div (initially) containing all the fields and buttons required.

4.2. System architecture

4.3. System level use cases

The system level use cases describe the systems behavior at a more detailed level. We provide here only the most relevant ones. All other use cases should perform in the same way with the ones listed.

4.3.1. Show info use case

This use case begins when the user access the applications main URL. The Struts Controller triggers the appropriate action class. The action uses a DAO Helper class to retrieve from the DB the current client list. The DAO Helper class performs a Hibernate query and returns a list of Client objects. Also, a bean with the list of companies is retrieved using the DAO Helper. The action packs the client list and the companies list in a bean and passes the control to the JSP page, which renders an alternate rows table in the HTML page. The JSP returns the final HTML code to the browser. The use case ends when the HTML page is rendered in the users browser.

4.3.2. enter/modify data use case

This use case begins when another use case calls it. The system sets the CSS visibility attribute of the edit form div to block. The edit form already contains the following fields: name (text box), email (text box), birth date (calendar control) and company (drop down). The user fills the name and email fields. When the user clicks on the birth date field, the system renders a YUI calendar control over that field. If the field already contains a date, the system moves the current date of the YUI calendar to that one. The user selects a year and a month and clicks on a day. The system closes the calendar control and displays the selected date in the birth date field. The user selects a company from the company drop-down. When the user clicks on the reset button, the system empties (trough a mapped Javascript events method) all the fields contained by the edit form. When the user clicks on the update button, the system validates the data entered in the above mentioned fields. If at least one of the fields is empty, the system displays an error alert box. And the processing stops, waiting for the user to correct the errors. If all the fields are non-empty, the CP calls the DWR method updateUser. This call triggers the corresponding method of the AjaxHelper Java class on server. This method uses DAOHelper to retrieve the Client object designated by the parameter id from the DB. If the id is zero, a new one is created and persisted to the DB. If the id is non-zero and no corresponding record exists in the DB an exception is thrown and an error message is returned to the CP. The system sets the properties of the retrieved Client object and persist the changes back in the DB. If any error occurs, an error message is returned to the CP. The AjaxHelper method returns to the CP a String containing OK if all operations went fine or error if something were wrong.

The CP displays an error message if appropriate or reloads the page if everything was OK on the SP. (Please note the on a production application a more sophisticated approach could be implemented: the SP method returns the new HTML code for the clients table, and the CP replaces the existing table with the received HTML) The use case ends when the new page is rendered in the users browser.

4.4. Class diagram

The class diagram shows the applications main classes. For simplicity, infrastructure classes (those provided or required by the programming framework) are not shown. The domain model is represented by the Client and Company classes. The database is accessed only trough the DAOHelper class. The client part (CP) executes operations on the server part (SP) only trough AjaxHelper class and DWR. All attributes are accessed only trough accessors (getter/setters). The accessors are not shown explicitly on the diagram.

-id : int +name : string +email : string +birth_date : Date +company : Company +accesors for all attributes()

-works for 0..* 1..1 -id : int +name : string +accesors for all attributes()

+getClientById(in id : int) : Client +getClients() : Client[] +getCompanies() : Company +deleteClient(in id : int)

+updateClient(in id : int, in name : string, in email : string, in birth_date : string, in company : int) +deleteClient(in id : int)

4.5. Database structure

The database model is very simple. Only two tables are used. The company_id field from Clients table points to a single record in the Companies table.

4.6. User interface

The UI should look like the image below. All layout and positioning tasks are performed with CSS. The whole user interaction is done in a single page.

Add client

5. Test plan
5.1. Unit tests
Unit testing will be performed using JUnit on the following classes: DAOHelper AjaxHelper

5.2. Integration tests

Due to the systems simplicity, we consider that passing the Unit and Functional test will be enough.

5.3. Functional tests

The following use cases will be tested: Show info Enter/modify data Add client Update client Delete client

The functional test should follow closely the all use case scenarios. If the client requires, a full Test scenarios document will be provided, containing test data, step-by-step testing scenarios for each use case and expected results for each test.

6. Final thoughts
Please note that SCM, as defined by this document and implemented in this stage, is a DEMO application. Its not ready to be deployed in a production environment. If one needs to do so, please consider the following aspects:

6.1. Performance aspects

SCM uses Hibernate to access the DB. Hibernate must be tuned to offer best performance in a production environment. Specifically, second level cache must be properly configured and enabled, with respect to the specific conditions (load, access patterns etc.) on the production site. Also, the connection pooling (C3P0 already configured) must be tuned to match the production requirements. If the business case allows and the application is expected to face high loads, additional front-end cache systems can be configured (with products like OSCache, far example). An almost mandatory action one should care of is minifying the application specific Javascript code (the libraries are already minified). This reduces load time, reduces bandwidth consumption and makes the code a lot less readable for pirates.

If further optimization is imposed by high traffic conditions, the Javascript libraries must be evaluated and unnecessary code striped out. Please dont forget to enable adaptive GZIP response compression on the app server. The minimum system requirements are quite low: the theoretically app runs on any modern standardcompliant Servlet container and with any database supported by Hibernate. The system was tested and is certified to run on Tomcat 5.0 with Java 1.5 and MySQL 5.0.

6.2. Security concerns

Even if the application is very simple and using Hibernate as a proxy between the app and the DB greatly reduce risks, some security aspects must be evaluated: SQL injection opportunities as text entries are allowed by the app in several text edit-boxes, a hacker can, theoretically, inject malicious SQL code trough them. The risk is minimal, as data is inserted in the DB using HQL, not directly with SQL, and all operations are intermediated by Java objects. As the app uses JSON to retrieve client data, the opportunity for a malicious user to inject bad Javascript code must be investigated. An URL-rewriting mechanism should be implemented. This hides the underlying technology and application architecture from users eyes. The communication channel between the CP and the SP must be encrypted (HTTPS). Depending on the broader application that includes our module, some authentication/authorization means can be required.

6.3. Functional enhancements

One major drawback of our current implementation is the lack of support for non-Javascript enabled browsers. Although a You are required to use Javascript-page is provided, the application cannot be used if Javascript support is disabled or not supported by the users browser. The following steps must be followed to enable those users to actually use the application: The add client link should reload the current page, adding a supplemental parameter to the URL (client=0). The underlying Struts action should instruct the rendering JSP to display the edit form div in its place, with empty fields. The edit link next to each users row in the table should also reload the current page, adding the URL parameter client=id, where id is the actual id of the user that should be edited. The Struts action will pass explicitly to the JSP the data for that client, and The JSP will display the edit form (on the left of the always present client table), with filled edit boxes. The forms ACTION attribute must point to a plain Struts action that will parse the request, extract the fields values and save the new data for the edited user. If the client id is zero (0), a new client is created and persisted in the DB. Then the main page is reloaded with the new values, as usual. Implement input validation (non-empty fields, valid email address, valid birth date) on the server side. In the current version the app performs all input validation at the client level, trough Javascript.

This approach ensures the expected graceful degradation, as Javascript-enabled browsers transparently use scripts/AJAX to perform the tasks and the other ones use plain old page reloading/forwarding mechanism to achieve the same result. Other usability enhancements could be envisaged. For example, a method to close the edit form without saving anything should be provided (now, one needs to either hit the update button or reload the page to get rid of the edit form). Also, the user input validations can be enhanced by imposing format restrictions on the clients name (for example exactly two words with more than 1 character each, space separated, only alpha characters). The current version checks only for non-empty name field. In a production environment and depending on the real usage of the client database, the email address can be checked using an opt-in approach (an email asking for approval is sent to the clients email address and the clients account is validated only when he replies to this message). In present the system checks only for well-formed email addresses. In addition, a supplemental check could be envisaged on the birth date field: the system might restrict users to enter birth dates in the future or in the way to distant past (only clients with a max age of 100, for example). Better error handling and reporting should be implemented. The error messages returned by the application are now quite generic. More useful ones could improve the UI substantially. Also the Javascript alerts can be replaced by a nicer error display (divs right in the page). Another aspect of the UI that must be taken care of is the visual feedback given to the user when AJAX transactions are in progress. Some wait we are working GIFs should appear when such actions take place.