org.lsst.ccs

Class ConfigurationService

java.lang.Object

org.lsst.ccs.ConfigurationService

All Implemented Interfaces:

AlertHandler, ClearAlertHandler, HasLifecycle, AgentPresenceListener, ServiceLifecycle, AgentService, HasDataProviderInfos

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

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.

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 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.
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.
ClearAlertHandler.ClearAlertCode	canClearAlert(Alert alert, AlertState state) 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	commitBulkChangeForComponent(String component)
void	connected(AgentInfo... ai) All the provided agents are fully connected to the buses, they are OPERATIONAL and ready to receive commands.
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.
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.
Properties	getBuildProperties()
static Properties	getBuildProperties(String descriptionName, String initialConfig) Utility method to fetch build level properties.
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
ConfigurationInfo	getConfigurationInfo() Gets the current configurationInfo object depicting the state of the configuration parameters of this subsystem.
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.
ConfigurationDescription	getCurrentConfigurationDescription(String... categories) Get the current configuration description.
List<DataProviderInfo>	getDataProviderInfos() Get the list of available DataProviderInfos.
ConfigurationDescription	getInitialConfigurationDescription(String... categories) Get the initial configuration description.
ConfigurationView	getInitialView() CORE ONLY.
ConfigurationParameterHandler	getParameterByPath(ParameterPath path) CORE ONLY.
ConfigurationDescription	getRequestedConfigurationDescription(String... categories) Get the requested configuration description.
Map<String,String>	getSubmittedChangesForComponent(String name) Gets the submitted changes for the specified component
String	getTag()
boolean	isParameterReadOnly(String componentName, String parameterName)
void	loadCategories(String... taggedCategories) Loads a configuration for the specified categories.
void	loadConfiguration(String... taggedCategories) Full configuration load.
void	preBuild()
void	preInit()
void	preStart() Called from the enclosing Subsystem when org.lsst.ccs.Subsystem#start() has been called.
String	printConfigurationParameters(String... categories) Returns the current values of the configuration parameters that belong to the specified categories.
String	printDirtyConfigurationParameters(String... categories) Returns the current values of the dirty configuration parameters that belong to the specified categories.
void	publishConfigurationInfo() Publishes the current configurationInfo object on the status bus.
void	publishDataProviderCurrentData(AgentInfo agentInfo) Publish the current data of all the DataProviderInfos managed by this object.
void	removeConfigurationListener(ConfigurationListener listener) Remove a configuration listener.
void	saveChanges() Saves the current value of each parameter that has changed from the last configuration load.
void	saveChangesForCategories(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	saveChangesForCategoriesAs(String... categoryTags) Deprecated. Use saveChangesForCategories instead
void	saveFullConfiguration() Saves the current values for all the parameters.
void	saveFullConfigurationForCategories(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.

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

afterInit, afterStart, preShutdown

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

connecting, disconnected, 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, postInit, postShutdown, postStart, start

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.
• HardwareController.checkStopped() has been called

It should be overridden to free non hardware related resources.

Specified by:

shutdown in interface HasLifecycle

canClearAlert

public ClearAlertHandler.ClearAlertCode canClearAlert(Alert alert,
                                                      AlertState state)

Description copied from interface: ClearAlertHandler

Callback to clear an Alert instance. Return a ClearAlertCode for the provided Alert.

Specified by:

canClearAlert in interface ClearAlertHandler

Parameters:

alert - The Alert instance to clear.

state - The AlertState for the provided Alert.

Returns:

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

preBuild

public void preBuild()

Specified by:

preBuild in interface ServiceLifecycle

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

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 agentInfo)

Description copied from interface: HasDataProviderInfos

Publish the current data of all the DataProviderInfos managed by this object.

Specified by:

publishDataProviderCurrentData in interface HasDataProviderInfos

Parameters:

agentInfo - The AgentInfo for which we are requesting to publish the data.

getConfigurationParameterValue

@Command(category=CORE,
         type=QUERY,
         level=0)
public String getConfigurationParameterValue(@Argument(allowedValueProvider="getAllConfigurableComponents")
                                                                                                            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)
public String printConfigurationParameters(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:

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.

printDirtyConfigurationParameters

@Command(category=CORE,
         type=QUERY,
         level=0)
public String printDirtyConfigurationParameters(String... categories)

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

Parameters:

categories - The categories to print. If empty or null, all categories are displayed.

Returns:

A String with a printout of the dirty configuration parameters for the provided categories.

saveChanges

@Command(description="Saves all changes in the current configurations",
         type=CONFIGURATION,
         category=CORE,
         level=1)
public void saveChanges()

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.

saveFullConfiguration

@Command(description="Saves all changes in the current configurations",
         type=CONFIGURATION,
         category=CORE,
         level=1)
public void saveFullConfiguration()

Saves the current values for all the parameters.

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.

saveChangesForCategories

@Command(description="Saves the specified categories with a name",
         type=CONFIGURATION,
         category=CORE,
         level=1)
public void saveChangesForCategories(@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:

categoryTags - 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.

saveChangesForCategoriesAs

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

Deprecated. Use saveChangesForCategories instead

Parameters:

categoryTags -

saveFullConfigurationForCategories

@Command(description="Saves the specified categories with a name",
         type=CONFIGURATION,
         category=CORE,
         level=1)
public void saveFullConfigurationForCategories(@Argument(name="taggedCategories",description="A list of categories")
                                                                                                                                                                                         String... categoryTags)

dropAllChanges

@Command(description="drop all unsaved changes",
         type=CONFIGURATION,
         category=CORE,
         level=1)
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.

dropChangesForCategories

@Command(description="drop unsaved changes for the specified categories",
         type=CONFIGURATION,
         category=CORE,
         level=1)
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.

loadConfiguration

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

Full configuration load.

Not allowed if there are uncommitted submitted changes. 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.

loadCategories

@Command(description="loads the configuration for the specified categories",
         type=CONFIGURATION,
         category=CORE,
         level=1)
public void loadCategories(@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:

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.

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.

getInitialConfigurationDescription

@Command(description="return the initial configuration for the provided categories",
         type=QUERY,
         category=CORE,
         level=0)
public ConfigurationDescription getInitialConfigurationDescription(String... categories)

Get the initial configuration description. This is the configuration that was loaded during the agent startup procedure. This is the configuration on top of which additional configurations are loaded.

Parameters:

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.

getRequestedConfigurationDescription

@Command(description="return the requested configuration for the provided categories",
         type=QUERY,
         category=CORE,
         level=0)
public ConfigurationDescription getRequestedConfigurationDescription(String... categories)

Get the requested configuration description. This is the configuration that was requested by the users.

Parameters:

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 requested configuration for the provided categories.

getCurrentConfigurationDescription

@Command(description="return the current configuration for the provided categories",
         type=QUERY,
         category=CORE,
         level=0)
public ConfigurationDescription getCurrentConfigurationDescription(String... categories)

Get the current configuration description. This is the configuration that is currently loaded.

Parameters:

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 current configuration for the provided categories.

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.

change

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

getAllConfigurableComponents

public List<String> getAllConfigurableComponents()

submitChange

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

submitChanges

@Command(description="Submits changes of parameters to be validated later",
         type=CONFIGURATION,
         category=CORE,
         level=1)
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. 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(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(description="Drops the submitted changes for the given component",
         type=CONFIGURATION,
         category=CORE,
         level=1)
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,
         category=CORE,
         level=1)
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,
         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="getAllConfigurableComponents")
                                                                                                                                                                                                                                                      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)

getTag

public String getTag()

Returns:

tag name

connected

public void connected(AgentInfo... ai)

Description copied from interface: AgentPresenceListener

All the provided agents are fully connected to the buses, they are OPERATIONAL and ready to receive commands. This method is invoked when the listener is added with all the agents that are already connected. When this method is invoked the agent is in PhaseState::OPERATIONAL state and all its services are guaranteed to have been properly initialized. The implementation should return immediately : any blocking operations should be scheduled on a separate thread.

Specified by:

connected in interface AgentPresenceListener

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.