org.lsst.ccs.config

Class ConfigurationFacade

java.lang.Object

org.lsst.ccs.config.ConfigurationFacade

public class ConfigurationFacade
extends Object

implements complex strategies on top of the DBInterface. Dues to cache problems there should be only one instance of this class operating on the network. services are to be addressed remotely if needed.

Author:

bamade

Nested Class Summary

Nested Classes

Modifier and Type

Class and Description

static class

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

Constructor Summary

Constructors

Constructor and Description
ConfigurationFacade(DBInterface dao) creates a facade object on top of a Data Access Object that implements the base services.

Method Summary

Modifier and Type	Method and Description
ConfigProfile	deprecateConfigProfile(String subsystemName, String name, String tag) Deprecates a ConfigProfile.
SubsystemDescription	deprecateSubsystemDescription(String subsystemName, String tag, ConfigurationFacade.Profiles results) Deprecates a Subsystem description already in the database.
void	endRun(String subsystemName, String configName, String tag, long endTime) marks the end of a run.
ParameterConfiguration	engineerParmConfig(ParameterConfiguration parameterConfiguration) registration of a modified parameter during an engineering session in the database
ConfigProfile	getActiveConfigProfile(String subsystemName, String name, String tag) returns an active ConfigProfile with name and tag
SubsystemDescription	getActiveSubsystemDescription(String name, String tag) returns the active subsystem description with name and tag.
String	getActiveValueAt(String subsystemName, String parameterPath, long date) returns the value of a parameter for a subsystem at a given date.
ConfigProfile	getConfigRunningAt(String subsystemName, long date) returns the ConfigProfile active when a subsystem was running at that date.
ConfigProfile	getConfigValidAt(String subsystemName, String configName, String configTag, long date) tries to get a ConfigProfile which was valid at a given date.
ConfigProfile	getNext(ConfigProfile current) gets the next modified ConfigProfile with same name and tag
ConfigProfile	getPrevious(ConfigProfile current) gets a previous ConfigProfile with the same name and tag.
SubsystemDescription	getPrevious(SubsystemDescription current) returns the previous description with same name and tag.
String	getValueValidAt(String subsystemName, String profileName, String profileTag, String parameterPath, long date) returns the value of a parameter at a given time for a given Profile.
ParameterConfiguration	modifyParmDuringEngineering(ConfigProfile profile, String path, long timeStamp, String value) changes a parameter value during engineering session
ConfigProfile	registerConfigProfile(ConfigProfile newProfile) registers a ConfigProfile in the database.
void	registerRun(String subsystemName, String configName, String tag, long startTime) the run and end registrations are based on messages received from a subsystem.
SubsystemDescription	registerSubsystemDescription(SubsystemDescription newDescription, ConfigurationFacade.Profiles results) registers a new (and complete) SubsystemDescription to the persistence Layer.
ConfigurationFacade.Profiles	repair(SubsystemDescription description, ConfigurationFacade.Profiles requestedProfiles) tries to repair automatically a set of ConfigProfiles that have been deprecated as the result of a Description change.
void	setDeprecationListener(DeprecationListener deprecationListener)
List<?>	simpleHQLRequest(String hqlString) forwards an HQLrequest to the DAO.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ConfigurationFacade

public ConfigurationFacade(DBInterface dao)

creates a facade object on top of a Data Access Object that implements the base services.

Parameters:

dao -

Method Detail

setDeprecationListener

public void setDeprecationListener(DeprecationListener deprecationListener)

registerSubsystemDescription

public SubsystemDescription registerSubsystemDescription(SubsystemDescription newDescription,
                                                         ConfigurationFacade.Profiles results)
                                                  throws PersistenceLayerException

registers a new (and complete) SubsystemDescription to the persistence Layer. if a previous SubsystemDescription with same subsystemName AND tag is present then it is pushed in history and replaced by the new one as a subsystem which is "alive".

To avoid side effects always write code like this:

 description = facade.registerSubsystemDescription(description);
 

if trying to save a Subsystem description already under DB management this method does nothing.

Parameters:

newDescription - a new SubsystemDescription with all ParameterDescriptions (this object is managed and modified by the persistence layer)

results - (side effect) a Profiles object to be populated by the invocation

Returns:

an unmodifiable version of the subsystem description

Throws:

PersistenceLayerException

IllegalArgumentException - if argument not a "new" description (generated by the factories)

deprecateSubsystemDescription

public SubsystemDescription deprecateSubsystemDescription(String subsystemName,
                                                          String tag,
                                                          ConfigurationFacade.Profiles results)
                                                   throws PersistenceLayerException

Deprecates a Subsystem description already in the database. If it's not there nothing happens!

Parameters:

subsystemName -

tag - use "" if there is no tag

Returns:

the deprecated description (or null if none was deprecated)

Throws:

PersistenceLayerException

getActiveSubsystemDescription

public SubsystemDescription getActiveSubsystemDescription(String name,
                                                          String tag)
                                                   throws PersistenceLayerException

returns the active subsystem description with name and tag.

Parameters:

name -

tag -

Returns:

null if none is found

Throws:

PersistenceLayerException

registerConfigProfile

public ConfigProfile registerConfigProfile(ConfigProfile newProfile)
                                    throws PersistenceLayerException

registers a ConfigProfile in the database. if one with the same name and tag exists it is pushed in history and a DeprecationListener is warned.

Beware of side effect: better assign the returned object to the reference holding the argument.

if trying to save a Config Profile already under DB management this method does nothing.

Parameters:

newProfile -

Returns:

unmodifiable copy of argument

Throws:

PersistenceLayerException

deprecateConfigProfile

public ConfigProfile deprecateConfigProfile(String subsystemName,
                                            String name,
                                            String tag)
                                     throws PersistenceLayerException

Deprecates a ConfigProfile. If not in database does nothing.

Important note: deprecating a configProfile to provide later a replacement will break the link between ConfigProfile (previousConfigID) so it is preferable to create directly a new replacement that will deprecate the previous one and update the link.

Parameters:

name -

tag -

Returns:

the deprecated ConfigProfile (or null if there was none)

Throws:

PersistenceLayerException

getActiveConfigProfile

public ConfigProfile getActiveConfigProfile(String subsystemName,
                                            String name,
                                            String tag)
                                     throws PersistenceLayerException

returns an active ConfigProfile with name and tag

Parameters:

name -

tag -

Returns:

null if none found

Throws:

PersistenceLayerException

modifyParmDuringEngineering

public ParameterConfiguration modifyParmDuringEngineering(ConfigProfile profile,
                                                          String path,
                                                          long timeStamp,
                                                          String value)
                                                   throws PersistenceLayerException

changes a parameter value during engineering session

Parameters:

profile - the configuration profile the parameter belongs to

path - the path of the parameter on which to perform the change

timeStamp - the timestamp of the change

value - the new value to affect to the parameter

Returns:

the modified ParameterConfiguration

Throws:

PersistenceLayerException

engineerParmConfig

public ParameterConfiguration engineerParmConfig(ParameterConfiguration parameterConfiguration)
                                          throws PersistenceLayerException

registration of a modified parameter during an engineering session in the database

Parameters:

parameterConfiguration -

Returns:

the modified ParameterConfiguration

Throws:

PersistenceLayerException

IllegalArgumentException - if the parameterConfiguration is not a regsitered active parameter of if the configuration is not in engineering mode

registerRun

public void registerRun(String subsystemName,
                        String configName,
                        String tag,
                        long startTime)
                 throws PersistenceLayerException

the run and end registrations are based on messages received from a subsystem. As much as possible the code tries to deal with lost messages (there is only one subsystem with a given name running at any time):

• if an end message is lost: next time a subsystem with same name is started the previous run is searched, if this previous run has no end date it is "guessed" that is an arbitrary date is set just before the current run.
• if a start message is lost (much more unlikely) an artificial start date is created jsut after the latest run with no "next data"
• if both message are lost there is nothing we can do to guess the startDate of a subsystem with differnet configuration

Parameters:

subsystemName -

configName -

tag -

startTime -

Throws:

PersistenceLayerException

endRun

public void endRun(String subsystemName,
                   String configName,
                   String tag,
                   long endTime)
            throws PersistenceLayerException

marks the end of a run. See the documentation of registerRun

Parameters:

subsystemName -

configName -

tag -

endTime -

Throws:

PersistenceLayerException

getConfigRunningAt

public ConfigProfile getConfigRunningAt(String subsystemName,
                                        long date)
                                 throws PersistenceLayerException

returns the ConfigProfile active when a subsystem was running at that date.
PROBLEM: a subsystem may be running without a configProfile. so beware

Parameters:

subsystemName -

date -

Returns:

the ConfigProfile running at the specified date

Throws:

PersistenceLayerException

getConfigValidAt

public ConfigProfile getConfigValidAt(String subsystemName,
                                      String configName,
                                      String configTag,
                                      long date)
                               throws PersistenceLayerException

tries to get a ConfigProfile which was valid at a given date. Since there is only one Config profile active with a given name at a given date there is only one parameter needed (there is no need for a subsystem name)

Parameters:

configName -

configTag -

Returns:

a ConfigProfile that was valid at the given date

Throws:

PersistenceLayerException

getActiveValueAt

public String getActiveValueAt(String subsystemName,
                               String parameterPath,
                               long date)
                        throws PersistenceLayerException

returns the value of a parameter for a subsystem at a given date.

BUG: this method is not correct when a "default" subsystem is run without a configuration. Will be changed!

Parameters:

subsystemName -

parameterPath -

date -

Returns:

a string representation of the active value for the specified parameter at the given date.

Throws:

PersistenceLayerException

getValueValidAt

public String getValueValidAt(String subsystemName,
                              String profileName,
                              String profileTag,
                              String parameterPath,
                              long date)
                       throws PersistenceLayerException

returns the value of a parameter at a given time for a given Profile.

Parameters:

profileName -

profileTag -

parameterPath - a String in Path syntax ("componentName//parameterName")

date -

Returns:

null if profile or parameter not found

Throws:

PersistenceLayerException

getPrevious

public ConfigProfile getPrevious(ConfigProfile current)
                          throws PersistenceLayerException

gets a previous ConfigProfile with the same name and tag.

Parameters:

current -

Returns:

null if there is none (or if the deprecation was not carried out through a replacement or repair)

Throws:

PersistenceLayerException

getNext

public ConfigProfile getNext(ConfigProfile current)
                      throws PersistenceLayerException

gets the next modified ConfigProfile with same name and tag

Parameters:

current -

Returns:

null if none or deprecation was not carried out through a replacement or repair

Throws:

PersistenceLayerException

getPrevious

public SubsystemDescription getPrevious(SubsystemDescription current)
                                 throws PersistenceLayerException

returns the previous description with same name and tag.

Parameters:

current -

Returns:

previous description or null if there was none (or if the previous one was not deprecated through a replacement)

Throws:

PersistenceLayerException

repair

public ConfigurationFacade.Profiles repair(SubsystemDescription description,
                                           ConfigurationFacade.Profiles requestedProfiles)

tries to repair automatically a set of ConfigProfiles that have been deprecated as the result of a Description change. If everything in a deprecated is compatible with the new Description it will be changed and registered, otherwise it will be put in the "unRegistered" list of the result.
A ConfigProfile is compatible if:

• All Modified parameters are known to the Description and if their value is correct with the description type and constraints.

if its path is unknown or if the value is incompatible the "repair" is rejected.

Parameters:

description -

requestedProfiles -

Returns:

another Profile object that knows about which ConfigProfiles wee registered and which were not there may be cases where the ConfigProfile is compatible but has not been registered due to databse problems see the "registrationExceptions" in the resulting Profile object.

simpleHQLRequest

public List<?> simpleHQLRequest(String hqlString)
                         throws PersistenceLayerException

forwards an HQLrequest to the DAO. Though this is not yet tested only "from" (SELECT) request should be accepted

Parameters:

hqlString -

Returns:

the HQL request

Throws:

PersistenceLayerException