SOR Architecture

Architecture documenation for SensorObservableRegistry.

Package, Class and File Structure

The base class of the service is SOR.java, which extends HttpServlet, and serves all incoming GET and POST requests. It is located in the base package org.n52.sor along with the following classes (excerpt):

• PhenomenonManager.java Basically serves as the database. It's a singleton and the access methods are synchronized (though this is not extensively tested) for concurrent access. After every insert or delete operation it saves a backup file. The count of backup files can be set in the properties file.
• PropertiesManager.java Singleton for access to all config properties within the service.
• RequestOperator.java works as a dispatcher and forwards the incoming request to the appropriate listener classes.

Data structure

The data set for the SOR is a single XML file WEB-INF/conf/data/phenomena.xml containing a gml:Dictionary with a list of gml:dictionaryEntry elements. Currently only a single file is supported. The name of the file can be changed in the properties file ( sor.config).

Only one data entity is used within SOR at the moment, IDictionaryEntry.java (and the according implementation DictionaryEntryImpl.java from the package or.n52.sor.datastructures) represents all properties of a gml:dictionaryEntry required for the use in SOR. On first creation of the phenomenon manager, the GML Dictionary is read in from a file and dictionary entry instances are created for every gml:dictionaryEntry in the document. These instances are then utilized (that is mostly querying) during runtime.

Request and Response Handling

The flow of the request through the classes is as follows (italic words refer to components described below): Incoming request is decoded in the request operator using get and post decoders. The decoded request is then inserted into the according listener class, which actually processes the request and create the respective response class instance. This is then handed through the request operator back to the servlet.

The request and response handling consists of four components:

Decoding

The decoders transform the incoming GET URLs or XML documents into the Java request classes (see next step). The respective decoders are HttpGetRequestDecoder.java and HttpPostRequestDecoder.java in the package org.n52.sor.decoder.

Requests

The request classes extending ISorRequest.java in the package org.n52.sor.request mirror all the incoming requests. They hold all required values from the incoming requests and are created in the respective decoder.

Listeners

The listener classes in the package org.n52.sor.listener do the actual processing of the request, i.e. they query the database for the definition, or consult the reasoner for matching definitions, and so forth. They create an according ISorResponse.java which is returned into the request operator.

Responses

The response classes extending ISorResponse.java in the package org.n52.sor.response mirror all the outgoing responses.

Semantic Reasoning

The package org.n52.sor.reasoner contains all classes for semantic reasoning. At the moment, only one implementation of IReasoner.java can be found. ReasonerImpl.java acts as a singleton for the actual reasoner, which is based on the Jena Semantic Web Framework. The singleton was added to avoid multiple downloads of ontology files that have to be one on instatiation of the reasoner class JenaReasoner.java.

Tests and Utilities

Tests

The Java code contains very rudimentary unit tests in the package org.n52.sor.util.test. The can be run using JUnit very easily in Eclipse: Right click on the file SorTestSuite.java, then navigate to Run As... > JUnit Test to run all tests.

It is important to point out that this test Suite does currently NOT check the content of the received responses, it merely checks for validity of the document (so an exception response does lead do a failed test).

The tests utilize the request examples from the folder .../TestRequests, so the URLs for testing the GET interface are taken from the file RequestExamples _GET.txt" and the XML documents for testing the POST interface are the respective =...Request.xml files. In addition, the POST is tested a second time using the client's beans - so a simple test of the client is included as well.

Utilities

The package org.n52.sor.util contains two classes designated for encapsulation of reoccuring tasks. XmlTools.java contains helpful methods and constants for creating and validation XmlBeans.

Clients

The test client is written using [[http://java.sun.com/products/jsp/][Java Server Pages]. It provides a simple interface to comfortably create and send POST requests to the service and inspect the response. The identifiers of available observables are included in some pages for convenient selection.

All Java classes for the test client can be found in the package org.n52.sor.client. These comprise currently only the beans for the respective JSPs and the class Client.java to send the actual requests.

The index.jsp is in the folder .../WebContent/, the sub-pages for all operations in the subfolder .../WebContent/pages, one .jsp respectively. The pages include the JSPs header.jsp for the images and title, menu.jsp for the menu, and htmlHead.jsp for Javascript and style sheet configuration that is required across all pages. The file sor.css contains style information and the folder /images contains the logos for the client's header.

The syntax highlighting in the editor relies on CodeMirror. All codemirror files are in the folder .../WebContent/codemirror and the configuration/initialization of the editors is handled for all pages in the file htmlHead.jsp.

The simple test client is only a single HTML file, testClient.html. It uses codemirror for syntax highlighting and includes a drop-down menu for selecting some request examples. These examples are taken from the folder .../WebContent/TestRequests/. There is one example file for every possible request via POST, and a single text file containing examples of possible GET requests. These example files are also used for testing!

RESTful interface

The RESTful interface is in the package org.n52.sor.rest and consists of a servlet, Frontend.java, which extends RestWebService.java, and naturally only services GET requests. The latter class provides functionality for creating browsable HTML pages. Regarding configuration: The servlet does not rely on PropertiesManager.java but accesses the configuration file directly, and a few settings that are very unlikely to change are saved as constants in the classes (this includes the style and markup of the HTML listing).

Metadata

• Topic created by: DanielNuest
• Topic created on: 2012-05-30