org.lsst.ccs.framework

Interface Configurable

All Known Implementing Classes:

ConfigurableComponent, ConfigurationServerModule, Module

public interface Configurable

This interface is implemented by Objects that have access to current configuration service and to Component lookup Service.

It is mandatory that these objects are referenced and named in the description file when used.

Normally the methods of this interface are not to be called by user's code. the setEnvironment is called by the subsystem code before init is called on Module and at the same time on other Configurable Objects that are part of the Description

The minimum implementation code is always the same but since there is no Mixin mechanism in Java it should be copied in each class that implements this interface:

 private Configurable.Environment environment ;

 public void setEnvironment(Environment env) {
 this.environment = env ;
 }

 public Environment getEnvironment() {
  return this.environment ;
 }
 

Since Java 8: many methods are now default methods and so do not need to be implemented using the Environment object.

Author:

bamade

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Configurable.Environment instances of this class are created by the subsystem startup.

Method Summary

Modifier and Type	Method and Description
default void	change(String parameterName, Object value) Implementation of this method should be annotated as
default void	dropSubmittedChanges()
default ViewValue	getCheckedValueFromConfiguration(String parameterName, Object value) Deprecated. use isParameterConfigurable(String parameterName) instead.
default <T> LinkedHashMap<String,T>	getChildren(Class<T> clazz) return a map of children that are "assignable to" the argument class.
default Object	getComponentByName(String name) Request for a component that bears the specified name.
Configurable.Environment	getEnvironment()
default String	getName()
default Map.Entry<String,Object>	getParent() Returns name and value of the parent object.
default Object	getParentObject()
default Map<String,String>	getSubmittedChanges()
default Subsystem	getSubsystem()
default void	init() This method is called from the enclosing subsystem constructor.
default Boolean	isParameterConfigurable(String parameterName)
default void	notifyChange(String parameterName, String value) to be used by "facade" commands that may set a value the calling must have made a preliminary check with the configuration service.
default void	notifyChangeWithoutPreliminaryChecks(String parameterName, Object value) to be used by "facade" commands that may set a value then notify the configuration without going through the preliminary check of the configuration service.
default void	postStart() once all hardware components have been started this method is invoked.
default Map<String,String>	printConfigurableParameters(String... categories)
default Map<String,Object>	setBulkParameter(Map<String,Object> parametersView) Override with by hand setting of the parameters in parametersView
void	setEnvironment(Configurable.Environment environment) sets the current Environment Object for the Component.
default void	shutdownNow() requires the component to perform end of life operation.
default void	start() The component is ready to respond.
default void	submitChange(String parameterName, Object value) Submit a change for a parameter.
default void	submitChanges(Map<String,Object> values) Submit a collection of changes.
default void	validateBulkChange(Map<String,Object> parametersView) Override with more advanced parameter validation checking.

Method Detail

setEnvironment

void setEnvironment(Configurable.Environment environment)

sets the current Environment Object for the Component. this method should be called once by the Subsystem initialization process just after the Component constructor has been called (a "PostConstruct" method).

Parameters:

environment -

getEnvironment

Configurable.Environment getEnvironment()

Returns:

the "virtual field" Environment.

getSubsystem

default Subsystem getSubsystem()

Returns:

the current Subsystem in which this object is deployed

init

default void init()

This method is called from the enclosing subsystem constructor. if overriden it is highly recommended to invoke super.init().
the actual code performs resource injection: all fields declared in the current class and annotated as Resource are queried from the Environment and their reference initialize the field.

start

default void start()

The component is ready to respond. This code is invoked from the subsystem to notify that the component should be ready.

postStart

default void postStart()
                throws HardwareException

once all hardware components have been started this method is invoked. it notifies all component that now the subsystem is going to end initialization phase that could be the place to start ticks (module) or to "home" hardwares (that's the reason why this method throws a HardwareException)

Throws:

HardwareException

shutdownNow

default void shutdownNow()

requires the component to perform end of life operation. (hardwares have been stopped before by stop command)

getName

default String getName()

Returns:

the name of the Configurable

getComponentByName

default Object getComponentByName(String name)

Request for a component that bears the specified name.

Parameters:

name -

Returns:

a component that bears this name

getChildren

default <T> LinkedHashMap<String,T> getChildren(Class<T> clazz)

return a map of children that are "assignable to" the argument class.

Type Parameters:

T -

Parameters:

clazz - could be an interface (or even Object.class)

Returns:

a map of children that are assignable to the argument class.

getParentObject

default Object getParentObject()

Returns:

parent object or null if the current Configurable is the main

getParent

default Map.Entry<String,Object> getParent()

Returns name and value of the parent object. The top component has a parent named "_EDEN_" and with value null

Returns:

name and value of the parent object

change

@Command(description="engineering mode change of parameter value",
         type=CONFIGURATION)
default void change(@Argument(name="parameterName",description="Configuration parameter name")
                                                                                                                    String parameterName,
                                                                                                                    @Argument(name="value",description="Configuration parameter value")
                                                                                                                    Object value)

Implementation of this method should be annotated as

  @Command(description = "engineering mode change of parameter value", type = CommandType.CONFIGURATION)
 

Parameters:

parameterName - the name of the parameter to change

value - the value to affect to this parameter

submitChange

@Command(description="submit a potential change for a parameter",
         type=CONFIGURATION)
default void submitChange(@Argument(name="parameterName",description="Configuration parameter name")
                                                                                                                         String parameterName,
                                                                                                                         @Argument(name="value",description="Configuration parameter value")
                                                                                                                         Object value)

Submit a change for a parameter. The change will be effective once commitChange is issued.

Parameters:

parameterName - the name of the parameter

value - the new value to submit for this parameter

submitChanges

@Command(description="submit potential changes for parameters",
         type=CONFIGURATION)
default void submitChanges(Map<String,Object> values)

Submit a collection of changes. If one submission fails all preceding submissions are dropped. The changes will be validated and set when issuing ConfigurableSubsystem#commitBulkChange()

Parameters:

values - a map of parameter name and the new value to submit for this parameter

printConfigurableParameters

@Command(description="displays the current values of the parameters that belong to the given categories",
         type=CONFIGURATION)
default Map<String,String> printConfigurableParameters(String... categories)

getSubmittedChanges

@Command(description="prints the current state of the submitted changes",
         type=CONFIGURATION)
default Map<String,String> getSubmittedChanges()

dropSubmittedChanges

@Command(description="drops the submitted changes for this component",
         type=CONFIGURATION)
default void dropSubmittedChanges()

validateBulkChange

default void validateBulkChange(Map<String,Object> parametersView)

Override with more advanced parameter validation checking. This method should throw an IllegalArgumentException when parameters have a proposed value that is decided as not valid by the user.

Parameters:

parametersView - the whole set of parameters with their value to be validated

setBulkParameter

default Map<String,Object> setBulkParameter(Map<String,Object> parametersView)

Override with by hand setting of the parameters in parametersView

Parameters:

parametersView - a map of parameter names with the new value for this parameter

Returns:

the subset of parameters of the input map that are not handled by this method.

getCheckedValueFromConfiguration

@Deprecated
default ViewValue getCheckedValueFromConfiguration(String parameterName,
                                                               Object value)
                                                        throws Exception

Deprecated. use isParameterConfigurable(String parameterName) instead.

to be used by "facade" commands that may set a value.

Parameters:

parameterName -

value -

Returns:

an Object whose value is the result of a proper parse of the stringValue parameter if the argument is a String or the Object itself accompanied by its String representation

Throws:

Exception - if the configuration service is unreachable or the parsing fails or additional constraints added by the configuration fail

isParameterConfigurable

default Boolean isParameterConfigurable(String parameterName)

notifyChangeWithoutPreliminaryChecks

default void notifyChangeWithoutPreliminaryChecks(String parameterName,
                                                  Object value)

to be used by "facade" commands that may set a value then notify the configuration without going through the preliminary check of the configuration service.
use at your own risk!

Parameters:

parameterName -

value - A string representing the value to be changed (use String.valueOf(Object) if necessary)

notifyChange

default void notifyChange(String parameterName,
                          String value)

to be used by "facade" commands that may set a value
the calling must have made a preliminary check with the configuration service.
indiscriminate use should be discouraged

Parameters:

parameterName -

value -