Data objects tutorial

This article shows an example where a complex data structure is distributed as an object.

Use case

Suppose that we have a FMS module sending a flightplan service which contains an array of waypoints. Each waypoint is a structure with a latitude and longitude.

The problem with this architecture is that if we have several modules notified of the flightplan service, each one of them will have to decode the content of the data structure upon notification:

Initial implementation

Waypoints service definition

The definition of the flightplan service is the following:

      <event name="flightplan">
         <data name="flightplan" type="waypointArray" />
      </event>

The types used by this service are:

      <simpleType name="float" baseType="float" />
      <arrayType name="waypointArray" type="waypoint" />
      <structType name="waypoint">
         <field name="latitude" type="float" />
         <field name="longitude" type="float" />
      </structType>

Initial applications definition

We have the following definition for the applications:

      <application name="Aircraft">
         <deployment>
            <lib url="FMS.jar" />
            <lib url="Systems.jar" />
         </deployment>
         <modules>
            <module name="FMS" >
               <implementation path="org.da.aircraft.FMS" >
                  <initEntryPoint method="init" />
                  <startEntryPoint method="start" />
                  <defaultSendEntryPoint method="send" />
               </implementation>
               <interfaces>
                  <eventSend service="flightplan" />
               </interfaces>            
            </module>
            <module name="userModule1" >
               <implementation path="org.da.aircraft.userModule1" >
                  <initEntryPoint method="init" />
                  <startEntryPoint method="start" />
                  <defaultReceiveEntryPoint method="receive" />
               </implementation>
               <interfaces>
                  <eventReceived service="flightplan" />
               </interfaces>              
            </module>
            <module name="userModule2" >
               <implementation path="org.da.aircraft.userModule2" >
                  <initEntryPoint method="init" />
                  <startEntryPoint method="start" />
                  <defaultReceiveEntryPoint method="receive" />
               </implementation>
               <interfaces>
                  <eventReceived service="flightplan" />
               </interfaces>              
            </module>            
         </modules>
      </application>

Flightplan decoding

We will need the following code to decode the flightplan service data:

      public void receive(ServiceInstance service) {
         Data<ArrayType> fpData = (Data<ArrayType>) service.getData("flightplan");
         StructType wptType = (StructType) fpData.getType().getType();
         List<Waypoint> wpts = new ArrayList<>
         List<Object> array = fpData.getValueAsArray();
         Iterator<Object> it = array.iterator();
         while (it.hasNext()) {
           Object o = it.next();
           float latitude = wptType.getFieldValueAsFloat("latitude", o, Units.DEG);
           float longitude = wptType.getFieldValueAsFloat("longitude", o, Units.DEG);
           Waypoint wpt = new Waypoint();
           wpt.setPosition(latitude, longitude);
           wpts.add(wpt);
         }      
      }

Where the Waypoint class has the following definition:

      public class Waypoint {
         public float latitude = 0f;
         public float longitude = 0f;   
         
         public Waypoint() {
         }
      
        public void setPosition(float latitude, float longitude) {
          this.latitude = latitude;
          this.longitude = longitude;      
        }     
      }

Data objects implementation

We want to use this array of waypoints in several Java modules, but we don't want to decode it in each module. We can define a WaypointsConverter module which will be notified from the waypoints service, will decode the array of waypoints, and send a flightplanObject service which will not contain an array of waypoints but a Waypoints Java object.

The user modules will be notified from the flightplanObject service reception, and will only have to get the Waypoints object from the received data rather than having to make the decoding.

Waypoints object service definition

The definition of the flightplanObject service is the following:

      <event name="flightplanObject">
         <data name="waypoints" type="waypointsObject" />
      </event>

The types used by this service are:

      <objectType name="waypointsObject" class="org.da.Waypoints" />

Applications definition

We have the following definition for the applications:

      <application name="Aircraft">
         <deployment>
            <lib url="FMS.jar" />
            <lib url="Systems.jar" />
         </deployment>
         <modules>
            <module name="FMS" >
               <implementation path="org.da.aircraft.FMS" >
                  <initEntryPoint method="init" />
                  <startEntryPoint method="start" />
               </implementation>
               <interfaces>
                  <eventSend service="flightplan" />
               </interfaces>            
            </module>
            <module name="WaypointsConverter" >
               <implementation path="org.da.aircraft.WaypointsConverter" >
                  <initEntryPoint method="init" />
                  <startEntryPoint method="start" />
                  <defaultReceiveEntryPoint method="receive" />
               </implementation>
               <interfaces>
                  <eventReceived service="flightplan" />
                  <eventSend service="flightplanObject" />
               </interfaces>              
            </module>            
            <module name="userModule1" >
               <implementation path="org.da.aircraft.userModule1" >
                  <initEntryPoint method="init" />
                  <startEntryPoint method="start" />
                  <defaultReceiveEntryPoint method="receive" />
               </implementation>
               <interfaces>
                  <eventReceived service="flightplanObject" />
               </interfaces>              
            </module>
            <module name="userModule2" >
               <implementation path="org.da.aircraft.userModule2" >
                  <initEntryPoint method="init" />
                  <startEntryPoint method="start" />
                  <defaultReceiveEntryPoint method="receive" />
               </implementation>
               <interfaces>
                  <eventReceived service="flightplanObject" />
               </interfaces>              
            </module>            
         </modules>
      </application>

Flightplan decoding

We will create a Flightplan class with the following definition:

      public class Flightplan {
         public List<Waypoint> wpts = new ArrayList<>();   
         
         public Flightplan() {
         }
      
        public List<Waypoint> getWaypoints() {
          return wpts;    
        }     
      }

In our case, we will decode the flightplan service data in the WaypointsConverter module, and send the Waypoints class as an object. The code is exactly the same as the one shown before, except that we will invoke the flightplanObject service after the decoding:

      public void init(Module module) {
         flightplan = new Flightplan();
      }      
      
      public void receive(ServiceInstance service) {
         flightplan.getWaypoints().clear();
         Data<ArrayType> fpData = (Data<ArrayType>) service.getData("flightplan");
         ...
         List<Object> array = fpData.getValueAsArray();
         Iterator<lt;Object> it = array.iterator();
         while (it.hasNext()) {
           Object o = it.next();
           float latitude = wptType.getFieldValueAsFloat("latitude", o, Units.DEG);
           float longitude = wptType.getFieldValueAsFloat("longitude", o, Units.DEG);
           Waypoint wpt = new Waypoint();
           wpt.setPosition(latitude, longitude);
           flightplan.getWaypoints().add(wpt);
         }   
         flightplanObject.getData("waypoints").setValue(flightplan); 
      }

FlightplanObject decoding

The decoding of the flightplanObject service data in the user modules is now much more simple:

      public void receive(ServiceInstance service) {
         Data fpData = service.getData("waypoints");
         Flightplan fp = fpData.getValue();
      }