Data manipulation

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

The framework allows to use several ways to get and set data values:

• Default Data manipulation: The default way, which allows to navigate through the data structure
• Mapping a data type to a class : By mapping a data type to a class through class annotations
• Data manipulation by using a value to set a Data : By using a Data created in the module to set or get the value of the Service data

Note that if you have a service containing complex data structures, and you need to use them in several modules, but you don't want to decode the structure for each module, it is possible to distribute them as objects. See distributing data structures as objects.

Data types

This paragraph explains the correspondance between data types and their associated Java type.

Simple data types

simple Data types have their corresponding associated Java type:

Data type	Java Type	Data class
char	char	Data.Char
short	short	Data.Short
byte	byte	Data.Byte
int	int	Data.Int
long	long	Data.Long
float	float	Data.Float
double	double	Data.Double
boolean	boolean	Data.Bool
string	String	Data.Str
xmlType	String, see XML values	Data.Xml
jsonType	String, see JSON values	Data.JSON
enumType	int, see enumerations	Data.Enum

Complex Data types

Complex data types have their corresponding associated Java type:

Data type	Java Type	Data class
array	List	Data.Array
structure	List	Data.Structure
union	List	Data.Union
map	Map	Data.MapData

Specific simple data types

Enumerations

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

• Getting the value^[1]
  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

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()

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.

Getting a default for a Type

The Type.getDefaultValue() will return a default value for any type.

Note that for complex types (such as arrays or structures), a new default value will be instanciated each time, so for example with this type specification:

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

The following code will work correctly:

      ArrayType myArray = (ArrayType)module.getType("arrayOfInt");
      List<Object> firstInstance =  myArray.getDefaultValue();
      firstInstance.add(1);
      List<Object> secondInstance =  myArray.getDefaultValue();
      int size = secondInstance.getSize(); // size is equal to 0

Casting a value for a Type

Many specific methods allow to cast any value to a value corresponding to the type. For example, suppose the following type specification:

      <types>
         <simpleType name="int" baseType="int" />
      </types>

We will have:

      Type myInt = module.getType("int");
      String str = myInt.getValueAsString(2); // str is "2"

Casting a String value for an EnumType

For enumerations, the Type.getValueAsString(Object) will return the state name if possible. For example, with the following enumeration specification:

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

We will have:

      EnumType myEnum = (EnumType)module.getType("intEnum");
      String str = myEnum.getValueAsString("ONE"); // str is "ONE"
      str = myEnum.getValueAsString(1); // str is "TWO"
      str = myEnum.getValueAsString(2); // str is "2"
      str = myEnum.getValueAsString("TUTU"); // str is null     

The EnumType.getProtectedStateValueAsString(Object) will return a guaranteed state value as a String. It a corresponding state does not exist, the first state name will be returned. For example, with the same enumeration:

      EnumType myEnum = (EnumType)module.getType("intEnum");
      String str = myEnum.getProtectedStateValueAsString("ONE"); // str is "ONE"
      str = myEnum.getProtectedStateValueAsString(1); // str is "TWO"
      str = myEnum.getProtectedStateValueAsString(2); // str is "ONE"
      str = myEnum.getValueAsString("TUTU"); // str is "ONE"    

Make copies of datas

It is possible to make copies of datas. Two methods allow to make copies from one data to another, regardless of their service:

• The Data.copy(Data, boolean) method allow to make a copy, specifying if the copy must take care of the corrrsponding type of the datas
• The Data.copy(Data, boolean) method is a shortcut to the copy(Data fromData, true) vesion of the previous method