Package macaw.persistenceLayer.demo

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

See:
Description

Class Summary

DemonstrationCurationService	Implements the MacawCurationAPI interface as a service which manages all of its data in-memory instead of in a database.
DemonstrationRetrievalService	Implements the MacawRetrievalAPI interface as a service which retrieves all of its data from in-memory objects rather than from a database.
InMemoryChangeEventManager	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.
InMemoryCurationConceptManager	a base class for Manager classes that each handle curation operations for a specific domain concept such as a variable, a value label, ontology terms, supporting documents, etc.
InMemoryListChoiceManager	an In-memory class that manages instances of subclasses of MacawListChoice.
InMemoryOntologyTermFilter	holds code used to support the search feature that lets end-users select an ontology term from an existing list.
InMemoryOntologyTermManager	manages instances of OntologyTerm in memory.
InMemorySourceVariableManager	manages associations between derived variables and references to their source variables.
InMemorySupportingDocumentFilter	filter class that performs different searches to retrieve instances of SupportingDocument.
InMemorySupportingDocumentsManager	manages instances of SupportingDocument in memory rather than managing them in a database.
InMemoryUserManager	manages instances of User in-memory.
InMemoryValueLabelManager	Manages instances of ValueLabel in memory.
InMemoryVariableFilter	Contains code to support searching for variables in the Macaw forms found in the package macaw.view
InMemoryVariableManager	manages instances of Variable in memory.

Package macaw.persistenceLayer.demo Description

This package contains all the code required to run versions of Macaw's curation and retrieval services which store data in-memory. The implementations of MacawCurationAPI and MacawRetrievalAPI in the package can be run without requiring and end-user to have MySQL installed on their machines.

Identifying the Major Classes

Main service classes

The service classes that implement Macaw's APIs are DemonstrationCurationService and DemonstrationRetrievalService. 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, macaw.persistenceLayer.demo.InMemoryValueManager handles editing operations for ValueLabel objects. All manager classes are prefixed with "InMemory", 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. DemonstrationCurationService will throw any exceptions its manager classes encounter. DemonstrationCurationService 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 InMemoryCurationConceptManager, 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.businessLayer. 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 autogenerated 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 InMemoryChangeEventManager.

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

You shouldn't have to change anything in InMemoryYYYManager

Change code in the test cases

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

Change the UI forms

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