Application properties configuration

The application properties XML configuration file allows to specify the values for the module properties defined in the application configuration.

There are two ways to define these properties:

• Defining all the properties at the root of the XML file. In this case the name of the property in the configuration file will specify the path of the property^[1]
  application and module for each property
• Defining the applications and modules, and each properties under its owner module

These two ways are completely equivalent.

All properties can be retrieved in the Module class by the various getPropertyxxx methods.

Note that general framework properties are directly set at the configuration file level. See framework properties for more information.

Grammar

See the grammar for the properties schema.

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.

If an invocation for a module which has this property is called, and the duration between this invocation and the last effective one is smaller than the specified update cap, the invocation will be called at the end of a timer set with the update cap value:

For example:

      <properties>
         <application name="appli1" >
            <module name="module1" >
               <moduleProperty key="publishServices.updateCap" value="500" />
            </module>
         </application>
      </properties>

Global properties

The globalProperty element allows to specify properties which can be shared by several modules. It can be useful if you want several modules to have the same value for the same property name.

For example suppose the following applications configuation:

         <applications>
            <application name="myAppli">
               <modules>
                  <module name="module1">
                      <properties>
                          <property key="prop1" type="int" />
                          <property key="prop2" type="url" />
                      </properties>
                  </module>
                  <module name="module2">
                      <properties>
                          <property key="prop1" type="int" />
                      </properties>
                  </module>                  
            </application>
         </applications>

and the properties specification:

      <properties>
         <globalProperty key="prop1" key="3" />
         <application name="appli1" >
            <module name="module1" >
               <moduleProperty key="prop2" value="my/file.xml" />
            </module>
            <module name="module2" />          
         </application>
      </properties>

It is equivalent to the following properties specification:

      <properties>
         <application name="appli1" >
            <module name="module1" >
               <moduleProperty key="prop1" value="3" />
               <moduleProperty key="prop2" value="my/file.xml" />
            </module>
            <module name="module2" > 
               <moduleProperty key="prop1" value="3" />
            </module>         
         </application>
      </properties>

Variables

The var element allows to specify variables which values can be used by several properties. The values defined for these properties can be used for any property by using the "${var key}" construct.

For example:

      <properties>
         <var key="globalVar" key="500" />
         <application name="appli1" >
            <module name="module1" >
               <moduleProperty key="prop1" value="${globalVar}" />
            </module>
            <module name="module2" >
               <moduleProperty key="myProperty" value="${globalVar}" />
            </module>            
         </application>
      </properties>

Note that variables defined in the properties file take precedence over the properties defined for the framework in the framework properties.

AllowConfigVariables attribute

By default property values will take into account variables, but if the module property configuration allowConfigVariables is set to false, then the proeprty will not take variables into account.

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}".

Retrieving a property value

Retrieving a property value can be performed in Java with the methods called getPropertyxxxValue(propertyName) or getPropertyxxxValue(propertyName, unit) for properties with units.

Defining the properties for an application with only one module

If an application has only one module, it is not necessary to use the module element under the application element.

For example, if the application appli1 has only one module named module1, the two following declarations for the properties are equivalent:

      <properties>
         <application name="appli1" >
            <module name="module1" >
               <moduleProperty key="prop1" value="3" />
               <moduleProperty key="prop3" value="3" />
            </module>
         </application>
      </properties>

and

      <properties>
         <application name="appli1" >
            <module name="module1" >
               <moduleProperty key="prop1" value="3" />
               <moduleProperty key="prop3" value="3" />
            </module>
         </application>
      </properties>

Examples

Example with a tree of properties

      <properties>
         <application name="appli1" >
             <moduleProperty key="prop1" value="3" />
             <moduleProperty key="prop3" value="3" />
         </application>
      </properties>

Example with all properties at the root of the XML file

      <properties>
         <property key="appli1.module1.prop1" value="3" />
         <property key="appli1.module1.prop3" value="3" />
      </properties>

Examples with array properties

Suppose the following module properties configuration:

      <properties>
         <propertyGroup>
            <propertyArray key="prop1" type="int" />
            <propertyArray key="prop2" type="url" />
         </propertyGroup>
      </properties>

We can have for example the following properties configuration:

      <properties>
         <arrayProperty key="appli1.module1.prop1">
            <value value="3" />
            <value value="4" />
         </arrayProperty>
         <arrayProperty key="appli1.module1.prop2">
            <value value="http://docs.oracle.com/javase/8/docs/api" />
            <value value="http://docs.oracle.com/javase/8/docs" />
         </arrayProperty>
      </properties>

or we can also have:

      <properties>
         <application name="appli1" >
            <module name="module1" >
               <moduleArrayProperty key="prop1">
                  <value value="3" />
                  <value value="4" />
               </moduleArrayProperty>
               <moduleArrayProperty key="prop2">
                  <value value="http://docs.oracle.com/javase/8/docs/api" />
                  <value value="http://docs.oracle.com/javase/8/docs" />
               </moduleArrayProperty>
            </module>
         </application>
      </properties>

Example with arrayGroup properties

Suppose the following module properties configuration:

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

We can have for example the following properties configuration:

      <properties>
         <application name="appli1" >
            <module name="module1" >
               <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>
               <moduleProperty key="prop3" value="3" />
            </module>
         </application>
      </properties>

or we can also have:

      <properties>
         <arrayGroupProperty key="appli1.module1.array1">
            <arrayValue>
               <property key="appli1.module1.prop1" value="1" />
               <property key="appli1.module1.prop2" value="2" />
            </arrayValue>
            <arrayValue>
               <property key="appli1.module1.prop1" value="3" />
               <property key="appli1.module1.prop2" value="4" />
            </arrayValue>
         </arrayGroupProperty>
         <property key="appli1.module1.prop3" value="3" />
      </properties>

Both these two cases are equivalent. In these two cases we will have two array of int properties for "prop1" and "prop2" (stored asd a List), which can be retrieved by Module.getPropertyIntArrayValue(String).

Example with a map property

      <properties>
         <application name="appli1" >
            <module name="module1" >
               <moduleProperty key="prop1" >
                  <mapValue key="key1" value="value1" />
                  <mapValue key="key2" value="value2" />
               </moduleProperty>
            </module>
         </application>
      </properties>

Retrieving a property

Retrieving a basic property

If we define for a module:

      <property key="myProp" type="int"/>

And we have in the properties configuration:

      <properties>
         <application name="appli1" >
            <module name="module1" >
               <moduleProperty key="myProp" value="150"/>
            </module>
         </application>
      </properties>

To retrieve the value of the property in the module:

      public void init(Module module) {
        // the value will be 150
        int value = module.getPropertyFloatValue("myProp");
      }

Retrieving a property with a unit

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);
      }