apis sofia2sofia2.com/docs/sofia2-apis sofia2.pdf · apis sofia2 página 8/111 3 protocolos de...

APIS SOFIA2

Septiembre 2014

Versión 7

APIs SOFIA2 Página 2/111

1 INDICE

1 INDICE ............................................................................................................................................ 2

2 INTRODUCCIÓN .............................................................................................................................. 7

2.1 REQUISITOS ........................................................................................................................ 7

2.2 OBJETIVOS Y ALCANCE DEL PRESENTE DOCUMENTO .................................................................... 7

3 PROTOCOLOS DE COMUNICACIÓN (KP-SIB).................................................................................... 8

3.1 MQTT ............................................................................................................................... 8

3.1.1 Gateway MQTT no seguro ....................................................................................... 8

3.1.2 Gateway MQTT seguro ............................................................................................. 8

3.2 RESTFUL ............................................................................................................................ 9

3.2.1 Gateway RESTFul ...................................................................................................... 9

3.3 AJAX PUSH (JAVASCRIPT) .................................................................................................... 20

3.3.1 Gateway Ajax Push ................................................................................................. 20

3.4 WEBSOCKET ...................................................................................................................... 21

3.4.1 Gateway Websocket: ............................................................................................. 21

3.5 OTROS PROTOCOLOS .......................................................................................................... 22

4 MENSAJERÍA SSAP ........................................................................................................................ 23

4.1 JOIN ............................................................................................................................... 23

4.1.1 Request: ................................................................................................................. 24

4.1.2 Response: ............................................................................................................... 25

4.1.3 Response antes Request’s Incorrectos: ................................................................. 25

4.2 LEAVE ............................................................................................................................. 28

4.2.1 Request: ................................................................................................................. 28

4.2.2 Response: ............................................................................................................... 28

4.3 QUERY ............................................................................................................................ 29

4.3.1 Query tipo Nativo ................................................................................................... 29

4.3.2 Query tipo SQL-Like ................................................................................................ 34


4.3.3 Query tipo SIB-DEFINED ......................................................................................... 39

4.3.4 Query tipo BDH ...................................................................................................... 42

4.4 INSERT ........................................................................................................................... 45

4.4.1 Request: ................................................................................................................. 45

4.4.2 Response: ............................................................................................................... 45

4.5 UPDATE .......................................................................................................................... 46

4.5.1 Request: ................................................................................................................. 46

4.5.2 Response: ............................................................................................................... 46

4.6 DELETE ........................................................................................................................... 47

4.6.1 Request: ................................................................................................................. 47

4.6.2 Response: ............................................................................................................... 47

4.7 SUBSCRIBE ..................................................................................................................... 48

4.7.1 Request: ................................................................................................................. 48

4.7.2 Response: ............................................................................................................... 49

4.8 UNSUBSCRIBE ................................................................................................................ 50

4.8.1 Request: ................................................................................................................. 50

4.8.2 Response: ............................................................................................................... 50

4.9 INDICATION ................................................................................................................... 51

4.9.1 Response ................................................................................................................ 51

4.10 CONFIG .......................................................................................................................... 52

4.10.1 Request: ................................................................................................................. 52

4.10.2 Response: ............................................................................................................... 52

4.11 BULK .............................................................................................................................. 53

4.11.1 Request: ................................................................................................................. 53

4.11.2 Response: ............................................................................................................... 54

5 API JAVA ...................................................................................................................................... 55

5.1 INTRODUCCIÓN .................................................................................................................. 55


5.2 DEPENDENCIA MAVEN ........................................................................................................ 55

5.3 INTERFAZ KP ..................................................................................................................... 55

5.4 CONECTORES DE PROTOCOLOS EN EL API ............................................................................... 56

5.4.1 MQTT ...................................................................................................................... 56

5.4.2 RESTFul ................................................................................................................... 57

5.4.3 Websocket .............................................................................................................. 60

5.4.4 Extensión con nuevos protocolos .......................................................................... 61

5.5 UTILIDADES DEL API ........................................................................................................... 63

5.5.1 Clase SSAPMessageGenerator ............................................................................... 63

5.5.1 Soporte Binary ........................................................................................................ 64

5.5.2 Clases SSAPMessage y derivadas ........................................................................... 68

5.5.3 Clase SSAPBulkMessage y derivadas: ..................................................................... 70

5.6 EJEMPLO DE USO................................................................................................................ 71

6 API ANDROID ............................................................................................................................... 72

6.1 INTRODUCCIÓN .................................................................................................................. 72

6.2 DISTRIBUCIÓN ................................................................................................................... 72

6.3 INTERFAZ KP ..................................................................................................................... 72

6.4 PARALELISMOS CON EL API JAVA ......................................................................................... 73

6.5 EJEMPLO DE USO................................................................................................................ 73

7 API ARDUINO ............................................................................................................................... 75

7.1 LIBRERÍA KPMQTT ............................................................................................................. 75

7.2 PROTOCOLOS SOPORTADOS ................................................................................................. 76

7.2.1 MQTT ...................................................................................................................... 76

8 API JAVASCRIPT ............................................................................................................................ 77

8.1 LIBRERÍA KP-CORE.JS (DEPRECADA) Y SOFIA2-API-JS_V2<MINOR-VERSION>.JS ............................. 77


8.2.1 Websocket .............................................................................................................. 82


8.2.2 AJAX/AJAX Push...................................................................................................... 82

9 API NODE.JS ................................................................................................................................. 84

9.1 INTRODUCCIÓN .................................................................................................................. 84

9.2 LIBRERÍA KPMQTT.JS ......................................................................................................... 84

9.3 GENERADOR DE MENSAJES SSAP ......................................................................................... 85


9.4.1 MQTT ...................................................................................................................... 89

9.5 EJEMPLO DE USO................................................................................................................ 89

10 API C ............................................................................................................................................. 92

10.1 LIBRERÍA LIBSSAP-CORE-API-C .............................................................................................. 92

10.2 COMPILAR CON MAKE ........................................................................................................ 93


10.4 CARACTERÍSTICAS DEL API ................................................................................................... 93

10.5 FUNCIONES DEL API ........................................................................................................... 93

10.5.1 Funciones de comunicación KP-SIB ........................................................................ 93

10.5.2 Funciones de manejo de mensajes SSAP ............................................................... 96

10.5.3 Estructuras utilizadas en el API ............................................................................ 104

10.6 UTILIDADES ADICIONALES .................................................................................................. 105

10.6.1 cJSON .................................................................................................................... 105

10.7 UTILIZACIÓN DEL API ........................................................................................................ 106

10.7.1 Conectar con la plataforma .................................................................................. 106

10.7.2 Desconectar de la plataforma .............................................................................. 107

10.7.3 Enviar mensaje SSAP ............................................................................................ 108

10.7.4 Procesado de respuesta con cJSON ..................................................................... 109

10.7.5 Liberar memoria de estructuras utilizadas .......................................................... 110

10.8 PARÁMETROS DEL COMPILADOR PARA INCLUIR EL API ............................................................ 110

11 OTRAS APIS ................................................................................................................................ 111


2 INTRODUCCIÓN

2.1 Requisitos

Antes de seguir esta guía se recomienda leer la guía SOFIA2-Conceptos SOFIA2.doc

2.2 Objetivos y alcance del presente

documento

El presente documento pretende describir las diferentes APIs que proporciona la Plataforma

SOFIA para el desarrollo de KPs.


3 PROTOCOLOS DE COMUNICACIÓN (KP-SIB)

En un Smart Space SOFIA el SIB actúa como gateway de comunicación con los KPs

recibiendo mensajes SSAP.

El SIB soporta out-of-the-box varios protocolos de comunicación que permiten a los

KPs conectarse con el SIB

Estos protocolos pueden habilitarse o deshabilitarse por configuración.

El SIB además ofrece el concepto de plugin para poder desarrollar nuevos conectores y

habilitar nuevos protocolos adecuados a necesidades específicas.

A continuación veremos los protocolos que disponibiliza el SIB:

3.1 MQTT

MQTT (Message Queue Telemetry Transport) es un protocolo de conectividad enfocado a M2M

(machine-to-machine) y al IoT (Internet of Things).

Es un protocolo de mensajería ligero basado en TCP y especialmente diseñado para

dispositivos remotos con poca memoria y poco poder de procesamiento. Está basado en un

modelo de mensajería publish/subscribe que facilita la distribución one-to-many.

3.1.1 Gateway MQTT no seguro

El despliegue de la plataforma SOFIA2 en la dirección sofia2.com proporciona el puerto 1880

balanceando a los Gateways MQTT de los SIBs de la plataforma.

Asimismo, si se opta por apuntar directamente a alguna de las instancias del SIB, ambas

instancias tienen Gateways MQTT a través de TCP en los puertos 1883 y 1884.

Este Gateway responde a mensajes MQTT que contengan como payload un mensaje SSAP

enviado remotamente.

3.1.2 Gateway MQTT seguro

El despliegue de la plataforma SOFIA2 en la dirección sofia2.com proporciona el puerto 8883

balanceando a los Gateways MQTT de los SIBs de la plataforma de manera segura utilizando

TCP sobre SSL utilizando el certificado de sofia2.

Asimismo, si se opta por apuntar directamente a alguna de las instancias del SIB, ambas

instancias tienen Gateways MQTT a través de TCP sobre SSL en los puertos 8884 y 8885.

Es necesario solicitar explícitamente a la oficina técnica de Sofia2 el certificado de sofia2.com

para poder hacer uso de él.

http://scfront.cloudapp.net/



Este Gateway responde a mensajes MQTT que contengan como payload un mensaje SSAP

enviado remotamente.

3.2 RESTFul

3.2.1 Gateway RESTFul

El despliegue de la plataforma SOFIA2 en la dirección sofia2.com proporciona un Gateway

RESTFul para realizar operaciones sobre la misma.

Este Gateway trabaja en torno al recurso SSAPResource, que representa junto a los verbos

HTTP del Gateway las distintas operaciones SSAP.

El recurso SSAPResource se describe por el esquema:

<xs:sequence> <xs:element minOccurs="0" name="data" type="xs:string"/> <xs:element minOccurs="0" name="instanceKP" type="xs:string"/> <xs:element name="join" type="xs:boolean"/> <xs:element name="leave" type="xs:boolean"/> <xs:element minOccurs="0" name="ontology" type="xs:string"/> <xs:element minOccurs="0" name="sessionKey" type="xs:string"/> <xs:element minOccurs="0" name="token" type="xs:string"/> </xs:sequence>

Las propiedades son:

join: Si el recurso representa una operación SSAP JOIN, su valor será true.

instanceKP: En caso de que el recurso represente una operación SSAP JOIN

(join=true), su valor será la instancia de KP que hace JOIN con el SIB. Se ignorará en

cualquier otro tipo de operación.

token: En caso de que el recurso represente una operación SSAP JOIN (join=true), su

valor será el token de autenticación para la instancia de KP que solicita la operación.

leave: Si el recurso representa una operación SSAP LEAVE, su valor será true.

data: Contiene los datos de la petición o la respuesta SSAP para cualquier operación

que los necesite.

ontology: Indica la ontología sobre la que se tiene que realizar la operación SSAP

sessionKey: SessionKey de la sesión lógica SSAP para la que se solicita la operación



El Gateway RESTFul acepta y devuelve información en formato json. Por lo que tanto las

peticiones como las respuestas al Gateway llevan en la cabecera el atributo Content-type:

application/json, y el Recurso SSAPResource deberá enviarse en el cuerpo de la petición

codificado como un objeto JSON.

El wadl descriptor del Gateway RestFul puede consultarse en:

http://sofia2.com/sib/services/api_ssap?_wadl

Asimismo, se puede consultar una documentación web del Gateway en

http://sofia2.com/sib/

seleccionando en el menú APIS la opción API RESTFul SOFIA2 y en el menú OBJECTS la

opción SSAPResource:

La correspondencia entre el Gateway RESTFul y el protocolo SSAP es la siguiente:

JOIN: Operación con metodo HTTP POST sobre /api_ssap/v01/SSAPResource/

enviando en el body de la petición un objeto SSAPResource con los atributos:

o join: valor true.

o instanceKP: <nombre de KP>:<instancia de KP>.

o token: Token con el que el KP se identifica.

Ejemplo:

{

http://sofia2.com/sib/services/api_ssap?_wadl

http://sofia2.com/sib/


"join": true,

"instanceKP": "KPvisualizacionHT:KPvisualizacionHT01",

"token": "cbb9364c434543a18dc6efa30dc780eb"

}

LEAVE: Operación con método HTTP POST sobre /api_ssap/v01/SSAPResource/

enviando en el body de la petición un objeto SSAPResource con los atributos:

o leave: valor true.

o sessionKey: sessionKey de la sesion SSAP a cerrar.

Ejemplo:

{

"leave": true,

"sessionKey": "f74babaa-26c5-4b8f-901c-98c3e7254fc"

}

INSERT: Se resuelve de dos modos sobre la BDTR:

o NATIVO: Operación con método HTTP POST sobre

/api_ssap/v01/SSAPResource/ enviando en el body de la petición un objeto

SSAPResource con los atributos:

data: Instancia de la ontología a insertar.

ontology: Ontología sobre la que insertar la instancia.

sessionKey: sessionKey de la sesión SSAP.

Ejemplo:

{

"sessionKey":"5d59872f-4e64-4111-a660-5d7d4e415bad",

"ontology":"SensorTemperatura",

"data":"······"

}

o SQL LIKE: Operación con método HTTP GET sobre

/api_ssap/v01/SSAPResource/ enviando la petición con los siguientes query

params:

$sessionKey: sessionKey de la sesión SSAP.

$query: Sentencia Insert SQL.

$queryType: valor SQLLIKE


Ejemplo:

/api_ssap/v01/SSAPResource?$sessionKey=b0e24264-6606-4682-b816-

49831ec1f5ae&$query=insert into SensorTemperatura (identificador, timestamp,

medida,unidad) values ("Nuevo",1357930309163,0, "C");&$queryType=SQLLIKE

Además se soporta sobre la BDH:

o BDH: Operación con método HTTP GET sobre /api_ssap/v01/SSAPResource/

enviando la petición con los siguientes query params:


$query: Sentencia Insert SQL.

$queryType: valor BDH

Ejemplo:


49831ec1f5ae&$query=insert into SensorTemperatura (identificador, timestamp,

medida,unidad) values ("Nuevo",1357930309163,0, "C");&$queryType=BDH

UPDATE: Se resuelve de dos modos:

o NATIVO: Operación con método HTTP PUT sobre



data: Instancia de ontología a actualizar. Se compone de (Ver ejemplo):

ObjectId de la instancia en la BTDR (Devuelto por el SIB al hacer

el INSERT).

Nuevos datos de la instancia en el mismo formato descrito en el

esquema de sus ontologia

ontology: Ontologia sobre la que realizar la actualización

sessionKey: sessionKey de la sesión SSAP

Ejemplo:

{

"sessionKey":"ab77b168-6389-4d62-aa79-97984037de1a",



"data":"

{"_id":{"$oid": "527a6352c0af4380e54822e1"},

"SensorTemperatura":

{"coordenadaGps":{"altitud":10,

"latitud":40.508277,"longitud":-3.676827},

"identificador":"S_Temperatura_00001",

"medida": 30,

"timestamp":1383678276000,

"unidad": "C"}

}"

}



params:


$query: Sentencia Select SQL.


Ejemplo:


49831ec1f5ae&$query=update SensorTemperatura set

SensorTemperatura.identificador="ST-TA32312" where

SensorTemperatura.identificador = "ST-TA3231-2";&$queryType=SQLLIKE

DELETE: Se resuelve de tres modos:

o NATIVO: Operación con método HTTP DELETE sobre



data: Instancia de ontología a eliminar. Contiene el ObjectId de la

instancia en la BTDR (Devuelto por el SIB al hacer el INSERT).

(Ver Ejemplo)

ontology: Ontologia sobre la que realizar el borrado.

sessionKey: sessionKey de la sesión SSAP.



params:



$query: Sentencia Delete SQL.


Ejemplo:


49831ec1f5ae&$query=delete from SensorTemperatura where

SensorTemperatura.identificador = "ST-TA3231-2";&$queryType=SQLLIKE

o Por ID como path param: Esta opción no es RESTFul, pero se ha incluido en

el API por facilidad de utilización.

Operación con método HTTP DELETE sobre el path /api_ssap/v01/{objectId}

con los siguientes parámetros:

{objectId}: Path param con el ObjectId de la instancia a borrar.

$sessionKey: Query param con la sessionKey de la sesión SSAP.

$ontology: Query param con la ontologia sobre la que realizar el

borrado.

Ejemplo:

/api_ssap/v01/SSAPResource/527a6346c0af4380e54822db?$sessionKey=fe70c

11e-6ca1-4cad-8cfd-737cdfe0277a&$ontology=SensorTemperatura

QUERY: Se resuelve de 4 modos distintos sobre la BDTR

o NATIVA por criterios: Operación con método HTTP GET sobre


params:


$query: Criterios de búsqueda nativos (Cuerpo del find()).

$ontology: Ontologia sobre la que realizar la busqueda

$queryType: valor NATIVE

Ejemplo:

/api_ssap/v01/SSAPResource?$sessionKey=fe70c11e-6ca1-4cad-8cfd-

737cdfe0277a&$ontology=SensorTemperatura&$query={"SensorTemperatura.m

edida":{$gt:30}}&$queryType=NATIVE


o Sentencia NATIVA: Operación con método HTTP GET sobre


params:


$query: sentencia de búsqueda nativa sobre la BDTR.

$queryType: valor NATIVE

Ejemplo:

/api_ssap/v01/SSAPResource?$sessionKey=fe70c11e-6ca1-4cad-8cfd-

737cdfe0277a&$query=db.SensorTemperatura.find({"SensorTemperatura.medid

a":{$gt:30}})&$queryType=NATIVE



params:


$query: sentencia de tipo Select SQL.

$queryType: valor SQLLIKE.

Ejemplo:

/api_ssap/v01/SSAPResource?$sessionKey=<session_key>&$query=delete

from SensorTemperatura where SensorTemperatura.identificador = "ST-

TA32311";&$queryType=SQLLIKE

o Query SIB DEFINED: Operación con método HTTP GET sobre


params:


$query: Identificador de la sentencia SIB_DEFINED en el SIB.

$queryType: valor SIB_DEFINED.

$queryArguments: Si la query predefina admite parámetros, mapa

JSON con los pares clave-valor de los argumentos de la query.

Ejemplo:

/api_ssap/v01/SSAPResource?$sessionKey=<session_key>&$query=selectAll

WithParam&$queryArguments={"PARAM1":"\"S_Temperatura_00001\""}&$quer

yType=SIB_DEFINED


Además se soporta sobre la BDH:

o BDH: Operación con método HTTP GET sobre /api_ssap/v01/SSAPResource/

enviando la petición con los siguientes query params:


$query: Sentencia Select SQL.

$queryType: valor BDH

Ejemplo:

/api_ssap/v01/SSAPResource?$sessionKey=<session_key>&$query=delete

from SensorTemperatura where identificador = "ST-

TA32311";&$queryType=BDH

CONFIG: Operación con metodo HTTP GET sobre

/api_ssap/v01/SSAPResource/config enviando en el body de la petición un objeto


o kp: <nombre de KP>

o instancekp: <instancia de KP>.

o token: Token con el que el KP se identifica.

Ejemplo:

{

"kp": “KPvisualizacionHT”,

"instancekp": "KPvisualizacionHT01",

"token": "cbb9364c434543a18dc6efa30dc780eb"

}

La respuesta de cada operación, con los posibles códigos de error es la siguiente:

JOIN

Resultado Codigo Respuesta Cuerpo Respuesta

Correcto 200 (OK) SSAPResource con la sessionKey

asignada

Parámetros vacios 400 (BAD_REQUEST) Mensaje descriptivo

Instancia de KP no 401 (UNAUTHORIZED) Mensaje descriptivo



existe

Token erróneo 401 (UNAUTHORIZED) Mensaje descriptivo

Otro error 501

(INTERNAL_SERVER_

ERROR)

Información del error

LEAVE


Correcto 200 (OK) vacio


sessionKey

incorrecta

400 (BAD_REQUEST) Mensaje descriptivo

Otro error 501

(INTERNAL_SERVER_

ERROR)


INSERT


Correcto 200 (OK) SSAPResource con el objectId asignado

a la instancia de ontología en BDTR


sessionKey

incorrecta


Ontologia no existe 400 (BAD_REQUEST) Mensaje descriptivo

Operación no

permitida sobre la

ontología

403 (FORBIDDEN) Mensaje descriptivo

Instancia de

ontología a insertar

no cumple




validación del

esquema

Otro error 501

(INTERNAL_SERVER_

ERROR)


UPDATE




sessionKey

incorrecta



Operación no

permitida sobre la

ontología


No existe instancia

de la ontología a

actualizar


Otro error 501

(INTERNAL_SERVER_

ERROR)


DELETE




sessionKey

incorrecta





Operación no

permitida sobre la

ontología


No existe instancia

de la ontología a

borrar


Otro error 501

(INTERNAL_SERVER_

ERROR)


QUERY


Correcto 200 (OK) SSAPResource con el resultado de la

consulta


sessionKey

incorrecta



Operación no

permitida sobre la

ontología


queryType invalido 400 (BAD_REQUEST) Mensaje descriptivo

Identificador de

query predefina no

existe en SIB


Falta argumento

en query

predefinida


Otro error 501

(INTERNAL_SERVER_

ERROR)



CONFIG


Correcto 200 (OK) SSAPResource con el resultado de la

consulta


Otro error 501

(INTERNAL_SERVER_

ERROR)


3.3 Ajax Push (Javascript)

AJAX (Asynchronous JavaScript And XML - JavaScript asíncrono y XML) es una técnica de

desarrollo web para crear aplicaciones interactivas o RIA (Rich Internet Applications). Estas

aplicaciones se ejecutan en el cliente, es decir, en el navegador de los usuarios mientras se

mantiene la comunicación asíncrona con el servidor en segundo plano.

Ajax es una tecnología asíncrona, en el sentido de que los datos adicionales se solicitan al

servidor y se cargan en segundo plano sin interferir con la visualización ni el comportamiento

de la página.

Ajax Push posibilita la interacción con el código java del servidor a través del javascript del

navegador y a la inversa: hacer llamadas a funciones javascript del navegador del usuario

desde el código del servidor (Ajax inverso), y modificar las páginas web con los resultados de

las ejecuciones de forma transparente para el usuario.

3.3.1 Gateway Ajax Push

El despliegue de la plataforma SOFIA2 en la dirección sofia2.com proporciona un Gateway Ajax

y Ajax Push. Y mediante la librería Javascript kp-core.js o sofia2-api-js_v<version>.js que

debe importar el cliente para interoperar con el SIB.

La forma de importar la librería es a través de la etiqueta <script>

<script type='text/javascript' src='kp-core.js'>;</script>

http://es.wikipedia.org/wiki/JavaScript

http://es.wikipedia.org/wiki/XML

http://es.wikipedia.org/wiki/Desarrollo_web

http://es.wikipedia.org/wiki/Rich_Internet_Application

http://es.wikipedia.org/wiki/Cliente_%28inform%C3%A1tica%29

http://es.wikipedia.org/wiki/Navegador_web

http://es.wikipedia.org/wiki/As%C3%ADncrono



Un ejemplo de uso de la librería.

/* Por ejemplo para conectar con el SIB, podríamos implementarnos la siguiente función que

invoca a la operación join, pasando como parámetros el usuario, password, la instancia y el

mensaje SSAP*/

function conectarSIB(user, pass, inst) { join(user, pass, inst,function(mensajeSSAP){ if(mensajeSSAP != null && mensajeSSAP.body.data != null && mensajeSSAP.body.ok == true){ $("#infoConexion").text("Conectado al sib con sessionkey: "+mensajeSSAP.sessionKey).show(); }else{ $("#infoConexion").text("Error conectando del sib").show(); } }); }

3.4 Websocket

WebSocket es una tecnología que proporciona un canal de comunicación bidireccional y full-

duplex sobre un único socket TCP. Está diseñada para ser implementada

en navegadores y servidores web, pero puede utilizarse por cualquier aplicación

cliente/servidor.

El uso de esta tecnología proporciona una funcionalidad similar a la apertura de varias

conexiones en distintos puertos, pero multiplexando diferentes servicios WebSocket sobre un

único puerto TCP (a costa de una pequeña sobrecarga del protocolo)..

Navegadores que actualmente soportan WebSocket son:

3.4.1 Gateway Websocket:

El despliegue de la plataforma SOFIA2 en la dirección sofia2.com proporciona un Gateway

Websocket. En el endpoint ws://sofia2.com/sib/api_websocket

http://es.wikipedia.org/wiki/Duplex_(telecomunicaciones)#Full-duplex

http://es.wikipedia.org/wiki/Duplex_(telecomunicaciones)#Full-duplex

http://es.wikipedia.org/wiki/Socket_de_Internet

http://es.wikipedia.org/wiki/Transmission_Control_Protocol

http://es.wikipedia.org/wiki/Navegador_web

http://es.wikipedia.org/wiki/Servidor_web

http://es.wikipedia.org/wiki/Multiplexaci%C3%B3n



3.5 Otros protocolos

En el roadmap de SOFIA está la incorporación de otros protocolos, como:

AMQP (Advanced Message Queuing Protocol) protocolo estándar abierto de la capa de

aplicación para mensajería. Permite interoperabilidad entre diferentes sistemas. Es

independiente del lenguaje y de la implementación. Incluye patrones Point To Point,

Publish, Subscribe, Fan-Out y Request-Response. Entre las implementaciones más

conocidas está RabbitMQ, OpenAMQ, StormMQ.

JMS (Java Message Service) API que forma parte de la plataforma J2EE para acceder

a Sistemas de Mensajería (MOM). Permite a los componentes de aplicaciones crear,

enviar, recibir y leer mensajes. JMS ofrece un interfaz de acceso común a diferentes

MOMs. Las implementaciones JMS soportan acceso a mensajería P2P y

Publish/Suscribe.

WebSockets: Estándar HTML5 que permiten comunicación bidireccional entre el cliente

(cualquier navegador nuevo) y el Servidor web. No funciona directamente sobre HTTP

sino directamente sobre un socket TCP, lo que permite crear una comunicación

bidireccional de forma nativa, los mensajes se distribuyen instantáneamente con poca

sobrecarga.


4 MENSAJERÍA SSAP

SSAP (Smart Space Access Protocol) es el protocolo de mensajería estándar para comunicar

entre los SIBs y los KPs.

SOFIA2 soporte SSAP-XML y SSAP-JSON, se recomienda el uso de SSAP-JSON, que al estar

basado en JSON es más adecuado para la comunicación IoT (con dispositivos móviles,

navegadores, etc.).

Los mensajes SSAP son:

4.1 JOIN

Es un mensaje enviado desde un KP al SIB y puede tener dos funcionalidades

o Solicitar un inicio de sesión: Se trata del primer mensaje de una sesión SSAP. Mediante el mensaje JOIN, un KP se autentica ante el SIB recibiendo la sessionKey que le servirá de identificador para el resto de mensajes.

o Renovar una sesión existente: La sessionKey recibida al establecer una sesión lógica con la plataforma tiene un periodo de caducidad de 24 horas. Este periodo se renueva cada vez que el KP actua con el SIB (Pej: enviando un mensaje de tipo QUERY o INSERT). Pero si no hay comunicación con el SIB durante ese tiempo, el SIB procederá a invalidar la sesión, dándola por caducada.

Para evitar esto, se puede enviar un mensaje JOIN para renovar la sessionKey otras 24 horas. Se trata del mismo mensaje JOIN utilizado para el establecimiento de sesión, incluyendo en este caso la sessionKey a renovar.

Es un mensaje síncrono en el que el SIB responde con:

o SessionKey si autenticación es correcta

o Error de autenticación si falla


4.1.1 Request:

4.1.1.1 Ejemplo solicitando un inicio de sesión (no incluye sessionkey)

{

"body": {

"token": "e48ddd78ba17464ebb9db9f40013b20a",

"instance": " kpName:kpInstance "

},

"direction": "REQUEST",

"messageId": null,

"messageType": "JOIN",

"ontology": null,

"sessionKey": null

}

4.1.1.2 Ejemplo solicitando renovación de sesión (incluye sessionkey)

{

"body": {

"token": "e48ddd78ba17464ebb9db9f40013b20a",

"instance": "Kp_OntPrueba: Kp_OntPrueba01"

},


"messageId": null,


"ontology": null,

"sessionKey": "f260cfbd-e740-416b-81be-e6aaaa6e5a1b"

}


4.1.2 Response:

{

"body": {

"data": "f260cfbd-e740-416b-81be-e6aaaa6e5a1b",

"error": null,

"errorCode": null,

"ok": true

},

"direction": "RESPONSE",

"messageId": null,


"ontology": null,


}

4.1.3 Response antes Request’s Incorrectos:

4.1.3.1 Ejemplo con Token Desactivado

{

"body": {

"data": null,

"error": "Token is deactivated",

"errorCode": "AUTENTICATION",

"ok": false

},

"direction": "ERROR",

"messageId": null,


"ontology": null,

"sessionKey": null

}


4.1.3.2 Ejemplo con KP Inexistente

{

"body": {

"data": null,

"error": "KP does not exist",


"ok": false

},


"messageId": null,


"ontology": null,

"sessionKey": null

}

4.1.3.3 Ejemplo con Token no perteneciente al KP

{

"body": {

"data": null,

"error": "Token not valid the kp",


"ok": false

},


"messageId": null,


"ontology": null,

"sessionKey": null

}


4.1.3.4 Ejemplo con Token Inexistente

{

"body": {

"data": null,

"error": "Token does not exist",


"ok": false

},


"messageId": null,


"ontology": null,

"sessionKey": null

}

4.1.3.5 SessionKey Inexistente

{

"body": {

"data": null,

"error": "Cannot renovate the sessionkey, the user is not logged in

the SIB",

"errorCode": "AUTHORIZATION",

"ok": false

},


"messageId": null,


"ontology": null,

"sessionKey": null

}


4.2 LEAVE

Mensaje enviado por un KP al SIB para realizar un cierre de sesión.

Es un mensaje síncrono.

4.2.1 Request:

{

"body": null,


"messageId": null,

"messageType": "LEAVE",

"ontology": null,


}

4.2.2 Response:

{

"body": {

"data": "f260cfbd-e740-416b-81be-e6aaaa6e5a1b",

"error": null,

"errorCode": null,

"ok": true

},


"messageId": null,

"messageType": "LEAVE",

"ontology": null,


}


4.3 QUERY

Mensaje enviado por un KP al SIB realizando una consulta sobre la información de la BDTR del SIB.

Es un mensaje síncrono en el que el SIB responde con datos de la consulta.

Un mensaje QUERY puede ser de tipo Nativo, SQL-Like o SIB-DEFINED

4.3.1 Query tipo Nativo

Se entiende por tipo nativo, cuando la query es resuelta por el motor de BDTR subyacente,

siendo en la implementación de referencia MongoDB.

Las queries de consulta a MongoDB presentan una estructura determinada: comienzan con

“db” seguido del carácter “.” seguido por el “nombre de la colección” (sobre la que se desea

consultar los datos) seguido de nuevo por el carácter “.”, seguido del método (find,

aggregate,...) y entre paréntesis las condiciones que se deben cumplir (combinación de fields y

operadores).

Las condiciones suelen ir dentro de los paréntesis, agrupadas por corchetes “{}”. Un ejemplo

sería ({medida: 4}), para decir los que cumplan que el campo medida tiene valor 4. Después de

los paréntesis se pueden añadir más métodos siguiendo la misma estructura.

db.[collection].[method]([operadores])

SOFIA2 soporta sentencias con las operaciones: find, count, distinct, aggregate, limit y skip.

Ejemplos de sentencia en MongoDB para consultar aquellas medidas que sean

mayores de 25:

db.SensorTemperatura.find({"SensorTemperatura.medida":{$gt:20}});

Para consultar el número de elementos de una colección (ontología) utilizaremos la

siguiente sentencia:

db.SensorTemperatura.count()

Para consultar el número de elementos de una colección (ontología) que cumplen una

condición:

db.SensorTemperatura.count({"SensorTemperatura.identificador":"S_Temperatur

a_00001"});

Para limitar el número de registros utilizaremos la operación limit():

db.SensorTemperatura.find({"SensorTemperatura.medida":{$gt:20}}).limit(3);


El limit se puede acompañar con la operación skip():

db.SensorTemperatura.find({"SensorTemperatura.identificador":"S_Temperatura

_00001"}).limit(3).skip(10);

db.SensorTemperatura.find({"SensorTemperatura.medida":{$gt:20}}).limit(3).skip(

10);

Unos ejemplos de operaciones agregadas (con la operación aggregate):

db.SensorTemperatura.aggregate([{$group:_id:{"_id":"$SensorTemperatura.ident

ificador"},"total":{$sum:"$SensorTemperatura.medida"}}}]);

db.SensorTemperatura.aggregate([{$group:{_id:"$SensorTemperatura.identificad

or","total":{$sum:1}}}])

Para realizar consultas geoespaciales:

db.SensorTemperatura.find({"SensorTemperatura.geometry":{$nearSphere:[12,12],

$maxDistance:1}})

En el siguiente enlace podemos ver los operadores para lanzar consultas.

4.3.1.1 Request:

{

"body": {

"query": "Jardin.parcela:45",

"queryType": "NATIVE"

},


"ontology": "Jardin",

"messageType": "QUERY",

"messageId": null,

"sessionKey": "e2bcd400-37e5-4067-bc4b-f495ba9a8090"

}

http://docs.mongodb.org/manual/reference/operator/query/


4.3.1.2 Response:

{

"body": {

"data": [

{

"_id": {

"$oid": "5359262bdef7260a09e96709"

},

"contextData": {

"session_key": "ff5b6c48-4cc3-4ce3-a30f-6bf8e18dc340",

"user_id": "1",

"kp_id": "2f84dd5c-2566-4ac3-9aca-d62bf8985ddc",

"kp_identificador": "kp_perro01",

"timestamp": {

"$date": "2014-04-24T16:56:43.269Z"

}

},

"Jardin": {

"timestamp": 125896,

"assetId": "1",

"parcela": 45,

"humedad": 78.9

}

}

],

"error": null,

"errorCode": null,

"ok": true

},


"messageId": null,



"sessionKey": "e2bcd400-37e5-4067-bc4b-f495ba9a8090"

}


4.3.1.3 Request (find):

{

"body": {

"query": "db.feedAutobus.find({'Feed.assetId':'316'}).limit(1)",

"queryType": "NATIVE"

},


"ontology": "feedAutobus",


"messageId": null,

"sessionKey": "4e21da4d-5009-4463-b771-29a437dfa86e"

}

4.3.1.4 Response (find):

{

"body": {

"data": [

{

"_id": {

"$oid": "533bff5f50ae67a5ab0c433c"

},

"contextData": {

"session_key": "dfa0fc30-7fbe-455b-8775-9eb317c42b85",

"user_id": 18,

"kp_id": 75,

"kp_identificador": "pt_kp_test1_instance2",

"timestamp": {

"$date": "2014-04-02T12:15:27.310Z"

}

},

"Feed": {

"assetId": "316",

"assetName": " Autobús nº 316 ",

"assetSource": "guiaLocal",

"assetType": "Autobus",


"attribs": [

{

"name": "linea",

"value": "1"

},

{

"name": "nombreLinea",

"value": "Abente y Lago - Os Castros"

},

{

"name": "estado",

"value": "Tipo de Autobús: Normal piso bajo . Última parada por la que ha pasado

Plaza de Mina, 26 Hora de paso 14:15 Proxima parada: Plaza de Orense\\n"

}

],

"feedId": "1:316:2014-04-02T12:15:28.706266",

"feedSource": "guiaLocal",

"geometry": {

"coordinates": [

-8.403705353600992,

43.36721562022267

],

"type": "Point"

},

"measures": [ ],

"measuresTimestamp": {

"$date": "2014-04-02T12:15:28.706Z"

},

"measuresType": "INSTANT",

"timestamp": {

"$date": "2014-04-02T12:15:28.706Z"

},

"type": "MOBILE"

}

}

],

"error": null,


"errorCode": null,

"ok": true

},


"messageId": null,




}

4.3.2 Query tipo SQL-Like

En este caso, la query Sql es transformada por SOFIA al lenguaje de query subyacente, en la implementación de referencia, a MongoDB.

SOFIA permite que a través de un lenguaje más sencillo y conocido se puedan realizar

consultas sobre la BDTR sin necesidad de previas suscripciones a colecciones de datos.

Cuando se lanzan consultas sobre una ontología hay que tener en cuenta que los datos se

habrán guardado como “documentos” y por tanto cuando se quiera preguntar por un atributo en

concreto de una ontología, se deberá especificar del siguiente modo: [ontologia].[atributo],

por ejemplo SensorTemperatura.medida.

Un ejemplo de sentencia en SQL-Like sería:

select * from SensorTemperatura where SensorTemperatura.medida > 25

Y su equivalente en MongoDB:

db.SensorTemperatura.find({"SensorTemperatura.medida":{$gt:25}});

Expresiones:

SELECT

FROM

WHERE

ORDER BY

GROUP BY

COUNT

LIMIT

HAVING


ASC

DESC

AS

Operadores de comparación:

>

<

=

>=

<=

!=

Operadores lógicos

||

&&

OR

NOT

AND

Otros operadores

+

MAX

MIN

SUM

AVG

Ejemplo de mapeo de expresiones SQL a MongoDB

SQL-Like Lenguaje MongoDB

select * from SensorTemperatura; db.SensorTemperatura.find();

select db.SensorTemperatura.find({},{"SensorTemperatu


SensorTemperatura.identificador,SensorT

emperatura.unidad from

SensorTemperatura;

ra.identificador":1,"SensorTemperatura.unidad":1});

select * from SensorTemperatura where

SensorTemperatura.identificador =

"S_Temperatura_00001";

db.SensorTemperatura.find({"SensorTemperatura

.identificador":"S_Temperatura_00001"});


SensorTemperatura.medida = 20 and

SensorTemperatura.unidad = “C”;

db.SensorTemperatura.find({"SensorTemperatura

.medida":20, "SensorTemperatura.unidad":"C"})


“SensorTemperatura.unidad” = “C” order

by “SensorTemperatura.identificador”

ASC;

db.SensorTemperatura.find({"SensorTemperatura.medida":20, "SensorTemperatura.unidad":"C"}).sort({"SensorTemperatura.identificador":1})

select count(*) from SensorTemperatura; db.SensorTemperatura.count();

select count(*) from SensorTemperatura

where SensorTemperatura.medida >20

db.SensorTemperatura.count({SensorTemperatura.medida:{$gt:20}})

select from SensorTemperatura limit 1 db.SensorTemperatura.find().limit(1)

select distinct

(SensorTemperatura.identificador) from

SensorTemperatura;

db.SensorTemperatura.distinct('SensorTemperatura.identificador')

select * form SensorTemperatura limit 5

skip 10

db.SensorTemperatura.find().limit(5).skip(10)

select SensorTemperatura.identificador,

count(*) as total from SensorTemperatura

db.SensorTemperatura.aggregate([{$group:{_id:”$SensorTemperatura.identificador”, total:{$sum:1}}}])

select count(*) from SensorTemperatura

group by SensorTemperatura.identificador

having count(*) >1

db.SensorTemperatura.aggregate([{$group:{_id:”$SensorTemperatura.identificador”, count:{$sum:1}}},{$match:{count:{$gt:1}}}])

select SensorTemperatura.identificador,

sum(SensorTemperatura.measure) as

total from SensorTemperatura group by

SensorTemperatura.identificador

db.SensorTemperatura.aggregate([{$group:{_id:{"SensorTemperatura":"$SensorTemperatura.identificador"},"total":{$sum:"$SensorTemperatura.medida"}}})


4.3.2.1 Request:

{

"body":{

"query":"select * from feedAutobus where Feed.assetId='316' limit 1",

"queryType":"SQLLIKE"

},

"direction":"REQUEST",

"ontology":"feedAutobus",

"messageType":"QUERY",

"messageId":null,


}

4.3.2.2 Response:

{

"body": {

"data": [

{

"_id": {

"$oid": "533bff5f50ae67a5ab0c433c"

},

"contextData": {

"session_key": "dfa0fc30-7fbe-455b-8775-9eb317c42b85",

"user_id": 18,

"kp_id": 75,

"kp_identificador": "pt_kp_test1_instance2",

"timestamp": {

"$date": "2014-04-02T12:15:27.310Z"

}

},

"Feed": {

"assetId": "316",

"assetName": " Autobús nº 316 ",


"assetSource": "guiaLocal",

"assetType": "Autobus",

"attribs": [

{

"name": "linea",

"value": "1"

},

{

"name": "nombreLinea",

"value": "Abente y Lago - Os Castros"

},

{

"name": "estado",

"value": "Tipo de Autobús: Normal piso bajo

. Última parada por la que ha pasado Plaza de Mina, 26 Hora de paso 14:15

Proxima parada: Plaza de Orense\\n"

}

],

"feedId": "1:316:2014-04-02T12:15:28.706266",

"feedSource": "guiaLocal",

"geometry": {

"coordinates": [

-8.403705353600992,

43.36721562022267

],

"type": "Point"

},

"measures": [ ],

"measuresTimestamp": {

"$date": "2014-04-02T12:15:28.706Z"

},

"measuresType": "INSTANT",

"timestamp": {

"$date": "2014-04-02T12:15:28.706Z"

},

"type": "MOBILE"

}


}

],

"error": null,

"errorCode": null,

"ok": true

},


"messageId": null,




}

4.3.3 Query tipo SIB-DEFINED

Tipo de consulta que permite realizar consultas a BDTR enviando en lugar de la query, el

identificador de consulta definido en el SIB. El motor de persistencia será el encargado de

recuperar de la base de datos la query a partir del identificador de consulta dado y retornar la

información.

SOFIA permite que a través de un editor visual se puedan gestionar consultas predefinidas

(esto es definir, modificar, eliminar y ejecutarlas). Las consultas predefinidas serán queries de

tipo SQL-Like o Native que quedarán almacenadas en base de datos.

Es un tipo de consulta a BDTR bajo demanda que no requiere de suscripción previa.

El sistema permite definir parámetros en una query predefinida. La forma de definir los

parámetros será utilizando el carácter ‘#’ seguido del nombre del parámetro,

“#[NombreParametro]”, por ejemplo #PARAM1. Unos ejemplos de queries con parámetros:

select * from SensorTemperatura where humedad = #PARAMHUM

db.SensorTemperatura.find({humedad:#PARAMHUM})

Los parámetros se pasarán en mensajes SSAP enviados por los KPs, como pares de clave-

valor (es decir, parámetro y valor del parámetro). El SIB será el que construya la query

completa, añadiendo los parámetros pasados en el mensaje.


4.3.3.1 Request sin parámetros:

{

"body":{

"query":"{selectAllSensorTemp}",

"queryType":"SIB_DEFINED"},




"messageId":null,

"sessionKey":"5b9349ab-d9a8-4fd0-b155-a11c5d8df6fa"

}

4.3.3.2 Response sin parámetros:

{

"body":{

"data":[

{ "_id" : {"$oid" : "510f86598dfe0dd9595f2e15"} ,

"SensorTemperatura" : {

"coordenadaGps" : {

"altitud" : 0.0 ,

"latitud" : 40.51083 ,

"longitud" : -3.669006} ,

"identificador" : " TA3231-1'",

"medida" : 23 ,

"timestamp" : 1359971931226 ,

"unidad" : "C"}}

],

"error":null,

"ok":true

},

"direction":"RESPONSE",

"messageId":null,




}


4.3.3.3 Request con parámetros:

{

"body":{

"query":"{selectAll }",

"queryParams":"{'PARAM1':'ST-TA3231-1'}"

},


"ontology": null,


"messageId":null,


}

La query predefinida indicada en el mensaje SSAP, habrá definido previamente y será: select *

from SensorTemperatura where identificador = #PARAM1

4.3.3.4 Response con parámetros:

{ "body":{

"data":[

{ "_id" : {"$oid" : "510f86598dfe0dd9595f2e15"} , "SensorTemperatura" : {

"coordenadaGps" : {

"altitud" : 0.0 ,

"latitud" : 40.51083 ,

"longitud" : -3.669006} ,

"identificador" : " ST-TA3231-1 ",

"medida" : 23 ,

"timestamp" : 1359971931226 ,

"unidad" : "C"}}

],

"error":null,

"ok":true

},


"messageId":null,





}

4.3.4 Query tipo BDH

Tipo de consulta que permite realizar operaciones sobre BDH.

Hay que tener en cuenta que los datos son movidos automáticamente desde la BDTR a la BDH

cuando finaliza el periodo de tiempo real para cada ontología.

De manera que los datos de cada ontología son mapeados a una tabla con el mismo nombre

que la ontologia en la BDH.

La BDH permite de forma nativa 2 tipos de operaciones mediante el envío de un mensaje

QUERY a la BDH en formato SQL: SELECT e INSERT.

Estas dos operaciones se pueden solicitar desde un mensaje tipo QUERY con queryType

BDH.

SELECT: Permite consultar datos de la BDH mediante una sentencia SQL.

La sentencia SELECT permite recuperar datos de una o mas tablas y produce un

resultado consistente en en conjutos de filas y columnas.

El motor de la BDH se basa en Impala que soporta para la sentencia SELECT:

o Clausula DISTINCT.

o Subqueries en el bloque FROM.

o Clausulas WHERE, GROUP BY, HAVING

o Clausula ORDER BY

o Clausula LIMIT

o Clausula JOIN

o Clausula UNION ALL

o Clausula OFFSET

o Clausula UNION

o Operadores relacionales (>, <, =)

o Operadores aritméticos (+, -)

o Operadores lógicos (AND, OR, NOT)

o Funciones de agregado (COUNT, SUM, CAST, LIKE, IN, BETWEEN,

COALESCE).


Documentación completa en http://www.cloudera.com/content/cloudera-

content/cloudera-docs/Impala/latest/Installing-and-Using-

Impala/ciiu_langref_sql.html?scroll=select_unique_1

NOTA: Dada la gran cantidad de datos existentes en la BDH, una consulta de tipo

SELECT a la BDH deberá siempre llevar la clausula LIMIT, quedando limitada por el

SIB en caso de no incluir la clausula.

Una solicitud SSAP QUERY de tipo BDH para realizar un SELECT deberá informar en

el mensaje SSAP REQUEST los siguientes datos en el campo body:

o query: Sentencia SQL enviada al motor de la BDH

o queryType: Enumerado BDH

Presentando la siguiente forma:

{ "body":{

"query":"

select * from SensorTemperatura where identificador = '**-

TA3231-1'",

"queryType":"BDH"},




"messageId":null,


}

La respuesta un mensaje SSAP de respuesta incluyendo la tabla con los resultados de

la sentencia en el atributo data.

La tabla de resultados se representa mediante un objeto JSON que incluye un array con

metainformación de las columnas y la matriz con los resultados. La forma de este objeto

es la siguiente:

{ "columns": [ {"name":"id","type":"VARCHAR","index":1}, {"name":"timestamp_","type":"INTEGER","index":2}, {"name":"mensajealarma","type":"VARCHAR","index":3}, {"name":"mensajeexcepcion","type":"VARCHAR","index":5}, {"name":"causa","type":"VARCHAR","index":6}, {"name":"contextdata__session_key","type":"VARCHAR","index":7}, {"name":"contextdata__user_id","type":"VARCHAR","index":8}, {"name":"contextdata__kp_id","type":"VARCHAR","index":9}, {"name":"contextdata__kp_identificador","type":"VARCHAR","index":10}, {"name":"contextdata__timestamp_","type":"VARCHAR","index":11} ],

"values": [

http://www.cloudera.com/content/cloudera-content/cloudera-docs/Impala/latest/Installing-and-Using-Impala/ciiu_langref_sql.html?scroll=select_unique_1




["ObjectID(52fa4787fee7acf12f75a893)",null,"","3.0","69.0","\"KPproductorHT01\"","1391976200443.0"], ["ObjectID(52fa530375926e9d0a8d4a66)",null,"","","",""," ","3.0","69.0","\"KPproductorHT01\"","1391976200441.0"], ["ObjectID(52fa53e475926e9d0a8d4a67)",null,"","","",""," ","3.0","69.0","\"KPproductorHT01\"","1391976200431.0"], ·········

] }

INSERT: Permite insertar datos en la BDH mediante una sentencia SQL INSERT.

La sentencia INSERT soporta:

o INSERT INTO

o INSERT OVERWRITE

o Utilizar SELECT para recuperar datos de otra tabla.

Documentación completa en http://www.cloudera.com/content/cloudera-

content/cloudera-docs/Impala/latest/Installing-and-Using-

Impala/ciiu_langref_sql.html?scroll=insert_unique_1

Una solicitud SSAP QUERY de tipo BDH para realizar un INSERT deberá informar en el

mensaje SSAP REQUEST los siguientes datos en el campo body:

o query: Sentencia SQL enviada al motor de la BDH

o queryType: Enumerado BDH

Presentando la siguiente forma:

{

"body":{

"query":"

insert into SensorTemperatura(id, identificador, medida) values (1, ‘ST-

TA23’, 23)",

"queryType":"BDH"

},




"messageId":null,


}

http://www.cloudera.com/content/cloudera-content/cloudera-docs/Impala/latest/Installing-and-Using-Impala/ciiu_langref_sql.html?scroll=insert_unique_1




La respuesta un mensaje SSAP de respuesta incluyendo el numero de registros

afectados en el atributo data.

4.4 INSERT

Mensaje enviado por un KP al SIB para insertar información en la BDTR

Es un mensaje síncrono en el que el SIB responde con el ID del Objeto insertado.

4.4.1 Request:

{

"body": {

"query": "{insert into Jardin (timestamp,assetId,parcela,humedad)

values (125896,'1',45,78.9)}",

"queryType": "SQLLIKE",

"queryParams": null

},



"messageType": "INSERT",

"messageId": null,

"sessionKey": "ff5b6c48-4cc3-4ce3-a30f-6bf8e18dc340"

}

4.4.2 Response:

{

"body":{

"data":{

"_id":ObjectId("53591d96def7260a09e96708")

},

"error":null,

"errorCode":null,

"ok":true

},


"messageId":null,

"messageType":"INSERT",


"ontology":"Jardin",

"sessionKey":"ff5b6c48-4cc3-4ce3-a30f-6bf8e18dc340"

}

4.5 UPDATE

Mensaje enviado por un KP al SIB para actualizar información contenida en la BDTR

Es un mensaje síncrono en el que el SIB responde con el ID del Objeto actualizado.

4.5.1 Request:

{ "body": {

"query": "{update Jardin set Jardin.humedad = 100.0 where

Jardin.parcela = 45}",


"queryParams": null

},



"messageType": "UPDATE",

"messageId": null,

"sessionKey": "59ff077c-d8a4-4cb8-be03-ebbcad32dec5"

}

4.5.2 Response:

{

"body":{

"data":{

"_ids":[{"_id":ObjectId("53591d96def7260a09e96708")}]

},

"error":null,

"errorCode":null,

"ok":true

},


"messageId":null,

"messageType":"UPDATE",



"sessionKey":"59ff077c-d8a4-4cb8-be03-ebbcad32dec5"

}

4.6 DELETE

Mensaje enviado por un KP al SIB para borrar información contenida en la BDTR

Es un mensaje síncrono en el que el SIB responde con el ID del Objeto eliminado.

4.6.1 Request:

{

"body": {

"query": "{delete from Jardin where Jardin.parcela = 45}",


"queryParams": null

},



"messageType": "DELETE",

"messageId": null,

"sessionKey": "59ff077c-d8a4-4cb8-be03-ebbcad32dec5"

}

4.6.2 Response:

{

"body":{

"data":{

"_ids":[{"_id":ObjectId("53591d96def7260a09e96708")}]

},

"error":null,

"errorCode":null,

"ok":true

},


"messageId":null,

"messageType":"DELETE",



"sessionKey":"59ff077c-d8a4-4cb8-be03-ebbcad32dec5"

}

4.7 SUBSCRIBE

Mensaje enviado por un KP al SIB para suscribirse a un determinada condición que se produzca en la BDTR del SIB (se puede indicar tiempo de refresco)

La respuesta es síncrona indicando si el SIB acepta la suscripción, junto con el identificador de la suscripción

Existen 3 tipos de suscripciones:

o Suscripción a QUERY: Soporta los mismos tipos de query que el mensaje QUERY. Se notifica al KP suscriptor cuando en una ontología se insertan o actualizan datos que cumplen los criterios de la sentencia

o Suscripción al último valor de ontología: Permite a un KP suscribirse a una ontología para ser notificado cada vez que se añade una instancia de dicha ontología, sin necesidad de que la instancia tenga que cumplir ningún criterio de una sentencia de consulta.

o Suscripción a CEP: Permite a un KP suscribirse a un evento CEP de manera que cuando en el SIB se inserten datos que desencadenen el evento, el KP será notificado.

4.7.1 Request:

{

"body":{

"msRefresh":10000,

"query":"{SensorTemperatura.medida:{$gt:1}}",

"queryType":"NATIVE"

},


"messageId":"c260fbd6-ce7e-4f1d-983d-0152b419223c",

"messageType":"SUBSCRIBE",



}

Parámetros del cuerpo de la petición para elegir cada una de las modalidades de suscripción:

o Suscripción a QUERY:

query: Admite una de las siguientes posibilidades

Criterios de sentencia Nativa de la BDTR


Sentencia Nativa de la BDTR

Identificador de sentencia definida en el SIB

Sentencia SQLLike

queryType: Admite uno de los siguientes valores

NATIVE

SQLLIKE

SIB_DEFINED

null o no aparecer (solo para query que indique criterios de sentencia Nativa)

o Suscripción al último valor de ontología: Permite a un KP suscribirse a una ontología para ser notificado cada vez que se añade una instancia de dicha ontología, sin necesidad de que la instancia tenga que cumplir ningún criterio de una sentencia de consulta.

query: cadena vacía. Si no se indica sentencia de query se interpreta que se trata de una suscripción al último valor

queryType: Obligatorio el valor

NATIVE

o Suscripción a CEP: Permite a un KP suscribirse a un evento CEP de manera que cuando en el SIB se inserten datos que desencadenen el evento, el KP será notificado.

query: Identificador de regla CEP a la que se suscribe.

queryType: Obligatorio el valor

CEP

4.7.2 Response:

{

"body":"{

"data":"d43a929d-4883-4640-8f73-1337c518bd17",

"error":null,

"ok":true

}",


"messageId":"c260fbd6-ce7e-4f1d-983d-0152b419223c",

"messageType":"SUBSCRIBE",



}


4.8 UNSUBSCRIBE

Mensaje enviado por un KP al SIB para cancelar una suscripción previa.


4.8.1 Request:

{

"body":{

"idSuscripcion":"cef33c81-970f-4e9c-9203-6c87e25ca37c"

},


"messageId":null,

"messageType":"UNSUBSCRIBE",

"ontology":"Watorimetro",

"sessionKey":"5230064e-f4f7-41ab-b6de-7ef7ad11668f"

}

4.8.2 Response:

{

"body": {

"data": "",

"error": null,

"ok": true

},


"messageId": null,

"messageType": "UNSUBSCRIBE",

"ontology": "Watorimetro",

"sessionKey": "5230064e-f4f7-41ab-b6de-7ef7ad11668f"

}


4.9 INDICATION

Mensaje utilizado por el SIB para notificar a los KPs suscritos.

Es un mensaje asíncrono que se ejecuta cuando sea cierta la condición introducida por el KP

4.9.1 Response

{

"body": {

"data": [

{

"_id": {

"$oid": "511397883006732cf413d47b"

},

"SensorTemperatura": {

"coordenadaGps": {

"altitud": 0,

"latitud": 40.508416,

"longitud": -3.669918

},

"identificador": "S_Temperatura_00001",

"medida": 17,

"timestamp": 1360238472000,

"unidad": "C"

}

}

],

"error": null,

"ok": true

},


"messageId": "d1bc4fe5-54c3-4add-abb4-3108201e761f",

"messageType": "INDICATION",

"ontology": null,

"sessionKey": null

}


4.10 CONFIG

Mensaje enviado por un KP al SIB para obtener la configuración de software de sus aplicaciones.


Operación sólo disponible para KPs JAVA

4.10.1 Request:

{

"body":"{

"instanciaKp":"KPvisualizacionHT01",

"kp":"KPvisualizacionHT",

"token":"cbb9364c434543a18dc6efa30dc780eb"

}",


"messageId":null,

"messageType":"CONFIG",

"ontology":null,

"sessionKey":null

}

4.10.2 Response:

{

"body":"{

\"instanciaKp\":\"KPpubliAnuncios:KPpubliAnuncios01\",

\"kp\":\"KPpubliAnuncios\",

\"lappsw\":[{\"identificacion\":\"app1\",\"propiedadescfg\":{\"\\\"puerto\\\"\":\"\\\"808

0\\\"\",\"\\\"host\\\"\":\"\\\"localhost\\\"\"},\"url\":\"file:///Volumes/DATOS/app1.war\",\"versio

ncfg\":1,\"versionsw\":1}],

\"lasset\":[],

\"lmisc\":[],

\"lontologia\":[{\"esquemajson\":\"{ \\\"$schema\\\": \\\"http://json-

schema.org/draft-03/schema#\\\", \\\"title\\\": \\\"Anuncios Schema\\\", \\\"type\\\":

\\\"object\\\", \\\"properties\\\": { \\\"_id\\\": { \\\"type\\\": \\\"object\\\",

\\\"$ref\\\": \\\"#/titulo\\\" }, \\\"SensorAnuncio\\\": { \\\"type\\\": \\\"string\\\",

\\\"$ref\\\": \\\"#/datos\\\" } }, \\\"titulo\\\": { \\\"title\\\": \\\"id\\\",

\\\"description\\\": \\\"Titulo insertado del Anuncio\\\", \\\"type\\\": \\\"object\\\",

\\\"properties\\\": { \\\"$oid\\\": { \\\"type\\\": \\\"string\\\",

\\\"required\\\": false } } }, \\\"datos\\\": { \\\"title\\\": \\\"datos\\\",


\\\"description\\\": \\\"Info contenido\\\", \\\"type\\\": \\\"object\\\", \\\"properties\\\":

{ \\\"titulo\\\": { \\\"type\\\": \\\"string\\\", \\\"required\\\": true

}, \\\"timestamp\\\": { \\\"type\\\": \\\"integer\\\", \\\"minimum\\\":

0, \\\"required\\\": true }, \\\"contenido\\\": { \\\"type\\\":

\\\"string\\\", \\\"required\\\": true } } }, \\\"additionalItems\\\":

false}\",\"identificacion\":\"Anuncios\",\"tipopermiso\":\"QUERY\"}],

\"token\":\"d9e77d01d3c84f96994bfdcd428faa97\" }",


"messageId":null,

"messageType":"CONFIG",

"ontology":null,

"sessionKey":null

}

4.11 BULK

Mensaje enviado por un KP al SIB pudiendo agrupar varios mensajes de tipo INSERT, UPDATE y DELETE.

El mensaje será descompuesto en el SIB, que procesará los mensajes de manera individual del mismo modo que si hubieran sido enviado de manera individual

Es un mensaje síncrono en el que el SIB responde con un resumen conteniendo

o Operaciones correctas: El ID de los objetos insertados, modificados, eliminados

o Operaciones erróneas: El mensaje erróneo junto con la descripción del error

4.11.1 Request:

{

"body":"[

{\"body\":\"<INSERT_MESSAGE1_BODY>\", \"ontology\":\"TestSensorTemperatura\",

\"type\":\"INSERT\"},

{\"body\":\"<INSERT_MESSAGE2_BODY>\", \"ontology\":\"TestSensorTemperatura\",

\"type\":\"INSERT\"},

{\"body\":\"<UPDATE_MESSAGE1_BODY>\", \"ontology\":\"TestSensorTemperatura\",

\"type\":\"UPDATE\"},

{\"body\":\"<UPDATE_MESSAGE2_BODY>\", \"ontology\":\"TestSensorTemperatura\",

\"type\":\"UPDATE\"}

]",



"messageId":null,

"messageType":"BULK",

"ontology":null,

"sessionKey":"<SESSION_KEY>"

}

4.11.2 Response:

{

"body":"{

\"data\":\"{

\\\"deleteSummary\\\":null,

\\\"insertSummary\\\":{

\\\"errors\\\":[],

\\\"objectIds\\\":[···········]

},

\\\"updateSummary\\\":{

\\\"errors\\\":[],

\\\"objectIds\\\":[···········]

}

}\",

\"error\":null,

\"errorCode\":null,

\"ok\":true

}",


"messageId":null,

"messageType":"BULK",

"ontology":null,

"sessionKey":"<SESSION_KEY>"

}


5 API JAVA

5.1 Introducción

SOFIA2 proporciona un API Java para el desarrollo de KPs. Este API consta de un conjunto de

clases e interfaces Java que facilitan la generación y tratamiento de mensajes SSAP así como

la conexión con la plataforma a través de conectores que se comunican con los gateways de la

misma.

5.2 Dependencia Maven

El SDK de SOFIA 2 proporciona un repositorio Maven que incluye la librería del API Java. La

dependencia Maven que se debe incluir en el pom.xml de un KP para importar el API Java de

SOFIA2 es:

<dependency>

<groupId>com.indra.jee.arq.spring.</groupId>

<artifactId>ssap</artifactId>

<version>2.10.0</version>

</dependency>

5.3 Interfaz KP

Proporciona los métodos para conectar con la plataforma e intercambiar mensajes SSAP.

Se trata de una interfaz, que implementan varias clases, representando cada clase un conector

de protocolo específico (MQTT, HTTP).

Facilita la migración de un KP a nuevos protocolos que se puedan definir en un futuro,

abstrayendo el modo de conectar y enviar/recibir mensajes SSAP del protocolo utilizado.

La interfaz tiene el siguiente aspecto:

public interface Kp { boolean isConnected();

String getSessionKey(); void connect() throws ConnectionToSibException; void disconnect();

void setConnectionConfig(ConnectionConfig config); void setXxteaCipherKey(String cipherKey); SSAPMessage send(SSAPMessage msg) throws ConnectionToSibException; SSAPMessage sendCipher(SSAPMessage msg) throws ConnectionToSibException; void addListener4SIBNotifications(Listener4SIBIndicationNotifications listener); void removeListener4SIBNotifications(Listener4SIBIndicationNotifications listener);

}


Estas operaciones en las distintas implementaciones permiten a las aplicaciones Java: boolean isConnected():Conocer si el KP está conectado a un SIB

String getSessionKey(): Una vez conectado al SIB, recuperar la sessionKey

asignada para la conexión void connect(): Establecer una conexión física con el SIB a través del Gateway del

protocolo implementado por la clase. void disconnect(): Cerrar la conexión física establecida con el SIB en una

operación connect(). void setConnectionConfig(ConnectionConfig config): Configura los parametros

de conexión al SIB. El parámetro ConnectionConfig, informa al KP de los parámetros de configuración para conectar conectar con el Gateway del SIB.

void setXxteaCipherKey(String cipherKey): Establece la clave del algoritomo de

cifrado XXTEA para cifrar el intercambio de mensajes SSAP.

SSAPMessage send(SSAPMessage msg): Envía un mensaje SSAP al SIB, recibiendo

el mensaje SSAP de respuesta. SSAPMessage sendCipher(SSAPMessage msg): Envía un mensaje SSAP al SIB,

recibiendo el mensaje SSAP de respuesta. La comunicación irá cifrada por algoritmo XXTEA.

void addListener4SIBNotifications(Listener4SIBIndicationNotifications listener): Añade un listener para recibir notificaciones de mensajes de suscripción.

Un listener, es una clase que implementa la interfaz Listener4SIBIndicationNotifications, que obliga a implementar el método onIndication, que recibe por parámetros el mensaje SSAP INDICATION con los datos de notificación de la suscripción.

void removeListener4SIBNotifications(Listener4SIBIndicationNotifications listener): Elimina un listener para dejar de recibir notificaciones de mensajes de

suscripción.

5.4 Conectores de protocolos en el API

Los protocolos de comunicación proporcionados por el API Java son:

5.4.1 MQTT

La implementación de la interfaz Kp para el protocolo MQTT es la clase KpMQTTClient.

Conecta con el Gateway MQTT del SIB.

Esta clase recibe su configuración MQTT mediante una instancia de la clase

MQTTConnectionConfig, donde se informa:

Host: Máquina donde escucha el Gateway MQTT del SIB.

Port: Puerto donde escucha el Gateway MQTT del SIB.

Calidad de Servicio: Cuantas instancias del SIB deben recibir el mensaje.

Timeout: Timeout de conexión al Gateway MQTT del SIB.

MQTTConnectionConfig config = new MQTTConnectionConfig(); config.setHostSIB(host); config.setPortSIB(port); config.setQualityOfService(QoS.AT_LEAST_ONCE); config.setTimeOutConnectionSIB(5000);


//Creamos la instancia del KP pasando la configuración de conexión Kp kp=new KpMQTTClient(config);

Una vez instanciada el funcionamiento es el descrito en la interfaz.

En caso de necesitar conectar de manera segura utilizando MQTTS, la uri del HOST debe empezar por ssl://. Por ejemplo ssl://sofia2.com y añadir a los parámetros de la JVM el keystore que tenga la clave pública de sofia2.com y su password, mediante las propiedades:

-Djavax.net.ssl.keyStore=<keystore>.jks

-Djavax.net.ssl.keyStorePassword=<password>

5.4.2 RESTFul

El API Java RESTFul difiere del resto de APIs debido a las características intrínsecas de la

especificación RESTFul y la necesidad de manejar recursos a través de los verbos HTTP. En

este sentido, este API no utiliza el protocolo estándar SSAP, sino que maneja un objeto o

recurso denominado SSAPResource a través de las operaciones HTTP: POST, PUT, GET y

DELETE

En el API Java, el recurso SSAPResource queda representado por la clase SSAPResource

que tiene las siguientes propiedades:


Mientras que la interfaz del Gateway con las operaciones HTTP GET, POST, PUT, DELETE la

proporciona la clase SSAPResourceAPI con los métodos:

insert(ssap:SSAPResource): Response

update(ssap:SSAPResource): Response

query($sessionkey:String, $ontology:String, $query:String, $queryArg:String,

$queryType:String):Response

query($oid:String, $sessionKey:String, $ontology:String):Response

delete(ssap:SSAPResource):Response

deleteOid($oid:String, $sessionKey:String, $ontology:String):Response

getConfig($kp:String, $instanciakp:String, $token:String):Response

Lo que permite cubrir el juego de operaciones SSAP de la siguiente forma:

Operación SSAP Operación RESTFul a través de SSAPResourceAPI

JOIN

insert (POST) enviando un SSAPResource informando:

join: true

instanceKP: Identificador de KP e indentificador de instancia de KP

token: Token de autenticación

LEAVE

insert (POST) enviando un SSAPResource informando:

leave: true

sessionkey: Clave de sesión a caducar

INSERT

insert (POST) enviando un SSAPResource infomando:

ontology: Ontologia sobre la que envia una nueva instancia.

data: Intancia de ontologia enviada.

sessionkey: clave de sesión SSAP en la que pertenece el mensaje

ó

query (GET) enviando un SSAPResource informando a traves de los queryParams de

la URL:

$ontology: Ontologia sobre la que envia una nueva instancia.

$query: Sentencia SQLLIKE de tipo INSERT.

$sessionKey: clave de sesión SSAP en la que pertenece el mensaje

$queryType: SQLLIKE

UPDATE

update (PUT) enviando un SSAPResource infomando:

ontology: Ontologia sobre la que se realiza la actualización.

data: Intancia de ontologia con datos actualizados.

sessionkey: clave de sesión SSAP en la que pertenece el mensaje

ó

query (GET) informando a traves de los queryParams de la URL:


$ontology: Ontologia sobre la que se realiza la actualización.

$query: Sentencia SQLLIKE de tipo UPDATE.


$queryType: SQLLIKE

DELETE

delete (DELETE) enviando un SSAPResource infomando:

ontology: Ontologia sobre la que se realiza el borrado.

data: Intancia de ontologia a borrar.

sessionkey: clave de sesión SSAP en la que pertenece el mensaje ó

delete (DELETE) informando a traves de pathParam: el objectId en BDTR de la

instancia de ontologia a borrar. Y a traves de queryParams de la URL:

$ontology: Ontologia sobre la que se realiza el borrado.

$sessionKey: clave de sesión SSAP en la que pertenece el mensaje ó


$ontology: Ontologia sobre la que se realiza el borrado.

$query: Sentencia SQLLIKE de tipo DELETE.


$queryType: SQLLIKE

QUERY


$ontology: Ontologia sobre la que se realiza la consulta.

$query: Sentencia de consulta


$queryType: Tipo de lenguaje de consulta

$queryParams: Parámetros a informar en caso de consulta predefinida en el SIB con argumentos.

ó

query (GET) informando a traves de pathParam: el objectId en BDTR de la instancia

de ontologia a consultar. Y a traves de queryParams de la URL:

$ontology: Ontologia sobre la que se realiza la consulta.


GET_CONFIG

getConfig (GET) informando a traves de los queryParams de la URL:

$kp: Identificador de KP del que se quiere recuperar su configuración

$instanciaKp: Identificador de la instancia de KP de la que se quiere recuperar su configuración

$token:Token de autenticación

Todas las operaciones devuelven un objeto de tipo RESPONSE, que puede ser mapeado a un objeto SSAPResource con la respuesta del SIB utilizando el método de la clase SSAPResourceAPI:

responseAsSsap(resp:Response):SSAPResource


El constructor de SSAPResourceAPI recibe por argumentos la url del endpoint del Gateway

RESTFul de Sofia2 sobre el que realizará las operaciones.

Ejemplo de utilización:

SSAPResourceAPI api = new SSAPResourceAPI("http://sofia2.com/sib/services/api_ssap/");

//Genera un recurso SSAP con un JOIN SSAPResource ssapJoin=new SSAPResource(); ssapJoin.setJoin(true); ssapJoin.setInstanceKP(KP_INSTANCE); ssapJoin.setToken(TOKEN);

//Hace un POST del recurso, equivalente a una petici�n SSAP JOIN Response respJoin=this.api.insert(ssapJoin); String sessionkey=null; log.info("Codigo http retorno JOIN: "+respJoin.getStatus()); try{ sessionkey=this.api.responseAsSsap(respJoin).getSessionKey(); log.info("Sessionkey:"+sessionkey); assertEquals(respJoin.getStatus(), 200); }catch(ResponseMapperException e){ log.error(e.getMessage()); assertEquals(false, true); } if(sessionkey!=null){ //Genera un recurso SSAP con un LEAVE SSAPResource ssapLeave=new SSAPResource(); ssapLeave.setLeave(true); ssapLeave.setSessionKey(sessionkey); Response respLeave=this.api.insert(ssapLeave); log.info("Codigo http retorno LEAVE: "+respLeave.getStatus()); assertEquals(respLeave.getStatus(), 200); }

5.4.3 Websocket

La implementación de la interfaz Kp para el protocolo Websocket es la clase

KpWebSocketClient.

Conecta con el Gateway Websocket del SIB.

Esta clase recibe su configuración mediante una instancia de la clase

WebSocketConnectionConfig, donde se informa:


endPointUri: URL donde escucha el Gateway Websocket del SIB.

method: Metodo HTTP utilizado por el Gateway Websocket del SIB (por defecto en

sofia2.com GET).

timeOutConnectionSIB: Timeout para recibir la respuesta desde el SIB.

WebSocketConnectionConfig config=new WebSocketConnectionConfig(); config.setEndpointUri("http://sofia2.com/sib/api_websocket"); config.setMethod(METHOD.GET); config.setTimeOutConnectionSIB(5000); KpWebSocketClient kp=new KpWebSocketClient(config);

Una vez instanciada el funcionamiento es el descrito en la interfaz.

5.4.4 Extensión con nuevos protocolos

Tal como se indica en la guía SOFIA-Guía Configuración Extensión y Personalización

SIB.doc, es posible extender el SIB a un nuevo protocolo de comunicación (Gateway). Una vez

extendido el SIB con el nuevo protocolo, para facilitar la utilización del nuevo protocolo en el

API Java, es recomendable extender este API para soportar tal protocolo siguiendo la filosofía

aplicada en los protocolos actuales. Para ello, los pasos para extender el API a un nuevo

protocolo son:

Crear la clase que represente la implementación del conector del nuevo protocolo

(Aquella con la que instanciaremos la interfaz Kp, para enviar mensajes SSAP al SIB).

El código fuente de los protocolos actuales puede encontrarse en el paquete

com.indra.sofia2.ssap.kp.implementations.

Esta clase deberá implementar la clase abstracta KpToExtend, que a su vez

implementa la interfaz Kp:


En el diagrama anterior se indican sólo las operaciones más importantes del API. La

interfaz Kp describe todas las operaciones que debe tener el API independiemente del

protocolo que se utilice, mientras que la clase KpToExtend agrupa los atributos y

operaciones que serán comunes a todas las implementaciones independientemente del

protocolo.

Finalmente, cada implementación de protocolo particular, implementa aquellas

operaciones de la interfaz Kp, que sea diferente en función del protocolo de transporte.

En concreto las operaciones:

o connect(): Establece la conexión física con el Gateway del SIB según el

protocolo utilizado.

o disconnect(): Cierra la conexión física con el Gateway del SIB según el

protocolo utilizado.

o send(): Envia los mensajes SSAP al Gateway del SIB a través del canal

proporcianado por el protocolo.

Cada protocolo tendrá unos parámetros de configuración distintos. Para cubrir la configuración

de cada protocolo se proporciona la clase ConnectionConfig. Esta clase podrá ser extendida

para crear una nueva clase que cubra todas las propiedades de configuración del nuevo

protocolo. La clase abstracta KPToExtend, que implementará la implementación del nuevo

protocolo, tiene entre sus atributos una instancia de ConnectionConfig, que recibirá por

parámetros en el constructor. De este modo, al instanciar cada protocolo específico, se pasará


a su constructor una instancia de ConnectionConfig específica para el protocolo, que

recogerá lo parámetros de conexión:

5.5 Utilidades del API

5.5.1 Clase SSAPMessageGenerator

Es una clase de utilidad que proporciona una serie de operaciones que permiten generar

mensajes SSAP sin tener que bajar al detalle de componer el JSON.

generateJoinMessage: Permite construir el mensaje SSAPMessageJOIN indicando el

usuario, password, la instancia y la sessionkey en caso de tratarse de un mensaje JOIN de renovación de sessionkey.

generateLeaveMessage: Permite construir el mensaje SSAPMessageLEAVE, es

necesario indicar la sessionKey.


generateInsertMessage: Permite construir el mensaje SSAPMessageINSERT

indicando la sessionKey, ontologia y los datos a insertar.

generateUpdateMessage: Permite construir el mensaje SSAPMessageUPDATE

indicando la sessionKey, ontología, los datos a actualizar y la query.

generateRemoveMessage: Permite construir el mensaje SSAPMessageREMOVE

indicando la sessionKey, ontología y la query.

generateQueryMessage: Permite construir el mensaje SSAPMessageQUERY

indicando la sessionKey, ontología y la query.

generateSubscribeMessage: Permite construir el mensaje

SSAPMessageSUBSCRIBE indicando la sessionKey, ontología, tiempo de refresco y la query.

generateUnsubscribeMessage:Permite construir el mensaje

SSAPMessageUNSUBSCRIBE indicando la sessionKey, ontología y el id de suscripción.

generateGetConfigMessage: Permite construir el mensaje SSAPMessageCONFIG

indicando el kp, la instancia de kp y el token de conexión.

generateBulkMessage: Permite construir un mensaje SSAPBulkMessage indicando la

ontologia global del mensaje y la sessionKey.

Adicionalmente añade soporte para la manipulación de tipo de datos binary.

5.5.1 Soporte Binary

El soporte a datos de tipo Binary se soporta en clases de utilidades y estructurales, a

continuación se exponen los métodos que facilitan el trabajo con este tipo de Datos.

Las clases SSAPBinaryMessage y SSAPBinaryMediaMessage son clases estructurales, que

modelan la estructura física del tipo de datos Binary. Es importante conocer su funcionamiento

pese a que las clases de utilidades abstraen al desarrollador de su uso.

El Constructor de la clase SSAPBinaryMessage que cumple el siguiente contrato public

SSAPBinaryMessage(File data, Encoding binaryEncoding, Mime mime) crea un

objeto con el fichero (data) serrializado utilizando el encoding (binaryEncoding) y el mime-

type (mime) que seleccionemos.

El enumerado Encoding únicamente soporta los tipo de datos BASE64 y BASE91, y será el

modo en el que se serializará el fichero adjuntado.


NOTA: El encoding que se utiliza para serializar el fichero ha de ser el mismo que el

empleado para generar el objeto binario a partir de su cadena serializada.

El enumerado Mime contiene un amplio listado de enumerados.

APPLICATION_ATOM ("application/atom+xml"),

APPLICATION_VND ("application/vnd.dart"),

APPLICATION_ECMASCRIPT ("application/ecmascript"),

APPLICATION_EDIX12 ("application/EDI-X12"),

APPLICATION_EDIFACT ("application/EDIFACT"),

APPLICATION_JSON ("application/json"),

APPLICATION_JACASCRIPT("application/javascript"),

APPLICATION_OCTET ("application/octet-stream"),

APPLICATION_OGG ("application/ogg"),

APPLICATION_DASH ("application/dash+xml"),

APPLICATION_PDF ("application/pdf"),

APPLICATION_POSTCRIPT ("application/postscript"),

APPLICATION_RDF ("application/rdf+xml"),

APPLICATION_RSS ("application/rss+xml"),

APPLICATION_SOAP ("application/soap+xml"),

APPLICATION_FONT ("application/font-woff"),

APPLICATION_XHTML ("application/xhtml+xml"),

APPLICATION_XML ("application/xml"),

APPLICATION_XML_DTD ("application/xml-dtd"),

APPLICATION_XOP ("application/xop+xml"),

APPLICATION_ZIP ("application/zip"),

APPLICATION_GZIP ("application/gzip"),

APPLICATION_EXAMPLE ("application/example"),

APPLICATION_X_NACL ("application/x-nacl"),

APPLICATION_X_PNACL ("application/x-pnacl"),

APPLICATION_SMIL ("application/smil+xml"),

APPLICATION_VND_DEBIAN ("application/vnd.debian.binary-package"),

APPLICATION_VND_OASIS_TEXT ("application/vnd.oasis.opendocument.text"),

APPLICATION_VND_OASIS_SPREADSHEET ("application/vnd.oasis.opendocument.spreadsheet"),

APPLICATION_VND_OASIS_PRESENTATION

("application/vnd.oasis.opendocument.presentation"),

APPLICATION_VND_OASIS_GRAPHICS ("application/vnd.oasis.opendocument.graphics"),

APPLICATION_VND_MS_EXCEL ("application/vnd.ms-excel"),

APPLICATION_VND_OPENXMLFORMART_SHEET ("application/vnd.openxmlformats-

officedocument.spreadsheetml.sheet"),

APPLICATION_VND_MS_POWERPOINT ("application/vnd.ms-powerpoint"),

APPLICATION_VND_OPENXMLFORMART_PRESENTATION ("application/vnd.openxmlformats-

officedocument.presentationml.presentation"),

APPLICATION_VND_MOZILLA ("application/vnd.mozilla.xul+xml"),

APPLICATION_VND_GOOGLE_EARTH_XML ("application/vnd.google-earth.kml+xml"),

APPLICATION_VND_GOOGLE_EARTH ("application/vnd.google-earth.kmz"),

APPLICATION_VND_ANDROID ("application/vnd.android.package-archive"),

APPLICATION_VND_MS_XPS ("application/vnd.ms-xpsdocument"),

APPLICATION_X_7Z ("application/x-7z-compressed"),

APPLICATION_X_CHROME ("application/x-chrome-extension"),

APPLICATION_X_DVI ("application/x-dvi"),

APPLICATION_X_FONT ("application/x-font-ttf"),

APPLICATION_X_JAVASCRIPT ("application/x-javascript"),

APPLICATION_X_LATEX ("application/x-latex"),

APPLICATION_X_MPEGURL ("application/x-mpegURL"),

APPLICATION_X_RAR ("application/x-rar-compressed"),

APPLICATION_X_SHOCKWAVE ("application/x-shockwave-flash"),

APPLICATION_X_STUFFIT ("application/x-stuffit"),

APPLICATION_X_TAR ("application/x-tar"),

APPLICATION_X_WWW ("application/x-www-form-urlencoded"),

APPLICATION_X_XINSTALL ("application/x-xpinstall"),

APPLICATION_X_ACC ("audio/x-aac"),

APPLICATION_X_CAF ("audio/x-caf"),

APPLICATION_X_XCF ("image/x-xcf"),

APPLICATION_X_RPC ("text/x-gwt-rpc"),

APPLICATION_X_JQUERY ("text/x-jquery-tmpl"),


APPLICATION_X_MARKDOWN ("text/x-markdown"),

APPLICATION_X_PKCS12 ("application/x-pkcs12"),

AUDIO_BASIV ("audio/basic"),

AUDIO_L24 ("audio/L24"),

AUDIO_MP4 ("audio/mp4"),

AUDIO_MPEG ("audio/mpeg"),

AUDIO_OGG ("audio/ogg"),

AUDIO_FLAC ("audio/flac"),

AUDIO_OPUS ("audio/opus"),

AUDIO_VORBIS ("audio/vorbis"),

AUDIO_VND_RN ("audio/vnd.rn-realaudio"),

AUDIO_VND_WAVE ("audio/vnd.wave"),

AUDIO_WEBM ("audio/webm"),

AUDIO_EXAMPLE ("audio/example"),

EXAMPLE ("EXAMPLE"),

IMAGE_GIF ("/gif"),

IMAGE_JPEG ("image/jpeg"),

IMAGE_PJPEG ("image/pjpeg"),

IMAGE_PNG ("image/png"),

IMAGE_SVG ("image/svg+xml"),

IMAGE_TIFF ("image/tiff"),

IMAGE_VND ("image/vnd.djvu"),

IMAGE_EXAMPLE ("image/example"),

MESSAGE_HTTP ("message/http"),

MESSAGE_IMDN ("message/imdn+xml"),

MESSAGE_PARTIAL ("message/partial"),

MESSAGE_RFC822 ("message/rfc822"),

MESSAGE_EXAMPLE ("message/example"),

MODEL_IGES ("model/iges"),

MODEL_MESH ("model/mesh"),

MODEL_VRML ("model/vrml"),

MODEL_X3D_BINARY ("mdel/x3d+binary"),

MODEL_X3D_FASTINFOSET ("model/x3d+fastinfoset"),

MODEL_X3D_VRML ("model/x3d-vrml"),

MODEL_X3D_XML ("model/x3d+xml"),

MODEL_EXAMPLE ("model/example"),

MULTIPART_MIXED ("multipart/mixed"),

MULTIPART_ALTERNATIVE ("multipart/alternative"),

MULTIPART_RELATED ("multipart/related"),

MULTIPART_FORM ("multipart/form-data"),

MULTIPART_SIGNED ("multipart/signed"),

MULTIPART_ENCRYPTED ("multipart/encrypted"),

MULTIPART_EXAMPLE ("multipart/example"),

TEXT_CMD ("text/cmd"),

TEXT_CSS ("text/css"),

TEXT_CSV ("text/csv"),

TEXT_EXAMPLE ("text/example"),

TEXT_HTML ("text/html"),

TEXT_PLAIN ("text/plain"),

TEXT_RTF ("text/rtf"),

TEXT_VCARD ("text/vcard"),

TEXT_VND_A ("text/vnd.a"),

TEXT_VND_ABC ("text/vnd.abc"),

TEXT_XML ("text/xml"),

VIDEO_AVI ("video/avi"),

VIDEO_EXAMPLE ("video/example"),

VIDEO_MPEG ("video/mpeg"),

VIDEO_MP4 ("video/mp4"),

VIDEO_OGG ("video/ogg"),

VIDEO_QUICKTIME ("video/quicktime"),

VIDEO_WEBM ("video/webm"),


VIDEO_MATROSKA ("video/x-matroska"),

VIDEO_X_MS ("video/x-ms-wmv"),

VIDEO_X_FLV ("video/x-flv"),

OTHER ("not-defined");

El esquema de la ontología define cuales son los Encodig que soporta.

Una vez que hemos creado el objeto SSAPBinaryMessage la recuperación de la información se

realiza a través de los métodos

getMedia() Devuelve el objeto SSAPBinaryMediaMessage con la meta-información nombre

del fichero, tipo de encodig y mime-type asociada al binario.

getBinaryData()Devuelve un byte[] con el binario deserializado. Este método detecta el

encodign de su meta-información y lo utiliza la revertir la serialización del dato binario.

{"data":"SERIALIZACION DEL BINARIO OMITIDA"

,"media":{"binaryEncoding":"BASE91","mime":"application/pdf","name":"A

XADOC124013.pdf"}}

La clase SSAPMessageGenerator exponde una serie de métodos que son la intersención entre la estructura del tipo de datos Binary y los mensajes SSAP.

El método addBinary(String fieldName, File binary, Mime mime) permite añadir

archivos binarios indicando

El nombre del campo en el que queremos añadir el archivo (Esto es especialmente útil en ontologías que permiten más de un archivo binario)

El fichero del archivo binario

El mime-type al que se corresponde el archivo.

Un vez que hemos añadido todos los binarios que deseamos adjuntar a nuestra ontología. El

método generateJSONBinary() nos devuelve un String con las diferentes estructuras Binary

en formato JSON. Esta estructura JSON la podremos añadir a nuestro apartado Data de nuestro SSAP de inserción y registrar la información en SOFIA2.

NOTA: Una vez hallamos terminado de trabajar con los binarios debemos borrar la estructura de datos haciendo uso del método cleanBinary().

Una vez que queremos recuperar los datos almacenados en SOFIA2, y hemos lanzado nuestro SSAP Query, podemos rcuperar todos los binarios que contenga se mensaje.

A través del método getBinary(String JSON) obtendremos una estrcutura Map<String,

SSAPBinaryMessage> que contendrá todos los binarios que existan en el JSON de

respuesta. Donde la clave será el nombre del campo y el valor la estructura SSAPBinaryMessage con el binario serializado y su meta-información.


5.5.2 Clases SSAPMessage y derivadas

Representan la abstracción de los mensajes SSAP JSON para ser manejados desde Java.

SSAPMessage es la clase que agrupa todas las propiedades de un mensaje SSAP de

cualquier tipo. Se trata de un Java bean con métodos get() y set() para todas las propiedades

así como métodos toJson() y fromJson() para la transformación a/de JSON:

Las propiedades direction y messageType representan respectivamente el sentido y tipo de

mensaje SSAP:

SSAPMessageDirection: Enumeración con los valores REQUEST, RESPONSE,

ERROR.

SSAPMessageTypes: Enumeracion con los valores JOIN, INSERT, UPDATE,

DELETE, QUERY, LEAVE, SUBSCRIBE, UNSUBSCRIBE.

La propiedad body representa el cuerpo del mensaje SSAP. Se trata de un String que contiene

el JSON con las propiedades del mensaje de que se trate. La manera de tratar el atributo body

varía dependiendo del tipo de mensaje, ya que cada uno tiene sus propiedades. Para ello se

dispone de las clases:

SSAPBodyJoinUserPasswordMessage: Cuerpo de mensaje JOIN con autenticación

usuario/password.

SSAPBodyJoinTokenMessage: Cuerpo de mensaje JOIN con autenticación por token.

SSAPBodyLeaveMessage: Cuerpo de mensaje LEAVE.

SSAPBodyOperationMessage: Cuerpo de mensaje INSERT, UPDATE y REMOVE.

SSAPBodyQueryMessage: Cuerpo de mensaje QUERY.

SSAPBodyQueryWithParamMessage: Cuerpo de mensaje QUERY que incluye un

Map con los parámetros a enviar a una query predefinida.

SSAPBodySubscribeMessage: Cuerpo de mensaje SUBSCRIBE.

SSAPBodyUnsubscribeMessage: Cuerpo de mensaje UNSUBSCRIBE.

SSAPBodyReturnMessage: Cuerpo de mensaje de retorno desde el SIB.


SSAPBodyConfigMessage: Cuerpo de mensaje CONFIG. Incluye

o String kp, con el que se ha invocado la operación

o String instancia de kp, con el que se ha invocado la operación

o String token, con el que se ha invocado la operación

o List<SSAPBodyConfigAppsw>, lista con las aplicaciones y configuración de

software para el kp e instancia.

SSAPBodyConfigAppsw, dto que contiene

String identificación, identificación de la aplicación de software

Integer versiónsw, número de versión de software a utilizar por el

KP

String url, url donde se encuentra el WAR

Integer versioncfg, número de versión de configuración de

software a utilizar por el KP

Map<String,String> propiedadescfg, con las propiedades de

configuración definidas para la aplicación.

o List<SSAPBodyConfigAsset>, lista de los assets y propiedades de los assets

asociados al KP.

SSAPBodyConfigAsset, dto que contiene

String identificación, identificación del asset

double latitud, latitud donde se encuentra el asset.

double longitud, longitud donde se encuentra el asset.

Map<String,String>propiedades, propiedades asociadas al tipo

de asset, no son configurables

Map<String,String>propiedadescfg, propiedades configurables

del asset asociado al KP.

o List<SSAPBodyConfigOntologia>, lista de las ontologías utilizadas por el KP,

los permisos sobre ella y esquema json.

SSAPBodyConfigOntologia, dto que contiene

String identificación, nombre de la ontología que utiliza el KP


String esquemajson, esquema JSON de la ontología que utiliza

el KP

String tipopermiso, permisos que tiene sobre la ontología

o List<Serializable>, otra información de interés.

SSAPBodyBulkReturnMessage: Cuerpo de la respuesta de un mensaje de tipo BULK.

Contiene 3 atributos de tipo SSAPBulkOperationSummary indicando el resumen de la

ejecución en el SIB de las operaciones INSERT, UPDATE o DELETE contenidas en el

mensaje de BULK.

SSAPBulkOperationSummary: Resumen de un conjunto de operaciones INSERT,

UPDATE o DELETE tras ser procesadas en el SIB. Contiene la lista de ObjectsIds

afectados en BDTR para cada operación. Asi como en caso de producirse una lista

objetos de tipo SSAPBulkOperationErrorSummary conteniendo la informacióncada

error provocado por cada mensaje durante su operación.

SSAPBulkOperationErrorSummary: Contiene para cada mensaje ejecutado con

errorores en el SIB el atributo body de la petición y de la respuesta.

Todas estas clases JavaBean disponen de métodos toJson() y fromJson() para la

transformación a/de Json.

La forma de crear los mensajes a través de la utilidad sería del siguiente modo.

// Para conectar con el SIB generamos el mensaje SSAP JOIN SSAPMessage msg = this.ssapMessageGenerator.generateJoinMessage( usuario, password, instance); //Enviamos el SSAP JOIN SSAPMessage retorno = kp.send(msg); //Comprobamos la respuesta del SIB if (retorno == null)

throw new ExcepcionGateway("Imposible conectar al SIB"); //Realizamos la transformación del mensaje de JSON al Objeto. SSAPBodyReturnMessage retornoBody =

SSAPBodyReturnMessage.fromJsonToSSAPBodyReturnMessage(retorno.getBody());

5.5.3 Clase SSAPBulkMessage y derivadas:

Se trata de la clase utilizada en el API Java para construir mensajes de tipo SSAP

BULK. Es una clase derviada de SSAPMessage, hereda todos sus atributos y añade

métodos para facilitar la construcción de un mensaje SSAP de tipo BULK a partir de

mensajes SSAP de tipo INSERT, UPDATE y DELETE. Estos métodos son:


addMessage(ssapMessage: SSAPMessage):SSAPBulkMessage: Añade al

atributo “body” del mensaje SSAPBulkMessage el mensaje INSERT, UPDATE

o DELETE indicado por parámetros.

Devuelve el propio objeto SSAPBulkMessage para facilitar el encadenamiento

de mensajes:

msgBulk.addMessage(msgInsert1).addMessage(msgInsert2).addMessage(msgInsert3);

En caso de que el mensaje añadido no sea de tipo INSERT, UPDATE o

DELETE, el método lanzará una excepción de tipo

NotSupportedMessageTypeExepcion.

addMessage(ssapMessages: List<SSAPMessage>):void: Añade al atributo

“body” del mensaje SSAPBulkMessage una lista de mensajes INSERT,

UPDATE o DELETE indicada por parámetros.

En caso de que alguno de los mensajes añadidos no sea de tipo INSERT,

UPDATE o DELETE, el método lanzará una excepción de tipo

NotSupportedMessageTypeExepcion.

5.6 Ejemplo de uso

Para crear un KP que usa el protocolo MQTT, definiremos la conexión física con el SIB a través

de MQTT y crearemos la instancia del KP.

Una vez hecho esto estaremos preparados para invocar a las operaciones para interoperar con

el SIB.

// Establecemos los parámetros de configuración para la conexión física con el SIB

Kp kp; try { MQTTConnectionConfig config = new MQTTConnectionConfig(); config.setHostSIB(host); config.setPortSIB(port); config.setQualityOfService(QoS.AT_LEAST_ONCE); config.setTimeOutConnectionSIB(5000);

// Creamos la instancia del KP con la configuración MQTT kp=new KpMQTTClient(config); } catch (Exception e) { log.error("Imposible conectar al SIB por TCP: "+e.getMessage()); throw new ExcepcionGateway("Imposible conectar al SIB por TCP:

"+e.getMessage()); }

//A partir de aquí a través de la clase de utilidad de SSAPMessageGenerator iríamos

invocando a las diferentes operaciones para interoperar con el SIB


6 API ANDROID

6.1 Introducción

El desarrollo de aplicaciones para Android se realiza con el lenguaje de programación Java y

un conjunto de herramientas de desarrollo llamado Android SDK.

SOFIA2 proporciona un API Java para el desarrollo de KPs sobre el SDK de Android. Este API

consta de un conjunto de clases e interfaces Java que facilitan la generación y tratamiento de

mensajes SSAP así como la conexión con la plataforma a traves de conectores que se

comunican con los gateways de la misma.

6.2 Distribución

El API de SOFIA2 para desarrollo en Android se proporciona en forma de librería jar que será

necesario incluir en los KPs y proyectos que incluyan conectividad de dispositivos android con

el SIB. La librería ssap-android.jar vendrá incluida como parte de la distribución del SDK de

Android para SOFIA2.

6.3 Interfaz KP

Proporciona los métodos para conectar con la plataforma e intercambiar mensajes SSAP.

Se trata de una interfaz, que implementan varias clases, representando cada clase un conector

de protocolo específico (MQTT, HTTP).

Facilita la migración de un KP a nuevos protocolos que se puedan definir en un futuro,

abstrayendo el modo de conectar y enviar/recibir mensajes SSAP del protocolo utilizado.

La interfaz tiene el siguiente aspecto:

public interface Kp { boolean isConnected();

String getSessionKey(); void connect() throws ConnectionToSibException; void disconnect();

void setConnectionConfig(ConnectionConfig config); void setXxteaCipherKey(String cipherKey); SSAPMessage send(SSAPMessage msg) throws ConnectionToSibException; SSAPMessage sendCipher(SSAPMessage msg) throws ConnectionToSibException; void addListener4SIBNotifications(Listener4SIBIndicationNotifications listener); void removeListener4SIBNotifications(Listener4SIBIndicationNotifications listener);

}

Estas operaciones en las distintas implementaciones permiten a las aplicaciones Java: boolean isConnected():Conocer si el KP está conectado a un SIB

String getSessionKey(): Una vez conectado al SIB, recuperar la sessionKey

asignada para la conexión void connect(): Establecer una conexión física con el SIB a través del Gateway del

protocolo implementado por la clase.


void disconnect(): Cerrar la conexión física establecida con el SIB en una

operación connect(). void setConnectionConfig(ConnectionConfig config): Configura los parametros

de conexión al SIB. El parámetro ConnectionConfig, informa al KP de los parámetros de configuración para conectar conectar con el Gateway del SIB.

void setXxteaCipherKey(String cipherKey): Establece la clave del algoritomo de

cifrado XXTEA para cifrar el intercambio de mensajes SSAP.

SSAPMessage send(SSAPMessage msg): Envia un mensaje SSAP al SIB, recibiendo

el mensaje SSAP de respuesta. SSAPMessage sendCipher(SSAPMessage msg): Envia un mensaje SSAP al SIB,

recibiendo el mensaje SSAP de respuesta. La comunicación irá cifrada por algoritmo XXTEA.

void addListener4SIBNotifications(Listener4SIBIndicationNotifications listener): Añade un listener para recibir notificaciones de mensajes de suscripcion.

Un listener, es una clase que implementa la interfaz Listener4SIBIndicationNotifications, que obliga a implementar el método onIndication, que recibe por parámetros el mensaje SSAP INDICATION con los datos de notificación de la suscripción.

void removeListener4SIBNotifications(Listener4SIBIndicationNotifications listener): Elimina un listener para dejar de recibir notificaciones de mensajes de

suscripción.

6.4 Paralelismos con el API JAVA

El API de SOFIA2 para desarrollo en Android es un desarrollo independiente del API Java. No

obstante, su desarrollo es una adaptación de las clases Java originales para ser compatibles

con implementaciones concretas en el dalvik de Android: limpieza de AOP, minimización de las

dependencias, seguridad, etc.

Debido a este paralelismo, el aspecto, funcionamiento y las funcionalidades del API para

Android son exactamente las mismas que en el API Java, salvo un par de peculiaridades:

Las clases del API se encuentran en los paquetes

package com.indra.sofia2.ssapandroid;

Permitir la conexión a internet de las apps desarrolladas, en el AndroidManifest.xml

<uses-permission android:name="android.permission.INTERNET" />

Este apartado del API Android se centra tan solo en repasar los aspectos principales de esta

implementación. Para mayor detalle del API repasar los puntos 5.4 Conectores de Protocolos

en el API y 5.5 Utilidades del API.

6.5 Ejemplo de uso

Para crear un KP que usa el protocolo MQTT, definiremos la conexión física con el SIB a través

de MQTT y crearemos la instancia del KP.

Una vez hecho esto estaremos preparados para invocar a las operaciones para interoperar con

el SIB.


// Establecemos los parámetros de configuración para la conexión física con el SIB

Kp kp; try { MQTTConnectionConfig config = new MQTTConnectionConfig(); config.setHostSIB(host); config.setPortSIB(port); config.setQualityOfService(QoS.AT_LEAST_ONCE); config.setTimeOutConnectionSIB(5000);

// Creamos la instancia del KP con la configuración MQTT kp=new KpMQTTClient(config); } catch (Exception e) { log.error("Imposible conectar al SIB por TCP: "+e.getMessage()); throw new ExcepcionGateway("Imposible conectar al SIB por TCP:

"+e.getMessage()); }

//A partir de aquí a través de la clase de utilidad de SSAPMessageGenerator iríamos

invocando a las diferentes operaciones para interoperar con el SIB


7 API ARDUINO

7.1 Librería KPMqtt

API que proporciona la Plataforma para dispositivos Arduino, incluye operaciones para

interoperar con el SIB: conectar, enviar y recibir mensajes del SIB.

/** * Método que permite establece el id dle cliente */ void setClientId(char* cId);

/** * Método que te da el id del cliente */

char* getClientId();

/** * Método que retorna si el KP está actualmente conectado con el SIB */

bool isConnected();

/** * Método que devuelve la session Key para la conexión actual con el SIB * Retorna null si no está conectado al SIB */

char* getSessionKey();

/** * Método que conecta al KP con el SIB enviando un mensaje SSAP de JOIN */

void connect();

/** * Método que desconecta físicamente al KP del SIB */

void disconnect();

/** * Método que establece los parámetros de configuración para la conexión física del KP * con el SIB */

void setConnectionConfig(ConnectionConfig* config);

/** * Método para enviar mensajes SSAP al SIB * @return */

SSAPMessage send(SSAPMessage* msg);

/** * Método para enviar mensajes SSAP encriptados al SIB usando el algoritmo XXTea */

SSAPMessage sendEncrypt(char* msgJson, unsigned char* key, int keyLength);

/** * Método para registrar un escuchador para las notificaciones de suscripción. */

void addListener4SIBNotifications(Listener4SIBIndicationNotifications listener);

/** * Método para liberar un escuchador de notificaciones de suscripción


*/ void removeListener4SIBNotifications(Listener4SIBIndicationNotifications listener);

/** * Método para registrar un escuchador para recibir mensajes desde el SIB */

void addListener4SIBCommandMessageNotifications(Listener4SIBCommandMessageNotifications listener);

/** * Método para liberar un escuchador para dejar de recibir mensajes desde el SIB */

void removeListener4SIBCommandMessageNotifications(Listener4SIBCommandMessageNotifications listener);

/** * Método para lanzar el bucle para recibir notificaciones del SIB*/

void loopMqtt();

/** * Callback para recibir notificaciones del SIB */

void callback( char* topic, byte* payload, unsigned int length );

7.2 Protocolos soportados

7.2.1 MQTT

Arduino dispone de la librería PubSubClient que permite realizar operaciones simples de

publicación y suscripción de cliente sobre un servidor sobre el protocolo MQTT.

Para hacer uso de esta librería, basta con importarla en el código del Arduino.

#include <PubSubClient.h>

Los mensajes para conectar con el SIB se realizan de forma similar al resto de APIs a través de

mensajes SSAP

SSAPMessage joinMessage; Serial.println("Send join"); //Generamos el mensaje SSAP de join joinMessage=ssapGenerator.generateJoinMessage("abcd23efca238daddd32398d", "KPArdu:001"); //Enviamos el mensaje SSAPMessage joinResponse=kp.send(&joinMessage); Serial.println("Receives join"); char* bodyJoin=joinMessage.getBody(); delete[] bodyJoin; //Obtenemos el cuerpo del mensaje de respueta char* responseBody=joinResponse.getBody(); //Transformamos el mensaje recibido de JSON al objeto SSAPBodyReturnMessage bodyMessage=SSAPBodyReturnMessage::fromJSonToSSAPMessage(responseBody);


8 API JAVASCRIPT

8.1 Librería kp-core.js (deprecada) y

sofia2-api-js_v2<minor-version>.js

La Plataforma también proporciona un API para poder interoperar con el SIB por medio de

JavaScript.

La versión de la librería kp-core.js está deprecada actualmente, el API Javascript evolucionará

con la librería sofia2-api-js_v2<minor_version>.js

El API Javascript proporciona un conjunto de funciones que comprenden todas las operaciones

SSAP, abstrayendo al programador de la construcción del mensaje.

Cada función recibe por argumentos los datos del tipo de mensaje que abstrae, así como una

función callback que invocará el API para notificar la respuesta una vez se produzca.

El API Javascript considera que todas las funciones callback tienen un único argumento, que es

un objeto con el mensaje SSAP de respuesta.

La interfaz de la librería Javascript tiene el siguiente aspecto:

Nota: A partir de la librería sofia2-api-js_v2<minor_version>.js, todas las funciones del API

quedan encapsuladas dentro del namespace sofia2. Por lo que para ser invocadas desde la

capa de aplicación, debe utilizarse este namespace.

Pej: sofia2.join(···)

function setKpName(kpName); function join(user, pass, instance, joinResponse); function joinRenovateSessionKey (user, pass, instance, joinResponse); function joinCipher(user, pass, instance, joinResponse); function joinRenovateSessionKeyCipher(user, pass, instance, joinResponse); function joinToken(token, instance, joinResponse); function joinRenovateSessionKeyToken(token, instance, joinResponse); function joinTokenCipher(token, instance, joinResponse); function joinRenovateSessionKeyTokenCipher(token, instance, joinResponse); function leave(leaveResponse); function leaveCipher(leaveResponse); function insert(data, ontology, insertResponse); function insertCipher(data, ontology, insertResponse); function insertWithQueryType(data, ontology, queryType, insertResponse); function insertWithQueryTypeCipher(data, ontology, queryType, insertResponse); function update(data, query,ontology, updateResponse); function updateCipher(data, query,ontology, updateResponse); function updateWithQueryType(data, query, ontology, queryType, updateResponse); function updateWithQueryTypeCipher(data, query, ontology, queryType, updateResponse); function remove(query, ontology, removeResponse); function removeCipher(query, ontology, removeResponse); function removeWithQueryType(query, ontology, queryType, removeResponse); function removeWithQueryTypeCipher(query, ontology, queryType, removeResponse); function query(query, ontology, queryResponse); function queryCipher(query, ontology, queryResponse); function queryWithQueryType(query, ontology, queryType, queryParams, queryResponse);


function queryWithQueryTypeCipher(query, ontology, queryType, queryParams, queryResponse); function subscribe(suscription, ontology, refresh); function subscribeCipher(suscription, ontology, refresh); function subscribeWithQueryType(suscription, ontology, queryType, refresh); function subscribeWithQueryTypeCipher(suscription, ontology, queryType, refresh); function subscribeWithQueryTypeSibDefinedParams(suscription, ontology,

queryType, queryParams, refresh) function unsubscribe(querySubs, unsubscribeResponse, unsubscribeMessages); function unsubscribeCipher(querySubs, unsubscribeResponse, unsubscribeMessages); function setCipherKey(key);

setKpName: Informa al API del nombre del Kp.

join: Envía un mensaje SSAP JOIN de autenticación por usuario/password. Recibe la

respuesta a través de la función callback joinResponse, que tiene como argumento el

mensaje SSAP JOIN de tipo RESPONSE con la sessionkey asignada por el SIB una

vez comprobadas las credenciales.

joinRenovateSessionKey: Envía un mensaje SSAP JOIN de renovación de

sessionkey por usuario/password. Recibe la respuesta a través de la función callback

joinResponse, que tiene como argumento el mensaje SSAP JOIN de tipo RESPONSE

con la sessionkey renovada por el SIB una vez comprobadas las credenciales

joinToken: Envía un mensaje SSAP JOIN de autenticación por token. Recibe la



vez comprobada la validez del token.

joinRenovateSessionKeyToken: Envía un mensaje SSAP JOIN de renovación de

sessionkey por token. Recibe la respuesta a través de la función callback

joinResponse, que tiene como argumento el mensaje SSAP JOIN de tipo RESPONSE

con la sessionkey renovada por el SIB una vez comprobada la validez del token.

leave: Envía un mensaje SSAP LEAVE. No es necesario especificar la sessionKey, ya

que la controla el API. Recibe la respuesta a través de la función callback

leaveResponse, que tiene como argumento el mensaje SSAP LEAVE de tipo

RESPONSE indicando si la operación se ha realizado satisfactoriamente.

insert: Envía un mensaje SSAP INSERT con los datos y sobre la ontología indicados.

Recibe la respuesta a través de la función callback insertResponse, que tiene como

argumento el mensaje SSAP INSERT de tipo RESPONSE indicando si la operación se

ha realizado satisfactoriamente.

Los datos enviados deben estar en formato Nativo de MongoDB para ser insertados.


InsertWithQueryType: Envía un mensaje SSAP INSERT con los datos y sobre la

ontología indicados. Recibe la respuesta a través de la función callback

insertResponse, que tiene como argumento el mensaje SSAP INSERT de tipo


Los datos enviados pueden estar tanto en formato nativo, como pueden ser sentencia

Insert de tipo SQL Like. El argumento queryType con los valores “NATIVE” o

“SQLLIKE” sirve para indicar una circunstancia u otra.

update: Envía un mensaje SSAP UPDATE para actualizar datos existentes sobre la

ontología indicada. Para ello, el valor de los nuevos datos se notifica en el argumento

data, y los criterios a cumplir para ser actualizados se notifican en el argumento query.

Recibe la respuesta a través de la función callback updateResponse, que tiene como

argumento el mensaje SSAP UPDATE de tipo RESPONSE indicando si la operación se


Tanto los datos enviados como los criterios de selección para actualizar, deben estar en

formato Nativo de MongoDB para ser actualizados.

updateWithQueryType: Envía un mensaje SSAP UPDATE para actualizar datos

existentes sobre la ontología indicada. Recibe la respuesta a través de la función

callback updateResponse, que tiene como argumento el mensaje SSAP UPDATE de

tipo RESPONSE indicando si la operación se ha realizado satisfactoriamente.

Los datos se pueden actualizar tanto utilizando el formato nativo, como mediante una

sentencia Update de tipo SQL Like. El argumento queryType con los valores “NATIVE”

o “SQLLIKE” sirve para indicar una circunstancia u otra.

En caso de utilizarse el formato Nativo, hay que indicar en el argumento data el nuevo

valor, y en el argumento query los criterios a cumplir para ser actualizados.

En caso de utilizarse el formato SQLLIKE, el argumento data será null y el argumento

query será la sentencia Update en formato SQLLIKE.

remove: Envía un mensaje SSAP DELETE para borrar datos existentes sobre la

ontología indicada. Para ello, se notifica la sentencia de borrado nativa en formato

MongoDB en el argumento query. Recibe la respuesta a través de la función callback

removeResponse, que tiene como argumento el mensaje SSAP DELETE de tipo


removeWithQueryType: Envía un mensaje SSAP DELETE para borrar datos



callback removeResponse, que tiene como argumento el mensaje SSAP DELETE de


Los datos se pueden borrar tanto utilizando el formato nativo, como mediante una

sentencia Delete de tipo SQL Like. El argumento queryType con los valores “NATIVE” o


En caso de utilizarse el formato Nativo, hay que indicar en el argumento query la

sentencia MongoDB de borrado.

En caso de utilizarse el formato SQLLIKE, el argumento query será la sentencia Delete

en formato SQLLIKE.

query: Envía un mensaje SSAP QUERY con la consulta y sobre la ontología indicados.

Recibe la respuesta a través de la función callback queryResponse, que tiene como

argumento el mensaje SSAP QUERY de tipo RESPONSE devolviendo los datos de la

consulta.

Los datos de la consulta deben estar en formato Nativo de MongoDB.

queryWithQueryType: Envía un mensaje SSAP QUERY con la consulta y sobre la


queryResponse, que tiene como argumento el mensaje SSAP QUERY de tipo

RESPONSE devolviendo los datos de la consulta.

Los criterios de la consulta del argumento query, se pueden indicar tanto utilizando el

formato nativo, como mediante una sentencia Select de tipo SQL Like. El argumento

queryType con los valores “NATIVE” o “SQLLIKE” sirve para indicar una circunstancia

u otra.

En caso de utilizarse el formato Nativo, hay que indicar en el argumento query los datos

para la consulta en formato MongoDB

En caso de utilizarse el formato SQLLIKE, el argumento query será la sentencia Select

en formato SQL Like.

Asimismo, se pueden ejecutar consultas predefinidas en el SIB, en este caso hay que

indicar en el argumento query el identificador de la consulta predefinida y en el

argumento queryType el valor “SIB_DEFINED”.

Adicionalmente, en caso de tratarse de una consulta predefinida SIB_DEFINED que

admita parámetros de entrada, estos pueden enviarse a través del argumento

queryParams, pasando un Map javascript:

var params = {};


params["PARAM1"] = '\"S_Temperatura_00001\"';

params["PARAM2"] = '20';

En el resto de casos (NATIVE, SQLLIKE o SIB_DEFINED sin parámetros), el

argumento queryParams será null.

subscribe: Envía un mensaje SSAP SUBSCRIBE con la consulta de suscripción,

refresco y sobre la ontologia indicados.

Los datos de la consulta de suscripción deben estar en formato Nativo de MongoDB.

subscribeWithQueryType: Envía un mensaje SSAP SUBSCRIBE con la consulta de

suscripción, refresco y sobre la ontología indicados.




u otra.


para la consulta suscripción en formato MongoDB


de suscripción en formato SQL Like.

subscribeWithQueryTypeSibDefinedParams: Ofrece la misma funcionalidad que

SubscribeWithQueryType, pero permitiendo añadir parámetros para query

SIB_DEFINED

unsubscribe: Envía un mensaje SSAP UNSUBSCRIBE sobre la query de suscripción

indicada. Recibe la respuesta a través de la función callback unsubscribeResponse.

Así como errores a través de unsubscribeMessages.

Asi mismo, en el caso de suscripciones, el programador deberá implementar las siguientes

funciones:

function subscriptionWellLaunchedResponse(subscriptionId, suscription):

Notifica el Id de suscripción de una query una vez suscritos.

Function indicationForSubscription(ssapMessage): Notifica un mensaje SSAP

de tipo INDICATION para una notificación de suscripción.

El API Javascript permite cifrado XXTEA. Para ello, el API proporciona la función:

setCipherKey: que informa al API de la clave de cifrado.


Y proporciona para función, su función homónima de cifrado xxxCipher(). (joinCipher(),

insertCipher()….).


8.2.1 Websocket

Se soporta a través del Gateway Websocket de Sofia2.

Este API necesita:

Importar las siguientes librerías:

o Librería del API Javascript: sofia2-api-js_v2<minor-version>.js (soportado

a partir de la versión sofia2-api-js_v2.8.0.js.

Inicializar la variable pathToWebsocketServer que indica al API el endpoint del

Gateway del SIB.

Ejemplo de utilización

//Cargamos la librería del api <script type='text/javascript' src="sofia2-api-js_v2<minor-version>.js">;</script> <script type="text/javascript"> var pathToWebsocketServer =

"ws://sofia2.com/sib/api_websocket";</script>

//Para conectar con el SIB, nos creamos una función que será la que invoque a la operación de //conectar disponibilizada en la librería. function conectarSIB(user, pass, inst) { sofia2.join(user, pass, inst,function(mensajeSSAP){ //Comprobamos si se ha establecido la conexión o no if(mensajeSSAP != null && mensajeSSAP.body.data != null &&

mensajeSSAP.body.ok == true){

$("#infoConexion").text("Conectado al sib con sessionkey: "+mensajeSSAP.sessionKey).show(); }else{ $("#infoConexion").text("Error conectando del sib").show(); } });

}

8.2.2 AJAX/AJAX Push

Se soporta a través del Gateway DWR de Sofia2.

Este API necesita:

Importar las siguientes librerías:


o Librería del API Javascript: kp-core.js (deprecada) ó sofia2-api-

js_v2<minor-version>.js

o Librerias DWR del Gateway de sofia2.com:

http://sofia2.com/sib/dwr/engine.js, http://sofia2.com/sib/dwr/util.js,

http://sofia2.com/sib/dwr/interface/GatewayDWR.js

Inicializar la variable pathToDwrServlet que indica al API el endpoint del Gateway

del SIB

Activar la opción de reverse Ajax de DWR para recibir notificaciones de suscripción

mediante:

o dwr.engine.setActiveReverseAjax(true);

o dwr.engine.setTimeout(0);

Ejemplo de utilización:

//Cargamos la librería del api <script type='text/javascript' src="sofia2-api-js_v2<minor-version>.js">;</script> <script type='text/javascript' src='http://sofia2.com/sib/dwr/engine.js'></script> <script type='text/javascript' src='http://sofia2.com/sib/dwr/util.js'></script> <script type='text/javascript' src='http://

sofia2.com/sib/dwr/interface/GatewayDWR.js'></script> <script type="text/javascript"> var pathToDwrServlet = 'http://sofia2.com/sib/dwr';</script> $(function(){

try {

dwr.engine.setActiveReverseAjax(true);

dwr.engine.setTimeout(0);

} catch(e) {}

});

//Para conectar con el SIB, nos creamos una función que será la que invoque a la operación de //conectar disponibilizada en la librería. function conectarSIB(user, pass, inst) { sofia2.join(user, pass, inst,function(mensajeSSAP){ //Comprobamos si se ha establecido la conexión o no if(mensajeSSAP != null && mensajeSSAP.body.data != null &&

mensajeSSAP.body.ok == true){

$("#infoConexion").text("Conectado al sib con sessionkey: "+mensajeSSAP.sessionKey).show(); }else{ $("#infoConexion").text("Error conectando del sib").show(); } }); }

http://sofia2.com/sib/dwr/engine.js

http://sofia2.com/sib/dwr/util.js


9 API NODE.JS

9.1 Introducción

Node.js (http://nodejs.org/) es una plataforma que permite desarrollar sobre JavaScript en el

lado del servidor a través del motor V8 JavaScript desarrollado por Google. Su arquitectura

está basada a eventos y pensada para la programación asíncrona. Está formado por varios

módulos que facilitan el uso de este lenguaje.

SOFIA2 proporciona un API Node.js para el desarrollo de KPs. Este API consta de un conjunto

de utilidadesque facilitan la generación y tratamiento de mensajes SSAP así como la conexión

con la plataforma a través de MQTT para la comunicación con los gateways de la misma.

9.2 Librería KpMQTT.js

La Plataforma proporciona también un API para interoperar desde el lado del Servidor a través

de javascript.

Se proporciona una “interfaz” que abstrae de la implementación de bajo nivel de la clase

MQTTClient.js y que junto al generador de mensajes SSAP nos permite operar directamente

con el SIB. Para este API se establece el criterio de dos topics, uno para publicar mensajes y

otro topic para la recepción de mensajes del SIB.

Los métodos de la “interfaz” KpMQTT.js son los siguientes:

function connect(port, host);

function disconnect();

function isConnected();

function send(ssapMessage);

function sendCipher(ssapMessage);

function setCipherKey(_cipherKey);

function messageDispatcher();

connect: Allow Permite la conexión con el SIB suministrando la url y el puerto..

disconnect: Libera una conexión existente con el SIB.

isConnected: Devuelve un booleano que indica si la sesión ha sido iniciada o no.

send: Envía un mensaje SSAP al SIB y se subscribe al topic de respuesta para ese

mensaje.

sendCipher: Envía un mensaje SSAP cifrado al SIB. Para ello con el API se suministran

las clases de cifrado XXTEA.js y base64.js..

http://nodejs.org/


setCipherKey: Establece la clave de cifrado que recibe como parámetro.

messageDispatcher: Listener de espera de un mensaje que llegue por el topic de

notificaciones.

9.3 Generador de Mensajes SSAP

También está disponible una clase encargada de generar los distintos mensajes con formato

SSAP, llamada SSAPMessageGenerator.js. Esta clase es idéntica a la del api de Javascript,

con la salvedad de que los mensajes que van cifrados no están incluídos, puesto que la clase

KpMQTT.js permite el envío de mensajes cifrados y sin cifrar a través de los métodos send () y

sendCipher ().

Las funciones que expone son las siguientes:

function join(user, pass, instance, joinResponse);

function joinToken(token, instance, joinResponse);

function leave(leaveResponse);

function insert(data, ontology, insertResponse);

function insertWithQueryType(data, ontology, queryType, insertResponse);

function update(data, query,ontology, updateResponse);

function updateWithQueryType(data, query, ontology, queryType, updateResponse);

function remove(query, ontology, removeResponse);

function removeWithQueryType(query, ontology, queryType, removeResponse);

function query(query, ontology, queryResponse);

function queryWithQueryType(query, ontology, queryType, queryParams, queryResponse);

function subscribe(suscription, ontology, refresh);

function subscribeWithQueryType(suscription, ontology, queryType, refresh);

function unsubscribe(querySubs, unsubscribeResponse, unsubscribeMessages);

join: Envía un mensaje SSAP JOIN de autenticación por usuario/password. Recibe la



vez comprobadas las credenciales.

joinToken: Envía un mensaje SSAP JOIN de autenticación por token. Recibe la



vez comprobada la validez del token.


leave: Envía un mensaje SSAP LEAVE. No es necesario especificar la sessionKey, ya

que la controla el API. Recibe la respuesta a través de la función callback

leaveResponse, que tiene como argumento el mensaje SSAP LEAVE de tipo


insert: Envía un mensaje SSAP INSERT con los datos y sobre la ontología indicados.

Recibe la respuesta a través de la función callback insertResponse, que tiene como

argumento el mensaje SSAP INSERT de tipo RESPONSE indicando si la operación se


Los datos enviados deben estar en formato Nativo de MongoDB para ser insertados.

InsertWithQueryType: Envía un mensaje SSAP INSERT con los datos y sobre la


insertResponse, que tiene como argumento el mensaje SSAP INSERT de tipo


Los datos enviados pueden estar tanto en formato nativo, como pueden ser sentencia

Insert de tipo SQL Like. El argumento queryType con los valores “NATIVE” o


update: Envía un mensaje SSAP UPDATE para actualizar datos existentes sobre la

ontología indicada. Para ello, el valor de los nuevos datos se notifica en el argumento

data, y los criterios a cumplir para ser actualizados se notifican en el argumento query.

Recibe la respuesta a través de la función callback updateResponse, que tiene como

argumento el mensaje SSAP UPDATE de tipo RESPONSE indicando si la operación se


Tanto los datos enviados como los criterios de selección para actualizar, deben estar en

formato Nativo de MongoDB para ser actualizados.

updateWithQueryType: Envía un mensaje SSAP UPDATE para actualizar datos


callback updateResponse, que tiene como argumento el mensaje SSAP UPDATE de


Los datos se pueden actualizar tanto utilizando el formato nativo, como mediante una

sentencia Update de tipo SQL Like. El argumento queryType con los valores “NATIVE”

o “SQLLIKE” sirve para indicar una circunstancia u otra.

En caso de utilizarse el formato Nativo, hay que indicar en el argumento data el nuevo

valor, y en el argumento query los criterios a cumplir para ser actualizados.


En caso de utilizarse el formato SQLLIKE, el argumento data será null y el argumento

query será la sentencia Update en formato SQLLIKE.

remove: Envía un mensaje SSAP DELETE para borrar datos existentes sobre la

ontología indicada. Para ello, se notifica la sentencia de borrado nativa en formato

MongoDB en el argumento query. Recibe la respuesta a través de la función callback

removeResponse, que tiene como argumento el mensaje SSAP DELETE de tipo


removeWithQueryType: Envía un mensaje SSAP DELETE para borrar datos


callback removeResponse, que tiene como argumento el mensaje SSAP DELETE de


Los datos se pueden borrar tanto utilizando el formato nativo, como mediante una

sentencia Delete de tipo SQL Like. El argumento queryType con los valores “NATIVE” o


En caso de utilizarse el formato Nativo, hay que indicar en el argumento query la

sentencia MongoDB de borrado.

En caso de utilizarse el formato SQLLIKE, el argumento query será la sentencia Delete

en formato SQLLIKE.

query: Envía un mensaje SSAP QUERY con la consulta y sobre la ontología indicados.

Recibe la respuesta a través de la función callback queryResponse, que tiene como

argumento el mensaje SSAP QUERY de tipo RESPONSE devolviendo los datos de la

consulta.

Los datos de la consulta deben estar en formato Nativo de MongoDB.

queryWithQueryType: Envía un mensaje SSAP QUERY con la consulta y sobre la

ontología indicada. Recibe la respuesta a través de la función callback queryResponse,

que tiene como argumento el mensaje SSAP QUERY de tipo RESPONSE devolviendo

los datos de la consulta.




u otra.


para la consulta en formato MongoDB



en formato SQL Like.

Asimismo, se pueden ejecutar consultas predefinidas en el SIB, en este caso hay que

indicar en el argumento query el identificador de la consulta predefinida y en el

argumento queryType el valor “SIB_DEFINED”.

Adicionalmente, en caso de tratarse de una consulta predefinida SIB_DEFINED que

admita parámetros de entrada, estos pueden enviarse a través del argumento

queryParams, pasando un Map javascript:

var params = {};

params["PARAM1"] = '\"S_Temperatura_00001\"';

params["PARAM2"] = '20';

En el resto de casos (NATIVE, SQLLIKE o SIB_DEFINED sin parámetros), el

argumento queryParams será null.

subscribe: Envía un mensaje SSAP SUBSCRIBE con la consulta de suscripción,

refresco y sobre la ontologia indicados.

Los datos de la consulta de suscripción deben estar en formato Nativo de MongoDB.

subscribeWithQueryType: Envía un mensaje SSAP SUBSCRIBE con la consulta de

suscripción, refresco y sobre la ontología indicados.




u otra.


para la consulta suscripción en formato MongoDB


de suscripción en formato SQL Like.

unsubscribe: Envía un mensaje SSAP UNSUBSCRIBE sobre la query de suscripción

indicada. Recibe la respuesta a través de la función callback unsubscribeResponse.

Así como errores a través de unsubscribeMessages.



9.4.1 MQTT

El API de Node.js funciona sobre el protocolo MQTT, para ello se ha dispuesto de la clase

MQTTClient.js que gestiona dicho protocolo y exporta las siguientes funciones:

function create_conection(port, host, clientID);

function publish(pub_topic, payload);

function subscribe(sub_topic);

function unsubscribe(topic);

function ping();

function disconnect();

create_connection: Crea una conexión al SIB utilizando Puerto, url del host e id de

cliente, este último parámetro es opcional.

publish: Envío de mensajes (payload) a una cola o topic de recepción de mensajes.

subscribe: Se subscribe directamente a un topic, que recibe como parámetro, para la

recepción de mensajes.

unsubscribe: Esta función envía un mensaje al SIB para dejar de recibir notificaciones

a través de un topic.

ping: Envía un mensaje para comprobar la conexión con el servidor MQTT.

disconnect: Libera la conexión establecida con el SIB.

9.5 Ejemplo de uso

A continuación se muestra un ejemplo de uso de cómo utilizar el API Node.js.

Lo primero que hay que hacer es importar los tres módulos que se ven en la cabecera de la

imagen, es decir:

kpMQTT para poder utilizar las funciones del API NODE.JS.

SSAPMessageGenerator para poder generar los distintos mensajes SSAP a enviar al

SIB.

Y finalmente el módulo wait.for, que permitirá lanzar la ejecución del programa en un

hilo independiente wait.launchFiber(main)


NOTA: wait.for. A través de esta función se puede llamar a cualquier función asíncrona

estándar de Node.js en modo secuencial o síncrono, a la espera de los resultados y sin

bloqueo del bucle de eventos del nodo. Disponible a través de los módulos que

proporcina Node.js

Seguidamente se muestra un ciclo básico para la ontología SensorTemperatura:

- Un mensaje JOIN al SIB para obtener el sessionKey en la respuesta, que nos permitirá

envíar mensajes de inserción, borrado, actualización, subscripción, etc…

- Lo siguiente en la prueba es el envío de un mensaje de subscripción para aquellas

medidas superiores a 18ºC, si todo va bien. Aquellos datos introducidos en la ontología

que cumplan esta condición serán devueltos mediante una notificación al topic

MQTT_INDICATION, y serán procesados por la función messageDispatcher del kp.

- Finalmente se realiza una inserción en la ontología de una medida de 21ºC, para

conseguir la correspondiente notificación.


10 API C

10.1 Librería libssap-core-api-c

Proporciona una librería de enlace dinámico para la construcción de KPs en lenguaje C.

Por compatibilidad de entre plataformas se entrega el código fuente de la librería junto con un

fichero Makefile para su compilación.

El API se puede encontrar en SOFIA_SDK_2.3\SOFIA\SOFIA-SDK\API\API-KP-C\ssap-core-

api-c.

De este modo es posible generar la librería y se proporcionan los ficheros de cabecera para

resolver las dependencias de compilación.

La estructura del código es la propia de un proyecto C de librería de enlace dinámico de

Netbeans, aunque puede ser compilado directamente con la herramienta make

build: Directorio donde se generan los ficheros objeto de la librería.

dist: Directorio donde se genera la librería.

nbproject: Directorio con los parámetros de compilación de la librería.

src: Código fuente de la librería.

Makefile: Fichero principal para la compilación de la librería. Hace referencia la

configuración almacenada en el directorio nbproject.

De este modo es posible abrir la proyecto con Netbeans y configurar los distintos parámetros

de compilación desde los asistentes, o configurarlos a manualmente en nbproject/ Makefile-

variables.mk


10.2 Compilar con Make

Para generar la libreria con la herramienta Make los pasos son los siguientes:

1. Configurar los variables en el fichero nbproject/Makefile-variables.mk.

En la sección Release asignar los directorios y nombre de la librería si se desean

modificar.

2. Borrar ficheros de compilaciones anteriores ejecutando desde la raíz del proyecto el

comando:

make –f nbproject/Makefile-Release.mk QMAKE= SUBPROJECTS= .clean-conf

3. Crear la libreria con el commando:

make –f nbproject/Makefile-Release.mk QMAKE= SUBPROJECTS= .build-conf

Una vez finalizado la libreria estará en el directorio indicado en el fichero nbproject/Makefile-

variables.mk.


El protocolo soportado por la librería para comunicar con el SIB es MQTT.

10.4 Características del API

El API proporciona un conjunto de utilidades y funciones para:

Conectar/Desconectar con la plataforma.

Generar y encapsular mensajes SSAP.

Enviar mensajes SSAP a la plataforma.

Parsear mensajes SSAP y JSON.

Suscribirse a eventos en la plataforma.

10.5 Funciones del API

10.5.1 Funciones de comunicación KP-SIB

KpMqtt_connect(connectionConfig: mqtt_connection_config*): enum ConnectionStatus


o Descripcion: Abre una conexión física con el Gateway MQTT de la plataforma.

Se describe en el fichero de cabecera KpMQTT.h

o Retorna: Estado de la conexión. Los posibles valores son:

CONNECTED: La conexión se ha realizado satisfactoriamente.

FAILED_CallbacksNotRegistered: La conexión no se ha realizado ya

que ha sido imposible registrar el mecanismo de retorno desde la

plataforma.

FAILED_PhysicalConnection: La conexión no se ha realizdo ya que es

imposible conectar con el gateway indicado.

FAILED_SubscriptionToSIBTopic: La conexión no se ha realizado ya

que el el gateway MQTT rechaza que el KP se suscriba a los tópicos

necesarios.

o Parámetros:

connectionConfig: mqtt_connection_config*: Puntero a estructura de

tipo mqtt_connection_config que almacena los parámetros de conexión al

Gateway MQTT de la plataforma. Los parámetros de conexión son:

serverAddress:char*: Dirección IP o nombre del Gateway MQTT.

serverPort:char*: Puerto donde escucha el Gateway MQTT.

clientId:char*: Identificador que se da a este cliente MQTT.

KpMqtt_disconnect(timeout: int, clientId: char*): enum DisconnectionStatus

o Descripcion: Cierra la conexión fisica con el Gateway MQTT de la plataforma.

Se describe en el fichero de cabecera KpMQTT.h.

o Retorna: Estado de la desconexión. Los posibles valores son:

DISCONNECTED: La desconexión se ha realizado correctamente.

FAILED_ClosePhysicalConnection: Ha habido un error cerrando la

conexión.

o Parámetros:

timeout:int: Tiempo en milisegundos para cerrar la conexión.

clientId: Identificador del cliente MQTT con el que se abrió la conexión.


KpMqtt_send(request: ssap_message*, response: ssap_message*, timeout: int): enum

SendStatus

o Descripción: Envia un mensaje SSAP a la plataforma y recibe la respuesta. Se

describe en el fichero de cabecera KpMQTT.h.

o Retorna: Estado del envio. Los posibles valores son:

OK: El envio se ha realizado correctamente.

FAILED_SendMessage: Se ha producido un fallo enviando el

mensaje.No ha llegado a la plataforma.

FAILED_SIBReceptionConfirmation: No se ha recibido confirmación de

recepción del mensaje. Podría haber llegado a la plataforma.

FAILED_ReceivingSSAPResponse: No se ha recibido respuesta SSAP

para el mensaje.

o Parámetros:

request:ssap_message*: Puntero a estructura ssap_message con el

mensaje SSAP enviado a la plataforma.

response:ssap_message*: Puntero a estructura ssap_message con el

mensaje SSAP de respuesta desde la plataforma.

timeout:int: Tiempo en milisegundos para completar la operación.

KpMqtt_setIndicationListener(KPMQTT_IndicationReceived* il):void

o Descripción: Registra la función callback a través de la que el KP recibirá las

notificaciones de suscripciones SSAP. Será en esta función donde el

desarrollador del KP programe la lógica para el tratamiento de la

correspondiente notificación. Se describe en el fichero de cabecera KpMQTT.h

o Parámetros:

il:KPMQTT_IndicationReceived*: Puntero a la función callback definida

por el usuario que tratará la recepción del mensaje SSAP. Esta función

será invocada cuando el API reciba una notificación de suscripción desde

la plataforma.

La definición de la función es la siguiente:

KPMQTT_IndicationReceived(indicationMessage ssap_message*):int


Recibe por parámetros un puntero a estructura ssap_message con los

datos del mensaje SSAP de tipo INDICATION recibido.

mqtt_connection_configFree(config: mqtt_connection_config*):void

o Descripción: Libera la memoria asignada una estructura

mqtt_connection_config. Se describe en el fichero de cabecera KpMQTT.h

o Parámetros:

config:mqtt_connection_config*: Puntero a la estructura a liberar.

10.5.2 Funciones de manejo de mensajes SSAP

generateJoinMessage(token: char*, instance: char*,joinMessage: ssap_message*):void

o Descripción: Genera una estructura ssap_message con los datos asociados a

un mensaje SSAP JOIN. Se define en el fichero de cabecera

SSAPMessageGenerator.h.

o Parámetros:

token:char*: Token de autenticación a incluir en el mensaje JOIN.

Instance:char*: Identicador de Instancia de KP a incluir en el mensaje

JOIN.

joinMessage:ssap_message*: Puntero a estructura ssap_message en

el que se devuelve el mensaje SSAP generado.

generateJoinRenovateMessage(char* token, char* instance, char* sessionKey,

ssap_message* joinMessage)void


un mensaje SSAP JOIN para renovar una sessionkey existente. Se define en el

fichero de cabecera SSAPMessageGenerator.h.

o Parámetros:

token:char*: Token de autenticación a incluir en el mensaje JOIN.

Instance:char*: Identicador de Instancia de KP a incluir en el mensaje

JOIN.

joinMessage:ssap_message*: Puntero a estructura ssap_message en

el que se devuelve el mensaje SSAP generado

sessionKey:char*: SessionKey a renovar


generateLeaveMessage(sessionKey: char*, leaveMessage: ssap_message*):void


un mensaje SSAP LEAVE. Se define en el fichero de cabecera


o Parámetros:

sessionKey:char*: SessionKey a incluir en el mensaje LEAVE.

leaveMessage:ssap_message*: Puntero a estructura ssap_message en


generateInsertMessage(sessionKey: char*, ontology: char*, data: char*,

insertMessage:ssap_message*):void


un mensaje SSAP INSERT. Se define en el fichero de cabecera


o Parámetros:

sessionKey:char*: SessionKey a incluir en el mensaje INSERT.

ontology:char*: Ontologia sobre la que se realiza el INSERT.

data: Datos de la instancia de ontología a insertar en formato nativo de

MongoDB

insertMessage:ssap_message*: Puntero a estructura ssap_message en


generateInsertMessageWithQueryType(sessionKey: char*, ontology: char*, data:

char*, queryType: enum SSAPQueryType, insertMessage ssap_message*):void


un mensaje SSAP INSERT, especificando el tipo de lenguaje utilizado. Se define

en el fichero de cabecera SSAPMessageGenerator.h.

o Parámetros:

sessionKey:char*: SessionKey a incluir en el mensaje INSERT.

ontology:char*: Ontologia sobre la que se realiza el INSERT.

data: sentencia INSERT en el lenguaje especificado

queryType: Tipo de lenguaje utilizado en la sentencia. Los posibles

valores son:


NATIVE: Se trata de una sentencia en lenguaje Nativo de

MongoDB

SQLLIKE: Se trata de una sentencia en lenguaje SQL.

insertMessage:ssap_message*: Puntero a estructura ssap_message en


generateUpdateMessage(sessionKey: char *, ontology: char*, data: char*, query: char*,

updateMessage: ssap_message*): void


un mensaje SSAP UPDATE. Se define en el fichero de cabecera


o Parámetros:

sessionKey:char*: SessionKey a incluir en el mensaje UPDATE.

ontology:char*: Ontologia sobre la que se realiza el UPDATE.

data: Datos se la actualización sobre las instancias de ontología en

formato nativo de MongoDB.

query: Criterios de selección de las instancias de ontología a actualizar

en formato nativo de MongoDB

updateMessage:ssap_message*: Puntero a estructura ssap_message

en el que se devuelve el mensaje SSAP generado.

generateUpdateMessageWithQueryType(sessionKey: char *,ontology: char*, data:

char*, query:char*, queryType: enum SSAPQueryType, updateMessage:

ssap_message*):void


un mensaje SSAP UPDATE, especificando el tipo de lenguaje utilizado. Se

define en el fichero de cabecera SSAPMessageGenerator.h.

o Parámetros:

sessionKey:char*: SessionKey a incluir en el mensaje UPDATE.

ontology:char*: Ontologia sobre la que se realiza el UPDATE.

data: Datos se la actualización sobre las instancias de ontología, en caso

de que se utilice formato nativo de MongoDB. En caso de utilizar

SQLLIKE, este parámetro será NULL.

query: sentencia UPDATE en el lenguaje utilizado.



valores son:


MongoDB


updateMessage:ssap_message*: Puntero a estructura ssap_message


generateRemoveMessage(sessionKey: char *, ontology: char *, query: char*,

removeMessage: ssap_message*):void


un mensaje SSAP DELETE. Se define en el fichero de cabecera


o Parámetros:

sessionKey:char*: SessionKey a incluir en el mensaje DELETE.

ontology:char*: Ontologia sobre la que se realiza el DELETE.

query: Criterios de selección de las instancias de ontología a borrar en

formato nativo de MongoDB

o removeMessage:ssap_message*: Puntero a estructura ssap_message en el

que se devuelve el mensaje SSAP generado.

generateRemoveMessageWithQueryType(sessionKey: char *, ontology: char *,query:

char*, queryType: enum SSAPQueryType, removeMessage: ssap_message*):void


un mensaje SSAP DELETE, especificando el tipo de lenguaje utilizado. Se


o Parámetros:

sessionKey:char*: SessionKey a incluir en el mensaje DELETE.

ontology:char*: Ontologia sobre la que se realiza el DELETE.

query: sentencia DELETE en el lenguaje especificado.


valores son:



MongoDB


deleteMessage:ssap_message*: Puntero a estructura ssap_message


generateQueryMessage(sessionKey: char *,ontology: char *, query: char*,

queryMessage: ssap_message*):void


un mensaje SSAP QUERY. Se define en el fichero de cabecera


o Parámetros:

sessionKey:char*: SessionKey a incluir en el mensaje QUERY.

ontology:char*: Ontologia sobre la que se realiza el QUERY.

query: Criterios de selección de las instancias de ontología a seleccionar

en formato nativo de MongoDB.

queryMessage:ssap_message*: Puntero a estructura ssap_message en


generateQueryMessageWithQueryType(sessionKey: char *,ontology: char *, query:

char*, queryType: enum SSAPQueryType, queryMessage: ssap_message*):void


un mensaje SSAP QUERY, especificando el tipo de lenguaje utilizado. Se define

en el fichero de cabecera SSAPMessageGenerator.h.

o Parámetros:

sessionKey:char*: SessionKey a incluir en el mensaje QUERY.

ontology:char*: Ontologia sobre la que se realiza el QUERY.

query: sentencia QUERY en el lenguaje especificado, o identificador de

la query en caso de tratarse de una query SIB_DEFINED


valores son:


MongoDB



SIB_DEFINED: Se trata de una query almacenada en el SIB. En

este caso, en el parámetro query, se especifica su identificador.

BDH: Se trata una query sobre la Base de datos Histórica.

o queryMessage:ssap_message*: Puntero a estructura ssap_message en el que

se devuelve el mensaje SSAP generado.

generateSIBDefinedQueryMessageWithParam(sessionKey: char *,query: char*,

params[]:queryParam, numOfParams: int, queryMessage: ssap_message*):void


un mensaje SSAP QUERY sobre una query almacenada en el SIB a la que se le

pasan parámetros para su ejecución. Se define en el fichero de cabecera


o Parámetros:

sessionKey:char*: SessionKey a incluir en el mensaje QUERY..

query: Idetificador de la.query almacenada en el SIB

params[]:queryParam: Array con los parámetros que se pasan a la

query. Los parámetros se encapsulan en una estructura del tipo

queryParam, que consite en un par clave-valor:

key: Nombre del parámetro en la query predefinida

value: Valor pasado desde el programa para tal parámetro

numOfParams: Numero de parámetros pasados en el array Params.

queryMessage:ssap_message*: Puntero a estructura ssap_message en


generateSubscribeMessage(sessionKey: char *, ontology: char *, msRefresh:int,

query: char*, subscribeMessage: ssap_message*):void


un mensaje SSAP SUBSCRIBE. Se define en el fichero de cabecera


o Parámetros:

sessionKey:char*: SessionKey a incluir en el mensaje SUBSCRIBE.

ontology:char*: Ontologia sobre la que se realiza el SUBSCRIBE.


msRefresh: Intervalo de notificación desde el SIB entre dos

notificaciones distintas en caso de existir datos.

query: Criterios de selección de las instancias de ontología a notificar en

formato nativo de MongoDB.

subscribeMessage:ssap_message*: Puntero a estructura

ssap_message en el que se devuelve el mensaje SSAP generado.

generateSubscribeMessageWithQueryType(sessionKey: char *, ontology: char *,

msRefresh: int, query: char*, queryType: enum SSAPQueryType, subscribeMessage:

ssap_message*):void


un mensaje SSAP SUBSCRIBE, especificando el tipo de lenguaje utilizado. Se


o Parámetros:

sessionKey:char*: SessionKey a incluir en el mensaje SUBSCRIBE.

ontology:char*: Ontologia sobre la que se realiza el SUBSCRIBE.

msRefresh: Intervalo de notificación desde el SIB entre dos

notificaciones distintas en caso de existir datos.

query: sentencia QUERY en el lenguaje especificado, o identificador de

la query en caso de tratarse de una query SIB_DEFINED


valores son:


MongoDB


SIB_DEFINED: Se trata de una query almacenada en el SIB. En

este caso, en el parámetro query, se especifica su identificador.

subscribeMessage:ssap_message*: Puntero a estructura

ssap_message en el que se devuelve el mensaje SSAP generado.

generateUnsubscribeMessage(sessionKey: char *, ontology: char *, suscriptionId: char

*, unsubscribeMessage: ssap_message*):void



un mensaje SSAP UNSUBSCRIBE. Se define en el fichero de cabecera


o Parámetros:

sessionKey:char*: SessionKey a incluir en el mensaje UNSUBSCRIBE.

ontology:char*: Ontologia sobre la que se realiza el UNSUBSCRIBE.

subscriptionId: Identificador de la suscripción de la que se desuscribe el

KP.

o unsubscribeMessage:ssap_message*: Puntero a estructura ssap_message en


ssap_messageFree(ssap_message* message):void

o Descripción: Libera la memoria asignada a una estructura con el contenido de

un mensaje SSAP. Se define en el fichero de cabecera


o Parámetros:

message:ssap_message*: Puntero a la estructura ssap_message cuya

memoria se debe liberar.

ssap_messageToJson(ssap_message* message): char*

o Descripción: Genera la cadena JSON con el mensaje SSAP a partir de los

datos almacenados en una estructura ssap_message. Se define en el fichero de

cabecera SSAPMessageGenerator.h.

o Parámetros:

message:ssap_message*: Puntero a la estructura ssap_message a

convertir en JSON

o Retorno: Cadena con el JSON del mensaje SSAP.

ssapMessageFromJson(char* source, ssap_message* message):void

o Descripción: Parsea una cadena JSON con un mensaje SSAP a la estructura

ssap_message equivalente. Se define en el fichero de cabecera


o Parámetros:

source:char*: JSON del mensaje SSAP.


message:ssap_message*: Puntero a la estructura ssap_message

obtenida a partir del JSON.

void query_paramFree(queryParam* param)

o Descripción: Libera la memoria de las propiedades de una estructura

queryParam. Se define en el fichero de cabecera SSAPMessageGenerator.h.

o Parámetros:

param: queryParam* Puntero a la estructura a liberar.

10.5.3 Estructuras utilizadas en el API

ssap_message:

o Descripción: Encapsula todas las propiedades de un mensaje SSAP. Se utiliza

a modo de DTO para enviarlos y recibirlos a través de las funciones de

comunicación el SIB. Asimismo puede ser parseado a JSON y generado desde

un JSON. Se define en el fichero de cabecera SSAPMessageGenerator.h

o Atributos: Son las propiedades de la especificación SSAP

messageId:char*

sessionKey:char*

ontology:char*

direction:enum SSAPMessageDirection Puede tomar uno de los

siguientes valores en función de si el mensaje viaja desde el KP al SIB o

viceversa:

REQUEST

RESPONSE

ERROR

messageType:enum SSAPMessageTypes. Puede tomar uno de los

siguientes valores en función del tipo de mensaje de que se trate:

JOIN

LEAVE

INSERT

UPDATE

DELETE


QUERY

SUBSCRIBE

INDICATION

UNSUBSCRIBE

persistenceType:enum SSAPPersistenceType. Actualmente no se

utiliza, pero se incluye por compatibilidad futura

body:char*

queryParam:

o Descripción: Encapsula un parámetro de una consulta predefinida. Se utiliza

para notificar a la función generateSIBDefinedQueryMessageWithParam la

lista de parámetros que se envían a una consulta predefinida. Se trata un par

clave-valor, para sustituir en la consulta el elemento clave por el correspondiente

valor. Se define en el fichero de cabecera SSAPMessageGenerator.h

o Atributos: Son las propiedades de la especificación SSAP

key: Clave del parámetro a sustituir en la consulta predefinida

value: Valor a asignar a al parámetro.

mqtt_connection_config:

o Descripción: Encapsula los parámetros de conexión enviados a la función

KpMqtt_connect informando los datos del Gateway MQTT al que conectar. Se

define en el fichero de cabecera KpMQTT.h.

o Atributos:

serverAddress:char*: Dirección IP o nombre del Gateway MQTT.

serverPort:char*: Puerto donde escucha el Gateway MQTT.

clientId:char*: Identificador que se da a este cliente MQTT.

10.6 Utilidades Adicionales

10.6.1 cJSON

Librería de utilidad para trabajar con JSON. Permite tanto construir un árbol JSON y parsearlo a

su cadena equivalente, como parsear una cadena JSON para obtener su equivalente árbol

JSON.

Se define en el fichero de cabecera cJSON.h


Toda la información relativa a la librería puede consultarse en la dirección

http://cjson.sourceforge.net/

Permitirá parsear el atributo body recibido en las estructuras ssap_message, asi como

cualquier otra funcionalidad que exija la construcción o parseo de un JSON.

10.7 Utilización del API

10.7.1 Conectar con la plataforma

Para utilizar las funciones que permiten conectar con la plataforma es necesario incluir en el

programa la cabecera KpMQTT.h

Una vez incluido hay que construir la estructura con los datos para conectar con la plataforma a

través de Gateway MQTT y pasarla a la función KpMqtt_connect. Esta función establecerá la

conexión física con el Gateway MQTT de la plataforma, posibilitando el envío/recepción de

mensajes SSAP en el resto del programa:



La función KpMqtt_connect devolverá un valor enumerado indicando como ha finalizado la

operación. Los posibles valores han sido especificados anteriormente en la descripción de la

función.

10.7.2 Desconectar de la plataforma

Una vez finalizado el programa, hay que desconectarse de la plataforma. Para ello se utiliza la

función KpMqtt_disconnect:

La función KpMqtt_disconnect devolverá un valor enumerado indicando como ha finalizado la

operación. Los posibles valores han sido especificados anteriormente en la descripción de la

función.


10.7.3 Enviar mensaje SSAP

Una vez conectados a la plataforma, el siguiente paso es generar y enviar mensajes SSAP a

través de una sesión SSAP. Para ello, hay que generar el correspondiente mensaje SSAP

utilizando el generador provisto en el API.

Incluimos el fichero de cabecera SSAPMessageGenerator.h a nuestro programa:

Y utilizamos la función correspondiente al mensaje a generar (Ver sección Funciones del API)

El mensaje SSAP queda encapsulado en una estructura, que hay que pasar a la función.

Una vez generado, se envía a la plataforma mediante la función KpMqtt_send, pasándole la

estructura del mensaje SSAP de respuesta para que la devuelva rellena:


10.7.4 Procesado de respuesta con cJSON

En caso de tener procesar el cuerpo de la respuesta de un mensaje SSAP, se provee la librería

cJSON (http://cjson.sourceforge.net/), que permite convertir el campo “body” de una estructura

de respuesta, en un objeto accesible por sus atributos JSON.



10.7.5 Liberar memoria de estructuras utilizadas

Tanto las estructuras de los mensajes SSAP como la de configuración del SIB deben ser

liberadas una vez han dejado de ser necesarias:

10.8 Parámetros del compilador para

incluir el API

Para incluir el API es necesario indicar al compilador el directorio donde se encuentran los

ficheros de cabecera del API mediante el parámetro -I:

gcc -c -g -I../includes

Tambien es necesario informar al liker la ubicaión de la Liberia .DLL o .so del API:

gcc -o dist/Debug/Cygwin_4.x-Windows/ejemploapi-c build/Debug/Cygwin_4.x-Windows/main.o

../ssap-core-api-c/dist/Release/Cygwin_4.x-Windows/libssap-core-api-c.dll


11 OTRAS APIs

En el roadmap de la Plataforma está implementar librerías al estilo API Java/Arduino para los

siguientes lenguajes:

Android

iOS

apis sofia2sofia2.com/docs/sofia2-apis sofia2.pdf · apis sofia2 página 8/111 3 protocolos de...

Documents