|
|
|
|
|
Below there is detailed information about XML representation of the property mapping. The Device Access mapping mechanism provides the ability to construct mapping between:
<property-mappings>
The <property-mappings> element is optional. It has one or many <property-mapping> child elements.
<property-mapping>
The <property-mapping> element is required. Each mapping is described in separate <property-mapping> child element. The <property-mapping> tag has two required attributes – "targetProperty" and sourceProperty". These attributes hold the names of the mapped properties. After defining the property names of the Device Items properties, the next step is to describe the way that they will be mapped. The <property-mapping> has the following optional child elements: <value-mapping>, <event>, <read> and <write>. Detailed information about them and how they are used is provided below.
When the types of the described properties are same, then there is no need to describe any child element. For example when the Source Device Item property "currentTemperature" of the com.prosyst.mbs.services.da.items.Sensor is changed, then the Target Device Item property "value" of the demo.da.items.Thermometer should be changed too. The reversed statement is also true – when the Target Device Item property "value" is changed, then the Source Device Item property "currentTemperature" should be changed also.
...
<source-info>
<class name="demo.da.items.Thermometer" />
</source-info>
<target-info>
<class name="com.prosyst.mbs.services.da.items.Sensor" />
</target-info>
<property-mappings>
<property-mapping targetProperty="value" sourceProperty="currentTemperature" />
</property-mappings>
...
<value-mapping>
The <value-mapping> element is optional. It is used to describe when the Source Device Item property is changed how the Target Device Item property should be changed. Also its describe when the Target Device Item property is changed how the Source Device Item property should be changed. This element is used when the mapping between the properties is not complex. With the <value-mapping> element is defined property to property mapping. The <value-mapping> element has one or many child elements <value>. The <value> element holds the representation of the property value – refer to Mapping XML Property Representation for detailed information. If the type of the properties are different or if the user has to describe only part of the mapping between Source Device Item property and Target Device Item property, then <event>, <read> and <write> child element should be used. Only one representation of the property mapping should be provided – using <value-mapping> element OR using <event>, <read> and/or <write>.
<property-mapping targetProperty="state" sourceProperty="state">
<value-mapping>
<value sourceValue="1" targetValue="true" />
<value sourceValue="0" targetValue="false" />
</value-mapping>
</property-mapping>
The following examples demonstrate the restrictions of the <value-mapping> element:
<value sourceProperty="1">
<target-value script="1 + 1" />
</value>
In this example there is limitation for the Target Device Item property access. The Target Device Item property must not have 'W' access. If the Target Device Item property has 'W' access, then the mapping between Source Device Item property and Target Device Item property have to be described using <event>, <read> and <write> XML elements.
<value targetProperty="1">
<source-value script="1 + 1" />
</value>
In this example there is limitation for the Target Device Item property access. The Target Device Item property must have only 'W' access. If the Target Device Item property has 'R' or/and 'E' access, then the mapping between Source Device Item property and Target Device Item property have to be described using <event>, <read> and <write> XML elements.
<event>
The <event> element is optional. It is used to describe how the Target Device Item property is changed when the Source Device Item property is changed. As an addition it is possible to describe which value of the Source Device Item property is used to change the Target Device Item property. The <event> element holds the representation of the property. Refer to Mapping XML Property Representation for detailed information.
For example when the Source Device Item property is changed, then the value of the com.prosyst.mbs.services.units.Quantity of the Target Device Item property should be changed by the formula: Source Device Item property value * 2.
...
<property-mapping targetProperty="value" sourceProperty="steps">
<event>
<target-value>
<map-value>
<element key="unit">
<map-value>
<element key="symbol" value="°" />
</map-value>
</element>
<element key="value">
<map-value>
<element key="value" script="#{sourceValue} * 2" />
</map-value>
</element>
</map-value>
</target-value>
</event>
</<property-mapping>
...
In the following example the Source Device Item is com.prosyst.mbs.services.da.items.Opener and the Target Device Item is com.prosyst.mbs.services.da.items.TransitionActuator. When the Source Device Item property "state" is changed, then the Target Device Item property should be changed by the following formula: Source Device Item property value equals to com.prosyst.mbs.services.da.items.OpenerState.OPENING.
<property-mappings>
<property-mapping targetProperty="started" sourceProperty="state">
<event>
<target-value script="#{sourceValue}.equals(com.prosyst.mbs.services.da.items.OpenerState.OPENING)" />
</event>
</property-mapping>
</property-mappings>
<read>
The <read> element is optional. It is used to initialize the Target Device Item properties – refer to Property Cache page for detailed information about property initialization
<property-mapping targetProperty="on" sourceProperty="state">
<read sourceValue="1" targetValue="true" />
<read sourceValue="0" targetValue="false" />
</<property-mapping>
<write>
The <write> element is optional. It is used to describe when the Target Device Item property is changed how the Source Device Item property is changed OR which Source Device Item operation is invoked. As an addition there is ability to describe at what value of the Target Device Item property is used to change the Source Device Item property or invoke Source Device Item operation. The <write> element holds the representation of the property. Refer to Mapping XML Property Representation for detailed information.
For example when the Target Device Item property is changed, then the Source Device Item property should be changed by the following formula: the Quantity value converted into angle decree divided by 2.
...
<property-mapping targetProperty="value" sourceProperty="steps">
<write>
<source-value script="(#{targetValue.unit}.convert(#{targetValue.value}, com.prosyst.mbs.services.units.system.SI.ANGLE_DEGREE)) / 2" />
</write>
</property-mapping>
...
In addition the <write> element has optional child element <source-operation>. The <source-operation> element holds the information about the Source Device Item operation. This element is used to describe the mapping between the Target Device Item property and Source Device Item operation. The <source-operation> tag has required attribute "name" that holds the name of the Source Device Item operation. The <source-operation> has optional child element <params> that describes the operation parameters. The <params> element has one or many child <param> elements . The <param> element holds the representation of the value of the operation parameter. This value can be simple value or complex object value. Refer to Mapping XML Value Representation for detailed information.
In addition to the"value", "script" and "ref" attributes, the <param> tag has also a "targetArgument". This attribute is also optional. It holds the Target Device Item parameter that should be passed as parameter on the Source Device Item operation.