Code Road Map

by Kevin Garwood

This section is supposed to make it easy for new developers to learn how to familiarise themselves with the code base. As the figure below shows, the code is divided into a number of sub-projects, some of which depend on one another.

We recommend that you learn about the code by following these steps:

Learning about the rifServices sub-project. Specifically, focus on classes in the rifServices.businessConceptLayer. The business classes describe the kinds of concepts that are involved in the RIF's environmental health studies. The service interfaces (source files ending in "API") describe the behaviour of the middleware and indicate what a client application can get it to do.
Most of the other packages in rifServices.businessConceptLayer in some way mirror the concepts in the business concept layer. For example, the classes in the rifServices.fileFormats project use different file formats to serialise and deserialise business objects.
Learn how test cases are designed. First examine the test suites in rifServices.test.businessConceptLayer. These test cases are easy to run because they don't involve contacting the database.
Now look at test cases designed for testing service methods.
Once you learn how the rifServices sub package, then it will be easy to learn the packages rifSubmissionTool and rifDataLoaderTool. Each major tool in the tool suite will divide its code into presentation, business concept and data storage layers. Each of the tools will have a front end which uses the database via service interfaces.

Summary of subprojects

The table below describes various aspects of each sub project and serves two learning purposes here:

it describes what kind of code you should expect to find in each of the sub projects
it provides criteria that can guide you when you are wondering where you should put new classes you create

Sup-project	Description
rifGenericLibrary	languages: contains Java source files and property files domain dependencies: contains no references to RIF concepts theme: SQL query formatters, generic classes for creating Swing UI components reuse: code that can be used in multiple sub-projects reuse: code may be useful in unrelated software projects libraries: depends on no dependencies except for standard Java libraries
rifServices	language: contains Java source files and property files domain dependencies: depends heavily on RIF-specific concepts theme: defines RIF business concepts that are used to support study submission and study retrieval activities theme: contains code that supports both web service and plain Java implementations of services for study submission and study retrieval reuse: the services and business classes can be reused in other projects. reuse: not likely to contain code that can be reused on unrelated software projects.
rifDatabase	languages: contains pgsql scripts, make file scripts domain dependencies: depends heavily on RIF-specific concepts theme: relates to installing and configuration the RIF database, which may either be PostgreSQL or SQL Server. reuse: not likely to contain code that can be reused on unrelated software projects.
rifWebPlatform	languages: Contains JavaScript and HTML5 code domain dependencies: Most of it is very dependent on RIF concepts theme: Contains all the code used to support study submission and study result retrieval activities in a web browser. reuse: may likely have a lot of graphical code for charts, tables, maps and menus which can be reused in unrelated software projects. libraries: depends on Node.js
rifDataLoaderTool	languages: contains Java source files and property files domain dependencies: Most of it is very dependent on RIF concepts theme: supports activities related to populating and managing the following kinds of data: health data, geospatial data and registration data for users reuse: contains some code which may be useful for generically loading and cleaning CSV files in the database.
rifSubmissionTool	languages: contains Java source files and property files domain dependencies: Most of it is very dependent on RIF concepts theme: contains code used to support the original desktop prototype of the study submission tool future: most coding to support the client front end of the study submission tool now happens in the `rifWebPlatform` package. The code in this package is maintained to help teach other developers how to make a client that calls service API methods
rifGovernanceTool	languages: contains Java source files and property files domain dependencies: Most of it is very dependent on RIF concepts theme: contains code used to support implementing information governance decisions related to disclosing sensitive data in results future: development deferred

Cross-Project Naming Convention

Understanding the code base is made easier if you keep in mind a few naming conventions which can appear in multiple projects. The following table of conventions should help you tell what a lot of the classes do without requiring you to look at the code in them.

Naming Conventions

Convention	Meaning
Packages marked `*.presentationLayer`	Contains classes that are used to generate Swing-based front ends. The front end code is responsible for converting data between forms and business objects. It interacts with the database by using business objects with calls to service interfaces.
Packages marked `*.businessConceptLayer`	Contains definitions of business classes and service interfaces. In any subproject, you should examine this package first.
Packages marked `*.dataStorageLayer`	Contains classes that use business objects to assemble SQL queries, which are then executed in the database. Typically the results of the SQL queries are packaged into business objects.
Packages marked `*.system`	Contains classes that are used throughout a subproject. For example, `rifServices.system.RIFServiceError` is an enumeration of error causes, and is used throughout the `rifServices`subproject.
Packages marked `*.fileFormats`	Contains classes that are used to serialise or deserialise business objects using one or more file formats (eg: XML, HTML, CSV).
Source files marked `Abstract*`	Abstract classes.
Source files marked `*API`.	interfaces that define the behaviour of services which are used by front end applications. They should always appear within a `businessConceptLayer` package.
Source files marked `*Service`.	Classes that implement a service interface (`API`). They should always appear within a `businessConceptLayer` package. `TestService` classes are usually used for testing and contain methods that can help reset the service or the database to a known state. `Production*Service` classes are what users will use and will not have these kinds of methods.
Source files marked `SQL*`.	Indicates the file is involved with generating or executing SQL queries.
Source files marked `*Manager`.	Service classes (`Service`) often delegate much of the work for their methods to corresponding methods in `Manager` delegation classes. A manager class is responsible for managing queries related to one or more business classes. For example, the `rifServices.dataStorageLayer.SQLCovariateManager` is responsible for managing `ExposureCovariate` and `AdjustableCovariate` classes found in the `rifServices.businessConceptLayer` package.

Individual Subprojects

Subproject: rifGenericLibrary

This subproject is meant to hold classes which are used across multiple projects and have no reason to be dependent on RIF concepts. For example, it holds a collection of convenience classes which can create common UI features in the Swing front ends. The classes are or will be reused in the electronic forms that are part of three subprojects:

rifSubmissionTool
rifDataLoaderTool
rifITGovernanceTool

The subproject also contains a collection of query formatter classes, which help centralise repetitive tasks that are part of concatenating parts of common SQL queries. Like the UI classes, the query formatter classes do not rely on any business concepts that are specific to the RIF.

During the lifetime of the software, we expect to migrate any class to this subproject which may later be reused on unrelated software projects. Developers who modify code in this subproject will not require specialised domain knowledge in order to make improvements.

Naming Conventions

Convention	Meaning
`*QueryFormatter`	used to help construct different types of SQL queries. The formatters are designed to manage issues such as indentations, adding comments and managing case sensitivity. They may also be modified so they can render different outputs depending on whether the database being used is PostgreSQL or SQL Server.
`ButtonPanel, ComboBox, ListPanel, Panel`	classes that contain various common UI components.

Subproject: rifServices

This subproject contains all the business concepts, service interfaces and service classes that support front ends for the Study Submission Tool and the Study Result Retrieval Tool. Code for the two tools is grouped together because they share many of the same business concepts and the same features.

The general naming conventions can tell you what most of these classes do. There are a few notable classes:

rifServices.dataStorageLayer.SQLConnectionManager is used to handle connection pooling for all of the other tools.
rifServices.util.RIFLogger is used to handle all calls to log messages. It hides references to SL4J from the rest of the code base.
rifServices.system.RIFServiceStartupProperties reads a property file that helps the middleware understand database properties such as the host, the port, whether it is SQL Server or PostgreSQL and the names of directories containing resource files.
rifServices.util.FieldValidationUtility has the only code in the code base which does the work of comparing a String against malicious patterns of code (eg: SQL injection attacks).
rifServices.dataStorageLayer.HealthOutcomeManager will probably be the only manager class in a *.dataStorageLayer package that does not rely on database queries. It manages taxonomy services that are managed by independent services.

Naming Conventions for package rifServices.restulWebServices

Convention	Meaning
`*Proxy`	These are classes whose sole purpose is to make is easier for the Jackson library to serialise RIF business objects. They are data container classes marked up with Java annotatations so that Jackson's `ObjectMapper` class can serialise business objects using JSON.
`*ServiceApplication`	Advertise a particular web service. The Java annotations in these classes are used to help build the URL fragment that identifies the service. For example "/studySubmission" and "/studyResultRetrieval".
`*ServiceResource`	Advertise a set of web service methods. These classes convert URL parameters into Java objects, which are then passed to the Java service classes (`API`). The `ServiceResource` classes convert results into JSON.

Naming Conventions for package rifServices.fileFormats

Convention	Meaning
`*ContentHandler`	A class that uses different file formats to serialises and deserialises objects from a particular business class, Each content handler class can write an HTML fragment, and can read and write an XML fragment appropriate for the business class.
`Writer, Reader`	A class that will write or read a file. They delegate parts of their tasks to `*ContentHandler` classes.

Coding Conventions

Coding conventions for this layer are described here.