8. Yocto-common module

The purpose of Yocto-common is to manage all the objects that can contain a VirtualHUB but will not contain the communication layer (that will be managed in the yocto-standalone module).

UML diagram

The diagram is quite straightforward:

• All the objects that can be accessed through an URL are YoctoObject. They have all a common interface to:
• get the name
• get the ProductID
• get the serial number
• get the parent hub
• refresh the object in an immediate or asynchronous way
• The YoctoHub object has to provide all the devices associated
• The YoctoMeteo and YoctoColor need a function to return their values

YoctoObjectImpl

YoctoObjectImpl is an abstract class used by all the yocto-devices, most of the functions are getters and setters except the refresh functions. 

69       public void refresh() { 
70           YoctoMap map = template.query(relativePath); 
71           internalRefresh(map); 
72       } 
73    
74       private void internalRefresh(YoctoMap map) { 
75           YoctoMap module = map.getMap("module"); 
76           logicalName = module.getString("logicalName"); 
77           String newSerialNumber = module.getString("serialNumber"); 
78           if (serialNumber == null || serialNumber.equals("")) 
79               serialNumber = newSerialNumber; 
80           else if (!serialNumber.equals(newSerialNumber)) 
81               throw new IllegalStateException("Internal error"); 
82    
83           refreshObject(map); 
84       } 
85    
86       protected abstract void refreshObject(YoctoMap map);

1. The refresh function basically calls a template with a relative path which depends on the object:
• the hub will always have a relative path: /api.json
• other yoctopuce devices will have the more complex path: /by-serial/<serial>/api.json
2. The template returns an object of type YoctoMap that provides API to access json parsed objects.
3. When this is done, ObjImpl will fill the parameters common to all the objects and delegate to children the rest of the operation.

Now that the synchronous refresh has been described, let's try to describe the asynchronous version:

 
56       public void refresh(final YoctoCallback<Void> callback) { 
57           template.aSyncQuery(relativePath, new YoctoCallback<YoctoMap>() { 
58               public void onSuccess(YoctoMap result) { 
59                   internalRefresh(result); 
60                   callback.onSuccess(null); 
61               } 
62    
63               public void onError(Throwable t) { 
64                   callback.onError(t); 
65               } 
66           }); 
67       }

For the asynchronous refresh, the aSyncQuery from the template is called and a callback will be called when the result has been fetched. When fetched, the first thing to do it to refresh the object and then to call the callback function provided to the function.

YoctoTemplate

The YoctoTemplate is an interface that is implemented in other modules but here is the source code of this interface:

public interface YoctoTemplate { 
24       public YoctoMap query(String relativePath); 
25    
26       public void aSyncQuery(String relativePath, YoctoCallback<YoctoMap> listener); 
27    
28   }

Difficult to be simpler!

YoctoMap

We have seen that the YoctoMap is the object returned by the YoctoTemplate, but what is it? It is a interface that helps us to access the JSON result in a xPath approach:

public interface YoctoMap { 
22    
23       public YoctoMap getMap(String name); 
24    
25       public String getString(String name); 
26    
27       public int getInt(String name); 
28    
29       public YoctoList getList(String name); 
30   }

For example, to access an object, the code: map.getMap("module").getString("logicalName") will allow getting the logicalName of a device.

There is nothing particularly complex in this module, the code consists mainly of implementing the different devices provided by yoctopuce.