Package org.lsst.ccs.config

Overview

See: Description

Interface Summary

Interface	Description
ConfigurationMismatchListener	An object that is warned when two objects do not match.
Constraints.Controler	A specific code to control a value.
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
LocalConfigurationProxy.WriterProvider	when locally registering properties the LocalConfigurationProxy may need to write properties "somewher" (be it a File or in memory for tests purposes) classes that support this interface are able to create the corresponding resource.
ParameterFilter	Filters a parameter: given its name and or a value accept or reject it to be included in a list of ParameterDescription (that is a list of Parameter open for modifications).
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.
ConfigurationFacade.Profiles	this class is used by methods that modify the state of the database: the registration of a SubsystemDescription will create a new "default" ConfigProfile and if there was a previous version of the same description then all profiles pointing to this old version will be returned in the notRegistered field the "repair" method will take such a Profiles object and will try to create a result report with registered and unregistered profiles
Constraints	A set of static methods to check constraints.
DeploymentDescriptor	A deployment descriptor is a key for a set of deployed jars.
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.
FIleBasedDAO	Creates a dummy file-based Configuration database.
HqlDAO	abstract class used to help build DAO that uses HQL but are in a different package
LocalConfigurationProxy	register locally changes in parameters (that is creates a new Properties "resource" for the configuration)
MachineConfiguration	Describes a Machine Configuration
MemoryDAO	a "dummy" data access object (to be used when Description and Configuration are to be handled locally without having access to a real configuration database).
NamesAndTag	A data structure that contains name of subsystem, configuration and tag, and the full path to the configuration file
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.
PreparedConfiguration	objects of this class represent a complete set of data with modified configuration parameters that can be used to start 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.
TextAndNode	Object to store both a text source for a Subsystem description and the binary data extracted from it (type ComponentNode)
TypeInfos	a utility class to document the way org.lsst.gruth.types are shown to the end-user (specifically for the configuration properties file)
ValueEvent	Registers the date of a value change in engineering mode.

Enum Summary

Enum	Description
DataFlavour	Data type used to store Subsystem descriptions.

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.
RollBackException	Exception that happens during rollback

Package org.lsst.ccs.config 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.