Interface Summary
Interface	Description
ConfigurationMismatchListener	An object that is warned when two objects do not match.
DBInterface	defines the basic methods implemented by a Data Access Object.
DeprecationListener	Call back methods called when a deprecation happens.
DescriptionMismatchListener	An object which is warned when trying to copy a ParameterDescription to a new SubsystemDescription that does not have a proper `ParameterBase` to match.
HqlDAO.AbstractQuery	delegate to Hibernate Query type
HqlDAO.AbstractSession	delegate to Hibernate Session type
PathObject	Two objects with the same ParameterPath are unique in their category.

Class Summary
Class	Description
AParameterDescription	Represents an actual parameterDescription.
ASubsystemDescription	An active subsystem Description.
ConfigProfile	This class represents a set of parameter that have been modified for a given subsystem.
ConfigurationFacade	implements complex strategies on top of the DBInterface.
Factories	A set of static methods to be used on Configuration service client's side : they are hiding some implementation details to the "outside" world.
HqlDAO	abstract class used to help build DAO that uses HQL but are in a different package
PackCst	Constants for this package.
ParameterBase	this is an explicit duplication of description of parameter as it is in the subsystem configuration.
ParameterConfiguration	abstract class for all parameter configurations
ParameterDescription	The base class for all Parameter descriptions
ParameterPath	Unique Path in a SubSystem.
RunHistory	Entries int his table are generated by reading the status bus where subsystem advertise their startup.
SubsystemDescription	Description for a subsystem as saved in database.

Exception Summary
Exception	Description
ImmutableStateException	Runtime exception to notify that an object is in an immutable state.
PersistenceLayerException	forwards an exception fired by the persistence layer.

Package org.lsst.ccs.localdb.configdb.model Description

Overview

The org.lsst.ccs.config package deals with configuration data. Data used to fire subsystems and modules may be modified for testing purposes or to run the code in specific conditions.

This data is registered to a database so it can be queried to run a worker subsystem and to know about any parameter value which was used at a given moment in time.

This means that the database registers configuration data and worker subsystem executions (An agent on the buses listens to subsystem start and end operations and must know which configuration set was used).

Data describing a subsystem and its configuration is split in two parts:

Description data: created and edited by subsystem designers. The initial descriptions of components and the properties of their parameters is in a resource file. The internal java structure used to describe and start a subsystem is an instance of DescriptiveNode (a "tree" structure). These can be generated from a Groovy DSL (Domain Specific Language) or from plain Java code. Thus the resource file can be a Serialized java object or a Groovy text that is dynamically compiled at runtime.
This java Object can be used to extract information to create SubsystemDescription objects that will be stored in the database. Parameter data is stored in a Set of ParameterDescription objects referenced by the overall description object.
Parameter descriptions can be directly extracted from detailed information contained in the DescriptiveNode object but it can also be edited and modified through a GUI before a description is saved through the Configuration Service.
Configuration data: created and edited by engineers. This data modifies a standard description that has been previously stored by the Configuration Service. The "edition" of this configuration data can be through text ( a simple ".properties" file) or through a GUI.
A configuration object is an instance of ConfigProfile and contains a set of ParameterConfiguration. Each ParameterConfiguration object references the corresponding ParameterDescription So modifications to parameter values can be checked as soon as possible by matching the value to the description constraints.

Other Objects are stored in the database :

PreparedConfiguration that contains a "ready to use" component node that results from the merging of default description data with data modified by a configuration (todo: reassess the need or use of this data)
MachineConfiguration that describes the configuration to be run by a specific machine (known by its MacAddress).
RunHistory which tells which subsystem with which configuration was running at any moment in time

Since historical data is important to know what happened the deprecated descriptions and configurations are kept in the database. Each deprecated Data is described by a different class with slightly different properties.
Important note: objects that are "alive" and objects that are "in history" should be recorded in different database tables. This pattern is important for databse management. There are right now two exceptions (that may need to modify the code)

RunHistory : (may be we should create a table of active runs,)
MachineConfiguration : (should we historicise these?)

So , due to this dual vision ("alive" and "in history"), each description or configuration is known by client codes through abstract classes and there are different actual (package friendly) subclasses to describe objects that are "alive" and object that are deprecated.
Thus :

SubsystemDescription is subclassed by ASubsystemDescription for "active" objects and by GhostSubsystemDescription objects.
The Ghost objects are peculiar: they are created in parallel with the active object they represent but they are ready to handle deprecation. Suppose you have a Configuration X that references Description Y, and now Configuration X is deprecated before Y. then the deprecated X references the ghost object. When Y is deprecated then only the "end date" of the ghost object is modified.
ParameterDescription is subclassed by AParameterDescription and GhostParameterDescription
ConfigProfile is subclassed by AConfigProfile and PastConfigProfile (these are not "ghost" objects: they are created only when the object is deprecated)
ParameterConfiguration is subclassed by AParameterConfiguration and PastParameterConfiguration

The reason for the presence of "ghost" objects if this:

when you deprecate a SubsystemDescription then you will deprecate all ConfigProfile that reference it. But if deprecated ConfigProfiles referenced an active Description the result will be wrong. So deprecated ConfigProfiles should point to a ghost instead of an active description.

All these objects are immutable once registered in the database (except date for ghost objects, and list of values in ParameterConfiguration objects handled during engineering mode) The handling of complex strategies on top of the database is made through a ConfigurationFacade Object. But this is still a rather low level methods collection.
So client codes are encouraged to use higher level codes that deal only with abstract classes:

the Factories class provides static factory methods to create/copy objects (todo: make this class package protected and accessed only through ConfigurationFacade)
the remote.ConfigurationService interface and its implementations give access to a simpler "Configuration service"

A Collection of codes that can be used to start a subsystem can be found in the org.lsst.ccs.startup package: some use purely local data, some use a remote configuration service.

Implementation of Configuration server can be found in org.lsst.ccs.config.remote package.