org.lsst.ccs.framework

Interface Configurable

All Known Implementing Classes:

ConfigurableComponent, ConfigurableProxy, ConfigurationServerModule, Context, GuardedActuatorForT, Module, RaceConditionCheck, ThermalSystem

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 class	Configurable.Environment instances of this class are created by the subsystem startup.

Method Summary

Modifier and Type	Method and Description
default void	alias(String alias) aliases this component.
default void	change(String parameterName, Object value) Implementation of this method should be annotated as
default ViewValue	getCheckedValueFromConfiguration(String parameterName, Object value) to be used by "facade" commands that may set a value.
default <T> LinkedHashMap<String,T>	getChildren(Class<T> clazz) return a map of children that are "assignale to" the argument class.
default Object	getComponentByName(String name) returns a component in the same subsystem that bears this name.
default Dictionary	getDictionary() returns a command dictionary for this object (or its delegate in case the object is a proxy)
Configurable.Environment	getEnvironment()
default String	getName() get the name of this component
default Map.Entry<String,Object>	getParent() returns name and value of the parent object.
default Object	getParentObject()
default Subsystem	getSubsystem()
default void	init() this method is called as a "postStart" operation.
default void	injectResources() this method enables to inject field values provided the fields are declared in the current class inherited fields are not accessible through this facility.
default List<Configurable>	listChildren() returns a list of children of the current object.
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 void	proceduralWalk(java.util.function.Consumer<Configurable> pre, java.util.function.Consumer<Configurable> post) applies method recursively from the current node in the Component's tree.
default void	publish(KVList kvlist) publishes a list of key_object on the status bus
default void	publish(List<ValueNotification> tdl) publishes a predefined list of ValueNotification on the status bus.
default void	publish(long timestamp, KVList kvlist) publishes a list of key_object on the status bus
default void	publish(long timestamp, String key, Object value) publishes a data object on the status bus
default void	publish(String key, long[] timestamps, Object[] objects) publishes a list of objects with corresponding timestamp on the bus
default void	publish(String key, Object value) publishes a data object on the status bus
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 TreeWalkerDiag	treeWalk(java.util.function.Function<Configurable,TreeWalkerDiag> func, java.util.function.Consumer<Configurable> post) walks the components tree applying rules of TreeWalkerDiag (the walk can be interrupted by HANDLING_CHILDREN (the code is not invoked on children) or STOP (the code abruptly ends)

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 initializaiton 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 as a "postStart" operation. 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()

get the name of this component

Returns:

alias

default void alias(String alias)

aliases this component. important note: avoid!

Parameters:

alias -

getComponentByName

default Object getComponentByName(String name)

returns a component in the same subsystem that bears this name.

Parameters:

name -

Returns:

getChildren

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

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

Type Parameters:

T -

Parameters:

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

Returns:

listChildren

default List<Configurable> listChildren()

returns a list of children of the current object.

Returns:

a safe list (empty if no child)

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:

injectResources

default void injectResources()

this method enables to inject field values provided the fields are declared in the current class inherited fields are not accessible through this facility. Fields should be other components in the same subsystem: they are queried by name: the name being the name of the field OR the argument of the Resource annotation.
//todo: annotate Resource for a mutator method (setFieldName)

getDictionary

@Command(description="returns the Command dictionary for this component",
         type=QUERY)
default Dictionary getDictionary()

returns a command dictionary for this object (or its delegate in case the object is a proxy)

Returns:

publish

default void publish(long timestamp,
                     String key,
                     Object value)

publishes a data object on the status bus

Parameters:

timestamp -

key -

value -

publish

default void publish(String key,
                     Object value)

publishes a data object on the status bus

Parameters:

key -

value -

publish

default void publish(long timestamp,
                     KVList kvlist)

publishes a list of key_object on the status bus

Parameters:

timestamp -

kvlist -

publish

default void publish(KVList kvlist)

publishes a list of key_object on the status bus

Parameters:

kvlist -

publish

default void publish(String key,
                     long[] timestamps,
                     Object[] objects)

publishes a list of objects with corresponding timestamp on the bus

Parameters:

key -

timestamps - should be the same size as the array of objects

objects -

publish

default void publish(List<ValueNotification> tdl)

publishes a predefined list of ValueNotification on the status bus. This method is left for compatibility with previous releases (prefer the KVList version (prefer the KVList version)

Parameters:

tdl -

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)
                                                                                                             throws Exception

Implementation of this method should be annotated as

Parameters:

parameterName -

value -

Throws:

Exception

getCheckedValueFromConfiguration

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

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

notifyChangeWithoutPreliminaryChecks

default void notifyChangeWithoutPreliminaryChecks(String parameterName,
                                                  Object value)
                                           throws Exception

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)

Throws:

Exception - any exception that the configuration service may fire

notifyChange

default void notifyChange(String parameterName,
                          String value)
                   throws Exception

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 -

Throws:

Exception

proceduralWalk

default void proceduralWalk(java.util.function.Consumer<Configurable> pre,
                            java.util.function.Consumer<Configurable> post)

applies method recursively from the current node in the Component's tree. if a method throws an Exception apply the Cocoon facility (in utilities)

     try {
         mainModule.proceduralWalk(Cocoon.consumer(MyClass::myMethodThatThrowsMyException), null);
     } catch (MyException exc) {
         //do something
     }
 

Parameters:

pre - the method applied when visiting the node

post - the method applied when all children of the node have been visited (can be null)

treeWalk

default TreeWalkerDiag treeWalk(java.util.function.Function<Configurable,TreeWalkerDiag> func,
                                java.util.function.Consumer<Configurable> post)

walks the components tree applying rules of TreeWalkerDiag (the walk can be interrupted by HANDLING_CHILDREN (the code is not invoked on children) or STOP (the code abruptly ends)

Parameters:

func -

post -

Returns: