APIS y librerías Sofia2

Transcripción

APIS SOFIA2
Septiembre 2014
Versión 7
1 INDICE
1
INDICE ............................................................................................................................................ 2
2
INTRODUCCIÓN .............................................................................................................................. 7
3
2.1
REQUISITOS ........................................................................................................................ 7
2.2
OBJETIVOS Y ALCANCE DEL PRESENTE DOCUMENTO .................................................................... 7
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
3.3
AJAX PUSH (JAVASCRIPT) .................................................................................................... 20
3.3.1
3.4
4
Gateway Ajax Push ................................................................................................. 20
WEBSOCKET ...................................................................................................................... 21
3.4.1
3.5
Gateway RESTFul ...................................................................................................... 9
Gateway Websocket: ............................................................................................. 21
OTROS PROTOCOLOS .......................................................................................................... 22
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
APIs SOFIA2
Página 2/111
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
5
4.11.1
Request: ................................................................................................................. 53
4.11.2
Response: ............................................................................................................... 54
API JAVA ...................................................................................................................................... 55
5.1
INTRODUCCIÓN.................................................................................................................. 55
APIs SOFIA2
Página 3/111
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
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
6
7
UTILIDADES DEL API ........................................................................................................... 63
EJEMPLO DE USO................................................................................................................ 71
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
API ARDUINO ............................................................................................................................... 75
7.1
LIBRERÍA KPMQTT ............................................................................................................. 75
7.2
PROTOCOLOS SOPORTADOS ................................................................................................. 76
7.2.1
8
MQTT ...................................................................................................................... 76
API JAVASCRIPT ............................................................................................................................ 77
8.1
LIBRERÍA KP-CORE.JS (DEPRECADA) Y SOFIA2-API-JS_V2<MINOR-VERSION>.JS ............................. 77
8.2
8.2.1
Websocket.............................................................................................................. 82
APIs SOFIA2
Página 4/111
8.2.2
9
AJAX/AJAX Push...................................................................................................... 82
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
9.4.1
9.5
10
MQTT ...................................................................................................................... 89
EJEMPLO DE USO................................................................................................................ 89
API C............................................................................................................................................. 92
10.1 LIBRERÍA LIBSSAP-CORE-API-C .............................................................................................. 92
10.2 COMPILAR CON MAKE ........................................................................................................ 93
10.3 PROTOCOLOS SOPORTADOS ................................................................................................. 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
APIs SOFIA2
Página 5/111
APIs SOFIA2
Página 6/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.
APIs SOFIA2
Página 7/111
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.
APIs SOFIA2
Página 8/111
Este Gateway responde a mensajes MQTT que contengan como payload un mensaje SSAP
enviado remotamente.
3.2
3.2.1
RESTFul
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
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
<xs:element
</xs:sequence>
minOccurs="0" name="data" type="xs:string"/>
minOccurs="0" name="instanceKP" type="xs:string"/>
name="join" type="xs:boolean"/>
name="leave" type="xs:boolean"/>
minOccurs="0" name="ontology" type="xs:string"/>
minOccurs="0" name="sessionKey" type="xs:string"/>
minOccurs="0" name="token" type="xs:string"/>
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
APIs SOFIA2
Página 9/111
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:
{
APIs SOFIA2
Página 10/111
"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:
APIs SOFIA2

$sessionKey: sessionKey de la sesión SSAP.

$query: Sentencia Insert SQL.

$queryType: valor SQLLIKE
Página 11/111
Ejemplo:
/api_ssap/v01/SSAPResource?$sessionKey=b0e24264-6606-4682-b81649831ec1f5ae&$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:
/api_ssap/v01/SSAPResource?$sessionKey=b0e24264-6606-4682-b81649831ec1f5ae&$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",
APIs SOFIA2
Página 12/111
"data":"
{"_id":{"$oid": "527a6352c0af4380e54822e1"},
"SensorTemperatura":
{"coordenadaGps":{"altitud":10,
"latitud":40.508277,"longitud":-3.676827},
"identificador":"S_Temperatura_00001",
"medida": 30,
"timestamp":1383678276000,
"unidad": "C"}
}"
}
o SQL
LIKE:
Operación
con
método
HTTP
GET
sobre
params:


$query: Sentencia Select SQL.

Ejemplo:
/api_ssap/v01/SSAPResource?$sessionKey=b0e24264-6606-4682-b81649831ec1f5ae&$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.
o SQL
LIKE:
Operación
con
método
HTTP
GET
sobre
params:
APIs SOFIA2
Página 13/111


$query: Sentencia Delete SQL.

Ejemplo:
/api_ssap/v01/SSAPResource?$sessionKey=b0e24264-6606-4682-b81649831ec1f5ae&$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-8cfd737cdfe0277a&$ontology=SensorTemperatura&$query={"SensorTemperatura.m
edida":{$gt:30}}&$queryType=NATIVE
APIs SOFIA2
Página 14/111
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-8cfd737cdfe0277a&$query=db.SensorTemperatura.find({"SensorTemperatura.medid
a":{$gt:30}})&$queryType=NATIVE
o SQL
LIKE:
Operación
con
método
HTTP
GET
sobre
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
APIs SOFIA2
Página 15/111
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
asignada
Parámetros vacios
400 (BAD_REQUEST)
Instancia de KP no 401 (UNAUTHORIZED)
APIs SOFIA2
Mensaje descriptivo
Mensaje descriptivo
Página 16/111
la
sessionKey
Resultado
Codigo Respuesta
Cuerpo Respuesta
Token erróneo
401 (UNAUTHORIZED)
Mensaje descriptivo
Otro error
501
Información del error
existe
(INTERNAL_SERVER_
ERROR)

LEAVE
Resultado
Codigo Respuesta
Cuerpo Respuesta
Correcto
200 (OK)
vacio
Parámetros vacios
400 (BAD_REQUEST)
Mensaje descriptivo
sessionKey
400 (BAD_REQUEST)
Mensaje descriptivo
501
incorrecta
Otro error
(INTERNAL_SERVER_
ERROR)

INSERT
Resultado
Codigo Respuesta
Cuerpo Respuesta
Correcto
200 (OK)
SSAPResource con el objectId asignado
a la instancia de ontología en BDTR
Parámetros vacios
400 (BAD_REQUEST)
Mensaje descriptivo
sessionKey
400 (BAD_REQUEST)
Mensaje descriptivo
400 (BAD_REQUEST)
Mensaje descriptivo
incorrecta
Ontologia no existe
Operación
no 403 (FORBIDDEN)
Mensaje descriptivo
permitida sobre la
ontología
Instancia
de 400 (BAD_REQUEST)
Mensaje descriptivo
ontología a insertar
no
APIs SOFIA2
cumple
Página 17/111
Resultado
validación
Codigo Respuesta
Cuerpo Respuesta
501
del
esquema
Otro error
(INTERNAL_SERVER_
ERROR)

UPDATE
Resultado
Codigo Respuesta
Cuerpo Respuesta
Correcto
200 (OK)
vacio
Parámetros vacios
400 (BAD_REQUEST)
Mensaje descriptivo
sessionKey
400 (BAD_REQUEST)
Mensaje descriptivo
400 (BAD_REQUEST)
Mensaje descriptivo
incorrecta
Ontologia no existe
Operación
no 403 (FORBIDDEN)
Mensaje descriptivo
permitida sobre la
ontología
No existe instancia 400 (BAD_REQUEST)
Mensaje descriptivo
de la ontología a
actualizar
Otro error
501
(INTERNAL_SERVER_
ERROR)

DELETE
Resultado
Codigo Respuesta
Cuerpo Respuesta
Correcto
200 (OK)
vacio
Parámetros vacios
400 (BAD_REQUEST)
Mensaje descriptivo
sessionKey
400 (BAD_REQUEST)
Mensaje descriptivo
400 (BAD_REQUEST)
Mensaje descriptivo
incorrecta
Ontologia no existe
APIs SOFIA2
Página 18/111
Resultado
Operación
Codigo Respuesta
no 403 (FORBIDDEN)
Cuerpo Respuesta
Mensaje descriptivo
permitida sobre la
ontología
No existe instancia 400 (BAD_REQUEST)
Mensaje descriptivo
de la ontología a
borrar
Otro error
501
(INTERNAL_SERVER_
ERROR)

QUERY
Resultado
Codigo Respuesta
Cuerpo Respuesta
Correcto
200 (OK)
SSAPResource con el resultado de la
consulta
Parámetros vacios
400 (BAD_REQUEST)
Mensaje descriptivo
sessionKey
400 (BAD_REQUEST)
Mensaje descriptivo
400 (BAD_REQUEST)
Mensaje descriptivo
incorrecta
Ontologia no existe
Operación
no 403 (FORBIDDEN)
Mensaje descriptivo
permitida sobre la
ontología
queryType invalido
Identificador
400 (BAD_REQUEST)
Mensaje descriptivo
de 400 (BAD_REQUEST)
Mensaje descriptivo
query predefina no
existe en SIB
Falta
argumento 400 (BAD_REQUEST)
en
Mensaje descriptivo
query
predefinida
Otro error
501
(INTERNAL_SERVER_
ERROR)
APIs SOFIA2
Página 19/111

CONFIG
Resultado
Codigo Respuesta
Cuerpo Respuesta
Correcto
200 (OK)
SSAPResource con el resultado de la
consulta
Parámetros vacios
400 (BAD_REQUEST)
Mensaje descriptivo
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>
APIs SOFIA2
Página 20/111
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 fullduplex 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
APIs SOFIA2
Página 21/111
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.
APIs SOFIA2
Página 22/111
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
APIs SOFIA2
Página 23/111
4.1.1
4.1.1.1
Request:
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"
}
APIs SOFIA2
Página 24/111
4.1.2
Response:
{
"body": {
"data": "f260cfbd-e740-416b-81be-e6aaaa6e5a1b",
"error": null,
"errorCode": null,
"ok": true
},
"direction": "RESPONSE",
"messageId": null,
"ontology": null,
}
Response antes Request’s Incorrectos:
4.1.3
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
}
APIs SOFIA2
Página 25/111
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
}
APIs SOFIA2
Página 26/111
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
}
APIs SOFIA2
Página 27/111
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,
}
APIs SOFIA2
Página 28/111
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);
APIs SOFIA2
Página 29/111

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"
}
APIs SOFIA2
Página 30/111
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"
}
APIs SOFIA2
Página 31/111
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",
APIs SOFIA2
Página 32/111
"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,
APIs SOFIA2
Página 33/111
"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
APIs SOFIA2
Página 34/111

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
APIs SOFIA2
Página 35/111
SensorTemperatura.identificador,SensorT
emperatura.unidad
from
ra.identificador":1,"SensorTemperatura.unidad":1}
);
SensorTemperatura;
select * from SensorTemperatura where db.SensorTemperatura.find({"SensorTemperatura
= .identificador":"S_Temperatura_00001"});
"S_Temperatura_00001";
SensorTemperatura.medida =
20
and .medida":20, "SensorTemperatura.unidad":"C"})
SensorTemperatura.unidad = “C”;
.medida":20,
“SensorTemperatura.unidad” = “C” order
"SensorTemperatura.unidad":"C"}).sort({"SensorT
by
“SensorTemperatura.identificador” emperatura.identificador":1})
ASC;
select count(*) from SensorTemperatura;
db.SensorTemperatura.count();
select count(*) from SensorTemperatura db.SensorTemperatura.count({SensorTemperatur
a.medida:{$gt:20}})
where SensorTemperatura.medida >20
select from SensorTemperatura limit 1
db.SensorTemperatura.find().limit(1)
select
distinct db.SensorTemperatura.distinct('SensorTemperatu
ra.identificador')
(SensorTemperatura.identificador)
from
SensorTemperatura;
select * form SensorTemperatura limit 5 db.SensorTemperatura.find().limit(5).skip(10)
skip 10
select
SensorTemperatura.identificador, db.SensorTemperatura.aggregate([{$group:{_id:”
$SensorTemperatura.identificador”,
count(*) as total from SensorTemperatura
total:{$sum:1}}}])
select count(*) from SensorTemperatura db.SensorTemperatura.aggregate([{$group:{_id:”
$SensorTemperatura.identificador”,
group by SensorTemperatura.identificador
count:{$sum:1}}},{$match:{count:{$gt:1}}}])
having count(*) >1
select
SensorTemperatura.identificador, db.SensorTemperatura.aggregate([{$group:{_id:{"
SensorTemperatura":"$SensorTemperatura.identi
sum(SensorTemperatura.measure)
as
ficador"},"total":{$sum:"$SensorTemperatura.medi
total from SensorTemperatura group by da"}}})
APIs SOFIA2
Página 36/111
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 ",
APIs SOFIA2
Página 37/111
"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"
}
APIs SOFIA2
Página 38/111
}
],
"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 clavevalor (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.
APIs SOFIA2
Página 39/111
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,
}
APIs SOFIA2
Página 40/111
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,
APIs SOFIA2
Página 41/111
}
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).
APIs SOFIA2
Página 42/111
Documentación
completa
en
http://www.cloudera.com/content/cloudera-
content/cloudera-docs/Impala/latest/Installing-and-UsingImpala/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": [
APIs SOFIA2
Página 43/111
["ObjectID(52fa4787fee7acf12f75a893)",null,"","3.0","69.0","\"KPproductor
HT01\"","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-UsingImpala/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, ‘STTA23’, 23)",
"queryType":"BDH"
},
"messageId":null,
}
APIs SOFIA2
Página 44/111
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",
APIs SOFIA2
Página 45/111
"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",
APIs SOFIA2
Página 46/111
"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",
APIs SOFIA2
Página 47/111
"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
APIs SOFIA2
Página 48/111
 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",
}
APIs SOFIA2
Página 49/111
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"
}
APIs SOFIA2
Página 50/111
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
}
APIs SOFIA2
Página 51/111
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.org/draft-03/schema#\\\",
\\\"object\\\",
\\\"title\\\": \\\"Anuncios Schema\\\",
\\\"properties\\\": {
\\\"$ref\\\": \\\"#/titulo\\\"
},
\\\"$ref\\\": \\\"#/datos\\\"
}
\\\"$schema\\\": \\\"http://json-
\\\"_id\\\": {
\\\"type\\\": \\\"object\\\",
\\\"SensorAnuncio\\\": {
},
\\\"titulo\\\": {
\\\"required\\\": false
APIs SOFIA2
\\\"$oid\\\": {
}
}
},
\\\"type\\\": \\\"string\\\",
\\\"title\\\": \\\"id\\\",
\\\"description\\\": \\\"Titulo insertado del Anuncio\\\",
\\\"properties\\\": {
\\\"type\\\":
\\\"type\\\": \\\"object\\\",
\\\"type\\\": \\\"string\\\",
\\\"datos\\\": {
Página 52/111
\\\"title\\\": \\\"datos\\\",
\\\"description\\\": \\\"Info contenido\\\",
{
\\\"titulo\\\": {
},
\\\"timestamp\\\": {
0,
\\\"type\\\": \\\"string\\\",
\\\"required\\\": true
\\\"string\\\",
\\\"type\\\": \\\"object\\\",
\\\"type\\\": \\\"integer\\\",
},
\\\"minimum\\\":
\\\"contenido\\\": {
}
\\\"properties\\\":
}
},
\\\"type\\\":
\\\"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\"}
]",
APIs SOFIA2
Página 53/111
"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>"
}
APIs SOFIA2
Página 54/111
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);
}
APIs SOFIA2
Página 55/111
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
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);
APIs SOFIA2
Página 56/111
la
clase
//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:
APIs SOFIA2
Página 57/111
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 (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
ó
INSERT
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.
ó
query (GET) informando a traves de los queryParams de la URL:
APIs SOFIA2
Página 58/111




$ontology: Ontologia sobre la que se realiza la actualización.
$query: Sentencia SQLLIKE de tipo UPDATE.
$sessionKey: clave de sesión SSAP en la que pertenece el mensaje
$queryType: SQLLIKE
delete (DELETE) enviando un SSAPResource infomando:
 ontology: Ontologia sobre la que se realiza el borrado.
 data: Intancia de ontologia a borrar.
ó
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:
DELETE


$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
 $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
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.
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
GET_CONFIG
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
APIs SOFIA2
Página 59/111
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
WebSocketConnectionConfig, donde se informa:
APIs SOFIA2
Página 60/111
una
instancia
de
la
clase

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);
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:
APIs SOFIA2
Página 61/111
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á
APIs SOFIA2
Página 62/111
a su constructor una instancia de ConnectionConfig específica para el protocolo, que
recogerá lo parámetros de conexión:
5.5
5.5.1
Utilidades del API
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.
APIs SOFIA2
Página 63/111

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
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.
el
mensaje
SSAPMessageQUERY
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 mimetype (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.
APIs SOFIA2
Página 64/111
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.openxmlformatsofficedocument.spreadsheetml.sheet"),
APPLICATION_VND_MS_POWERPOINT ("application/vnd.ms-powerpoint"),
APPLICATION_VND_OPENXMLFORMART_PRESENTATION ("application/vnd.openxmlformatsofficedocument.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"),
APIs SOFIA2
Página 65/111
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"),
APIs SOFIA2
Página 66/111
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.
APIs SOFIA2
Página 67/111
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.
APIs SOFIA2
Página 68/111
 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
APIs SOFIA2
Página 69/111
 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:
APIs SOFIA2
Página 70/111

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 {
// 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
APIs SOFIA2
Página 71/111
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;
}
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.
APIs SOFIA2
Página 72/111







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.
APIs SOFIA2
Página 73/111
// Establecemos los parámetros de configuración para la conexión física con el SIB
Kp kp;
try {
// 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
APIs SOFIA2
Página 74/111
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.
*/
/**
* Método para liberar un escuchador de notificaciones de suscripción
APIs SOFIA2
Página 75/111
*/
/**
* 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
7.2.1
Protocolos soportados
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);
APIs SOFIA2
Página 76/111
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
function
function
function
function
function
function
function
function
function
function
function
function
function
function
function
function
function
function
function
function
function
function
function
function
function
setKpName(kpName);
join(user, pass, instance, joinResponse);
joinRenovateSessionKey (user, pass, instance, joinResponse);
joinCipher(user, pass, instance, joinResponse);
joinRenovateSessionKeyCipher(user, pass, instance, joinResponse);
joinToken(token, instance, joinResponse);
joinRenovateSessionKeyToken(token, instance, joinResponse);
joinTokenCipher(token, instance, joinResponse);
joinRenovateSessionKeyTokenCipher(token, instance, joinResponse);
leave(leaveResponse);
leaveCipher(leaveResponse);
insert(data, ontology, insertResponse);
insertCipher(data, ontology, insertResponse);
insertWithQueryType(data, ontology, queryType, insertResponse);
insertWithQueryTypeCipher(data, ontology, queryType, insertResponse);
update(data, query,ontology, updateResponse);
updateCipher(data, query,ontology, updateResponse);
updateWithQueryType(data, query, ontology, queryType, updateResponse);
updateWithQueryTypeCipher(data, query, ontology, queryType, updateResponse);
remove(query, ontology, removeResponse);
removeCipher(query, ontology, removeResponse);
removeWithQueryType(query, ontology, queryType, removeResponse);
removeWithQueryTypeCipher(query, ontology, queryType, removeResponse);
query(query, ontology, queryResponse);
queryCipher(query, ontology, queryResponse);
queryWithQueryType(query, ontology, queryType, queryParams, queryResponse);
APIs SOFIA2
Página 77/111
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.
APIs SOFIA2
Página 78/111

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
APIs SOFIA2
Página 79/111
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
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 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 = {};
APIs SOFIA2
Página 80/111
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.
APIs SOFIA2
Página 81/111
Y proporciona para función, su función homónima de cifrado xxxCipher(). (joinCipher(),
insertCipher()….).
8.2
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.
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){
}else{
}
});
}
8.2.2
AJAX/AJAX Push
Se soporta a través del Gateway DWR de Sofia2.
Este API necesita:

Importar las siguientes librerías:
APIs SOFIA2
Página 82/111
o
Librería
del
API
Javascript:
kp-core.js
(deprecada)
ó
sofia2-api-
js_v2<minor-version>.js
o
Librerias
DWR
del
Gateway
http://sofia2.com/sib/dwr/engine.js,
de
sofia2.com:
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.
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){
}else{
}
});
}
APIs SOFIA2
Página 83/111
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..
APIs SOFIA2
Página 84/111

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.
APIs SOFIA2
Página 85/111

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
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

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.
APIs SOFIA2
Página 86/111
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
APIs SOFIA2
Página 87/111
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.
APIs SOFIA2
Página 88/111
9.4
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)
APIs SOFIA2
Página 89/111
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.
APIs SOFIA2
Página 90/111
APIs SOFIA2
Página 91/111
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-coreapi-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/ Makefilevariables.mk
APIs SOFIA2
Página 92/111
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/Makefilevariables.mk.
10.3 Protocolos soportados
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
APIs SOFIA2
Página 93/111
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:
APIs SOFIA2

timeout:int: Tiempo en milisegundos para cerrar la conexión.

clientId: Identificador del cliente MQTT con el que se abrió la conexión.
Página 94/111

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
APIs SOFIA2
Página 95/111
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

APIs SOFIA2
sessionKey:char*: SessionKey a renovar
Página 96/111

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:
APIs SOFIA2
Página 97/111
 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.

APIs SOFIA2
query: sentencia UPDATE en el lenguaje utilizado.
Página 98/111

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:
APIs SOFIA2
Página 99/111
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
APIs SOFIA2
Página 100/111
 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:
APIs SOFIA2

sessionKey:char*: SessionKey a incluir en el mensaje SUBSCRIBE.

ontology:char*: Ontologia sobre la que se realiza el SUBSCRIBE.
Página 101/111

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
APIs SOFIA2
Página 102/111
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:

APIs SOFIA2
source:char*: JSON del mensaje SSAP.
Página 103/111

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
APIs SOFIA2
Página 104/111
 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
APIs SOFIA2
Página 105/111
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:
APIs SOFIA2
Página 106/111
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.
APIs SOFIA2
Página 107/111
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:
APIs SOFIA2
Página 108/111
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.
APIs SOFIA2
Página 109/111
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
APIs SOFIA2
Página 110/111
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 SOFIA2
Página 111/111

APIS y librerías Sofia2

Transcripción

Documentos relacionados

Cómo desarrollar en Sofia2

Estudio sobre las condiciones de vida de la población usuaria de