SIR Development Documentation

Tasks

See SensorInstanceRegistryBacklog.

Changelog

0.5.4

• ...

UML

An extensive documentation of the class structure is in this Enterprise Architect project file: sir.eap.

Some core example diagrams are attached to this page as images:

• Main classes
• Internal datastructure
• Listeners

Package, Class and File Structure

Data structure

The data structure appears at several places in the service:

• All requests and responses, and their elements have matching Java classes in the service implementation (package org.n52.sir.datastructure).
• The data base access is based on a DAO pattern. Java classes are in the package org.n52.sir.ds, and the currently the only supported implementation is PostgreSQL (package org.n52.sir.ds.pgsql).
• The table structure, indices etc. of the data base are defined in the file /SIR/src/main/resources/datamodel_sir.sql.

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 interfaces and implemenations are IHttpGetRequestDecoder.java and IHttpPostRequestDecoder.java in the package org.n52.sir.decode[.impl].

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, validate incoming or outgoing documents, 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.

Transformation

The transformation of sensor metadata descriptions in SensorML to ebRIM compatible documents is based on XSLT.

The required transformation files ( .xslt) are saved in the directory /WebContent/WEB-INF/xslt, but this can be changed using the configuration parameter XSTL_DIRECTORY. Example files for testing can be found in the directory /SIR2/data/transformation.

The Java classes for transformation can be found in the package org.n52.sir.xml. A factory pattern is used.

Profile Conformity Testing

The document OGC 10-171 also contains an XML profile which defines all elements that shall be present in a SensorML description. This set can be seen as the minimal useful information which is needed for sensor discovery. These elements can then be used in the transformation. All incoming/inserted documents are checked against the profile and only accepted if they are conform with it! Users can test their documents beforehand (but only manually) using the test client, but the response contains information about why a document is not accepted, too.

The required XSLT files for transforming the profile into an XSLT file which in turn can be used for validation (check out the various Schematron resources on the web for details of this process) are in the folder pointed to by the configuration parameter XSTL_DIRECTORY. The actual profile file is SensorML_Profile_for_Discovery.sch and is currently saved in the conf folder. Of course, these can be changed in the properties file! Example files for testing can be found in the directory /SIR2/data/transformation.

The Java classes for validity testing can be found in the package org.n52.sir.xml. A factory pattern is used.

Tests and Utilities

Tests

The Java code contains very rudimentary unit tests in the package org.n52.sir.util.test. The can be run using JUnit very easily in Eclipse: Right click on the file SirTestSuite.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 .../WebContent/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 in a way as well.

The package org.n52.sir.util.testData contains a generator for dummy sensor descriptions that can be directly inserted into a SIR instance. Take a look at GeneratorClient.java if you want to try it out.

Utilities

Utility functionality, e.g. common tasks with XML documents, the job handling for catalog connections, clients to other webservices (like SOR), and more are collected in the package org.n52.sir.util. These are pretty straightforward and well-documented, so a lengthy explanation is abstained from at this point.

Browser Clients

Landing Page

The landing page shows a very simple user interface - just one text box to enter a search string into, just like many popular search engines. The response is also rendered in a fashion remotely similar to a popular search engine. This client utilizes an OpenSearch interface and several response formats such as HTML, XML, KML, or JSON.

Extended client

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. In addition to the service operations the client includes a page to transform SensorML documents into EbRIM documents using the same method that the service utilizes, and a page to view the log about last pushing events to other catalogs (during runtime only!).

All Java classes for the test client can be found in the package org.n52.sir.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 sir.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.

Form Client

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!

Build Process

The build process is completely based on Maven. Since several dependencies are not available in public repositories as binaries. Therefore you have to download and install ( mvn install) the following projects before being able to build the main project 52n-sir.

• 52n-xml-wrs-v101
• 52n-xml-sir-v032
• 52n-xml-sor-v031
• 52n-json-sir

The run mvn package on 52n-sir.

Development Instructions

An Eclipse project for development is available at https://svn.52north.org/svn/swe/incubation/SIR. You can browse the repository here.

Maven Checkout

To check out a working SIR installation into Eclipse follow these steps:

• Check out the following projects with your favourite SVN client for Eclipse (recommended and used for this step-by-step description: Subclipse).
  • File > New > Other... > Check out project from SVN
  • Repository location: https://svn.52north.org/svn/swe/incubation/
  • Navigate to directory SIR > trunk
  • One after the other, select one of these directory and click "Next" (Not "Finish". We do not automatically import is as a Maven project since Maven problems will interfere with the checkout.)
    • 52n-xml-wrs-v101
    • 52n-xml-sir-v032
    • 52n-xml-sor-v031
    • 52n-json-sir
  • Use "Check out as project in the workspace" and use the suggested name (the name of the component respectively directory).
  • Click "Finish".
• Right-click on the newly available project, select Configure > Convert to Maven Project
• If your have errors, right-click on the project and select Maven > Update Project...
• Repeat the process above for the main project 52n-sir.
• Optional: Take a look at the project 52n-arsearch to see integration of the SIR with augmented reality browsers.

Please follow the internal guidelines: DeveloperInformation and QualityManagement.

Troubleshooting

• Use mvn test on a project on the console, then update the Maven Project in Eclipse - this often solves problems with dependencies!

Requirements for Development

• Eclipse IDE for Java EE Developers (includes Web Tools Platform), http://www.eclipse.org/
• SVN client for Eclipse (e.g. subversive, http://www.eclipse.org/subversive/) or standalone SVN client

Development Workflow

Run Maven configuration with the goal tomcat6:run-war and the profile sir.dev in debug mode in Eclipse.

Metadata

• Topic created by: DanielNuest
• Topic created on: 2013-01-31