ConfigurationService (LSST CCS - Toolkit (Pom) 6.1.30 API)

java.lang.Object
- org.lsst.ccs.ConfigurationService

All Implemented Interfaces:

HasLifecycle, AgentPresenceListener, BusMessagePreProcessor, ServiceLifecycle, AgentService, DataProviderDictionaryService.DataProviderDictionaryListener, HasDataProviderInfos
```
public final class ConfigurationService
extends Object
implements ServiceLifecycle, AgentPresenceListener, AgentService, HasDataProviderInfos, HasLifecycle, BusMessagePreProcessor, DataProviderDictionaryService.DataProviderDictionaryListener
```
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.
Initial configuration state
Some configuration parameters may be marked as being needed during the build phase of subsystem booting, when components are created and registered. This requires that an initial configuration be prepared twice, once at the beginning of the build phase and again at the start of the init phase. The first time only those parameters marked as build-time are processed. The second time those parameters are ignored and all the others are processed. Each time, the Java code and the Groovy subsystem definition are scanned for configuration parameter definitions and values, then a load is performed from the external configuration service.
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 CONFIGURED.
- When configuration tags (or full configurations) are loaded successfully, 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` Encapsulates a reader lock on the subsystem configuration.
`class`	`ConfigurationService.ConfigurationWriteLock` Encapsulates a writer lock on the subsystem configuration.
`static class`	`ConfigurationService.ConvertedParameterizedType`

Field Summary

Fields
Modifier and Type Field and Description

protected Agent agent
GUARDED BY CCS bootstrap (ref), thread safety (object).

Fields
Modifier and Type	Field and Description
`protected Agent`	`agent` GUARDED BY CCS bootstrap (ref), thread safety (object).

Constructor Summary

Constructors
Constructor and Description

ConfigurationService()

Constructors
Constructor and Description
`ConfigurationService()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`ConfigurationService.ConfigurationLock`	`acquireConfigurationLock()` Acquires a read lock on the subsystem configuration.
`ConfigurationService.ConfigurationWriteLock`	`acquireConfigurationWriteLock()` Acquires a writer lock on the subsystem configuration.
`void`	`addConfigurationListener(ConfigurationListener listener)` Add a configuration listener.
`ConfigurationDescription`	`buildConfigurationDescription(ConfigurationListener.ConfigurationOperation co, Options options, String... taggedCategories)`
`ConfigurationInfo.Builder`	`buildConfigurationInfo(ConfigurationView newView)` See the description for `buildConfigurationInfo(org.lsst.ccs.config.ConfigurationView, boolean)` which this method calls with a second argument of `true` (new configuration must be complete).
`ConfigurationInfo.Builder`	`buildConfigurationInfo(ConfigurationView newView, boolean mustBeComplete)` Takes a configuration view and extracts from it the information needed to construct an instance of `ConfigurationInfo`, which is what later gets sent on the CCS status bus.
`void`	`change(String componentName, String parameterName, Object value)` Single change of parameter.
`void`	`commitBulkChange()` Initiates the bulk change process of the submitted changes.
`void`	`commitBulkChangeForComponent(String component)`
`static Type`	`convertTypeNameToType(String typeName)`
`void`	`dataProviderDictionaryUpdate(DataProviderDictionaryService.DataProviderDictionaryEvent evt)` Invoked when there is a change in the dictionary of an Agent on the buses.
`void`	`disconnected(AgentInfo... agents)` Invoked when one or more agents are disconnected from this cluster, either because the shutdown or because they were lost.
`void`	`dropAllSubmittedChanges()` Drops the submitted changes for all components of the subsystem.
`String`	`dropChanges(Options options, 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.
`String`	`getAgentServiceName()` Get the name of this service.
`List<String>`	`getAllConfigurableComponentsWithTrailingSlash()` This method is to be used exclusively by the command processing code to fetch all the allowed values for the component argument.
`Map<String,Map<String,String>>`	`getAllSubmittedChanges()` Returns the current submitted changes for each component.
`Properties`	`getBuildProperties()`
`static Properties`	`getBuildProperties(String descriptionName, String initialConfig)` Utility method to fetch build level properties.
`Bus`	`getBus()` The Bus this BusMessagePreProcessor applies to.
`Set<String>`	`getCategories()` Returns the set of categories the subsystem's configurable parameters are split into.
`List<ConfigurationParameterHandler>`	`getCategoryParameters(String category)` CORE ONLY.
`ComponentConfigurationEnvironment`	`getComponentConfigurationEnvironment(String name)` Gets a configuration service dedicated to a specific component
`ConfigurationDAOWrapper`	`getConfigurationDAOWrapper()`
`ConfigurationDescription`	`getConfigurationDescription()`
`ConfigurationDescription`	`getConfigurationDescription(Options options, String... categories)` Get the configuration description.
`ConfigurationInfo`	`getConfigurationInfo()` Gets the current configurationInfo object depicting the state of the configuration parameters of this subsystem.
`ConfigurationLoadedData`	`getConfigurationLoadedData()` Get the ConfigurationLoadedData object that describes the data as it has been loaded/saved for the current description.
`String`	`getConfigurationParameterValue(String componentName, String parameterName)` Get the current value of a configuration parameter by providing its component name and the parameter name.
`Map<String,String>`	`getConfigurationParameterValuesForComponent(String componentName, String... categories)` Returns the current values of the configuration parameters that belong to `componentName` and that belong to the specified categories.
`List<DataProviderInfo>`	`getDataProviderInfos()` Get the list of available `DataProviderInfo`s.
`String`	`getDefaultSourceForCategory(String category)`
`ConfigurationView`	`getInitialView()` CORE ONLY.
`ConfigurationParameterHandler`	`getParameterByPath(ParameterPath path)` CORE ONLY.
`Map<String,String>`	`getSubmittedChangesForComponent(String name)` Gets the submitted changes for the specified component
`boolean`	`isParameterReadOnly(String componentName, String parameterName)`
`String`	`loadCategories(Options options, String... taggedCategories)` Loads a configuration for the specified categories.
`String`	`loadCategories(String... taggedCategories)`
`void`	`postInit()` Called from the enclosing `Subsystem` at construction phase.
`void`	`preBuild()`
`void`	`preInit()`
`BusMessage`	`preProcessMessage(BusMessage msg)` Pre-process the incoming BusMessage and return the message to be forwarded to the bus message listeners.
`void`	`preStart()` Called from the enclosing `Subsystem` when `org.lsst.ccs.Subsystem#start()` has been called.
`String`	`printConfigurationParameters(Options options, String... categories)` Returns the current values of the configuration parameters that belong to the specified categories.
`String`	`printConfigurationParameters(String... categories)`
`String`	`printConfigurationParametersForComponent(Options options, String component, String... categories)`
`void`	`publishConfigurationInfo()` Publishes the current configurationInfo object on the status bus.
`void`	`publishConfigurationInfo(ConfigurationData configData)`
`void`	`publishDataProviderCurrentData(AgentInfo... agents)` Publish the current data of all the `DataProviderInfo`s managed by this object for the provided list of Agents.
`void`	`removeConfigurationListener(ConfigurationListener listener)` Remove a configuration listener.
`void`	`requestConfigurationDataIfNeededForAgent(String agentName)` Method to request the publication of configuration data for a given agent if needed.
`String`	`saveCategories(Options options, String... categoryTags)` Saves the current value of each parameter that belongs to one of the specified categories in the current running configuration for this category.
`void`	`saveChanges()`
`void`	`saveChanges(Options options)` Saves the current value of each parameter that has changed from the last configuration load.
`void`	`saveChangesForCategories(String... categoryTags)`
`boolean`	`saveInitialConfiguration()` CORE ONLY.
`void`	`setReadOnlyParameter(String componentName, String parameterName, Object value)` Set ReadOnly Configuration Parameter.
`void`	`shutdown()` Called from the enclosing `Subsystem` when `org.lsst.ccs.Subsystem#shutdown()` has been called.
`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 a configuration read lock if it is free within the given waiting time and the current thread has not been interrupted.
`ConfigurationService.ConfigurationWriteLock`	`tryAcquireConfigurationWriteLock(long time, TimeUnit unit)` Acquires a configuration writer lock if it is available within the given waiting time and the current thread has not been interrupted.
`String`	`updateCategories(Options options, String... taggedCategories)` Updated the specified categories.
`String`	`updateCategories(String... taggedCategories)`

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
afterBuild, afterInit, afterStart, preShutdown

Methods inherited from interface org.lsst.ccs.messaging.AgentPresenceListener
connected, connecting, disconnecting

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

Methods inherited from interface org.lsst.ccs.services.HasDataProviderInfos
finalizeDictionary

Methods inherited from interface org.lsst.ccs.framework.HasLifecycle
build, init, postBuild, postShutdown, postStart, start

Field Detail
- agent
```
@LookupField(strategy=TOP)
protected Agent agent
```
  GUARDED BY CCS bootstrap (ref), thread safety (object).

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.

getBuildProperties
```
public static Properties getBuildProperties(String descriptionName,
                                            String initialConfig)
```
Utility method to fetch build level properties. These properties are loaded with the local implementation of the ConfigurationDAO as they must be fetched from the local file system. The properties are loaded both for the agentName and for the descriptionName; so the loaded properties files will start with either the agentName or the descriptionName. They are loaded independently using the BootstrapResourceUtils, and then chained with the agentName properties above the descriptionName properties.

Parameters:

descriptionName - The description name (groovy file)

initialConfig - The initial configuration string

Returns:

getBuildProperties

public Properties getBuildProperties()

shutdown
```
public void shutdown()
```
Description copied from interface: HasLifecycle

Called from the enclosing Subsystem when org.lsst.ccs.Subsystem#shutdown() has been called. At the time it is called PhaseState is CLOSING. It should be overridden to free non hardware related resources.

Specified by:

shutdown in interface HasLifecycle

preBuild
```
public void preBuild()
```
Specified by:

preBuild in interface ServiceLifecycle

preInit
```
public void preInit()
```
Specified by:

preInit in interface ServiceLifecycle

postInit
```
public void postInit()
```
Description copied from interface: HasLifecycle

Called from the enclosing Subsystem at construction phase. This method is called after init and postInit have been called on this component's children.

Specified by:

postInit in interface HasLifecycle

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

getDataProviderInfos
```
public List<DataProviderInfo> getDataProviderInfos()
```
Description copied from interface: HasDataProviderInfos

Get the list of available DataProviderInfos.

Specified by:

getDataProviderInfos in interface HasDataProviderInfos

Returns:

a List of DataProviderInfos

publishDataProviderCurrentData
```
public void publishDataProviderCurrentData(AgentInfo... agents)
```
Description copied from interface: HasDataProviderInfos

Publish the current data of all the DataProviderInfos managed by this object for the provided list of Agents.

Specified by:

publishDataProviderCurrentData in interface HasDataProviderInfos

Parameters:

agents - The array of AgentInfo for which we are requesting to publish the data.

getConfigurationParameterValue

@Command(category=CORE,
         type=QUERY,
         level=0)
public String getConfigurationParameterValue(@Argument(allowedValueProvider="getAllConfigurableComponentsWithTrailingSlash")
                                                                                                            String componentName,
                                                                                                            String parameterName)

Get the current value of a configuration parameter by providing its component name and the parameter name.

Parameters:: componentName - The component the parameter belongs to.; parameterName - The name of the configuration parameter.
Returns:: The String representation of the parameter's value.

printConfigurationParameters

@Command(category=CORE,
         type=QUERY,
         level=0)
 @Option(name="dirtyOnly",description="Only print information about dirty configuration parameters") @Option(name="originTag",description="Show in which tag the parameter is defined")
public String printConfigurationParameters(Options options,
                                                                                                                                                                                                                                                                                                  String... categories)

Returns the current values of the configuration parameters that belong to the specified categories. If no categories are provided we print configuration parameters for all categories.

Parameters:: options - The provided command options; categories - The categories to print. If empty or null, all categories are displayed.
Returns:: A String with a printout of the configuration parameters for the provided categories.

printConfigurationParameters

public String printConfigurationParameters(String... categories)

printConfigurationParametersForComponent

@Command(description="displays the current values of the parameters that belong to the given categories for the provided component",
         type=QUERY,
         category=CORE,
         level=0)
 @Option(name="dirtyOnly",description="Only print information about dirty configuration parameters") @Option(name="originTag",description="Show in which tag the parameter is defined")
public String printConfigurationParametersForComponent(Options options,
                                                                                                                                                                                                                                                                                                                                                                                                                                                   @Argument(allowedValueProvider="getAllConfigurableComponentsWithTrailingSlash")
                                                                                                                                                                                                                                                                                                                                                                                                                                                   String component,
                                                                                                                                                                                                                                                                                                                                                                                                                                                   String... categories)

saveChanges
```
public void saveChanges(Options options)
```
Saves the current value of each parameter that has changed from the last configuration load.
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.

saveChanges
```
public void saveChanges()
```

saveCategories

@Command(description="Saves the specified categories with a name",
         type=CONFIGURATION,
         category=CORE,
         level=1)
 @Option(name="allCategories",description="Load all categories, even the unspecified ones.") @Option(name="testRun",description="Perform a trial run of the command and report back the result.") @Option(name="originTag",description="The save is performend in the tag that last defined a configuration parameter") @Option(name="full",description="Saves all configuration parameters, rather than just the changes")
public String saveCategories(Options options,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   @Argument(name="categoryTags",description="A list of categories or category tags")
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   String... categoryTags)

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:: options - The Options for this operation; categoryTags - a list of categories to save
Returns:: a String containing information about the operation result. When the testRun Option is provided it includes all the information regarding the operation.
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.

saveChangesForCategories

public void saveChangesForCategories(@Argument(name="categoryTags",description="A list of categories or category tags")
                                     String... categoryTags)

dropChanges

@Command(name="dropChanges",
         description="drop unsaved changes for the specified categories",
         type=CONFIGURATION,
         category=CORE,
         level=1)
 @Option(name="allCategories",description="Load all categories, even the unspecified ones.") @Option(name="testRun",description="Perform a trial run of the command and report back the result.")
public String dropChanges(Options options,
                                                                                                                                                                                                                                                                                                                                                                                                          @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:: options - The Options for this operation; categories - A list of categories
Returns:: A String containing the outcome of the command
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.

updateCategories

@Command(description="Update the specified category tags",
         type=CONFIGURATION,
         category=CORE,
         level=1)
 @Option(name="allCategories",description="Load all categories, even the unspecified ones.") @Option(name="testRun",description="Perform a trial run of the command and report back the result.") @Option(name="dropChanges",description="Force the drop of all the outstanding changes.")
public String updateCategories(Options options,
                                                                                                                                                                                                                                                                                                                                                                                                                                                            @Argument(name="taggedCategories",description="a list of pairs categoryName:configurationName(version)")
                                                                                                                                                                                                                                                                                                                                                                                                                                                            String... taggedCategories)

Updated the specified categories. The category tags specified will be reloaded, if needed and their versions will be resolved anew. The specified category tags must already be loaded.

Parameters:: options - The Options for this operation; taggedCategories - a list of pairs categoryName:configurationName(version)
Returns:: A String containing the outcome of the command
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.

updateCategories

public String updateCategories(String... taggedCategories)

loadCategories

@Command(description="loads the configuration for the specified categories",
         type=CONFIGURATION,
         category=CORE,
         level=1)
 @Option(name="allCategories",description="Load all categories, even the unspecified ones.") @Option(name="dropChanges",description="Force the drop of all the outstanding changes.") @Option(name="testRun",description="Perform a trial run of the command and report back the result.")
public String loadCategories(Options options,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                            @Argument(name="taggedCategories",description="a list of pairs categoryName:configurationName(version)")
                                                                                                                                                                                                                                                                                                                                                                                                                                                                            String... taggedCategories)

Loads a configuration for the specified categories.
Not allowed if there are uncommitted submitted changes. 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:: options - The Options for this operation; taggedCategories - a list of pairs categoryName:configurationName(version)
Returns:: a String containing information about the operation result. When the testRun Option is provided it includes all the information regarding the operation.
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.

loadCategories

public String loadCategories(String... taggedCategories)

buildConfigurationDescription

public ConfigurationDescription buildConfigurationDescription(ConfigurationListener.ConfigurationOperation co,
                                                              Options options,
                                                              String... taggedCategories)

getConfigurationLoadedData
```
public ConfigurationLoadedData getConfigurationLoadedData()
```
Get the ConfigurationLoadedData object that describes the data as it has been loaded/saved for the current description.

Returns:

getConfigurationInfo
```
@Command(description="return a ConfigurationInfo object",
         type=QUERY,
         category=SYSTEM,
         level=0)
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 commands, the changes will not be reflected in the returned ConfigurationInfo object.

Returns:

a ConfigurationInfo object depicting the current configuration state.

getConfigurationDescription

@Command(description="Return the configuration description for the provided categories",
         type=QUERY,
         category=CORE,
         level=0)
 @Option(name="initial",description="Shows the initial configuration description, i.e. the one requested when the Subsystem started.") @Option(name="base",description="Shows the base configuration description")
public ConfigurationDescription getConfigurationDescription(Options options,
                                                                                                                                                                                                                                                                                                                                                                                                                                       String... categories)

Get the configuration description. By default we show the current configuration description. I.e. the complete set of tags that are currently loaded. By providing the "initial" option we will display the initial configuration description, i.e. the configuration description at the time the Subsystem started.

Parameters:: options - The options for this command.; categories - The categories that should be contained in the ConfigurationDescription. If no categories are provided, the ConfigurationDescription will include all categories.
Returns:: The ConfigurationDescription of the Agent's initial configuration for the provided categories.

getConfigurationDescription

public ConfigurationDescription getConfigurationDescription()

setReadOnlyParameter
```
public void setReadOnlyParameter(String componentName,
                                 String parameterName,
                                 Object value)
```
Set ReadOnly Configuration Parameter.
This method is to be used when changing values of ReadOnly configuration parameters. The configuration state is unchanged.

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.

publishConfigurationInfo
```
@Command(description="publish a ConfigurationInfo object",
         type=QUERY,
         category=SYSTEM,
         level=0)
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 not be reflected by the published ConfigurationInfo object.

publishConfigurationInfo

public void publishConfigurationInfo(ConfigurationData configData)

change

@Command(description="Submits a single change to be processed immediately",
         type=CONFIGURATION,
         category=CORE,
         level=1)
public void change(@Argument(allowedValueProvider="getAllConfigurableComponentsWithTrailingSlash")
                                                                                                                                                                      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.

getAllConfigurableComponentsWithTrailingSlash
```
public List<String> getAllConfigurableComponentsWithTrailingSlash()
```
This method is to be used exclusively by the command processing code to fetch all the allowed values for the component argument. It needs to be public to be invoked by the command processing code.

Returns:

The list of all configurable components with a trailing slash.

submitChange

@Command(description="Submits a change of parameter to be validated later",
         type=CONFIGURATION,
         category=CORE,
         level=1)
public void submitChange(@Argument(allowedValueProvider="getAllConfigurableComponentsWithTrailingSlash")
                                                                                                                                                                            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.

submitChanges

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

Submits several parameter changes.

The changes will be effective once commitBulkChange is invoked and successful. Until then the subsystem configuration state is not changed.

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(name="applySubmittedChanges",
         description="processes the bulk change",
         type=CONFIGURATION,
         category=CORE,
         level=1)
public void commitBulkChange()
```
Initiates the bulk change process of the submitted changes.
The bulk change process is described in the 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 or 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.

commitBulkChangeForComponent

public void commitBulkChangeForComponent(String component)

dropAllSubmittedChanges

@Command(name="cancelAllSubmittedChanges",
         description="Drops the submitted changes for all components",
         type=CONFIGURATION,
         category=CORE,
         level=1)
public void dropAllSubmittedChanges()

Drops the submitted changes for all components of the subsystem.

dropSubmittedChangesForComponent

@Command(name="cancelSubmittedChangesForComponent",
         description="Drops the submitted changes for the given component",
         type=CONFIGURATION,
         category=CORE,
         level=1)
public void dropSubmittedChangesForComponent(@Argument(allowedValueProvider="getAllConfigurableComponentsWithTrailingSlash",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,
         category=CORE,
         level=1)
public Map<String,String> getSubmittedChangesForComponent(@Argument(allowedValueProvider="getAllConfigurableComponentsWithTrailingSlash",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,
         category=CORE,
         level=1)
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,
         category=CORE,
         level=0)
public Set<String> getCategories()

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

Returns:: A read-only set of category names.

getConfigurationParameterValuesForComponent

@Command(description="returns the current values for a given component that belong to the specified categories",
         type=QUERY,
         category=CORE,
         level=0)
public Map<String,String> getConfigurationParameterValuesForComponent(@Argument(allowedValueProvider="getAllConfigurableComponentsWithTrailingSlash")
                                                                                                                                                                                                                                                      String componentName,
                                                                                                                                                                                                                                                      String... categories)

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

Parameters:: componentName - the component name; categories - 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

isParameterReadOnly

public boolean isParameterReadOnly(String componentName,
                                   String parameterName)

acquireConfigurationLock
```
public ConfigurationService.ConfigurationLock acquireConfigurationLock()
```
Acquires a read lock on the subsystem configuration.

Returns:

a ConfigurationService.ConfigurationLock object holding the lock.

tryAcquireConfigurationLock

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

Acquires a configuration read lock if it is free within the given waiting time and the current thread has not been interrupted.

Parameters:: time - how long to wait.; unit - the units in which the wait time is expressed.
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.

acquireConfigurationWriteLock
```
public ConfigurationService.ConfigurationWriteLock acquireConfigurationWriteLock()
```
Acquires a writer lock on the subsystem configuration.

Returns:

a ConfigurationService.ConfigurationWriteLock object holding the lock.

tryAcquireConfigurationWriteLock

public ConfigurationService.ConfigurationWriteLock tryAcquireConfigurationWriteLock(long time,
                                                                                    TimeUnit unit)
                                                                             throws InterruptedException,
                                                                                    TimeoutException

Acquires a configuration writer lock if it is available within the given waiting time and the current thread has not been interrupted.

Parameters:: time - how long to wait.; unit - the units in which the wait time is expressed.
Returns:: a ConfigurationService.ConfigurationWriteLock object holding the lock
Throws:: InterruptedException - if the current thread is interrupted while this lock is being acquired.; TimeoutException - if the wait time elapses before the lock is 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

addConfigurationListener
```
public void addConfigurationListener(ConfigurationListener listener)
```
Add a configuration listener.

Parameters:

listener - The ConfigurationListener to be added

removeConfigurationListener
```
public void removeConfigurationListener(ConfigurationListener listener)
```
Remove a configuration listener.

Parameters:

listener - The ConfigurationListener to be added

buildConfigurationInfo
```
public ConfigurationInfo.Builder buildConfigurationInfo(ConfigurationView newView)
```
See the description for buildConfigurationInfo(org.lsst.ccs.config.ConfigurationView, boolean) which this method calls with a second argument of true (new configuration must be complete).

Parameters:

newView - the view of the new configuration which needs a ConfigurationInfo made for it.

Returns:

A Builder for the new ConfigurationInfo.

See Also:

ConfigurationInfo

buildConfigurationInfo
```
public ConfigurationInfo.Builder buildConfigurationInfo(ConfigurationView newView,
                                                        boolean mustBeComplete)
```
Takes a configuration view and extracts from it the information needed to construct an instance of ConfigurationInfo, which is what later gets sent on the CCS status bus.

Parameters:

newView - the view of the new configuration which needs a ConfigurationInfo made for it.

mustBeComplete - true if and only if no missing parameters can be tolerated.

Returns:

A Builder for the new ConfigurationInfo.

See Also:

ConfigurationInfo

getCategoryParameters
```
public List<ConfigurationParameterHandler> getCategoryParameters(String category)
```
CORE ONLY. Gets a list of the parameters for a given category.

Parameters:

category - the name of the category.

Returns:

The read-only list of parameter handlers.

Throws:

RuntimeException - if no such category exists.

getParameterByPath
```
public ConfigurationParameterHandler getParameterByPath(ParameterPath path)
```
CORE ONLY. Gets the parameter handler given the path.

Parameters:

path - the parameter path object.

Returns:

The parameter handler.

Throws:

IllegalArgumentException - if the parameter doesn't exist.

saveInitialConfiguration
```
public boolean saveInitialConfiguration()
```
CORE ONLY. Was the subsystem started with the --saveInitialConfiguration option?

Returns:

true if it was, else false.

getInitialView
```
public ConfigurationView getInitialView()
```
CORE ONLY. Returns a copy of the initial configuration view gotten from the Java code and Groovy file.

Returns:

The copied view, or an empty one if none was available.

getConfigurationDAOWrapper

public ConfigurationDAOWrapper getConfigurationDAOWrapper()

convertTypeNameToType

public static Type convertTypeNameToType(String typeName)

dataProviderDictionaryUpdate
```
public void dataProviderDictionaryUpdate(DataProviderDictionaryService.DataProviderDictionaryEvent evt)
```
Description copied from interface: DataProviderDictionaryService.DataProviderDictionaryListener

Invoked when there is a change in the dictionary of an Agent on the buses.

Specified by:

dataProviderDictionaryUpdate in interface DataProviderDictionaryService.DataProviderDictionaryListener

Parameters:

evt - The DataProviderDictionaryService.DataProviderDictionaryEvent describing the nature of the change: ADDED, REMOVED. Information about the Agent for which the change occurred, and the new dictionary itself are contained in the event object.

preProcessMessage
```
public BusMessage preProcessMessage(BusMessage msg)
```
Description copied from interface: BusMessagePreProcessor

Pre-process the incoming BusMessage and return the message to be forwarded to the bus message listeners. The returned message can either be a modified version of the original message or a brand new message. The Class of the returned message can be different than the incoming message. If null is returned the message will not be sent to the BusMessage listeners, but it will still be passed to other BusMessagePreProcessors This method can be invoked by separate threads, but it's invoked by one thread at a time; there is no concurrent invocation of the method.

Specified by:

preProcessMessage in interface BusMessagePreProcessor

Parameters:

msg - The incoming BusMessage

Returns:

The modified BusMessage to be forwarded to the BusMessageListeners

getBus
```
public Bus getBus()
```
Description copied from interface: BusMessagePreProcessor

The Bus this BusMessagePreProcessor applies to.

Specified by:

getBus in interface BusMessagePreProcessor

Returns:

The Bus.

disconnected
```
public void disconnected(AgentInfo... agents)
```
Description copied from interface: AgentPresenceListener

Invoked when one or more agents are disconnected from this cluster, either because the shutdown or because they were lost. The implementation should return immediately : any blocking operations should be scheduled on a separate thread.

Specified by:

disconnected in interface AgentPresenceListener

getDefaultSourceForCategory

public String getDefaultSourceForCategory(String category)

requestConfigurationDataIfNeededForAgent
```
public final void requestConfigurationDataIfNeededForAgent(String agentName)
```
Method to request the publication of configuration data for a given agent if needed. If the data has already been published we push the last StatusConfigurationInfo on the STATUS bus, otherwise a command request to publish the data will be issued.

Parameters:

agentName - The name of the agent for which the data is needed.

Class ConfigurationService

Initial configuration state

The bulk change process

Validation step

Setting step

Configuration state diagram

Interaction with the configuration service

Configuration information publication

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface org.lsst.ccs.ServiceLifecycle

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

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

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

Methods inherited from interface org.lsst.ccs.framework.HasLifecycle

Field Detail

agent

Constructor Detail

ConfigurationService

Method Detail

getAgentServiceName

getBuildProperties

getBuildProperties

shutdown

preBuild

preInit

postInit

preStart

getDataProviderInfos

publishDataProviderCurrentData

getConfigurationParameterValue

printConfigurationParameters

printConfigurationParameters

printConfigurationParametersForComponent

saveChanges

saveChanges

saveCategories

saveChangesForCategories

dropChanges

updateCategories

updateCategories

loadCategories

loadCategories

buildConfigurationDescription

getConfigurationLoadedData

getConfigurationInfo

getConfigurationDescription

getConfigurationDescription

setReadOnlyParameter

publishConfigurationInfo

publishConfigurationInfo

change

getAllConfigurableComponentsWithTrailingSlash

submitChange

submitChanges

commitBulkChange

commitBulkChangeForComponent

dropAllSubmittedChanges

dropSubmittedChangesForComponent

getSubmittedChangesForComponent

getAllSubmittedChanges

getCategories

getConfigurationParameterValuesForComponent

isParameterReadOnly

acquireConfigurationLock

tryAcquireConfigurationLock

acquireConfigurationWriteLock

tryAcquireConfigurationWriteLock

getComponentConfigurationEnvironment

addConfigurationListener

removeConfigurationListener

buildConfigurationInfo

buildConfigurationInfo

getCategoryParameters

getParameterByPath

saveInitialConfiguration

getInitialView