= Semantic Query Resolver = The Semantic Query Resolver (SQR) acts as a single entry point for Resource Users into the SENSEI system. The SQR provides the Semantic Query Interface (SQI) to Resource Users which offers convenient methods for Resource lookups as well as information and actuation requests. The implementation features a Web GUI that allows users to access the SQI interface. For developpers, the latter is also directly accessible through REST calls. In what follows, we describe these features and specify the installation procedure of the corresponding software. [[PageOutline(2-3,Table of Contents,inline)]] ---- == Implementation == The SQR has been implemented using the restlet.org framework. As a result, the buisness logic of the component has been embedded within so-called RESTlet Resources that provide the API to manage the access to the SQR operations in a RESTful fashion. One of the key features of the RESTlet framework is also the integration within its API of a template engine, Freemarker that allows to build Web pages on top of the framework RESTful API. This makes the SQR accesible through both standard RESTful calls but also through a simple Web site. Given the complexity of the SQI we decided to bind each operation to a particular Resource so that maintenance is made easier. The implementation features the following path structure: * http://hostname:port/sqr/ : SQR index page * http://hostname:port/sqr/requestResDesc : Lookup resource descriptions (involving RD and ED lookups), simple and selector-based queries. See [[#Messages]] for the messages handled by this resource. * http://hostname:port/sqr/requestBinding : Lookup bindings on the ED, simple queries. See [[#Messages]] for the messages handled by this resource. * http://hostname:port/sqr/requestBindingIOPP : Lookup bindings on the ED, template queries. See [[#Messages]] for the messages handled by this resource. * http://hostname:port/sqr/requestInformation : Request information (involving planning, access to RD and ED, and EM invocation), selector-based queries. See [[#Messages]] for the messages handled by this resource. * http://hostname:port/sqr/subscribeInformation : Subscribe to information (involving planning, access to RD and ED, and EM invocation), selector-based queries. See [[#Messages]] for the messages handled by this resource. * http://hostname:port/sqr/listSubscriptionInformation: List of subscriptions for information. See [[#Messages]] for the messages handled by this resource. * http://hostname:port/sqr/listSubscriptionInformation/{subsName} : Access to information subscription with ID subsName. See [[#Messages]] for the messages handled by this resource. * http://hostname:port/sqr/requestActuation : Execution of an actuation task. See [[#Messages]] for the messages handled by this resource. The subscription database has been implemented using SEDNA, an XML database that supports native XML document storage as well as XML query processing over the set of XML documents stored in the database. As a result, the implementation presents itself as a software implementing the SQR functionalities and an instance of the SEDNA database. ---- == Requirements == * Windows or Linux operating system * [http://java.sun.com/javase/downloads/widget/jdk6.jsp Java SDK], version 6.0 or higher * [http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/heliossr1 Eclipse IDE for Java EE Developers] * [http://modis.ispras.ru/sedna/download.html SEDNA server] * [wiki:SQR-dwl Semantic Query Resolver version 3] ---- == Using the REST API == The implementation contains a client API for developpers to access the standard REST API of the SQR. The API is available in the package com.sap.research.sensei.sqr.api of the software. We refer the reader to the code !JavaDoc for a description of the methods part of the client implementation. The com.sap.research.sensei.sqr.test package features test cases for each usage scenario. Please refer to the !JavaDoc of each test for details. You need to fill in the SQR_test.properties file based on your own configuration of the SQR: {{{ #SQR CLIENT CONFIGURATION #----------------------- #Path to the server index page SQR_DIRECTORY_BASE_URI = http://localhost:8186/sqr }}} ---- == Web Interface == The Web Interface is depicted in the User Guide at [https://ncit-cluster.grid.pub.ro/trac/Sensei-Cookbook/wiki/RuSqr#WebInterface] . ---- == Installation == You need to download the SEDNA Database from [http://modis.ispras.ru/sedna/download.html] and dezip it. Run SEDNA : SEDNA_PATH/bin/se_gov.exe and create the sqrdb database (do it only once) : SEDNA_PATH/bin/se_cdb.exe sqrdb. Then start the sqrdb database : SEDNA_PATH/bin/se_sm.exe sqrdb. To stop the sqrdb database : SEDNA_PATH/bin/se_smsd.exe sqrdb To stop SEDNA : se_stop.exe The software can be started from the Main class in the package com.sap.research.sensei.sqr.startup . Fill in the SQR.properties file based on your own configuration: {{{ #SERVER CONFIGURATION #----------------------- #SQR Context Path SQR_CONTEXT_PATH = /sqr #Server port SERVER_PORT = 8186 #EOI, RD CONFIGURATION #----------------------- #RLI interface of the RD URI (no SPARQL) RESSOURCE_DIRECTORY_RLI_URI_NO_SPARQL = http://sensei-dev1.grid.pub.ro:8184/rli #RLI interface of the RD URI (with SPARQL) RESSOURCE_DIRECTORY_RLI_URI = http://sensei-dev1.grid.pub.ro:8184/rli/mix/lookup #Resource Directory base URI RESSOURCE_DIRECTORY_BASE = http://sensei-dev1.grid.pub.ro:8184/rd #Entity Directory base URI EOI_DIRECTORY_BASE_URI = http://localhost:8182/eoi #Entity Directory ELI URI EOI_DIRECTORY_ELI_URI = http://localhost:8182/eoi/eli #Execution Manager Base URI EM_BASE_URI = http://localhost:8180/subscribe #SEDNA CONFIGURATION #----------------------- #DB USERNAME DB_USERNAME = SYSTEM #DB PASSWORD DB_PASSWORD = MANAGER #DB BASE URI DB_URI_BASE = xmldb:sedna://localhost/sqrdb #DB SUBSCRIPTIONS COLLECTION URI DB_URI_SUBSCRIPTION = xmldb:sedna://localhost/sqrdb/subscriptions #VISUALIZATION TOOL CONFIGURATION (Not used in this version, left here in case this changes) #----------------------- #Activate visu tool VISU = NO #Time to let the GUI refresh SLEEP = 1500 #Paths the the visualization tool VISUARCHIPATH = http://localhost:8080/SVGMonitor/setstate.jsp }}} == Messages == === Request Resource Description === The lookup for resource descriptions requires sending the following request HTTP POST http://hostname:port/sqr/requestResDesc. In the case of simple requests, it mirrors the RD; and therefore the body of the message contains the following XML: {{{ apartment PREFIX ard: PREFIX om: SELECT ?description WHERE { ?description ard:hasSemanticOperationDescription ?operation . ?operation ard:hasOutput ?output . ?output ard:hasInformationType ?out_infoType . ?out_infoType rdfs:subClassOf om:HumanPresence . } ]]> }}} For the resource selector case, the XML in the body of the message is the following: {{{ Resource PREFIX ard: PREFIX om: SELECT ?description WHERE { ?description ard:hasSemanticOperationDescription ?operation . ?operation ard:hasOutput ?output . ?output ard:hasInformationType ?out_infoType . ?out_infoType rdfs:subClassOf om:HumanPresence . } ]]> }}} And in the context selector case, the XML in the body of the message is the following: {{{ Context Apartment123456 http://www.ict-sensei.org/EntityOfInterest#Apartment personPresent }}} === Request Binding === The lookup for bindings on the ED for simple queries requires sending the following request HTTP POST http://hostname:port/sqr/requestBinding with the XML in the body: {{{ Apartment123456 http://www.ict-sensei.org/EntityOfInterest#Apartment personPresent Output }}} The lookup for bindings on the ED for template queries requires sending the following request HTTP POST http://hostname:port/sqr/requestBindingIOPP with the XML in the body: {{{ 59.402925968170166-17.94867753982544 Apartment123456 http://www.ict-sensei.org/EntityOfInterest#Apartment personPresent }}} === Request Information === The request for information requires sending the following request HTTP POST http://hostname:port/sqr/requestInformation . The body of the message contains the following XML for the case of a context selector: {{{ Context Apartment123456 http://www.ict-sensei.org/EntityOfInterest#Apartment personPresent }}} In the case of a resource selector, the XML in the body of the message would be the following: {{{ Resource 123 req_value }}} === Subscribe to Information === The subscription for information requires sending the following request HTTP POST http://hostname:port/sqr/subscribeInformation . The body of the message contains the following XML for the case of a context selector: {{{ Context Apartment123456 http://www.ict-sensei.org/EntityOfInterest#Apartment personPresent true http://localhost:8190/callback 10000 }}} In the case of a resource selector, the XML in the body of the message would be the following: {{{ Resource 123 req_value true http://localhost:8190/callback 10000 }}} In order to list the subscriptions for information currently handled by the SQR, it is required to send the following request HTTP GET http://hostname:port/sqr/listSubscriptionInformation . And to access the information related to the subscription with ID subsName, it is required to send the following request HTTP GET http://hostname:port/sqr/listSubscriptionInformation/{subsName}. === Execute Actuation Task === The execution of an actuation task requires sending the following request HTTP POST http://hostname:port/sqr/requestActuation with the XML in the body: {{{ http://www.ict-sensei.org/EntityOfInterest#EntityOfInterest hasLight hasLight ON }}}