Configuration Editor - universAAL/tools.eclipse-plugins GitHub Wiki
The Configuration Editor (CE) supports the developer by creating configuration information for the integration of new AAL service into the AAL space. Therefore he is supported with concepts and software tools in order to create a configuration file. This XML-file will be delivered within every parts of a multi-part-application (MPA) if needed. During the installation the uCC (universAAL Control Center, Configuration and Personalization Tool) uses this information from the configuration definition registry and set properties to the configuration storage. The AAL service namely its different parts (MPA) access the configuration storage and read its values.
It is recommended to read the wikipage about the counterpart of the Configuration Editor: the uCC (universAAL Control Center). This will help to get an idea of the whole deployment live cycle
This tool is for AAL service developer and the following paragraph will give an overview about the functionality of it. As a AAL service developer you have to do mainly two things.
- First you have to create the configuration definition. Therefore you can define the configuration options for your service. Also, it is possible to validate the configuration entries done by the deployer later in the uCC. Furthermore, the usage of listeners is described. They allowed a direct reaction on every entry done by the deployer during the configuration in the uCC.
- And second you have to refer this configuration options within the source code of your use case.
In this step the generation of an XML configuration file is explained. This file is the main defines all configurable objects. Imagine you want to develop an use case which displays something and you want to make the font and the font scale configurable. Then you will create a XML file from the dashboard (Configuration Editor -> New) or via new configuration wizard (Figure 1). This wizard can be found in Eclipse under File->New->Other. After the generation of the XML file you will edit it, that it looks similar to this one:
<?xml version="1.0" encoding="UTF-8"?>
<universaal:configuration author="Tom Zentek" id="de.fzi.exampleusecase.config"
bundlename="de.fzi.exampleusecase" version="1.0"
xmlns:universaal="http://universaal.fzi.de"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://universaal.fzi.de universaalconfiguration.xsd ">
<universaal:category id="general" label="General Configuration">
<universaal:MapConfigItem cardinality="1..1" id="Font">
<universaal:label>The font</universaal:label>
<universaal:description>Please choose your font.</universaal:description>
<universaal:options>
<universaal:option key="1">Papyrus</universaal:option>
<universaal:option key="2">Tahoma</universaal:option>
<universaal:option key="3">Calibri</universaal:option>
</universaal:options>
</universaal:mapconfigitem>
<universaal:SimpleConfigItem cardinality="1..1" id="FontScale" type="double">
<universaal:label>The font scale</universaal:label>
<universaal:description>Please insert the font scale.</universaal:description>
<universaal:validators>
<universaal:validator class="de.fzi.exampleusecase.MySpecialValidatorFactory">
<universaal:attribute>0.5</universaal:attribute>
<universaal:attribute>1.5</universaal:attribute>
</universaal:validator>
</universaal:validators>
<universaal:defaultValue>1</universaal:defaultvalue>
</universaal:simpleconfigitem>
</universaal:category>
</universaal:configuration>
In the beginning of this generated XML file you see some general configuration information such as the author, bundle name, id and version. This segment is followed by one category in which the configuration options are describe. Of course more than one category is possible. Within the category there are the configuration options, a MapConfigurationItem and a SimpleConfigurationItem, both have an id, cardinality and description. The cardinality defines if the configuration option is required and if multi selection is allowed or not.
Beside the XML view the Studio Tools provide a form based editor (see picture above). With this editor it is easier for the developer to fill in the needed configuration parameter.
Perhaps you have already noticed that the in the example the SimpleConfigurationItem contains a Validator. The validator allows the developer to proof the input (from the deployer) for the defined values in the XML file. The validator classes can be developed by the AAL service developer on its own or a standard validator could be used. If you develop your own validator you need to implement the ConfigurationValidator and the ConfigurationValidatorFactory interface and start the validator factory as an OSGi service:
context.registerService(MySpecialValidatorFactory.class.getName(), new MySpecialValidatorFactory(), null);
Every validator has three main methods:
- The isValid() method, that only checks whether the given value is valid or not. See an example below:
@Override
public boolean isValid(ConfigOptionRegistry registry, Value value) {
if(value == null || value.getValue() == null || value.getValue().equals("")){
return true;
}else{
try {
Double.parseDouble(value.getValue());
} catch (Exception e) {
return false;
}
}
return true;
}
- The validate() method is called to check the configuration and throws an exception with more details about the fault.
@Override
public void validate(ConfigOptionRegistry registry, Value value)
throws ValidationException {
if(!isValid(registry, value)){
throw new ValidationException(msg);
}
}
- In the following you can see the setAttributes() method that is responsible for the validation attributes from the XML configuration definition.
@Override
public void setAttributes(String[] attributes) {
if(attributes.length > 1){
try{
min = Double.parseDouble(attributes[0]);
max = Double.parseDouble(attributes[0]);
}catch (Exception e){
//nothing logging...
}
}
}
The listeners directly react on the configuration input from the deployer. The listener can for example change the GUI related to the configuration input. For more information see the examples and the related explanations in section: Examples and Tutorials.
If you have finished the configuration definition you have to register this definition to the configuration definition registry.
configURL = FrameworkUtil.getBundle(this.getClass()).getResource("/config/example.xml");
configReg.registerConfigurationDefinition(configURL);
After you have done this the deployer is able to configure your AAL service with the uCC. And you are able to access this configuration with an instance of the "ConfigurationPreferences" class.
/**
* Create new ConfigPreferences for this bundle.
*/
public Config(){
config = new ConfigPreferences(FrameworkUtil.getBundle(this.getClass()).getBundleContext().getBundle());
}
public int getMax_displayed_events() {
// Get the value for id "calendarMsgCount" or the defualt 3.
return config.getInt("calendarMsgCount", 3);
}
public int getUpdatetime() {
return config.getInt("RSSUpdateTime", 10);
}
public int getImage_width() {
return config.getInt("ImageWidth", 1200);
}
public int getImage_height() {
return config.getInt("ImageHeight", 700);
}
public String getFont() {
return config.getString("InfoFont", "Arial");
}
- use cases implementing this configuration approch will not be able to run if the uCC is not installed
- only AAL application on the same note as the uCC are configurable
- No hardware configuration - rejected not in focus of this tool.
- No human resources configuration - rejected not in focus of this tool.
- uCC uses the uAAL buses instead of OSGi services - updateable on demand.
- More languages supported - updateable on demand.
The video below show the usage of the Configuration Editor : Video