hAPI Datamodel v 0.3.0

The hAPI datamodel defines semantics core to the Hubiquitus platform. It defines the core concepts of the hubiquitus programming model, the data structures associated with it and the way data is transmitted and processed through the network.

API heavily relies on JSON, which has been preferred to XML for two main reasons :

• Efficiency : JSON is structured but lightweight ; it is a perfect choice for exchanging data over constraint networks such as wireless mobile networks.
• Web-readiness: as a Web fellow, JSON is natively understood by any web browser complying to the W3C standards ; it is today the best candidate for an ubiquitous format (please notice that the hAPI model could easily be translated to any other structured semantic such as XML).

HAPI objects are internally JSON Objects. Getters and setters are convenient functions to set and access JSON object values.

Hubiquitus defines a set of basic data structure used to express elementary piece of typed data:

• Commands :
  • Hcommand
  • HResult
  • HStatus
• Messages :
  • HMessage
  • HMessage Payload :
    • HMeasure
    • HAlert
    • HAck
    • HConv
• Metadata :
  • HLocation

Commands

HCommand

The purpose of a hCommand is to execute an operation on a specific component, a hubot or a hServer.

public class HCommand implements HJsonObj {
	
	private JSONObject hcommand = new JSONObject();
	
	public HCommand() 
	
	public HCommand(String entity, String cmd, HJsonObj params) 
	
	public HCommand(JSONObject jsonObj)

        //Getters, Setters and HJsonObj implementation ...
}

Here is an enumeration of these properties :

• reqid : Request id. Do not fill. Filled by hapi.
• requester : Requester jid. (For request made on behalf of someone)
• sender : Sender jid. Do not fill. Filled by hapi.
• entity : entity that will execute the command (a hubot or the hserver for example). Mandatory.
• sent : Time at which the command has been requested. Mandatory. Filled by hapi if empty.
• cmd : Name of the command which will be executed. Mandatory.
• params : Parameters of the command.
• transient : Define if the message is persistant or volatile. If true, the message is volatile. By default, the value is true.

equals() checks are made on : reqid, requester, sender, entity, sent, cmd and transient

HResult

Describes how the result of a hcommand is serialized :

public class HResult implements HJsonObj {
	
	private JSONObject hresult = new JSONObject();
		
	public HResult() 
	
	public HResult(String reqid, String cmd, HJsonObj result) 

	public HResult(JSONObject jsonObj) 

        //Getters, Setters and HJsonObj implementation ...
}

Here is an enumeration of these properties :

• cmd : name of the command who has been executed.
• reqid : request id.
• status : result status (for more informations see ResultStatus)
• result : Command result object. Command dependent

equals() checks are made on : cmd, reqid and status.

###HStatus

This structure describe the connection status

public class HStatus implements HJsonObj{

	private JSONObject hstatus = new JSONObject();
		
	public HStatus()
	
	public HStatus(JSONObject jsonObj)
	
	public HStatus(ConnectionStatus status ,ConnectionError errorCode ,String errorMsg)

        //Getters, Setters and HJsonObj implementation ...
}

Here is an enumeration of these properties :

• status : currently connection status. For more information, see ConnectionStatus
• errorCode : 0 if no error. For moer information, see ConnectionError
• errorMsg : error message. Null if no error.

equals() checks are made on : status, errorcode and errormsg.

##Messages

###HMessage

HStructure for hubiquitus messages.

public class HMessage implements HJsonObj {
	
	private JSONObject hmessage = new JSONObject();
	
	public HMessage() 
	
	public HMessage(JSONObject jsonObj) 

        //Getters, Setters and HJsonObj implementation ...
}

Here is an enumeration of these properties :

• msgid : Message id. Mandatory. Filled by the hApi.
• chid : Channel id to which the message is published. Mandatory.
• convid : Conversation if to which the message belongs. Mandatory. Filled by the hApi if empty.
• type : Type of the message payload.
• priority : Message priority. If UNDEFINED, priority lower to 0.
• relevance : Define is the message is persistent. If true, the message is not persistent. True by defaut.
• location : The geographical location to which the message refer. See HLocation below.
• author : Author's id of this message.
• publisher : Publisher id. Mandatory.
• published : The date and time at which the message has been published.
• headers : The list of headers attached to this message. It is possible to not specify any header.
• payload : The content of the message.

equals() checks are made on : msgid, chid, convid, type, priority, relevance, transient, author, publisher, published and location.

###HMessage Payload :

####HMeasure

HStructure for measure payload.

public class HMeasure implements HJsonObj{

	private JSONObject hmeasure = new JSONObject();
		
	public HMeasure() 
	
	public HMeasure(JSONObject jsonObj)

        //Getters, Setters and HJsonObj implementation ...
}

Here is an enumeration of these properties :

• unit : Unit in which the measure is expressed, should be in lowercase. (ie : "celsius" , "fahrenheit")
• value : Specify the value of the measure (ie : "31.2")

equals() checks are made on : value, unit.

####HAck

hAPI allows to attach acknowledgements to each message Acknowledgements are used to identify the participants that have received or not received, read or not read a message. When a hMessage contains a such kind of payload, the convid must be provided with the same value has the acknowledged hMessage.

public class HAck implements HJsonObj{

	private JSONObject hack = new JSONObject();
		
	public HAck() 
	
	public HAck(JSONObject jsonObj)

        //Getters, Setters and HJsonObj implementation ...
}

Here is an enumeration of these properties :

• ackid : message id of the message to which this acknowledgment refers.
• ack : The status of the acknowledgement. See AckValue

equals() checks are made on : ackid, ack.

####HAlert

HStructure for alert payload. For a such kind of payload, the hMessage’s priority should be greater or equals to 2 and may be greater than the default channel’s priority.

public class HAlert implements HJsonObj{

	private JSONObject halert = new JSONObject();
		
	public HAlert() 
	
	public HAlert(JSONObject jsonObj)

        //Getters, Setters and HJsonObj implementation ...
}

Here is an enumeration of these properties :

• alert : Description of the alert

equals() checks are made on : alert.

####HConv

Any hubot or hubapp user can initiate a conversation Each participant is identified with its JID (full and bare JIDs are supported) This kind of payload is used to describe the metadata of a conversation identified by its convid. A conversation can have different instance of hConv object, the last one will be considered as the most relevant.

public class HConv implements HJsonObj{

	private JSONObject hconv = new JSONObject();
		
	public HConv()
	
	public HConv(JSONObject jsonObj)

        //Getters, Setters and HJsonObj implementation ...
}

Here is an enumeration of these properties :

• topic : Brief description of the topic of the conversation.
• participants : List of the participants id

equals() checks are made on : topic.

###Metadata

####HLocation

HStructure for hubiquitus location.

public class HLocation implements HJsonObj{

	private JSONObject hlocation = new JSONObject();
		
	public HLocation() {};
	
	public HLocation(JSONObject jsonObj)

        //Getters, Setters and HJsonObj implementation ...
}

Here is an enumeration of these properties :

• lat : Latitude of the location
• lng : Longitude of the location
• zip : Zip code of the location
• addr : Address of the location
• city : City of the location
• country : Country of the location
• extra : Additional field for user-defined use. It can be filled with application specific data.

equals() checks are made on : lng, lat, zip, address, city and country.