Basic Data manipulation

This article explains the default way get datas and set data values. Each Data for one Service can be retrieved through the ServiceInstance.getData(String).

Several methods in the Data Class allow to get the value directly in any of the simple types, for example:

• Data.getValueAsInt() for an int Data
• Data.getValueAsFloat() for a float Data
• etc...

The data value can also be retrieved directly through the ServiceInstance.getDataValue(String) method or the various getValueAsxxx(String) methods for each specific type.

To set the value of the Data, you can use the Data.setValue(Object) method. Several methods in the Data Class allow to set the value directly in any of the simple types, for example:

• Data.setIntValue(int) for an int Data
• Data.setFloatValue(float) for a float Data
• etc...

All these setValue methods allow a wide extend of compatibility with types^[1]

For example, setting a char value will work with any number type

.

All the methods which set a value will return a short which specify the result of the set:

• DataState.STATE_INVALID if the value could not be set^[2]
  Usually if the type of the value to set is not compatible with the Data type
• DataState.STATE_UNCHANGED if the value has not chang beend changed

Basic data types

Enumerations

Enumeration values are stored as int Datas. As such, as for int values:

• Getting the value^[3]
  The enumeration state
  will return an int
• Setting the value can be performed through the Data.setIntValue(int) method

The int value is the index of the state in the enumeration. For example:
In the following type definition, "ONE" will have the value 0, and "TWO" the value 1:

      <types>
         <enumType name="intEnum" >
            <enumValue name="ONE" />
            <enumValue name="TWO" />
         </enumType>
      </types>

In the following type definition, "ONE" will have the value 1, and "TWO" the value 2:

      <types>
         <enumType name="intEnum" >
            <enumValue name="ONE" value="1" />
            <enumValue name="TWO" value="2"/>
         </enumType>
      </types>

However, several additional methods allow to get or set the value of an enumeration according to the name of the state.

• Data.getValueAsString() will return the name of the state rather than its index
• Data.setValue(Object) or Data.setIntValue(int) will set the value of the state if providing the state index. For example, for the enumeration which is specified above, data.setIntValue(2) will set the state TWO
• Data.setValue(Object) or Data.setStringValue(String) will set the value of the state if providing the state name. For example, for the enumeration which is specified above, data.setStringValue("TWO") will set the state TWO
• DataUtilities.getStateValue(EnumType, String) will get the State value of the enumeration

Example

In the following enumeration type definition:

      <types>
         <enumType name="intEnum" >
            <enumValue name="ONE" />
            <enumValue name="TWO" />
         </enumType>
      </types>

We can for example use the following methods to get its value:

      public void subscribe(ServiceInstance service) {
        // return the index of the enumeration state
        int value = service.getValueAsInt("intEnum");
        // return the name of the enumeration state
        String valueS = service.getValueAsString("intEnum");
      }

And to set the value:

      public void push(ServiceInstance service) {
        // set the enumeration state by its index
        Data data = service.getData("intEnum");
        // set the "TWO" state for the enumeration
        data.setValueAsInt(1);
        // set the "ONE" state for the enumeration
        data.setValueAsString("ONE");
      }

XML values

XML values are XML content modelled as String Datas. They can be set or get as XML Nodes, or as Strings: The Data.Xml datas have two specific methods which allow to get or set the Data value as an XMLNode:

• Data.Xml.getValueAsXML() returns an XMLNode
• The Data.Xml.setValue(Object) accept an XMLNode as the argument

XMLNode

The XMLNode represents an element in the XML structure, this element hold:

• Its name: XMLNode.getName()
• Its attributes: XMLNode.getAttribute(String)
• Its children: XMLNode.getChildren()

Example

Suppose that we have the following types definition:

      <types>
         <xmlType name="xml" />
      </types>

And the associated service definition:

      <services>
         <event name="myService" id="1" >
            <data name="xmlData" type="xml" />
         </event>
      </services>

If the publisher module sends the following xmlData content^[4]

It is also possible to set a value as an XMLNode on the publisher side rather than as a raw String

:

      <root>
         <child name="theName" />
      </root>

Then we could write the following code on the receiver module:

      public void subscribe(ServiceInstance service) {
        // return the XML root node
        XMLNode node = service.getValueAsXML("xmlData");
        // will return the "child" child
        XMLNode theChild = node.getChildren().get(0);
        // will return the "theName" String
        String attrValue = theChild.getAttribute("name");
      }

JSON values

JSON values are JSON content modelled as String Datas. They can be set or get as JSONObject, or as Strings: The Data.JSON datas have two specific methods which allow to get or set the Data value as a JSONObject:

• Data.JSON.getValueAsJSON() returns a JSONObject
• The Data.JSON.setValue(Object) accept a JSONObject as the argument

The library which is used to manipulate JSON content is github.com/hervegirod/JSON-java.

Example

Suppose that we have the following types definition:

      <types>
         <jsonType name="json" />
      </types>

And the associated service definition:

      <services>
         <event name="myService" id="1" >
            <data name="jsonData" type="json" />
         </event>
      </services>

If the publisher module sends some jsonData content^[5]

It is also possible to set a value as a JSONObject on the publisher side rather than as a raw String

:

Then we could write the following code on the receiver module:

      public void subscribe(ServiceInstance service) {
        // return the json object
        JSONObject jsonObj = service.getValueAsJSON("jsonData");
      }

Complex data types

The following paragraphs describe how to manipulate complex data types ( arrays, structures, or unions), by manipulating the content of the data.

However, there is a more direct way to manipulate complex data structures, by mapping a type to a class through annotations. See Mapping a data type to a class.

Array types

The value for an array is a List of Objects, each index in the list is an element in the Array.

Example

In the following array type definition:

      <types>
         <simpleType name="int" baseType="int" />
         <arrayType name="arrayOfInt" type="int" />
      </types>

We can for example use the following method to get the "arrayOfInt" value:

      public void subscribe(ServiceInstance service) {
        // return the array
        List<Object> array = service.getValueAsArray("arrayOfInt");
      }

To add new elements or update existing elements for this array, we just have to add new values to the list, for example:

      // get the array
      List<Object> array = service.getValueAsArray("arrayOfInt");
      
      // set the value 23 at index 0
      array.set(0, 23);
      
      // add an element to the array
      array.add(24);

We also can do the same thing using the Data.Array itself. For example:

      // get the data array
      Data.Array array = (Data.Array)service.getData("arrayOfInt");
      
      // set the value 23 at index 0
      array.setValue(23, 0);
      
      // add an element at the end of the array
      array.pushValue(24);
      
      // remove the last element of the array
      array.popValue();

Structure types

The value for a structure is a List of Objects, each index in the list is the value for one field in the structure. The order in the list is the order of the field definitions in the structure type, but it is better to use utility methods which will take care of the position of the fields for you.

For that, you will have to cast the Data to a Data.Structure which has several methods allowing to get or set the value of a particular field:

• Data.Structure.getFieldValue(String) and all the type-specific getFieldValueAsxxx(String) methods return the value of a field with a specified name
• Data.Structure.setFieldValue(String, Object) and all the type-specific setFieldxxxValue(String, Object) methods set the value of a field with a specified name

Example

In 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" id="1" >
            <data name="myStruct" type="struct" />
         </event>
      </services>

We can for example use the following methods to get the "myStruct" value for its associated fields:

      public void subscribe(ServiceInstance service) {
        // get the structure
        Data.Structure struct = (Data.Structure)service.getData("myStruct");
        boolean b = struct.getFieldValueAsBoolean("field1");
        int i = struct.getFieldValueAsInt("field2");
      }

If we want to change the value for a field, we can perform:

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

Union types

The value for a union is a List of Objects:

• The first index represents the int value of the variant^[6]
  Note that the variant can be of any int type, which means that the variant can be an enumType
• The second index represents the value of the member for the specified variant

Methods in the Data.Union and UnionType allow to get or set the value of the variant or the current member:

• Data.Union.getVariant() returns the value of the variant
• Data.Union.getMemberValue() returns the member value
• Data.Union.setMemberValue(int, Object) set the value of the Union for a specified variant
• Data.Union.setMemberValue(String, Object) set the value of the Union for a specified member name

Example

In the following structure type definition:

      <types>
         <simpleType name="bool" baseType="boolean" />
         <simpleType name="int" baseType="int" />
         <unionType name="union" variant="int" >
            <member name="member1" type="bool" />
            <member name="member2" type="int" />
         </unionType>
      </types>

And the associated service definition:

      <services>
         <event name="myService" id="1" >
            <data name="myUnion" type="union" />
         </event>
      </services>

We can for example use the following methods to get the "myUnion" value for its current variant:

      public void subscribe(ServiceInstance service) {
        // get the union
        Data.Union union = (Data.Union)service.getData("myUnion");
        Object value = union.getMemberValue();
        int variant = union.getVariant();
      }

If we want to change the current value, we can perform:

      // get the union
      Data.Union union = (Data.Union)service.getData("myUnion");
      // set the value true for the "member1" variant
      union.setMemberValue("member1", true);
      }

Composite data types

The previous paragraphs explained how to get or set the values for simple datas or arrays or structures of simples datas. But you can also get or set the values for datas of arbitrary structuration^[7]

For example, arrays of structures, or structures for which some fields are arrays

.

• The first step is to get the "Object" value for the Data array or structure
• Then you can use the associated type of the array elements or the field to get or set the desired value. For example, for a structure, you can use the methods in the StructType class, such as for example StructType.getFieldValue(String, Object) or StructType.setFieldValue(String, Object, Object)

Example: an array of structure

Suppose the following types declaration:

      <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>
         <arrayType name="arrayOfStruct" type="struct" />
      </types>

And the associated service definition:

      <services>
         <event name="myService" id="1" >
            <data name="myStructArray" type="arrayOfStruct" />
         </event>
      </services>

To get the value of various fields in the array of structure, we can perform:

      public void subscribe(ServiceInstance service) {
        // get the array
        Data.Array data = (Data.Array)service.getData("myStructArray");
        List<Object> array = data.getValueAsArray();
        // get the array type (the type of the elements of the array are structures of the "struct" type:
        StructType type = (StructType)data.getElementsType();

        // get the first element of the array (note that this is a List)
        Object elt = array.get(0);
        // get the "field1" field
        boolean b = type.getFieldValueAsBoolean("field1", elt);
        // get the "field2" field
        int i = type.getFieldValueAsInt("field2", elt);
      }

To set the value of the array for an index and a field, we can perform:

      // get the array
      Data.Array data = (Data.Array)service.getData("myStructArray");
      List<Object> array = data.getValueAsArray();
      // get the array type (the type of the elements of the array are structures of the "struct" type:
      StructType type = (StructType)data.getElementsType();

      // get the first element of the array (note that this is a List)
      Object elt = array.get(0);
      // set the "field1" field value
      type.setFieldValueAsBoolean("field1", elt, true);
      // set the "field2" field
      type.setFieldValueAsInt("field2", elt, 23);

To add another element for the array, we must first create a default value for the structure:

      // get the array
      Data.Array data = (Data.Array)service.getData("myStructArray");
      List<Object> array = data.getValueAsArray();
      // get the array type (the type of the elements of the array are structures of the "struct" type:
      StructType type = (StructType)data.getElementsType();

      // create a new element with default values for the fields for the structure
      List<Object> elt = type.getDefaultValue();
      // add the element to the array
      array.add(elt);
      // set the "field1" field value
      type.setFieldValueAsBoolean("field1", elt, true);
      // set the "field2" field
      type.setFieldValueAsInt("field2", elt, 23);

Example: a structure with a structure field

Suppose the following types declaration:

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

And the associated service definition:

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

To get the value of the structField field in the internalStruct structure, we can perform:

      public void subscribe(ServiceInstance service) {
        // get the structure
        Data.Structure data = (Data.Structure)service.getData("myStructure");
        List<Object> structValue = data.getFieldValueAsStructure("structField");
      
      - // get the type of the internalStruct structure
        StructType structType = (StructType)module.getType("internalStruct");
      
        // get the "field2" field of this structure
        int i = type.getFieldValueAsInt("field2", structValue);
      }

To set the value of the structure for this field, we can perform:

      // get the structure
      Data.Structure data = (Data.Structure)service.getData("myStructure");
      List<Object> structValue = data.getFieldValueAsStructure("structField");
      
      // get the type of the internalStruct structure
      StructType structType = (StructType)module.getType("internalStruct");

      // set the value of the "field2" field of this structure
      structType.setFieldValueAsInt("field2", structValue, 10);

Example: a structure with an array field

Suppose the following types declaration:

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

And the associated service definition:

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

To get the value of the array field, we can perform:

      public void subscribe(ServiceInstance service) {
        // get the structure
        Data.Structure struct = (Data.Structure)service.getData("myStruct");
        // get the value for the "field2" field, this is an array of int
        List<Object> array = data.getFieldValueAsArray("field2");

        // get the first element of the array
        int elt = (Integer)array.get(0);
      }

Comparing two values

It is possible to compare the current value of a data with any Object, or two Objects of a specified type:

• Data.isEqualsTo(Object) for comparing the current value of a Data to any Object
• Type.areEqual(Object, Object) for comparing two Objects of a specified type

Note that the comparison will cast the values if necessary. For example, these expressions (for int types) will all return true:

      intType.isEqualsTo(5, 5);
      intType.isEqualsTo(5, 5f);

Comparing values for a nil type

Comparing values for the nil type will always return true.

Comparing values for an enum type

To compare enumeration type values, you can use either the int value of the enumeration, or the name of the corresponding state. For example for the following type definition:

      <enumType name="intEnum" >
         <enumValue name="ONE" />
         <enumValue name="TWO" />
      </enumType>

The following expressions will both return true:

      enumType.isEqualsTo(1, 1);
      intType.isEqualsTo(1, "TWO");