Package macaw.persistenceLayer.production

This package contains all the code required to run versions of Macaw's curation and retrieval services which store data in a MySQL database.

See:
Description

Class Summary

ProductionCurationService	Implements the interface MacawCurationAPI as a curation service which stores data in a MySQL database.
ProductionRetrievalService	Implements the MacawRetrievalAPI interface as a service which retrieves all of its data from a database.
SetupCurationDatabase	A convenience class that can be used to create all the database tables used by the production services.
SQLChangeEventManager	A manager class that is called by various classes to make a record of editing changes made to instances of objects found in macaw.model.
SQLConnectionManager	A class designed specifically to manage SQL connection pooling for the ProductionCurationService and ProductionRetrievalService and
SQLCurationConceptManager
SQLFilterQueries
SQLListChoiceManager
SQLOntologyTermManager
SQLSupportingDocumentsManager
SQLUserManager
SQLUtilities
SQLValueLabelManager
SQLVariableManager

Package macaw.persistenceLayer.production Description

This package contains all the code required to run versions of Macaw's curation and retrieval services which store data in a MySQL database. The implementations of MacawCurationAPI and MacawRetrievalAPI.

Note that wherever possible, the design of this package is analagous to the design of macaw.persistenceLayer.production.

Identifying the Major Classes

Main service classes

The service classes that implement Macaw's APIs are ProductionCurationService and ProductionRetrievalService. The main role of these classes is to delegate implementations of their API methods to a set of manager classes created to support major concepts defined in package macaw.businessLayer. For example, SQLValueLabelManager handles editing operations for ValueLabel objects. All manager classes are prefixed with "SQL", end in "Manager".

The service classes generally follow a format for implementing their API methods. For an API call, it first validates the user. If no exceptions are thrown it then calls a corresponding method in one of the manager classes. ProductionCurationService will throw any exceptions its manager classes encounter. ProductionCurationService catches all the exceptions from manager classes as a measure to prevent sensitive information from being viewed by people using tools that interact with Macaw.

Manager classes

Manager classes tend to support the following operations:

• get all items
• add an item
• update an item
• delete an item
• check that an item does exist
• check that an item is not a duplicate

All of the manager classes are sub-classes of SQLCurationConceptManager, which provides convenience methods that log changes made to records.

The manager classes manage collections of objects that come from classes defined in package macaw.model. Most of the model classes (eg: Variable, SupportingDocument,ValueLabel) are responsible for these tasks:

• set and get properties
• validate an instance of the class. Validation includes type checking each field and detecting erroneous combinations of values.
• detecting differences between any two instances
• support for cloning objects

Support for Persistence

The in-memory implementations of Macaw services rely on the cloning feature found in macaw.businessLayer classes to simulate persistent storage. Each manager class adopts the following policy in its operations:

• When an item is added, the manager class assigns it an auto-generated identifier and regards it as a stored item (an original).
• When an item is retrieved, the manager clones the original and returns an object that is treated as a working copy
• During updates, the manager uses the identifier value in the working copy to find the original item. It then invokes a static method in the model classes to detect any differences between the working copy and the original. If an update is allowed to happen, then the working copy becomes the new original
• Changes between working copy and original are logged via calls to the SQLChangeEventManager.

Supporting Future Changes

This section is included for the benefit of developers who want to alter the code base.

Adding a new field XXX to model concept YYY

Change the code in model class YYY

1. Add a field XXX, getXXX(...), setXXX(...) to model class YYY.
2. Modify the methods validateFields(...) and detectFieldChanges(...). These methods will require new messages you need to define in MacawMessages.properties. Search the list of message properties by looking for "YYY.". Now add new ones. Be sure that if your messages take parameters, that you pass them values in calls to MacawMessages.getMessage(...).
3. Modify public Object clone().
4. Determine whether the field you added should affect how the item is shown in a list of items. If you feel the property needs to become part of the class's display name, modify getDisplayName().

Change code in the InMemoryYYYManager

Modify the following methods:

createTable(...)

add(...)

edit(...)

update(...)

get(...)

checkDuplicates(...)

Change code in the test cases

Add new test cases to appropriate classes in package macaw.test.curation or macaw.test.retrieval.

Change the UI forms

Please see the "Supporting Future Changes" section of package macaw.presentationLayer.