Data Mapper Bundle

The Data Mapper Bundle provides a tool for converting byte arrays to Java objects and vise versa.

Contents:

• Bundle Information
  • Bundle JAR
  • Import
  • Export
• Main Features
• Data Mapper Architecture
• Providing a Data Mapping XML
  • XML DTD
  • Scheme
  • Example Data Mapping XML
• Data Mapper Manifest Header
• Services
  • Data Mapper Service
  • Custom Function Evaluator Service
• System Properties
• Data Mapper Demo
• References

Bundle Information

Bundle JAR

The Data Mapper Bundle is packed in the datamapper.jar file, located in the bundles directory of Framework Professional Edition Package.

Import

Export

The Data Mapper Bundle exports com.prosyst.mbs.services.datamapper package. It provides an API for to using the Data Mapper functionality.

Main Features

Data Mapper can convert an input byte array into a Dictionary holding objects of basic Java types and vise versa. It can also convert a Dictionary of byte arrays into a Dictionary of Java objects. Special XML files define the rules according to which Data Mapper performs each conversion. For details on creating data mapping XMLs, refer to the "Providing a Data Mapping XML " section.

Data Mapper provides an universal way to access the data from different types of networks and communication protocols in Java applications. For example, you can use Data Mapper to create XML-based device drivers for EHS and EIB based systems without need to implement any Java code. Another example of its usage is to access the data available in a CAN bus.

Data Mapper Architecture

The figure below depicts the modules structuring the Data Mapper:

Figure1: Data Mapper architecture model

Mapping Parser

Mapping Parser generates a structure of Java objects out of each data mapping XML and stores this structure for late usage. It uses the ProSyst XML Utilities to process the data mapping XMLs.

Data Mapping

A structure of objects representing a data mapping XML.

Data Mapper

The core unit of the Data Mapper module. It uses the stored Data Mappings to generate Dictionary of Java objects out of bite arrays and vise versa.

Expression Evaluator

It evaluates conditions and mathematical expressions using the mathematical evaluator provided by the JEval library. The JEval library is delivered by the JEVAL-ProSyst bundle. The Expression Evaluator also uses the default implementation of a Custom Function Evaluator to perform byte extracting and decode operations.

Custom Function Evaluator

Custom functions allow applications to insert custom functionality into the mathematical expressions Data Mapper operates with.

Providing a Data Mapping XML

When initially started, Data Mapper does not have any data mapping XMLs, therefore third party bundles must supply it with such. There can be different data mapping XMLs depending on the data formats they are intended for. As an instance, you can provide data mapping XMLs created according to the EHS and EIB data format specifics.

XML DTD

<case>
  <condition>some condition</condition>
  <value>some value</value>
</case>

<!ATTLIST mapper    
          name CDATA #REQUIRED   
          pid CDATA #REQUIRED>

<!ATTLIST const 
          name CDATA #REQUIRED
          type CDATA #REQUIRED>

<!ATTLIST var 
          name CDATA #REQUIRED
          type CDATA #REQUIRED>

<!ATTLIST map 
          name CDATA #REQUIRED
          type CDATA #REQUIRED>

Scheme

Variables defined in the mapper element of the XML are called scheme and have a special function. They define how the bytes of the original byte array should be interpreted in the output Dictionary. The scheme must exists when generateRawData and processRawData methods of the Data Mapper service are called.

Variables included in the scheme must obey to the following rules:

• The first variable must be of type "byte[]" without no value specified. It represents the actual byte array to be processed.
• All variables that follow can be of different types but their values can be only in one of the following formats:
  • var.<scheme_name>[a] - The variable's value will be taken from the byte with index "a".
  • var.<scheme_name>[a..b] - The variable's value will be taken from bytes placed between byte "a" to byte "b". If "a" is less then "b", the bytes will be taken from left to right. In this case, the least significant byte will be "a" and the most significant byte will be "b". If "a" is greater then "b", the bytes will be taken from right to left and the most significant byte will be "a" and the least significant byte will be "b".
  • var.<scheme_name>[a]{x}- The variable's value will be taken from bite "x" belonging to byte "a".
  • var.<scheme_name>[a]{x..y} - The variable's value will be taken from bite "x" to bite "y" belonging to byte "a".
  • var.<scheme_name>[a..b]{x..y} - The variable's value will be taken from bite "x" to bite "y" belonging to the bytes placed between byte "a" and byte "b".
• var.<scheme_name>[a;c] - The variable's value be taken from "c" number of bytes starting from byte "a".
• var.<scheme_name>[a..end] - The variable's value will be taken from the bytes placed starting from byte "a" to the end of the byte array.
• var.<scheme_name>[end..b] - The variable's value will be taken from the bytes placed starting from the byte array's end and its byte with index "b".
• var.<scheme_name>[size] - The variable's value will be the whole byte array.
• Every possible bit of the input byte array must be included in exactly one variable.

Note: A variable with no value specified in the XML means that it must be taken from the input Dictionary. This in is case of generating a byte array out of Dictionary holding Java objects.

Example Data Mapping XML

For example, a data mapping XML can look like this:

<!DOCTYPE mapper SYSTEM "mapper_dtd.dtd">
<mapper name="DataMapperExample" pid="datamapper.example">
  <!-- Scheme -->
  <var name="frame" type="byte[]"></var> 
  <var name="type" type="int">
    <value><![CDATA[var.frame[0]]]></value>
  </var> 
  <var name="data" type="int">
    <value><![CDATA[var.frame[1]]]></value>
  </var> 
  <!-- Generating a Dictionary of Java object out of a byte array -->
  <mapper_in> 
    <mapping>
      <condition><![CDATA[ var.type == 1]]></condition>
      <map name="exampleMap" type="int">
        <value><![CDATA[ var.data * 2 ]]></value>
      </map>
    </mapping>
  </mapper_in>
  <!-- Generating a byte array out of a Dictionary of Java objects>
  <mapper_out>
    <!-- The value of these variables will be taken from the input Dictionary -->
    <var name="action" type="int"></var>
    <var name="sourcedata" type="int"></var>
    <mapping>
      <condition><![CDATA[ var.action == 0]]></condition>
      <!-- Defining scheme variables -->
      <map name="type" type="int">
        <value><![CDATA[ 0 ]]></value>
      </map>
      <map name="data" type="int">
        <value><![CDATA[ var.sourcedata ]]></value>
      </map>
    </mapping>
  </mapper_out>
</mapper>

Data Mapper Manifest Header

Bundles that provide data mapping XMLs should have the following header in their manifest specifying the XML PIDs and names:

Data-Mapping: xml=<xml_name>;pid=<xml_pid> [, xml=<xml_name>;pid=<xml_pid>]

For example:

 Data-Mapping: xml=myDataMapping_1.xml; pid=my.data.mapping.1,
               xml=myDataMapping_2.xml; pid=my.data.mapping.2,
               xml=myDataMapping_3.xml; pid=my.data.mapping.3

Services

Data Mapper Service

The Data Mapper service provides means to using the Data Mapper functionality. It is registered under the com.prosyst.mbs.services.datamapper.DataMapper interface. For details on the methods provided by the service, refer to the Data Mapper API documentation.

Custom Function Evaluator Service

The Custom Function Evaluator service provides means to create custom functions. It is registered under the com.prosyst.mbs.services.datamapper.CustomFunctionEvaluator interface. For details on its usage, refer to the Data Mapper API documentation.

To provide custom functions in an application, you just have to implement the evaluate method and register a Custom Function Evaluator service in the framework.

System Properties

Data Mapper Demo

Data Mapper demo provides a simple data mapping XML and performs data conversion according to it on both the directions: it creates a Dictionary of Java objects out of a short byte array and vise versa.

The JAR file of the Data Mapper demo is datamapperdemo.jar and is located in the demo/bundles directory. The other components of the demo are placed in demo/framework/datamapper folder. You can conveniently install and start the demo from its Kit Manager script.

References

• Data Mapper API documentation
• JEVAL-ProSyst Bundle

Utility Bundles