Mapping a data type to a class

The default way to manipulate complex data types is described in the Basic Data manipulation article.

However, there is a more direct way to manipulate complex data structures, by mapping a type to a class through annotations. This allows to directly set a Data by providing a class with a specification annotation rather than setting the whole data type graph. This is useful if you have unions or structures in your types graph.

Overview

The idea is to represent a structure by a class where each field is associated with an annotated field. This way, it is possible to set the value of the structure by just directly using an instance of this class as argument rather than setting the value of each field:

• The DataTag annotation is used to specify that a Class is used to represent a structure
• The FieldTag annotation is used to specify the structure field which is associated with the annotated Class field

For a tutorial showing how to use it on an example, see Type annotation mapping tutorial.

Example

For example, if we have the following structure type definition:

      <types>
         <simpleType name="bool" baseType="boolean" />
         <simpleType name="int" baseType="int" />
         <structType name="struct">
            <field name="field1" type="bool" />
            <field name="field2" type="int" />
         </structType>
      </types>

And the associated service definition:

      <services>
         <event name="myService" >
            <data name="myStruct" type="struct" />
         </event>
      </services>

The regular way to set the value for the fields would be:

      // get the structure
      Data.Structure struct = (Data.Structure)service.getData("myStruct");
      // set the value true for the "field1" field
      struct.setFieldBooleanValue("field1", true);
      // set the value 23 for the "field2" field
      struct.setFieldIntValue("field2", 23);

But we can also define an annotated class:

      @DataTag
      public class MyStruct {
        @FieldTag(field="field1")
        public boolean b;
        @FieldTag(field="field2")
        public int i;
      }

Then we will be able to use directly instances of this class as values:

      // get the structure
      Data struct = service.getData("myStruct");
      MyStruct str = new MyStruct();
      str.i = 23;
      str.b = true;
      // set the value for the whole structure
      struct.setValue(str);