XML Object Representation

There is detailed information on this page about XML representation of the complex object values. This presentation is needed for the Device and Device Item attribute values, Device Item property value and Device Item operation argument values. The complex object value is reduced to the following groups of map value and array value. A map value is used for representing maps and beans objects. An array value is used for representing a collections and arrays objects.

XML Representation of the Device/ Device Item Attributes

The XML representation of Device and Device Item attributes is the same in filtering and configuring Devices and Device Items. The <attributes> element holds the Device or Device Items attributes. It has child element <attribute> that holds the representation of the concrete Device or Device Item attribute. The <attribute> tag has required attribute "name" that holds the key of the Device or Device Item attribute. Also the <attribute> tag has optional attribute "value" that holds the value of the Device or Device Item attribute.

This optional XML attribute "value" is used when the value is simple type. For example string, numeric, etc. For example the XML representation of Device attribute "hardware.vendor" with value "Bosch.IO" is:

</attributes>

When the Device or DeviceItem attribute has a complex object value, then this value is represented with the corresponding child elements - map-value or array-value. Detailed information about this child elements and set of examples are found bellow. The complex object values are collections, arrays, etc. As an additional restriction about the Device and Device Item attributes is that the value types are only of the FIM supported primary types.

The <attribute> element has optional child element <class>. The <class> tag has required attribute "value" that holds the full Java class name of the described Device or DeviceItem attribute. If the <class> element is not provided, then the java.lang.String should be provided as a default value. There are some specifics in description of the array of primitive types. The following table describes this specifics.

Array Type	String Representation
`boolean[]`	[Z
`byte[]`	[B
`char[]`	[C
`Object[]`	[Ljava.lang.Object;
`double[]`	[D
`float[]`	[F
`int[]`	[I
`long[]`	[J
`short[]`	[S
Multidimensional array (for example `int[][]`)	[[I

The <class> element specifies the type of the Device or Device Item attribute.The following examples demonstrate the importance of using <class> element.

The default value of element <class> is "java.lang.String". Thus the attribute with key "false_as_String" has the value of "false" as String:

In the following example the attribute with key "false_as_Boolean" has the value of "false" as Boolean:

</attribute>

This means that the <class> element has an optional child element <class>. For example if the Device or DeviceItem attribute value is a collection, then the main <class> element should contain the full Java class name for the collection and the child element <class> should contain the type of the collection's elements:

</class>

XML Representation of the Maps and FIM Bean Values

The <map-value> element has zero or more child elements – <element>. The <element> tag has a required attribute "key". If the value of the Map is an object, then the <element> should have child elements – map-value or array-value. If the value of the Map is not an object, then the <element> tag has an optional attribute "value". If the value of the <element> is null, then the attribute xsi:nil with value true should be presented. Only one of these attributes should be provided.

an example of Map<String, String> representation:
<map-value>

  <element key="Map Key 1" value="Map Value 1" />

  <element key="Map Key 2" value="Map Value 2" />

  <element key"Null Value" xsi:nil="true" />

</map-value>

an example of Map<String, Map<String, String>> representation:
<map-value>

  <element key="map_key">

    <map-value>

      <element key="nested_map_key" value="nested_map_value" />

    </map-value>

  </element>

</map-value>

an example of Map<String, List<String>> representation:
<map-value>

  <element key="map_key">

    <array-value>

      <element value="List Value 1" />

      <element value="List Value 2" />

    </array-value>

  </element>

</map-value>

an example of FIM bean representation (e.g. com.prosyst.mbs.services.units.Quantity):
<map-value>

  <element key="unit">

    <map-value>

      <element key="symbol" value="℃" />

    </map-value>

  </element>

  <element key="value">

    <map-value>

      <element key="value" value="25" />

    </map-value>

  </element>

</map-value>

an example of an Empty Map representation:
<attribute name="Empty Map">

  <map-value>

  </map-value>

  <class value="java.util.Map">

    <class value="java.lang.String" />

  </class>

</attribute>

XML Representation of the Collection and Array Values

The array-value element has zero or more child elements <element>. If the value of the represented element is an object, the then <element> has child elements – map-value or array-value. If the value of the represented element is not an object, then the <element> tag has optional attribute "value". If the value of the <element> is null, then the attribute xsi:nil with value true should be presented. Only one of these attributes should be provided.

an example of List<String> representation:
<array-value>

  <element value="element 1" />

  <element value="element 2" />

  <element xsi:nil="true" />

</array-value>

an example of Integer[] representation:
<array-value>

<element value="1" />

<element value="2" />

</array-value>

an example of List<Map<String, String>> representation:
<array-value>

  <element>

    <map-value>

      <element key="Key 1" value="Value 1" />

      <element key="Key 2" value="Value 2" />

    </map-value>

  </element>

</array-value>

an example of empty list representation:
<attribute name="Empty List">

  <array-value>

  </array-value>

  <class value="java.util.List">

    <class value="java.lang.String" />

  </class>

</attribute>