Module properties configuration

The module properties define constants which allow to configure a module. Their effective values for the framework are defined in the application properties configuration.

Uses cases for modules properties can be:

• Configuration files which are used by modules^[1]
  For example, the builtin UA application module needs an ARINC 661 configuration file
• Various configuration datas to customize the way the module can be used

Property definition

Simple properties definition

The property element denotes a simple property. A simple property definition has the following attributes:

• key: (mandatory) The property key
• type: (mandatory) The property type. See properties types
• defaultValue: (optional) The property default value
• unit: (optional) The property unit, can be useful for numeric properties. See properties units
• constraints: (optional) The constraints of the property, useful for URL properties. See property constraints
• mandatory: (optional) true if the property is mandatory. By default a property is optional^[2]
  Note that if the property belongs in a group, it means that the property is mandatory or optional in its parent group
• allowConfigVariables: (optional) boolean property, true if the property will take into account variables (see usage of variables in the properties for more information)

Property arrays definition

The arrayProperty element denotes a property which is an array of elements of the same type. A property array definition has the following attributes:

• key: (mandatory) The property key
• type: (mandatory) The array element type
• mandatory: (optional) true if the property is mandatory. As for simple properties, by default a property is optional^[2]
  Note that if the property belongs in a group, it means that the property is mandatory or optional in its parent group
• allowConfigVariables: (optional) boolean property, true if the property will take into account variables (see usage of variables in the properties for more information)

Properties types

Properties can have one of the following type:

• int: integer values
• boolean: boolean values
• float: float values
• string: integer values
• url: URL values. By default URL values must point to existing files, but it is possible to change this constraint, see property constraints
• duration: duration values. Duration values are instances of the Duration class. Duration values typically have a value followed by the unit of the duration^[3]
  For example, the following patterns are valid:

  • 200ms
  • 1.5s
  • 1min
  • 1hour
• position: position values. The format is <x position;>;<y position;. Position values are instances of the ScreenPosition class. These properties can be useful to position the GUI Window associated with a module if this module has an associated window
• map: Map of (String, String) values

Properties units

Numeric properties can (optionaly) have one of the following units:

• m: meter
• ft: feet
• in: inch
• nm: nautical mile
• deg: degree
• deg360: degree normalized in the [0, 360] range
• deg180: degree normalized in the [-180, 180] range
• rad: radian
• mrd: milliradian
• tr: "tour" (180 degrees = -0.5, -180 degrees = -0.5)
• m/s: meter per second
• m/s2 or ms2: meter per second squared
• g: G-force
• fr/s: feet per second
• fr/min: feet per minute
• knot: knots
• rad/s: radian per second
• deg/s: degree per second
• kg: kilogram
• lb: pound
• ms: millisecond
• utc: utc
• epoch: epoch
• s: second
• minute: minute
• hour: hour

Note: utc and epoch units are aliases for ms (millisecond).

Defining a unit for a property allow to retrieve their value by defining their unit in the properties configuration. For example, if we define for a module:

      <property key="myProp" type="float" unit="nm"/>

And we have in the properties configuration:

      <properties>
         <application name="appli1" >
            <module name="module1" >
               <moduleProperty key="myProp" value="18520" unit="m"/>
            </module>
         </application>
      </properties>

The value of the property in Nautical miles will be "10".

Also we can retrieve the value of the property in the module by defining the unit in which we want the property, for example:

      public void init(Module module) {
        // here valueNM will be 10
        float valueNM = module.getPropertyFloatValue("myProp", Units.NM);

        // here valueM will be 18520
        float valueM = module.getPropertyFloatValue("myProp", Units.M);
      }

Time unit properties

For time values, it is also possible to specify the properties directly in the value attribute. For example, these two definitions are equivalent:

      <moduleProperty key="prop1" value="15" unit="ms" />
      <moduleProperty key="prop3" value="1.5" unit="s" />            
      <moduleProperty key="prop4" value="1" unit="s"/> 
      <moduleProperty key="prop5" value="2" unit="minute" /> 
      <moduleProperty key="prop6" value="1.5" unit="minute" />        
      <moduleProperty key="prop7" value="1.5" unit="hour" />

and:

      <moduleProperty key="prop1" value="15ms" />
      <moduleProperty key="prop3" value="1.5s" />         
      <moduleProperty key="prop4" value="1s" />
      <moduleProperty key="prop5" value="2min" /> 
      <moduleProperty key="prop6" value="1.5min" />        
      <moduleProperty key="prop7" value="1.5hour" />

Properties enumeration values

Enumeration values can be associated with int properties definition. They allow to define the allowed values for the property^[4]

And also to specify their value with as their state names in the application properties configuration

.

For example:

      <property key="prop1" type="int">
         <enum name="first" value="0" />
         <enum name="second" value="1" />
         <enum name="third" value="3" />
      </property>

Usage of variables in the properties

The allowConfigVariables attribute allows to specify if the property will allow the usage of variables in their value.

For example for the following module configuration:

      <module name="myModule" >
      ...
         <properties>
           <property key="myProperty" type="string" />
         </properties>
      </module>

For the following properties configuration:

      <properties>
         <var key="globalVar" key="500" />
         <application name="appli" >
            <module name="myModule" >
               <moduleProperty key="myProperty" value="${globalVar}" />
            </module>           
         </application>
      </properties>

The value of the property will be the String "500".

But for the following module configuration:

      <module name="myModule" >
      ...
         <properties>
           <property key="myProperty" type="string" allowConfigVariables="false" />
         </properties>
      </module>

The value of the property will be the String "${globalVar}".

Property constraints

It is possible to specify constraints associated with a property with the constraints attribute.

For the moment it is only useful for URL properties. It is possible to specify if the property must specify :

• existingFile: an existing file
• notExistingFile: a not existing file
• allFiles: all files

Note that by default URL properties must point to existing files. For example:

      <properties>
         <property key="scenarioSave" type="url" constraints="notExistingFile" />
      </properties>

Property groups

It is possible to define that several properties belong to a group. This allows to consider for example that:

• One or another group of properties must be specified, but not both
• All of the properties of a group must be specified, or none

There are two kinds of property groups:

• The propertyGroup element specifies a group of properties^[5]
  Or property groups
• The propertyChoice element specifies a choice between several properties^[5]
  Or property groups

Both propertyGroup and propertyChoice elements have an optional mandatory property, which has the same meaning as for the property element.

Also a group can contain both terminal properties or other groups.

Property array groups

The propertyArrayGroup element denotes a group of properties which are arrays of elements, all with the same number of elements. A propertyArrayGroup definition has the following attributes:

• key: (mandatory) The propertyArrayGroup key
• mandatory: (optional) true if the property is mandatory. As for simple properties, by default a propertyArrayGroup is optional^[2]
  Note that if the property belongs in a group, it means that the property is mandatory or optional in its parent group

Note that as simple properties or property arrays, propertyArrayGroups have a key.

Default properties

Two properties exist by default for any Module without having to be specified in the application configuration:

• allServices.updateCap: the default property allowing to set an update cap in ms for all Services for a Module
• publishServices.updateCap: the default property allowing to set an update cap in ms for publish Services for a Module.

These properties allow to reduce the frequency of service invocations for a Module. It can be useful for example when the framework is controlled by an external application through an Owner module, and the rate of invocations from the external application is too high.

Auto-properties

An auto-property is a property which is defined implicitly as an attribute value in a module configuration. The pattern signaling an auto-property for an attribute value is ${<property name>}. For example:

       <cyclic service="theService" frequency="${freq}" attach="attach"/>

Auto-properties allow to configure attributes defined for a service implementation by properties in the properties file.

Auto-properties default values

By default auto-properties are mandatory, but it is possible to make them optional by adding them in the list of properties for the module, and setting their default value. For the previous example, we could have:

      <properties>
         <autoProperty key="freq" mandatory="false" defaultValue="200ms" />
      </properties>

Example

In the following example, the freq auto-property is defined:

      <module name="myModule" id="1" >
         <interfaces>
            <cyclic service="theService" frequency="${freq}" attach="attach"/>
         </interfaces>
         <properties>
           <autoProperty key="freq" mandatory="false" defaultValue="200ms" />
         </properties>
      </module>

The type of this property is a duration, derived from the type of the frequency attribute. This property is optional, and its default value is 200 ms.

Defining properties programmatically

It is possible for a module to define properties programmatically rather than in the application properties configuration file. This should be defined in the preconfigure method of the module. The method that can be used to create the properties is the Module.addPropertyType(String, Class, String, boolean)

Example

For example, suppose the following application configuration file:

      <module name="myImpl" id="1" >
         <implementation path="my.ModuleImpl" >
            <preConfigureEntryPoint method="preConfigure" />
         </implementation>
      </module>

and the following code for the module:

      public void preConfigure() {
        module.addPropertyType("myFile", URL.class, null, true);
      }

A myFile property will be created with the following characteristics:

• It is an URL property
• It does not have a default value
• It is mandatory

Examples

Simple properties

      <properties>
         <property key="hasWorld" type="boolean" />
         <property key="duration" type="duration" />
         <property key="aircraftConf" type="url" mandatory="true" />
      </properties>

Here we have the definition of the following properties:

• hasWorld is an optional boolean property
• duration is a mandatory integer property
• aircraftConf is an optional URL property

An example of actual properties values for this configuration is:

      <properties>
         <application name="appli1" >
            <module name="module1" >
               <moduleProperty key="hasWorld" value="true" />
               <moduleProperty key="duration" value="2" />
               <moduleProperty key="aircraftConf" value="my/directory/file.xml" />
            </module>
         </application>
      </properties>

Property arrays

      <properties>
         <property key="hasWorld" type="boolean" />
         <propertyArray key="configURLs" type="url" />
      </properties>

Here we have the definition of the following properties:

• hasWorld is an optional boolean property
• configURLs is an optional array of URLs

An example of actual properties values for this configuration is:

      <properties>
         <application name="appli1" >
            <module name="module1" >
               <moduleProperty key="hasWorld" value="true" />
               <moduleArrayProperty key="configURLs">
                  <value value="my/directory/file1.xml" />
                  <value value="my/directory/file2.xml" />
               </moduleArrayProperty>
            </module>
         </application>
      </properties>

Properties groups

      <properties>
         <propertyChoice mandatory="true">
            <property key="uaConfig" type="url" />
            <propertyGroup>
               <property key="uaImpl" type="url" mandatory="true"/>
               <property key="uaPath" type="string" mandatory="true"/>
            </propertyGroup>
         </propertyChoice>
      </properties>

Here we have the definition of the following properties:

• uaImpl and uaPath belong in an optional property group, but they are both mandatory in their parent group, which means that they must both be present or both absent
• uaConfig or both the uaImpl and uaPath properties must be present

Two valid examples of actual properties values for this configuration are:

      <properties>
         <application name="appli1" >
            <module name="module1" >
               <moduleProperty key="uaConfig" value="my/directory/file.xml" />
            </module>
         </application>
      </properties>

and:

      <properties>
         <application name="appli1" >
            <module name="module1" >
               <moduleProperty key="uaImpl" value="my/directory/uaImpl.xml" />
               <moduleProperty key="uaPath" value="the.path.UaClassName" />
            </module>
         </application>
      </properties>

Properties array groups

      <properties>
         <propertyArrayGroup key="array1" mandatory="true">
            <property key="prop1" type="int" />
            <property key="prop2" type="int" />
         </propertyArrayGroup>
         <property key="prop3" type="int" mandatory="true"/>
      </properties>

Here we have the definition of the following properties:

• prop1 and prop2 are two int arrays wich must have the same number of elements
• prop3 is an int property

An example of actual properties values for this configuration is:

      <properties>
         <application name="appli1" >
            <module name="module1" >
               <moduleProperty key="prop3" value="2" />
               <moduleArrayGroupProperty key="array1">
                  <moduleArrayValue>
                     <moduleProperty key="prop1" value="1" />
                     <moduleProperty key="prop2" value="2" />
                  </moduleArrayValue>
                  <moduleArrayValue>
                     <moduleProperty key="prop1" value="3" />
                     <moduleProperty key="prop2" value="4" />
                  </moduleArrayValue>
               </moduleArrayGroupProperty>
            </module>
         </application>
      </properties>