wiki:SQR

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.

Table of Contents

  1. Implementation
  2. Requirements
  3. Using the REST API
  4. Web Interface
  5. Installation
  6. Messages
    1. Request Resource Description
    2. Request Binding
    3. Request Information
    4. Subscribe to Information
    5. Execute Actuation Task

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:

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

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: 

<requestResource>
        <resourceSpecification>
                <tag>apartment</tag>
        </resourceSpecification>
	<AdvancedSpecification>
		<![CDATA[
			PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
	 		PREFIX ard: <http://www.ict-sensei.org/AdvancedResourceDescription#>
			PREFIX om: <http://www.ict-sensei.org/ObservationAndMeasurement#> 
	  		SELECT ?description 
	  		WHERE { 
	   		     ?description ard:hasSemanticOperationDescription ?operation .
	  		     ?operation ard:hasOutput ?output .
	   		     ?output ard:hasInformationType ?out_infoType .
	    		     ?out_infoType rdfs:subClassOf om:HumanPresence . } 
	  	]]>
	</AdvancedSpecification>
</requestResource>

For the resource selector case, the XML in the body of the message is the following: 

<requestResourceDescription xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<Selector xsi:type="ResourceSelector" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<Type>Resource</Type>
		<AdvResourceSpecification>
	   		<![CDATA[ 
	  			PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
		 		PREFIX ard: <http://www.ict-sensei.org/AdvancedResourceDescription#>
				PREFIX om: <http://www.ict-sensei.org/ObservationAndMeasurement#> 
		  		SELECT ?description 
		  		WHERE { 
		   		     ?description ard:hasSemanticOperationDescription ?operation .
		  		     ?operation ard:hasOutput ?output .
		   		     ?output ard:hasInformationType ?out_infoType .
		    		     ?out_infoType rdfs:subClassOf om:HumanPresence . } 
		  	]]>
   		 </AdvResourceSpecification>
	</Selector>
</requestResourceDescription>

And in the context selector case, the XML in the body of the message is the following: 

<requestResourceDescription>
	<Selector xsi:type="ContextSelector" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<Type>Context</Type>
		<EntityID>Apartment123456</EntityID>
		<EntityType>http://www.ict-sensei.org/EntityOfInterest#Apartment</EntityType>
		<Attribute>personPresent</Attribute>
	</Selector>
</requestResourceDescription>

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: 

<SimpleEDQuery>
	<EoI>Apartment123456</EoI>
	<EntityType>http://www.ict-sensei.org/EntityOfInterest#Apartment</EntityType>
	<Attribute>personPresent</Attribute>
	<IOPEType>Output</IOPEType>
</SimpleEDQuery>

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: 

<JokerBinding>
	<ObservationArea>59.402925968170166-17.94867753982544</ObservationArea>
	<Output>
		<EoI>Apartment123456</EoI>
		<EntityType>http://www.ict-sensei.org/EntityOfInterest#Apartment</EntityType>
		<Attribute>personPresent</Attribute>
	</Output>
</JokerBinding>

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: 

<requestInformation>
	<Selector xsi:type="ContextSelector" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<Type>Context</Type>
		<EntityID>Apartment123456</EntityID>
		<EntityType>http://www.ict-sensei.org/EntityOfInterest#Apartment</EntityType>
		<Attribute>personPresent</Attribute>
	</Selector>
</requestInformation>

In the case of a resource selector, the XML in the body of the message would be the following: 

<requestInformation>
	<Selector xsi:type="ResourceSelector" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<Type>Resource</Type>
		<ResourceID>123</ResourceID>
    		<OperationID>req_value</OperationID>
        </Selector>
</requestInformation>

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: 

<subscribeInformation>
	<Selector xsi:type="ContextSelector" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<Type>Context</Type>
		<EntityID>Apartment123456</EntityID>
		<EntityType>http://www.ict-sensei.org/EntityOfInterest#Apartment</EntityType>
		<Attribute>personPresent</Attribute>
	</Selector>
	<NotificationCondition>
		<OnlyOnChange>true</OnlyOnChange>
	</NotificationCondition>
	<Callback>http://localhost:8190/callback</Callback>
	<LifeTime>10000</LifeTime>
</subscribeInformation>

In the case of a resource selector, the XML in the body of the message would be the following: 

<subscribeInformation>
	<Selector xsi:type="ResourceSelector" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<Type>Resource</Type>
		<ResourceID>123</ResourceID>
    		<OperationID>req_value</OperationID>
        </Selector>
	<NotificationCondition>
		<OnlyOnChange>true</OnlyOnChange>
	</NotificationCondition>
	<Callback>http://localhost:8190/callback</Callback>
	<LifeTime>10000</LifeTime>
</subscribeInformation>

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: 

<requestActuation>
	<ActuationRequest xsi:schemaLocation="http://www.sensei-project.eu/actuation/schemas/actuationRequest.xsd" 
                          xmlns:act="http://www.sensei-project.eu/actuation" 
                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
		<ActuationTask>
			<PostCondition xsi:type="act:EntityPostCondition">
				<entity>
					<EntityType>http://www.ict-sensei.org/EntityOfInterest#EntityOfInterest</EntityType>
					<ContextAttribute>
						<attributeName>hasLight</attributeName>
						<attributeType>hasLight</attributeType>
						<Object xsi:type="act:ObservationMeasurement">
							<value>ON</value>
						</Object>
					</ContextAttribute>
				</entity>
			</PostCondition>
		</ActuationTask>
	</ActuationRequest>
</requestActuation>
Last modified 13 years ago Last modified on Mar 2, 2011, 8:14:39 AM