Data types

Data types are the types of the datas which are used by services. There are several types which can be used for datas used in Services:

• Simple types: a type which is an alias to a primitive type (boolean, integer, etc..)
• Switch types: a type which represent one of a list of specified types
• Array types: an array of elements of another type
• Structure types: a structure (each field having a specified type)
• Union types: a Union (each member having a specified variant)
• Map types: a Map which maps keys to values
• Object types: an type which maps to a serializable class

Note that it is perfectly valid to compose types with other types. For example if is possible to define an array composed of elements of a structure type.

Simple types

A simple type can have one of the following primitive types:

• char
• short
• byte
• int
• long
• float
• double
• boolean
• string
• xmlType: a type for XML datas
• jsonType: a type for JSON datas
• urlType: a type for URLs
• enumType: a type of datas which are integers (as for the int type), but with specified enumeration values

String types

String types can have an optional maximum length. For example:

      <types>
         <simpleType name="string1" baseType="string" />
         <simpleType name="string2" baseType="string" maxLength="20" />
      </types>

In this example, the "string1" type does not have a maximum length, but the "string2" type has a maximum length of 20 characters.

Enumeration types

Enumeration types are int types which have specified enumeration states:

• Each state has a name and an optional int value
• The name of the state must be specified in capital letters
• If the values are not defined, the parser will give by default consecutive values to the states

Examples:
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>

Note that enum types are derived from int types, and as such they have the same compatibility map as int types.

Enumeration values

Enumeration values can be specified as int or as hexadecimal values. For example, these specifications are both valid and represent the same enumeration:

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

and:

      <types>
         <enumType name="intEnum" >
            <enumValue name="ONE" value="0x10" />
            <enumValue name="TWO" value="0x20"/>
         </enumType>
      </types>

URL types

URL types represent URLs. The optional attributes are:

• fileExist: indicates if the URL must exist. The supported values are:
• any: (the default) the existence of the URL is not important
• exist: the URL must exist
• notExist: the URL must not exist
• fileType: indicates the type of the URL. The supported values are:
• any: (the default) the type of the URL is not important
• file: the URL must be a File
• directory: the URL must be a Directory
• extension: the optional extension of the URL

Example:

      <types>
         <urlType name="url" />
         <urlType name="url2" fileExist="exist" fileType="directory"/>
         <urlType name="url2" fileExist="noExist" fileType="file" extension="xml"/>
      </types>

XML types

XML types are string types which can easily be set or get as XML Nodes, or as Strings. It is possible to define an XML Schema for which the type must be consistent.

Example:

      <types>
         <xmlType name="xml" />
         <xmlType name="xml2" schema="schema.xsd"/>
      </types>

JSON types

JSON types are string types which can easily be set or get as JSONElement^[1]

They can be JSONObject or JSONArray

, or as Strings.

Example:

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

Any types

The any type is a built-in simple type which can contain any simple type value. The interest of this type is that the type of the value can change.

For example:

      <types>
         <anyType name="myType" />
      </types>

Nil type

The nil type is a built-in simple type which can be refered to (but not defined). It allows to define a data with an unused value. elements of this type will always have the false value.

For example:

      <types>
         <simpleType name="toggleState" baseType="boolean" />
         <unionType name="guiEvent" variant="int" >
            <member name="button1" type="nil" />
            <member name="button2" type="nil" />
            <member name="toggle1" type="toggleState" />
            <member name="toggle2" type="toggleState" />
         </structType>
      </types>

Simple types units

float and double types can be associated with their unit. The supported units are:

• m: meter
• ft: feet
• in: inch
• nm: nautical mile
• deg: degree
• deg360: degree normalized in the [0, 360] range
• deg180: degree normalized in the [-180, 180] range
• rad: radian
• mrd: milliradian
• tr: "tour" (180 degrees = -0.5, -180 degrees = -0.5)
• m/s: meter per second
• m/s2 or ms2: meter per second squared
• g: G-force
• fr/s: feet per second
• fr/min: feet per minute
• knot: knots
• rad/s: radian per second
• deg/s: degree per second
• kg: kilogram
• lb: pound
• ms: millisecond
• utc: utc
• epoch: epoch
• s: second
• minute: minute
• hour: hour

Note: utc and epoch units are aliases for ms (millisecond).

Simple types default value

Simple types can have a default value. This is the value for each data of this type if the data value is not set. For example:

      <types>
         <simpleType name="selected" baseType="boolean" defaultValue="true" />
         <simpleType name="speed" baseType="float" defaultValue="1.2"/>
         <simpleType name="count" baseType="int" defaultValue="10"/>
         <simpleType name="name" baseType="string" defaultValue="UNNAMED"/>
         <enumType name="intEnum" defaultValue="TWO" >
            <enumValue name="ONE" />
            <enumValue name="TWO" />
         </enumType>
      </types>

If the default value is not set, the framework will set a default value depending on the type:

• 0 for all numeric types
• false for a boolean type
• An empty JSON object for a jsonType type
• An empty String for string and xmlType types

Default values for numeric types can be specified as int or as hexadecimal values. For example:

      <types>
         <simpleType name="count" baseType="int" defaultValue="0x0D"/>
      </types>

Simple types examples

      <types>
         <simpleType name="selected" baseType="boolean" />
         <simpleType name="speed" baseType="float" unit="m/s" />
         <simpleType name="latitude" baseType="double" unit="deg" />
         <simpleType name="longitude" baseType="double" unit="deg" />
         <simpleType name="altitude" baseType="double" unit="ft" />
         <enumType name="intEnum" >
            <enumValue name="ONE" />
            <enumValue name="TWO" />
         </enumType>
      </types>

Alias types

It is possible to define a type as an alias of another one. This can be especially useful if you want to use a nil type type but with your own name.

Example:

      <types>
         <simpleType name="int" baseType="int" />
         <arrayType name="arrayOfInt" type="int" />
         <aliasType name="click" type="nil" />
         <aliasType name="aliasArray" type="arrayOfInt" />
      </types>

Complex types

Switch types

A switch type allows to define a type as one of a list of specified types. For example:

      <types>
         <simpleType name="int" baseType="int" />
         <simpleType name="bool" baseType="boolean" />
         <switchType name="theSwitch" types="int bool" />
      </types>

Each of the possible types is specified by its associated index. For example in the case above, int would have the index 0, and bool the index 1.

Array types

An array type is an array which has an associated element type. Note that by default an array has no specified size, which means that the size of the array can change during runtime.

Example:

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

Arrays can have a specified maximum size. For example:

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

Arrays can also have a specified fixed size^[2]

Of course an array can not have both a maximum and a fixed size. In that case, only the maximum size will be taken into account

. For example:

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

Structure types

A structure type represent a structure for which each field has an associated element type.

Example:

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

Union types

A Union type represent a union for which each member has an associated type.

Example:

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

The "variant" attribute specifies the type of the variant, which must be an "int" type (it can be an enum type).

Use cases

A possible pattern to use unions is for example the case of GUIs, where there are a lot of exclusive actions on the GUI (buttons clicks, changing values, etc...). In this case, it can be more interesting to specify only one Data for an event Service for the GUI, with an union type. For example:

      <types>
         <simpleType name="toggleState" baseType="boolean" />
         <unionType name="guiEvent" variant="int" >
            <member name="button1" type="nil" />
            <member name="button2" type="nil" />
            <member name="toggle1" type="toggleState" />
            <member name="toggle2" type="toggleState" />
         </structType>
      </types>

As you can see, in the above example, events with no associated content, such as button press events, can be associated with a field of the nil type.

It is even possible to combine the usage of unions with an anonymous type.

      <services>
         <event name="guiEvent" >
            <data name="event" type="guiEvent" />
         </event>
      </services>

Map types

A Map type represent a map for which:

• The key has an associated type
• The value has an associated type

Example:

      <types>
         <simpleType name="int" baseType="int" />
         <simpleType name="string" baseType="string" />
         <mapType name="map" keyType="string" valueType="int" />
      </types>

Object types

An object type maps to a serializable class. This means that datas of this type will be instances of the class.

For example, in the following example, datas of the "obj" type will be instances of the my.package.MyClass class:

      <types>
         <objectType name="obj" class="my.package.MyClass" />
      </types>

There are two constraints for the class which backs this type:

• The class must have a no-argument constructor. This will be used to get a default value)^[3]
  This means that the default value is an instance created from this class with a no-argument constructor)
• The class must be serializable. The class will be serialized if passed through a network or to another application
• This type can only be used by Java modules

Using instances or abstract classes

It is possible to use an interface or an abstract class for the type. In this case a concrete subclass of the class should be defined for the default values using the defaultClass attrbute. For example this declaration is incorrect because it is not possible to create a List with an empty constructor.

      <types>
         <objectType name="obj" class="java.util.List" />
      </types>

Instead this declaration is valid:

      <types>
         <objectType name="obj" class="java.util.List" defaultClass="java.util.ArrayList" />
      </types>

Continuous fields and union members

Numeric structure fields or union members can be specified as continuous or not continous. Setting a numeric data as not continuous specifies that even as this data is numeric, the possible values are discrete (as for enumerations).

In the following example, the "aircraftID" field is an int field but its values are not continuous (they correspond to an aircraft ID):

      <types>
         <simpleType name="int" baseType="int" />
         <simpleType name="float" baseType="float" />
         <structType name="struct">
            <field name="aircraftID" type="int" continuous="false" />
            <field name="aircraftLongitude" type="float" />
            <field name="aircraftLatitude" type="float" />
         </structType>
      </types>

Abstract types

structure types and union types have an optional isAbstract attribute which specifies if the type is abstract, meaning that it can not be directly used in a data or a field. For example:

      <types>
         <simpleType name="int" baseType="int" />
         <simpleType name="float" baseType="float" />
         <structType name="abstractPosition" isAbstract="true">
            <field name="latitude" type="float" />
            <field name="lontitude" type="float" />
         </structType>
      </types>

Types compatibility

The framework will always try to cast types when they are compatible, with the same restrictions as in C-like languages. This means that:

• If two simple types have both the same primitive type, they are alias to the same type, and as such they are equivalent
• If two simple types are both numeric types, they can be cast in both ways
• A simple type can always be cast to a String type
• Two array types are equivalent if their element types are compatible
• Two structure types are equivalent if they have the same number of fields and the fields all have compatible types
• Two map types are equivalent if their key and value types both have compatible types

Types compatibility examples

      <types>
         <simpleType name="bool" baseType="boolean" />
         <simpleType name="bool2" baseType="boolean" />
         <simpleType name="int" baseType="int" />
         <simpleType name="int2" baseType="int" />  
         <enumType name="intEnum" >  
            <enumValue name="ONE" />
            <enumValue name="TWO" />       
         </enumType>  
         <enumType name="intEnum2" >  
            <enumValue name="ONE" />
            <enumValue name="THREE" />       
         </enumType>      
         <enumType name="intEnum3" >  
            <enumValue name="ONE" />
            <enumValue name="TWO" /> 
            <enumValue name="THREE" />       
         </enumType>         
         <arrayType name="arrayOfInt" type="int" />
         <arrayType name="arrayOfInt2" type="int" />
         <arrayType name="arrayOfBool" type="bool" />    
         <structType name="struct">
            <field name="intArray" type="arrayOfInt" />
            <field name="enum" type="intEnum" />   
            <field name="int" type="int" />      
         </structType>      
         <structType name="struct2">
            <field name="intArray" type="arrayOfInt2" />
            <field name="enum" type="intEnum" />   
            <field name="int" type="int" />      
         </structType>          
         <structType name="struct3">
            <field name="enum" type="intEnum" />   
            <field name="int" type="int" />      
            <field name="intArray" type="arrayOfInt" />       
         </structType>          
      </types>

In this example:

• "bool" and "bool2" are equivalent
• "int" and "int2" are equivalent
• "arrayOfInt" and "arrayOfInt2" are equivalent
• "struct" and "struct2" are equivalent
• "intEnum" and "intEnum2" are equivalent
• "intEnum" and "int" are not equivalent, but "intEnum" datas can be cast to "int" datas
• "intEnum" and "intEnum3" are not equivalent
• "arrayOfInt" and "arrayOfBool" are not equivalent
• "struct" and "struct3" are not equivalent

Types description

It is possible to add an (optional) string description for any type and field. For example:

      <types>
         <simpleType name="bool" desc="the base boolean type" baseType="boolean" />
         <simpleType name="int" desc="the base int type" baseType="int" />
         <structType name="struct">
            <field name="field1" desc="my first field" type="bool" />
            <field name="field2" desc="my second field" type="int" />
         </structType>
      </types>

Using namespaces

To avoid names clashes, it is possible to define namespaces for types, as it is also possible for services. To define a namespace, you just have to declare the namespace element as a parent of the types declaration^[4]

Of course, you can define more than one namespace in a types XML file

. For example:

      <types>
        <namespace uri="http://mydomain.com/common" >
          <type name="bool">
          <type name="position">
        </namespace>
      </services>

Example

      <types>
         <simpleType name="bool" baseType="boolean" />
         <simpleType name="int" baseType="int" />   
         <enumType name="intEnum" >  
            <enumValue name="ONE" />
            <enumValue name="TWO" />       
         </enumType>  
         <arrayType name="arrayOfInt" type="int" />  
         <structType name="struct">
            <field name="intArray" type="arrayOfInt" />
            <field name="enum" type="intEnum" />   
            <field name="int" type="int" />      
         </structType>      
      </types>

Anonymous types

Normally types are specified in the types configuration file. However types used in datas can be defined directly under the datas which use them^[5]

These types are defined locally to the data which use them and can not be referred in other datas or types

. See anonymous types for more information.