Code Guide - serenapotts/lifeforachild GitHub Wiki

#Spring Roo and Aspect J

The following diagram shows how the AspectJ files relate to each other as used in the project. Starting with the Person.java class there are a number of .aj classes (Person_Roo_ToString.aj, Person_Roo_JavaBean.aj etc) that are combined by the AspectJ compiler into the final Person.class file. It is worth mentioning that every method in the .aj files starts with the java class name. i.e. the toString() method for Person.java would be public String Person.toString() { return name; }

#Model View Controller (MVC) Pattern

Spring Roo uses the MVC pattern. The Model is formed by the domain classes in org.lifeforachild.domain package, the view by the jspx files in webapp/WEB-INF and the controllers in org.lifeforachild.web. Internationalisation

Four languages are supported in the application: English, Spanish, French and Russian. Any visible text should be added via SQL to the messages table in English. It can then be edited within the application by LFAC Staff and translations added. A number of users of the application across the world have access to this to complete the translations for us.

#Database Schema

See the database schema diagram below for table relationships (download to see clearer).

Each tables’ purpose is described below.

Table	Description
child	Holds information about a individual child who visits the diabetes centre.
clinical_record	Holds information for a child about a particular visit to the diabetes centre. Each child can have many of these over their lifetime.
diabetes_centre	Represents a particular diabetes centre.
country	Represents an individual country.
user	Represents a user of the system. May be a doctor, nurse, researcher, administrator etc.
user_group	Defines the different groups users can be assigned to. Each user is in one group and each group has a different permission set.
user_group_permissions	Maps the permissions allowed by each user group.
permissions	Defines the different permissions available in the system. i.e. creating a child, editing a child, creating a country etc.
report	Defines a report which can generate a subset of information about children and their visits.
report_properties	I think this may be a legacy table that is not used.
report_childfields	Maps the child related fields that have been chosen to be displayed in each report.
report_clinicalrecordfields	Maps the clinical record related fields that have been chosen to be displayed in each report.
message	Contains each piece of text displayable in the application and the language translations in french, spanish and russian.
lms	Contains the LMS values used for BMI and SD calculations.
user_versions	Maintains each version of a user in the user table for audit-ability purposes. The user table only has the latest version.
child_versions	Maintains each version of a child in the child table for audit-ability purposes. The child table only has the latest version.
clinical_record_versions	Maintains each version of a clinical record in the clinical record table for audit-ability purposes. The clinical record table only has the latest version.

#Package Summary ##org.lifeforachild.domain

This package contains the ORM (object relational model) classes for each of the domain objects used by the application. They have hibernate annotations and usually map one to one to database tables. ##org.lifeforachild.enums

This package contains enumeration classes used mainly by the domain classes. You will see each value in the enum has a code in brackets. This is because the whole application is Internationalised. Any new values need to be translated and put in the messages database table. i.e. LESS_THAN_50_KMS("DistanceType.lessThan50") ##org.lifeforachild.security

This package contains the SimpleStringCipher class which is responsible for reading the encryption key. It will encrypt and decrypt values as needed. ##org.lifeforachild.tool.csvtosql

This package contains a developer utility that was used to convert LMS (?) values for Body Mass Index (BMI) and other Standard Deviation (SD) values provided initially to SQL to import into the database. It is not longer used. ##org.lifeforachild.util

Utility classes, some of which are developer classes and not used by the application. Classes of note include:

DatabaseMessageSource – this ties the message values into the database to a message source which can determine what value to show for each language.

SecurityUtil – This is a helper class to access the user and permission information read in by the CustomUserDetailsService when security related checks need to be made.

Other util classes are fairly self explanatory. ##org.lifeforachild.web

This package contains mainly the controllers which map to URL’s in the application.

AppContext – This class mainly contains static methods. It handles date formatting and message translation to different languages based on the locale of a user.

Each Controller file has a corresponding Roo_Controller.aj class (i.e. for ChildController.java there is a ChildController_Roo_Controller.aj class). Similar to the Person example above the aj class is combined at compile time to form a single controller class. The code is all in the Roo_Contoller.aj class with the controller class name at the start of each method. i.e. public String ChildController.create(@Valid Child child, BindingResult result, ModelMap modelMap) { … }

Controller methods have request mappings which are the url path relative to the root URL of the application. i.e @RequestMapping(value = "/child/form", method = RequestMethod.GET) is doing a HTTP GET on the URL http://localhsot:8080/lifeforachild/child/form.

Values in braces in request mappings are URL parameters i.e. for the URL http://localhost:8080/lifeforachild/child/100 the request mapping would be defined i.e. @RequestMapping(value = "/child/{id}", method = RequestMethod.GET)

URL request parameters i.e. http://localhost:8080/lifeforachild/child/list?page=3 are defined by a RequestParam i.e. @RequestParam(value = "page", required = false) Integer page

HTTP verbs are used as usual i.e. POST - create PUT - update GET - retrieve DELETE - deletion ##org.lifeforachild.web.ajax

This package contains classes that use ajax to make asynchronous calls from the application They do things like calculations for BMI and SD values based on the entered values on the screen. ##org.lifeforachild.web.query

This package contains helper classes to perform database queries using Hibernate criteria. The BaseQuery class is extended by all other classes and controls what data is returned so that only data from the diabetes centre and country the user is in can be viewed. i.e. they only see children in their centre or if they have admin privileges then only the users in their centre. ##org.lifeforachild.web.report

This package allows the generation of reports using Dynamic Jasper. ReportGenerator is the main class which does the report generation. The other classes defined the individual fields mappings to be exported in each report and extend ReportGenerator. ReportExporter generates the pdf report result. ##org.lifeforachild.report.enums

Defines enums used for reports. ##org.lifeforachild.web.service

Contains the CustomUserDetailsService class which must be implemented to use Spring Security. It loads the user information and their permissions to control what they have access to in the application. ##org.lifeforachild.web.validation

Contains validation classes for some of the domain objects, where more complicated validation needs to be done. #Resources

The following directories are used for the following: ##csv

Contains the initial LMS data that was imported into the database. This can be ignored. ##META-INF

• persistance.xml - defines the hibernate connection to the database
• spring/applicationContext-security.xml - defines security configuration for the application
• spring/applicationContext.xml - the main spring configuration file
• database.properties - defines the database connection host, username and password
• log4j.properties - defines logging properties for the application ##sql

Contains SQL database scripts to initialise the database. If database changes need to be made, a new script in sequence should be added to the updates directory. It should also be added to the initAll.sql script (though think is no longer used) and setupDB.bat. #Webapp

The web directory contains the frontend application. ##images

Images served by the application ##js

Javascript files used by the jspx pages. ##selenium

Selenium acceptance test suite. This should be run and all tests must pass to have confidence nothing has broken in the application. There can be timing issues with some of the tests that dynamically need to load data. i.e. if you select a country the diabetes centre dropdown will then load the centres for the country. Sometimes this happens slower than the field value been set and can report a false error. ##styles

CSS used by the application. This should not need to be altered generally. ##WEB-INF

• classes - css class definitions
• config - web mvc config. Should not need to be altered.
• i18n - legacy message properties. These are all in the database and should be deleted.
• layouts - Common HTML layouts used by all the jspx pages
• spring - more web mvc config. Should not need to be altered.
• tags - Define JSP tags. These were autogenerated by Roo and should not need to be altered.
• views - Contains jspx pages, which is the bulk of the web pages that are displayed to the user. You will see the controllers return a string i.e. ChildController returns return “child/create”. This maps to the child/create.jspx page in this directory.
• web.xml - main web application definition file

#Other Files

pom.xml – contains all the maven library dependencies used by the project.

/<user.dir>/lifeforachild/settings.txt – This is the encryption key used for private Child data encrypted in the database. For development this file should just contain a 16 character random string. Make sure there are no spaces at the end of the string. #Tests

src.test.java.org.lifeforachild.domain – These are intergration tests for the domain classes. They have not been run in a long time and may fail.

Selenium Tests – this has the best coverage of functionality in the system, and all must pass before you commit code. #Installer

Due to the fact some counties in the third world may not have a good internet connection, a standalone installer was built using <>. It can only be compiled on windows as far as I am aware. And is made to run on Windows XP and Windows 7. #Logging

System.out.println should NOT be used. Use the logger and pass the class name in. i.e. private static final Log LOG = LogFactory.getLog(ChildController.class);