org.lsst.ccs

Class ConfigurationService

java.lang.Object

org.lsst.ccs.ConfigurationService

All Implemented Interfaces:

AlertHandler, ClearAlertHandler, AgentPresenceListener, ServiceLifecycle, AgentService

public final class ConfigurationService
extends Object
implements ServiceLifecycle, ClearAlertHandler, AgentPresenceListener, AgentService

Provides the Configuration API to the subsystem it stands for. It is created and registered to the subsystem dictionary if fields annotated with ConfigurationParameter are found within the subsystem or its components. It is responsible for modifying configuration parameters of the subsystems and for interacting with the configuration service.

The configuration API covers the following actions :

• Run-time change of parameters (individual change or several as a bulk)
• Fetching tagged configurations from the configuration service and apply them on the subsystem.
• Saving the current state of configuration parameters to the configuration service.
• Getting access to the current configuration state of the subsystem.

The bulk change process

It consists in traveling the tree of component twice, first for validating the submitted changes and then for setting them. The bulk change process for a component can be customized by implementing ConfigurationBulkChangeHandler.

Validation step

Each component validates its submitted changes.
Each of the submitted values are tested against the range and isFinal elements of their corresponding ConfigurationParameter annotation. If the component implements ConfigurationBulkChangeHandler, its validation method is invoked. If the validation step fails, BulkValidationException is thrown, submitted changes are not dropped and the bulk change process is interrupted If out of the validation step, some parameters have been detected to have changed, a BulkSettingException is thrown, submitted changes are dropped and an alarm is raised, indicating an operator error.

Setting step

If the validation step succeeds, the submitted changes are then set.
If the component implements ConfigurationBulkChangeHandler, its setting method is invoked. Remaining parameters to be set are set through their corresponding ConfigurationParameterChanger annotated method if present, or directly set by reflection. If the validation step fails, the submitted changes are dropped, an alarm indicating an operator error is raised and a BulkSettingException is thrown. If at the end of the process, the values of the parameters don't match the one expected by the submitted changes, the submitted changes are dropped, an alarm indicating an operator error (id CCSCFGOP) is raised and a BulkSettingException is thrown.

Each of the methods of this object that involve changing parameters are internally following the bulk change process, and are therefore likely to throw one of the exceptions mentioned above, or to raise one of the alarms mentioned above.

Configuration state diagram

In general, configuration actions are accepted only when the subsystem has connected on the buses. See the methods documentation for other state constraints specific to each method. The configuration API implements the configuration state diagram :

• At subsystem startup, the state is INITIAL_SAFE and only a full configuration load can be performed.
• If the first configuration load is successful, the state is CONFIGURED
• Changing one or more parameters makes the subsystem go into DIRTY state
• Saving the changes makes the subsystem go into CONFIGURED

The commands that cause changes of parameters are only available when in engineering mode. The subsystem can switch from engineering mode to normal mode only if the state is CONFIGURED.

Interaction with the configuration service

The methods of this object that interact with the configuration service are likely to throw ConfigurationServiceException if the configuration service is unavailable. In that case an alarm with id CCSCFGSRV will also be raised.

Configuration information publication

Each of the methods of the configuration API are followed by a ConfigurationInfo publication representing the resulting configuration state

Author:

LSST CCS Team

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	ConfigurationService.ConfigurationLock Gets a handle on the configuration lock when an object of this class is instantiated.

Nested classes/interfaces inherited from interface org.lsst.ccs.framework.ClearAlertHandler

ClearAlertHandler.ClearAlertCode

Constructor Summary

Constructors

Constructor and Description
ConfigurationService()

Method Summary

Modifier and Type	Method and Description
ConfigurationService.ConfigurationLock	acquireConfigurationLock() Acquires the configuration lock.
ClearAlertHandler.ClearAlertCode	canClearAlert(Alert alert) Callback to clear an Alert instance.
void	change(String componentName, String parameterName, Object value) Single change of parameter.
void	commitBulkChange() Initiates the bulk change process of the submitted changes.
void	connecting(AgentInfo ai) Indicates that the agent represented by agent is present on the buses.
void	disconnecting(AgentInfo agent) Indicates that the agent represented by agent has left the buses.
void	dropAllChanges() Sets back all parameters to the value defined by the current configuration they are running.
void	dropAllSubmittedChanges() Drops the submitted changes for all components of the subsystem.
void	dropChangesForCategories(String... categories) Sets all parameters that belong to one of the specified categories to the value defined by the current running configuration for this category.
void	dropSubmittedChangesForComponent(String name) Drops the submitted changes for a given component of the subsystem.
Set<String>	findAvailableConfigurationsForCategory(String category) Returns the available configuration names for the given category.
String	getAgentServiceName() Get the name of this service.
List<String>	getAllConfigurableComponents()
Map<String,Map<String,String>>	getAllSubmittedChanges() Returns the current submitted changes for each component.
Set<String>	getCategories() Returns the set of categories the subsystem's configurable parameters are split into.
ComponentConfigurationEnvironment	getComponentConfigurationEnvironment(String name) Gets a configuration service dedicated to a specific component
ConfigurationInfo	getConfigurationInfo() Gets the current configurationInfo object depicting the state of the configuration parameters of this subsystem.
String	getConfigurationParameterValue(String componentName, String parameterName)
Map<String,String>	getCurrentValuesForComponent(String componentName, Set<String> categorySet) Returns the current values of the configuration parameters that belong to componentName and that belong to the specified categories.
Map<String,String>	getSubmittedChangesForComponent(String name) Gets the submitted changes for the specified component
String	getTag()
boolean	isParameterConfigurable(String componentName, String parameterName) Indicates whether their is a configuration parameter named parameterName that belong to the component componentName.
void	loadCategories(String... taggedCategories) Loads a configuration for the specified categories.
void	loadConfiguration(String... taggedCategories) Full configuration load.
void	loadGlobalConfiguration(String globalName, int version) Full configuration load, based on a named combination of named configurations for each existing category.
String	locateConfigurations()
void	preBuild()
void	preInit()
void	preStart() Called from the enclosing Subsystem when org.lsst.ccs.Subsystem#start() has been called.
String	printConfigurationParameters()
void	publishConfigurationInfo() Publishes the current configurationInfo object on the status bus. If configuration parameters are modified outside of one of the provided configuration API command, they will no be reflected by the published ConfigurationInfo object.
void	saveAllChanges() Saves the current value of each parameter in the current running configuration.
void	saveAllChanges(String configName)
void	saveChangesForCategories(String... categories) Saves the current value of each parameter that belongs to one of the specified categories in the current running configuration for this category.
void	saveChangesForCategoriesAs(String... taggedCategories) Saves the current value of each parameter that belongs to one of the specified categories in a new configuration for this category.
void	submitChange(String componentName, String parameterName, Object value) Submits a configuration parameter change.
void	submitChanges(String componentName, Map<String,Object> changes) Submits several parameter changes.
ConfigurationService.ConfigurationLock	tryAcquireConfigurationLock(long time, TimeUnit unit) Acquires the configuration lock if it is free within the given waiting time and the current thread has not been Thread.interrupt.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.lsst.ccs.ServiceLifecycle

preShutdown

Methods inherited from interface org.lsst.ccs.messaging.AgentPresenceListener

connecting

Methods inherited from interface org.lsst.ccs.services.AgentService

startForAgent

Constructor Detail

ConfigurationService

public ConfigurationService()

Method Detail

getAgentServiceName

public String getAgentServiceName()

Description copied from interface: AgentService

Get the name of this service. This name will be used to add the given service to the lookup tree.

Specified by:

getAgentServiceName in interface AgentService

Returns:

the AgentService name.

preBuild

public void preBuild()

Specified by:

preBuild in interface ServiceLifecycle

canClearAlert

public ClearAlertHandler.ClearAlertCode canClearAlert(Alert alert)

Description copied from interface: ClearAlertHandler

Callback to clear an Alert instance. Return true/false if the Alert can be cleared. When true is returned the Alert is cleared and no more handlers will be checked. When false is returned other handlers will be handed the Alert instance to be cleared. If no handler returns true, the Alert will not be cleared.

Specified by:

canClearAlert in interface ClearAlertHandler

Parameters:

alert - The Alert instance to clear.

Returns:

A ClearAlertCode to indicate which action is to be taken by the framework.

preInit

public void preInit()

Specified by:

preInit in interface ServiceLifecycle

preStart

public void preStart()

Description copied from interface: ServiceLifecycle

Called from the enclosing Subsystem when org.lsst.ccs.Subsystem#start() has been called.

The preceding lifecycle step is HasLifecycle.postInit()

The following lifecycle step is HasLifecycle.start() At the time it is called :

• the PhaseState is INITIALIZING
• connection with the messaging layer is effective, the enclosing subsystem has started StatusHeartBeat publication

Specified by:

preStart in interface ServiceLifecycle

getConfigurationParameterValue

@Command
public String getConfigurationParameterValue(@Argument(allowedValueProvider="getAllConfigurableComponents")
                                                      String componentName,
                                                      String parameterName)

printConfigurationParameters

@Command
public String printConfigurationParameters()

saveAllChanges

@Command(description="Saves all changes in the current configurations",
         type=CONFIGURATION)
public void saveAllChanges()

Saves the current value of each parameter in the current running configuration.
If it succeeds, the state will be CONFIGURED.

Throws:

ConfigurationServiceException - if the configuration service is unavailable. The configuration state does not change and the run-time changes are still considered unsaved. In addition, an alert is raised to indicate the configuration service unavailability.

IllegalStateException - if the subsystem is not in engineering mode or if the subsystem is is INITIAL_SAFE configuration state.

saveAllChanges

@Command(description="Saves all changes in the current configurations",
         type=CONFIGURATION)
public void saveAllChanges(String configName)

saveChangesForCategories

@Command(description="Saves the specified categories with a name",
         type=CONFIGURATION)
public void saveChangesForCategories(@Argument(name="taggedCategories",description="A list of categories")
                                                                                                                                     String... categories)

Saves the current value of each parameter that belongs to one of the specified categories in the current running configuration for this category.
If there were run-time changes in other categories, the state is DIRTY, otherwise CONFIGURED.

Parameters:

categories - a list of categories to save

Throws:

ConfigurationServiceException - if the configuration service is unavailable. The configuration state does not change and existing run-time changes are still considered unsaved. In addition, an alert is raised to indicate the configuration service unavailability.

IllegalStateException - if the subsystem is not in engineering mode or if the subsystem is is INITIAL_SAFE configuration state.

saveChangesForCategoriesAs

@Command(description="Saves the specified categories with a name",
         type=CONFIGURATION)
public void saveChangesForCategoriesAs(@Argument(name="taggedCategories",description="A list of pairs categoryName:configurationName")
                                                                                                                                       String... taggedCategories)

Saves the current value of each parameter that belongs to one of the specified categories in a new configuration for this category.
If there were run-time changes in other categories, the state is DIRTY, otherwise CONFIGURED.

Parameters:

taggedCategories - a list of pairs categoryName:configurationName. {

Throws:

ConfigurationServiceException - if the configuration service is not available.

IllegalStateException - if the subsystem is not in engineering mode or if the subsystem is is INITIAL_SAFE configuration state.

dropAllChanges

@Command(description="drop all unsaved changes",
         type=CONFIGURATION)
public void dropAllChanges()

Sets back all parameters to the value defined by the current configuration they are running.
First, all existing submitted changes are dropped.

Throws:

ConfigurationServiceException - if the configuration service is unavailable.

BulkValidationException - if setting the parameters back to their configured value fails at the validation step.

BulkSettingException - if setting the parameters back to their configured value fails at the setting step. An alert is raised.

IllegalStateException - if the subsystem is not in engineering mode or if the subsystem is is INITIAL_SAFE configuration state.

dropChangesForCategories

@Command(description="drop unsaved changes for the specified categories",
         type=CONFIGURATION)
public void dropChangesForCategories(@Argument(name="categories",description="A list of categories")
                                                                                                                                            String... categories)

Sets all parameters that belong to one of the specified categories to the value defined by the current running configuration for this category. Other categories are left untouched.
First, all existing submitted changes are dropped.

Parameters:

categories - A list of categories

Throws:

ConfigurationServiceException - if the configuration service is unavailable.

BulkValidationException - if setting the parameters back to their configured value fails at the validation step.

BulkSettingException - if setting the parameters back to their configured value fails at the setting step. An alert is raised.

IllegalStateException - if the subsystem is not in engineering mode or if the subsystem is is INITIAL_SAFE configuration state.

loadConfiguration

@Command(description="loads a new configuration",
         type=CONFIGURATION)
public void loadConfiguration(@Argument(name="taggedCategories",description="a list of pairs categoryName:configurationName(version)")
                                                                                                             String... taggedCategories)

Full configuration load.
First, all existing submitted changes are dropped. For each specified pair "cat:tag(v)" the parameters that belong to "cat" will be set to the value defined by the configuration named "tag". The parameters that belong to unspecified categories will be set to the value defined by their default configuration. If the fetched configurations are incomplete, missing parameters are set to their initial value.

Parameters:

taggedCategories - a list of pairs categoryName:configurationName(version)

Throws:

ConfigurationServiceException - if the configuration service is unavailable.

BulkValidationException - if loading the configuration fails at the validation step. The configuration state remains unchanged.

BulkSettingException - if loading the configuration fails at the setting step. An alert is raised.

IllegalStateException - if the subsystem is not connected on the buses.

loadGlobalConfiguration

@Command(description="loads all categories for a given configuration",
         type=CONFIGURATION)
public void loadGlobalConfiguration(@Argument(description="a name that defines a combination of tagegd categories")
                                                                                                                                        String globalName,
                                                                                                                                        int version)

Full configuration load, based on a named combination of named configurations for each existing category.

Parameters:

globalName - a name that defines a combination of tagged categories.

version - a version number. if negative, the latest version for the given tag is retrieved.

Throws:

IllegalArgumentException - if the named configuration does not define a configuration to load for all categories.

loadCategories

@Command(description="loads the configuration for the specified categories",
         type=CONFIGURATION)
public void loadCategories(@Argument(name="taggedCategories",description="a list of pairs categoryName:configurationName(version)")
                                                                                                                                     String... taggedCategories)

Loads a configuration for the specified categories.
First, all existing submitted changes are dropped. For each specified pair "cat:tag" the parameters that belong to "cat" will be set to the value defined by the configuration named "tag". The parameters that belong to unspecified categories are left untouched. If the fetched configurations are incomplete, missing parameters are set to their initial value.

Parameters:

taggedCategories - a list of pairs categoryName:configurationName(version)

Throws:

ConfigurationServiceException - if the configuration service is unavailable.

BulkValidationException - if loading the configurations fails at the validation step. The configuration state remains unchanged.

BulkSettingException - if loading the configuration fails at the setting step. An alert is raised.

IllegalStateException - if the subsystem is not in engineering mode or if the subsystem is is INITIAL_SAFE configuration state.

getConfigurationInfo

@Command(description="return a ConfigurationInfo object",
         type=QUERY)
public ConfigurationInfo getConfigurationInfo()

Gets the current configurationInfo object depicting the state of the configuration parameters of this subsystem.
If configuration parameters are modified outside of one of the provided configuration API command, they will no be reflected by the returned ConfigurationInfo object.

Returns:

a ConfigurationInfo object depicting the current configuration state.

publishConfigurationInfo

@Command(description="publish a ConfigurationInfo object",
         type=QUERY)
public void publishConfigurationInfo()

Publishes the current configurationInfo object on the status bus.
If configuration parameters are modified outside of one of the provided configuration API command, they will no be reflected by the published ConfigurationInfo object.

change

@Command(description="Submits a single change to be processed immediately",
         type=CONFIGURATION)
public void change(@Argument(allowedValueProvider="getAllConfigurableComponents")
                                                                                                                            String componentName,
                                                                                                                            String parameterName,
                                                                                                                            Object value)

Single change of parameter.
The value is validated and the parameter is immediately set to this value, without interfering with the current set of submitted changes. If the change is effective, the configuration state goes to DIRTY.

Parameters:

componentName - the name of the component the parameter belongs to.

parameterName - the name of the parameter.

value - the new value to affect to this parameter

Throws:

ConfigurationServiceException - if the change has not been registered to the configuration service.

BulkValidationException - if setting the parameters fails at the validation step. The configuration state remains unchanged.

BulkSettingException - if setting the parameter fails at the setting step, or if a suspicious change is detected at the validation step, or if the final values of the parameters is not consistent with the performed change. Existing submitted changes are dropped and an alert is raised.

IllegalStateException - if the subsystem is not in engineering mode or if the subsystem is is INITIAL_SAFE configuration state.

getAllConfigurableComponents

public List<String> getAllConfigurableComponents()

submitChange

@Command(description="Submits a change of parameter to be validated later",
         type=CONFIGURATION)
public void submitChange(@Argument(allowedValueProvider="getAllConfigurableComponents")
                                                                                                                                  String componentName,
                                                                                                                                  String parameterName,
                                                                                                                                  Object value)

Submits a configuration parameter change.
The change will be effective once commitBulkChange is invoked and successful. This does not affect the subsystem configuration state.

Parameters:

componentName - the component the parameter belongs to

parameterName - the parameter name

value - the submitted parameter value

Throws:

IllegalArgumentException - if componentName does not have a configurable parameter named parameterName

IllegalStateException - if the subsystem is not in engineering mode or if the subsystem is is INITIAL_SAFE configuration state.

submitChanges

@Command(description="Submits changes of parameters to be validated later",
         type=CONFIGURATION)
public void submitChanges(@Argument(allowedValueProvider="getAllConfigurableComponents")
                                                                                                                                   String componentName,
                                                                                                                                   Map<String,Object> changes)

Submits several parameter changes.
The changes will be effective once commitBulkChange is invoked and successful. This does not affect the subsystem configuration state.

Parameters:

componentName - the component name

changes - a map of parameter names to their submitted value. All parameters are assumed to belong to componentName

Throws:

IllegalArgumentException - if componentName does not have a configurable parameter named parameterName

commitBulkChange

@Command(description="processes the bulk change",
         type=CONFIGURATION)
public void commitBulkChange()

Initiates the bulk change process of the submitted changes.
The bulk change process is described in the above class documentation. If the validation step fails, the configuration state is unchanged, as no parameters have been modified yet. If the setting step fails (an exception is thrown), the current value for each parameter is retrieved, the subsystem goes into DIRTY state if one ore more have been modified and an alarm is raised, indicating an operator error. If the setting step succeeds, the subsystem goes into DIRTY state if one or more parameters have been effectively modified.

Throws:

BulkValidationException - if setting the parameters fails at the validation step. The configuration state remains unchanged. Submitted changes are not dropped.

BulkSettingException - if setting the parameter fails at the setting step, or if a suspicious change is detected at the validation step, or if the final values of the parameters is not consistent with the submitted changes. In all of those cases, an alarm is raised and the submitted changes are dropped.

IllegalStateException - if the subsystem is not in engineering mode or if the subsystem is is INITIAL_SAFE configuration state.

dropAllSubmittedChanges

@Command(description="Drops the submitted changes for all components",
         type=CONFIGURATION)
public void dropAllSubmittedChanges()

Drops the submitted changes for all components of the subsystem.

dropSubmittedChangesForComponent

@Command(description="Drops the submitted changes for the given component",
         type=CONFIGURATION)
public void dropSubmittedChangesForComponent(@Argument(allowedValueProvider="getAllConfigurableComponents",description="the component name")
                                                                                                                                                      String name)

Drops the submitted changes for a given component of the subsystem.

Parameters:

name - the component name.

Throws:

IllegalArgumentException - if there is no component named name

getSubmittedChangesForComponent

@Command(description="Returns the current submitted changes for the given component",
         type=CONFIGURATION)
public Map<String,String> getSubmittedChangesForComponent(@Argument(allowedValueProvider="getAllConfigurableComponents",description="the component name")
                                                                                                                                                                             String name)

Gets the submitted changes for the specified component

Parameters:

name - the component name

Returns:

a map of parameter names to their submitted value

Throws:

IllegalArgumentException - if there is no component named name

getAllSubmittedChanges

@Command(description="Returns the current submitted changes for each component",
         type=CONFIGURATION)
public Map<String,Map<String,String>> getAllSubmittedChanges()

Returns the current submitted changes for each component.

Returns:

a map of component name to their map of submitted changes.

Throws:

IllegalArgumentException - if there is no component named name

getCategories

@Command(description="returns the categories of this subsystem",
         type=QUERY)
public Set<String> getCategories()

Returns the set of categories the subsystem's configurable parameters are split into.

Returns:

a set of category names.

findAvailableConfigurationsForCategory

@Command(description="returns the available configurations for the given category",
         type=CONFIGURATION)
public Set<String> findAvailableConfigurationsForCategory(@Argument(allowedValueProvider="getCategoriesList")
                                                                                                                                                                           String category)

Returns the available configuration names for the given category.

Parameters:

category -

Returns:

a set of configuration names.

Throws:

ConfigurationServiceException - if the configuration service is unavailable

getCurrentValuesForComponent

@Command(description="returns the current values for a given component that belong to the specified categories",
         type=CONFIGURATION)
public Map<String,String> getCurrentValuesForComponent(@Argument(allowedValueProvider="getAllConfigurableComponents")
                                                                                                                                                                                                     String componentName,
                                                                                                                                                                                                     Set<String> categorySet)

Returns the current values of the configuration parameters that belong to componentName and that belong to the specified categories.

Parameters:

componentName - the component name

categorySet - regardless of the category if null.

Returns:

a map of parameter names to their current value

Throws:

IllegalArgumentException - if there is no component named name

isParameterConfigurable

@Command(type=CONFIGURATION)
public boolean isParameterConfigurable(@Argument(allowedValueProvider="getAllConfigurableComponents")
                                                                    String componentName,
                                                                    String parameterName)

Indicates whether their is a configuration parameter named parameterName that belong to the component componentName.

Parameters:

componentName - the component name

parameterName - the parameter name

Returns:

true if there is a configuration parameter name name which belong to the component {

locateConfigurations

@Command(description="locates configurations when they are loaded from the filesystem.",
         type=CONFIGURATION)
public String locateConfigurations()

getTag

public String getTag()

Returns:

tag name

connecting

public void connecting(AgentInfo ai)

Description copied from interface: AgentPresenceListener

Indicates that the agent represented by agent is present on the buses. The implementation should return immediately : any blocking operations should be scheduled on a separate thread.

Specified by:

connecting in interface AgentPresenceListener

disconnecting

public void disconnecting(AgentInfo agent)

Description copied from interface: AgentPresenceListener

Indicates that the agent represented by agent has left the buses. The implementation should return immediately : any blocking operations should be scheduled on a separate thread.

Specified by:

disconnecting in interface AgentPresenceListener

acquireConfigurationLock

public ConfigurationService.ConfigurationLock acquireConfigurationLock()

Acquires the configuration lock.

Returns:

a ConfigurationService.ConfigurationLock object holding the lock.

tryAcquireConfigurationLock

public ConfigurationService.ConfigurationLock tryAcquireConfigurationLock(long time,
                                                                          TimeUnit unit)
                                                                   throws InterruptedException,
                                                                          TimeoutException

Acquires the configuration lock if it is free within the given waiting time and the current thread has not been Thread.interrupt.

Parameters:

time -

unit -

Returns:

a ConfigurationService.ConfigurationLock object holding the lock

Throws:

InterruptedException - if the current thread is interrupted while this lock is being acquired.

TimeoutException - if the waiting time elapsed before the lock was acquired.

getComponentConfigurationEnvironment

public ComponentConfigurationEnvironment getComponentConfigurationEnvironment(String name)

Gets a configuration service dedicated to a specific component

Parameters:

name - the name of the component

Returns:

a ComponentConfigurationEnvironment object, providing a component level configuration API