ES Java Modules

This document outlines a proposed scheme for organizing and managing the various Java modules (i.e. jar files) that we are beginning to create. The goal is to have a clearly understood hierarchy for these modules and to set out simple rules and guidelines for the creation and the usage of these modules.

Levels

• We are proposing a layered architecture, with layers referred to as levels. Each level will be assigned a number. We expect all developers, particularly technical leads, to become conversant with the level numbers and their meaning.

Here is a prototype level diagram, illustrating our proposed approach:

Working from the bottom up:

Level 5 is the "core" CSF. This is itself a set of modules with its own internal module hierarchy, but as far as applications are concerned, it is one entity "csf". It is intended to house functionality that:

• changes very infrequently.
• is used by all, or the vast majority, of apps.

Level 4 holds services related to what might be called "reference data" or "base data". This data is generally fairly stable - it changes slowly over time - and examples are Subjects, Departments, Terms etc. This functionality:

• changes infrequently.
• is used by many, but not necessarily all, apps.

Level 3 holds services related to "reference data" or "base data", but which aggregates lower-level base data services. An example would be a student's enrolment profile, which aggregates student, course, and term information. This functionality:

• changes infrequently
• is used by many, but not necessarily all, apps.

Level 2 contains services related to business logic, and data that does change frequently. The modules are intended to be scoped around single business processes (e.g. registration, grading, student accounts). This functionality:

• changes more frequently.
• is used only by apps needing the specific business functions.

Level 1 is used for modules that need to aggregate services from multiple lower level business-logic modules. This functionality:

• changes quite frequently.
• is used typically only by  app.

The levels have these attributes:

• the higher the level, the less reusable the services provided by its modules.
• conversely, the lower the level, the more reusable its services.
• the higher the level, the more frequently the modules will change.
• conversely, the lower the level, the more stable the services provided by its modules.

Rules for Module Use

For this scheme to work, and to provide benefit, we need to impose the following rules, or guidelines, for using the modules, and for determining where new code should go:

• Downward calls only. A module can use services in another module only if the other module is in a lower level. From this rule follows:
• No upward calls.
• No sideways calls. 

If you are developing a service intended to go in a level 2 module (for example, a grading service) and you find that your new service needs to call out to a service in the registration module - also a level 2 module - you will need to move your new service to a level 1 module where it can safely aggregate lower-level services.

CSF "Common Legacy" and the Future

One large piece of code that does not currently conform to this architecture is csf-common-legacy. This currently is a level 4 module, but contains code that should really be in levels 1, 2, and 3. We will be working to move code out of common-legacy to the appropriate level as part of CSF version 3. Until then our plan is to deprecate code in CSF 2 csf-common legacy and where appropriate, design and code replacement modules in levels 1, 2, and 3. There will be a future infrastructure project that converts apps from CSF 2 to CSF 3.