APIS y librerías Sofia2
Transcripción
APIS y librerías Sofia2
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 PROTOCOLOS SOPORTADOS ................................................................................................. 82 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 PROTOCOLOS SOPORTADOS ................................................................................................. 89 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: $sessionKey: sessionKey de la sesión SSAP. $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 /api_ssap/v01/SSAPResource/ enviando en el body de la petición un objeto SSAPResource con los atributos: 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", "ontology":"SensorTemperatura", 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 /api_ssap/v01/SSAPResource/ enviando la petición con los siguientes query params: $sessionKey: sessionKey de la sesión SSAP. $query: Sentencia Select SQL. $queryType: valor SQLLIKE 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 /api_ssap/v01/SSAPResource/ enviando en el body de la petición un objeto SSAPResource con los atributos: 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 /api_ssap/v01/SSAPResource/ enviando la petición con los siguientes query params: APIs SOFIA2 Página 13/111 $sessionKey: sessionKey de la sesión SSAP. $query: Sentencia Delete SQL. $queryType: valor SQLLIKE 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 /api_ssap/v01/SSAPResource/ enviando la petición con los siguientes query params: $sessionKey: sessionKey de la sesión SSAP. $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 /api_ssap/v01/SSAPResource/ enviando la petición con los siguientes query params: $sessionKey: sessionKey de la sesión SSAP. $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 /api_ssap/v01/SSAPResource/ enviando la petición con los siguientes query params: $sessionKey: sessionKey de la sesión SSAP. $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 /api_ssap/v01/SSAPResource/ enviando la petición con los siguientes query params: $sessionKey: sessionKey de la sesión SSAP. $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: $sessionKey: sessionKey de la sesión SSAP. $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 SSAPResource con los atributos: 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 Información del error 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 Información del error 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 Información del error (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 Información del error (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 Información del error (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 Información del error (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" }, "direction": "REQUEST", "messageId": null, "messageType": "JOIN", "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, "messageType": "JOIN", "ontology": null, "sessionKey": "f260cfbd-e740-416b-81be-e6aaaa6e5a1b" } 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, "messageType": "JOIN", "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", "errorCode": "AUTENTICATION", "ok": false }, "direction": "ERROR", "messageId": null, "messageType": "JOIN", "ontology": null, "sessionKey": null } 4.1.3.3 Ejemplo con Token no perteneciente al KP { "body": { "data": null, "error": "Token not valid the kp", "errorCode": "AUTENTICATION", "ok": false }, "direction": "ERROR", "messageId": null, "messageType": "JOIN", "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", "errorCode": "AUTENTICATION", "ok": false }, "direction": "ERROR", "messageId": null, "messageType": "JOIN", "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 }, "direction": "ERROR", "messageId": null, "messageType": "JOIN", "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, "direction": "REQUEST", "messageId": null, "messageType": "LEAVE", "ontology": null, "sessionKey": "f260cfbd-e740-416b-81be-e6aaaa6e5a1b" } 4.2.2 Response: { "body": { "data": "f260cfbd-e740-416b-81be-e6aaaa6e5a1b", "error": null, "errorCode": null, "ok": true }, "direction": "RESPONSE", "messageId": null, "messageType": "LEAVE", "ontology": null, "sessionKey": "f260cfbd-e740-416b-81be-e6aaaa6e5a1b" } 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" }, "direction": "REQUEST", "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 }, "direction": "RESPONSE", "messageId": null, "messageType": "QUERY", "ontology": "Jardin", "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" }, "direction": "REQUEST", "ontology": "feedAutobus", "messageType": "QUERY", "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 }, "direction": "RESPONSE", "messageId": null, "messageType": "QUERY", "ontology": "feedAutobus", "sessionKey": "4e21da4d-5009-4463-b771-29a437dfa86e" } 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 SensorTemperatura.identificador = .identificador":"S_Temperatura_00001"}); "S_Temperatura_00001"; select * from SensorTemperatura where db.SensorTemperatura.find({"SensorTemperatura SensorTemperatura.medida = 20 and .medida":20, "SensorTemperatura.unidad":"C"}) SensorTemperatura.unidad = “C”; select * from SensorTemperatura where db.SensorTemperatura.find({"SensorTemperatura .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"}}}) SensorTemperatura.identificador 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, "sessionKey": "4e21da4d-5009-4463-b771-29a437dfa86e" } 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 }, "direction": "RESPONSE", "messageId": null, "messageType": "QUERY", "ontology": "feedAutobus", "sessionKey": "4e21da4d-5009-4463-b771-29a437dfa86e" } 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"}, "direction":"REQUEST", "ontology":"SensorTemperatura", "messageType":"QUERY", "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, "messageType":"QUERY", "ontology":"SensorTemperatura", "sessionKey":"5b9349ab-d9a8-4fd0-b155-a11c5d8df6fa" } APIs SOFIA2 Página 40/111 4.3.3.3 Request con parámetros: { "body":{ "query":"{selectAll }", "queryParams":"{'PARAM1':'ST-TA3231-1'}" }, "direction":"REQUEST", "ontology": null, "messageType":"QUERY", "messageId":null, "sessionKey":"5b9349ab-d9a8-4fd0-b155-a11c5d8df6fa" } 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 }, "direction":"RESPONSE", "messageId":null, "messageType":"QUERY", "ontology":"SensorTemperatura", "sessionKey":"5b9349ab-d9a8-4fd0-b155-a11c5d8df6fa" 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"}, "direction":"REQUEST", "ontology":"SensorTemperatura", "messageType":"QUERY", "messageId":null, "sessionKey":"5b9349ab-d9a8-4fd0-b155-a11c5d8df6fa" } 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" }, "direction":"REQUEST", "ontology":"SensorTemperatura", "messageType":"QUERY", "messageId":null, "sessionKey":"5b9349ab-d9a8-4fd0-b155-a11c5d8df6fa" } 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 }, "direction": "REQUEST", "ontology": "Jardin", "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 }, "direction":"RESPONSE", "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}", "queryType": "SQLLIKE", "queryParams": null }, "direction": "REQUEST", "ontology": "Jardin", "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 }, "direction":"RESPONSE", "messageId":null, "messageType":"UPDATE", APIs SOFIA2 Página 46/111 "ontology":"Jardin", "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}", "queryType": "SQLLIKE", "queryParams": null }, "direction": "REQUEST", "ontology": "Jardin", "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 }, "direction":"RESPONSE", "messageId":null, "messageType":"DELETE", "ontology":"Jardin", 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" }, "direction":"REQUEST", "messageId":"c260fbd6-ce7e-4f1d-983d-0152b419223c", "messageType":"SUBSCRIBE", "ontology":"SensorTemperatura", "sessionKey":"5b9349ab-d9a8-4fd0-b155-a11c5d8df6fa" } 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 }", "direction":"RESPONSE", "messageId":"c260fbd6-ce7e-4f1d-983d-0152b419223c", "messageType":"SUBSCRIBE", "ontology":"SensorTemperatura", "sessionKey":"5b9349ab-d9a8-4fd0-b155-a11c5d8df6fa" } APIs SOFIA2 Página 49/111 4.8 UNSUBSCRIBE Mensaje enviado por un KP al SIB para cancelar una suscripción previa. Es un mensaje síncrono. 4.8.1 Request: { "body":{ "idSuscripcion":"cef33c81-970f-4e9c-9203-6c87e25ca37c" }, "direction":"REQUEST", "messageId":null, "messageType":"UNSUBSCRIBE", "ontology":"Watorimetro", "sessionKey":"5230064e-f4f7-41ab-b6de-7ef7ad11668f" } 4.8.2 Response: { "body": { "data": "", "error": null, "ok": true }, "direction": "RESPONSE", "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 }, "direction": "RESPONSE", "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. Es un mensaje síncrono. Operación sólo disponible para KPs JAVA 4.10.1 Request: { "body":"{ "instanciaKp":"KPvisualizacionHT01", "kp":"KPvisualizacionHT", "token":"cbb9364c434543a18dc6efa30dc780eb" }", "direction":"REQUEST", "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\\\", \\\"required\\\": true \\\"type\\\": \\\"integer\\\", }, \\\"required\\\": true \\\"minimum\\\": \\\"contenido\\\": { } \\\"properties\\\": } }, \\\"type\\\": \\\"additionalItems\\\": false}\",\"identificacion\":\"Anuncios\",\"tipopermiso\":\"QUERY\"}], \"token\":\"d9e77d01d3c84f96994bfdcd428faa97\" }", "direction":"RESPONSE", "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 "direction":"REQUEST", "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 }", "direction":"RESPONSE", "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. sessionkey: clave de sesión SSAP en la que pertenece el mensaje ó 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. sessionkey: clave de sesión SSAP en la que pertenece el mensaje ó delete (DELETE) informando a traves de pathParam: el objectId en BDTR de la instancia de ontologia a borrar. Y a traves de queryParams de la URL: DELETE $ontology: Ontologia sobre la que se realiza el borrado. $sessionKey: clave de sesión SSAP en la que pertenece el mensaje ó query (GET) informando a traves de los queryParams de la URL: $ontology: Ontologia sobre la que se realiza el borrado. $query: Sentencia SQLLIKE de tipo DELETE. $sessionKey: clave de sesión SSAP en la que pertenece el mensaje $queryType: SQLLIKE query (GET) informando a traves de los queryParams de la URL: $ontology: Ontologia sobre la que se realiza la consulta. $query: Sentencia de consulta $sessionKey: clave de sesión SSAP en la que pertenece el mensaje $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. $sessionKey: clave de sesión SSAP en la que pertenece el mensaje 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); config.setTimeOutConnectionSIB(5000); KpWebSocketClient kp=new KpWebSocketClient(config); Una vez instanciada el funcionamiento es el descrito en la interfaz. 5.4.4 Extensión con nuevos protocolos Tal como se indica en la guía SOFIA-Guía Configuración Extensión y Personalización SIB.doc, es posible extender el SIB a un nuevo protocolo de comunicación (Gateway). Una vez extendido el SIB con el nuevo protocolo, para facilitar la utilización del nuevo protocolo en el API Java, es recomendable extender este API para soportar tal protocolo siguiendo la filosofía aplicada en los protocolos actuales. Para ello, los pasos para extender el API a un nuevo protocolo son: Crear la clase que represente la implementación del conector del nuevo protocolo (Aquella con la que instanciaremos la interfaz Kp, para enviar mensajes SSAP al SIB). El código fuente de los protocolos actuales puede encontrarse en el paquete com.indra.sofia2.ssap.kp.implementations. Esta clase deberá implementar la clase abstracta KpToExtend, que a su vez implementa la interfaz Kp: 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 { MQTTConnectionConfig config = new MQTTConnectionConfig(); config.setHostSIB(host); config.setPortSIB(port); config.setQualityOfService(QoS.AT_LEAST_ONCE); config.setTimeOutConnectionSIB(5000); // Creamos la instancia del KP con la configuración MQTT kp=new KpMQTTClient(config); } catch (Exception e) { log.error("Imposible conectar al SIB por TCP: "+e.getMessage()); throw new ExcepcionGateway("Imposible conectar al SIB por TCP: "+e.getMessage()); } //A partir de aquí a través de la clase de utilidad de SSAPMessageGenerator iríamos invocando a las diferentes operaciones para interoperar con el SIB 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; void addListener4SIBNotifications(Listener4SIBIndicationNotifications listener); void removeListener4SIBNotifications(Listener4SIBIndicationNotifications listener); } Estas operaciones en las distintas implementaciones permiten a las aplicaciones Java: boolean isConnected():Conocer si el KP está conectado a un SIB String getSessionKey(): Una vez conectado al SIB, recuperar la sessionKey asignada para la conexión void connect(): Establecer una conexión física con el SIB a través del Gateway del protocolo implementado por la clase. 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 { MQTTConnectionConfig config = new MQTTConnectionConfig(); config.setHostSIB(host); config.setPortSIB(port); config.setQualityOfService(QoS.AT_LEAST_ONCE); config.setTimeOutConnectionSIB(5000); // Creamos la instancia del KP con la configuración MQTT kp=new KpMQTTClient(config); } catch (Exception e) { log.error("Imposible conectar al SIB por TCP: "+e.getMessage()); throw new ExcepcionGateway("Imposible conectar al SIB por TCP: "+e.getMessage()); } //A partir de aquí a través de la clase de utilidad de SSAPMessageGenerator iríamos invocando a las diferentes operaciones para interoperar con el SIB 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. */ void addListener4SIBNotifications(Listener4SIBIndicationNotifications listener); /** * Método para liberar un escuchador de notificaciones de suscripción APIs SOFIA2 Página 75/111 */ void removeListener4SIBNotifications(Listener4SIBIndicationNotifications listener); /** * Método para registrar un escuchador para recibir mensajes desde el SIB */ void addListener4SIBCommandMessageNotifications(Listener4SIBCommandMessageNotifications listener); /** * Método para liberar un escuchador para dejar de recibir mensajes desde el SIB */ void removeListener4SIBCommandMessageNotifications(Listener4SIBCommandMessageNotifications listener); /** * Método para lanzar el bucle para recibir notificaciones del SIB*/ void loopMqtt(); /** * Callback para recibir notificaciones del SIB */ void callback( char* topic, byte* payload, unsigned int length ); 7.2 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 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 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 RESPONSE indicando si la operación se ha realizado satisfactoriamente. 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 ha realizado satisfactoriamente. 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 RESPONSE indicando si la operación se ha realizado satisfactoriamente. removeWithQueryType: Envía un mensaje SSAP DELETE para borrar datos existentes sobre la ontología indicada. Recibe la respuesta a través de la función APIs SOFIA2 Página 79/111 callback removeResponse, que tiene como argumento el mensaje SSAP DELETE de tipo RESPONSE indicando si la operación se ha realizado satisfactoriamente. 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 “SQLLIKE” sirve para indicar una circunstancia u otra. 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. 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 suscripción en formato MongoDB En caso de utilizarse el formato SQLLIKE, el argumento query será la sentencia Select 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 Protocolos soportados Websocket Se soporta a través del Gateway Websocket de Sofia2. Este API necesita: Importar las siguientes librerías: o Librería del API Javascript: sofia2-api-js_v2<minor-version>.js (soportado a partir de la versión sofia2-api-js_v2.8.0.js. Inicializar la variable pathToWebsocketServer que indica al API el endpoint del Gateway del SIB. Ejemplo de utilización //Cargamos la librería del api <script type='text/javascript' src="sofia2-api-js_v2<minor-version>.js">;</script> <script type="text/javascript"> var pathToWebsocketServer = "ws://sofia2.com/sib/api_websocket";</script> //Para conectar con el SIB, nos creamos una función que será la que invoque a la operación de //conectar disponibilizada en la librería. function conectarSIB(user, pass, inst) { sofia2.join(user, pass, inst,function(mensajeSSAP){ //Comprobamos si se ha establecido la conexión o no if(mensajeSSAP != null && mensajeSSAP.body.data != null && mensajeSSAP.body.ok == true){ $("#infoConexion").text("Conectado al sib con sessionkey: "+mensajeSSAP.sessionKey).show(); }else{ $("#infoConexion").text("Error conectando del sib").show(); } }); } 8.2.2 AJAX/AJAX Push Se soporta a través del Gateway DWR de Sofia2. Este API necesita: Importar las siguientes librerías: 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. function conectarSIB(user, pass, inst) { sofia2.join(user, pass, inst,function(mensajeSSAP){ //Comprobamos si se ha establecido la conexión o no if(mensajeSSAP != null && mensajeSSAP.body.data != null && mensajeSSAP.body.ok == true){ $("#infoConexion").text("Conectado al sib con sessionkey: "+mensajeSSAP.sessionKey).show(); }else{ $("#infoConexion").text("Error conectando del sib").show(); } }); } 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 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. joinToken: Envía un mensaje SSAP JOIN de autenticación 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 asignada por el SIB una 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 RESPONSE indicando si la operación se ha realizado satisfactoriamente. insert: Envía un mensaje SSAP INSERT con los datos y sobre la ontología indicados. Recibe la respuesta a través de la función callback insertResponse, que tiene como argumento el mensaje SSAP INSERT de tipo RESPONSE indicando si la operación se ha realizado satisfactoriamente. Los datos enviados deben estar en formato Nativo de MongoDB para ser insertados. InsertWithQueryType: Envía un mensaje SSAP INSERT con los datos y sobre la ontología indicados. Recibe la respuesta a través de la función callback insertResponse, que tiene como argumento el mensaje SSAP INSERT de tipo RESPONSE indicando si la operación se ha realizado satisfactoriamente. 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 ha realizado satisfactoriamente. 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. 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 RESPONSE indicando si la operación se ha realizado satisfactoriamente. removeWithQueryType: Envía un mensaje SSAP DELETE para borrar datos existentes sobre la ontología indicada. Recibe la respuesta a través de la función callback removeResponse, que tiene como argumento el mensaje SSAP DELETE de tipo RESPONSE indicando si la operación se ha realizado satisfactoriamente. 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 “SQLLIKE” sirve para indicar una circunstancia u otra. 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. 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 APIs SOFIA2 Página 87/111 En caso de utilizarse el formato SQLLIKE, el argumento query será la sentencia Select en formato SQL Like. Asimismo, se pueden ejecutar consultas predefinidas en el SIB, en este caso hay que indicar en el argumento query el identificador de la consulta predefinida y en el argumento queryType el valor “SIB_DEFINED”. Adicionalmente, en caso de tratarse de una consulta predefinida SIB_DEFINED que admita parámetros de entrada, estos pueden enviarse a través del argumento queryParams, pasando un Map javascript: var params = {}; params["PARAM1"] = '\"S_Temperatura_00001\"'; params["PARAM2"] = '20'; En el resto de casos (NATIVE, SQLLIKE o SIB_DEFINED sin parámetros), el argumento queryParams será null. subscribe: Envía un mensaje SSAP SUBSCRIBE con la consulta de suscripción, refresco y sobre la ontologia indicados. Los datos de la consulta de suscripción deben estar en formato Nativo de MongoDB. subscribeWithQueryType: Envía un mensaje SSAP SUBSCRIBE con la consulta de suscripción, refresco y sobre la ontología indicados. 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 suscripción en formato MongoDB En caso de utilizarse el formato SQLLIKE, el argumento query será la sentencia Select 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 Protocolos soportados 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 o Descripción: Genera una estructura ssap_message con los datos asociados a 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 o Descripción: Genera una estructura ssap_message con los datos asociados a un mensaje SSAP LEAVE. Se define en el fichero de cabecera SSAPMessageGenerator.h. o Parámetros: sessionKey:char*: SessionKey a incluir en el mensaje LEAVE. leaveMessage:ssap_message*: Puntero a estructura ssap_message en el que se devuelve el mensaje SSAP generado. generateInsertMessage(sessionKey: char*, ontology: char*, data: char*, insertMessage:ssap_message*):void o Descripción: Genera una estructura ssap_message con los datos asociados a un mensaje SSAP INSERT. 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: Datos de la instancia de ontología a insertar en formato nativo de MongoDB insertMessage:ssap_message*: Puntero a estructura ssap_message en el que se devuelve el mensaje SSAP generado. generateInsertMessageWithQueryType(sessionKey: char*, ontology: char*, data: char*, queryType: enum SSAPQueryType, insertMessage ssap_message*):void o Descripción: Genera una estructura ssap_message con los datos asociados a 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 el que se devuelve el mensaje SSAP generado. generateUpdateMessage(sessionKey: char *, ontology: char*, data: char*, query: char*, updateMessage: ssap_message*): void o Descripción: Genera una estructura ssap_message con los datos asociados a un mensaje SSAP UPDATE. 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 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 o Descripción: Genera una estructura ssap_message con los datos asociados a 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 queryType: Tipo de lenguaje utilizado en la sentencia. Los posibles valores son: NATIVE: Se trata de una sentencia en lenguaje Nativo de MongoDB SQLLIKE: Se trata de una sentencia en lenguaje SQL. updateMessage:ssap_message*: Puntero a estructura ssap_message en el que se devuelve el mensaje SSAP generado. generateRemoveMessage(sessionKey: char *, ontology: char *, query: char*, removeMessage: ssap_message*):void o Descripción: Genera una estructura ssap_message con los datos asociados a un mensaje SSAP DELETE. Se define en el fichero de cabecera SSAPMessageGenerator.h. 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 o Descripción: Genera una estructura ssap_message con los datos asociados a un mensaje SSAP DELETE, 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 DELETE. ontology:char*: Ontologia sobre la que se realiza el DELETE. query: sentencia DELETE en el lenguaje especificado. queryType: Tipo de lenguaje utilizado en la sentencia. Los posibles valores son: APIs SOFIA2 Página 99/111 NATIVE: Se trata de una sentencia en lenguaje Nativo de MongoDB SQLLIKE: Se trata de una sentencia en lenguaje SQL. deleteMessage:ssap_message*: Puntero a estructura ssap_message en el que se devuelve el mensaje SSAP generado. generateQueryMessage(sessionKey: char *,ontology: char *, query: char*, queryMessage: ssap_message*):void o Descripción: Genera una estructura ssap_message con los datos asociados a un mensaje SSAP QUERY. 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: 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 el que se devuelve el mensaje SSAP generado. generateQueryMessageWithQueryType(sessionKey: char *,ontology: char *, query: char*, queryType: enum SSAPQueryType, queryMessage: ssap_message*):void o Descripción: Genera una estructura ssap_message con los datos asociados a 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 queryType: Tipo de lenguaje utilizado en la sentencia. Los posibles valores son: NATIVE: Se trata de una sentencia en lenguaje Nativo de MongoDB APIs SOFIA2 Página 100/111 SQLLIKE: Se trata de una sentencia en lenguaje SQL. 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 o Descripción: Genera una estructura ssap_message con los datos asociados a 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 SSAPMessageGenerator.h. 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 el que se devuelve el mensaje SSAP generado. generateSubscribeMessage(sessionKey: char *, ontology: char *, msRefresh:int, query: char*, subscribeMessage: ssap_message*):void o Descripción: Genera una estructura ssap_message con los datos asociados a un mensaje SSAP SUBSCRIBE. Se define en el fichero de cabecera SSAPMessageGenerator.h. 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 o Descripción: Genera una estructura ssap_message con los datos asociados a un mensaje SSAP SUBSCRIBE, 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 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 queryType: Tipo de lenguaje utilizado en la sentencia. Los posibles valores son: NATIVE: Se trata de una sentencia en lenguaje Nativo de MongoDB SQLLIKE: Se trata de una sentencia en lenguaje SQL. 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 o Descripción: Genera una estructura ssap_message con los datos asociados a un mensaje SSAP UNSUBSCRIBE. Se define en el fichero de cabecera SSAPMessageGenerator.h. 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 el que se devuelve el mensaje SSAP generado. 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 SSAPMessageGenerator.h. 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 SSAPMessageGenerator.h. 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
Documentos relacionados
Cómo desarrollar en Sofia2
de los conceptos del dominio con los que interoperarán los distintos KPs, de manera que distintos KPs trabajando con las mismas ontologías pueden intercambiar información a través de la plataforma ...
Más detalles