SIR Tutorial

All software development under the name "SIR" / "Sensor Instance Registry" is continued in OpenSensorSearch.

General information about the SIR and its concept can be found at http://52north.org/communities/sensorweb/discovery/index.html.

Introduction

Scope

This document describes the install process of the 52°North Sensor Instance Registry (SIR) version 0.3.x ( DEPRECATED, see OpenSensorSearch).

What you are doing when following the installation procedure?

You will download a provided archive file that is ready for deployment, or check out the SIR package from a SVN repository. The package contains an implementation of the SIR as a Java Servlet. Executing the installation steps will deploy this service in your Apache Tomcat (or any other) web container as an web application (sometimes called "webapp").

Some words on the SIR

The Sensor Instance Registry is a web service interface for discovering sensors, collecting sensor metadata (based on SensorML), handling sensor status information and automatically inserting sensor metadata into OGC Catalogues (based on the ebRIM Catalogue Information Model).

Generally the SIR interface can be grouped into four parts: sensor discovery (possibly using semantic search via a Sensor Observable Registry) , sensor metadata collection (including harvesting of SWE service instances), sensor status handling , catalog linking.

SensorML documents which are processed by the SIR shall comply with the SensorML Profile for Discovery as it is defined in OGC 09-163. The profile ensures the completeness of sensor metadata for discovery purposes as well as a consistent metadata structure that can automatically be processed by a SIR instance.

The current release implements the following operations:

GetCapabilities

This operation allows a client to receive service metadata (namely Capabilities) documents that describe the cabilities of the specific server implementation.

SearchSensor

This operation allows a client to search for sensor instances and related service instances. It is possible to specify spatial, temporal and thematic search criteria.

DescribeSensor

This operation allows a client to retrieve a SensorML based description of a sensor managed by a SIR instance.

HarvestService

This operation allows a client to initiate the harvesting process (retrieval and processing) of sensor metadata from a certain SWE service instance.

InsertSensorInfo

This operation allows a client to insert sensor metadata (complete metadata records or relationships between sensors and services) into a SIR instance.

DeleteSensorInfo

This operation allows a client to delete sensor metadata (complete metadata records or relationships between sensors and services) from a SIR instance.

UpdateSensorDescription

This operation allows a client to update the description of a sensor already contained in a SIR instance.

GetSensorStatus

This operation allows a client to request status information about a specific sensor using spatial, temporal and thematic options.

InsertSensorStatus

This operation allows a client to insert status information about a sensor contained in the SIR instance.

ConnectToCatalog

This operation allows a client to establish a (one time only or scheduled) link between a SIR instance and a specific OGC Catalogue server. The request offers options for one time only, or repeated push operations of the full SIR database.

DisconnectFromCatalog

This operation allows a client to stop the process of pushing metadata from a SIR instance into an OGC Catalog server.

Requirements

This list contains a list of minimum and tested required software. Other, especially newer, versions might work as well – please contact the developers if you run SIR successfully in a different set-up.

• Java Runtime Environment (JRE) or Java Contributor Kit (JDK), version 1.6
• Apache Tomcat 6.0.xx (or any other servlet container)
• PostreSQL Version 8.3.x
• PostGIS Version 1.5.x
• SVN-Client (if you want to download the SIR package from the SVN repository), for example TortoiseSVN or Eclipse
• Apache Maven (if you want to build SIR yourself)

Installation

Get Required Progammes

• Download Apache Tomcat from http://tomcat.apache.org/, or install any other servlet container. Follow the installation instructions given on the website to install Tomcat.
• Download PostgreSQL from http://www.postgresql.org/download/. Install PostgreSQL as descibed in the PostgreSQL manual available at http://www.postgresql.org/docs/manuals/.
• Download PostGIS from http://www.postgis.org/download/ or use the PostgreSQL → Application Stack Builder. Install PostGIS as descibed in the PostGIS documentation available at http://postgis.org/documentation/.

Get SIR

Source Code

Software project is deprecated, see OpenSensorSearch for the follow-up software project.

Binary (WAR file)

You can also download a deployable war file at the URL given below and change the configuration files manually after deployment (see section Changing Settings):

http://52north.org/downloads/sensor-web/sir

Please be aware that this might not be the latest version from the SVN but only sparsely released major versions.

Build

The way you configure your SIR instance depends on the way of deployment. If you build the SIR yourself using Maven, please read this section. If you deploy the Tomcat based on an existing WAR file, please skip this section and read on in "Create the Database".

Configuration

The SIR build configuration is completely managed in Maven, i.e. in the root POM filem using profiles. The development profile is activated by default called sir.dev and is ready to use for development on localhost. The deployment profile is called sir.deploy and must be configured in two places, the properties section and the properties section within the profiles section:

• The file /pom.xml file in the root of the source project. You can edit deployment parameters such as the service path and the different available endpoints. The standard configuration looks as follows:
  <properties>
  ...
  <service.path>/SIR</service.path>
  <service.endpoint.service>sir</service.endpoint.service>
  <service.endpoint.rest>rest</service.endpoint.rest>
  <service.endpoint.opensearch>search</service.endpoint.opensearch>
  </properties>
  ...
  <profile>
  <properties>
  <service.url>http://localhost:8080</service.url>
  <db.connectionstring>jdbc:postgresql://localhost:5432/SIR_DATABASE</db.connectionstring>
  <db.driver>org.postgresql.Driver</db.driver>
  <db.user>postgres</db.user>
  <db.password>postgres</db.password>
  </properties>
  ...
• The file <home folder>/.m2/settings.xml. This is your Maven settings file that is used to store usernames and passwords only. An example configuration looks as follows:
  ...
  <profile>
  <id>sir.deploy</id>
  <properties>
  <sir.deploy.server>http://MY_SERVER.TLD</sir.deploy.server>
  <sir.deploy.database.user>MY_USERNAME</sir.deploy.database.user>
  <sir.deploy.database.password>MY_PASSWORD</sir.deploy.database.password>
  </properties>
  </profile>
  ...
  • The properties in this file are used to fill in the placeholders in the deployment profile.

Based on the properties in these files, Maven will automatically fill the placeholders in the runtime configuration files sir.properties and db.properties which are described later in this tutorrial.

Build Application

You have to run Maven with the build file /pom.xml in the dependency projects first.

Build and Install Dependencies

• Please make sure that Maven is correctly installed.
• Open a command line and navigate to the directory .../52n-json.
• Type mvn install. The build file will be found and the build process started. You should see the message "BUILD SUCCESS".
• Repeat the process with the folders .../52n-xml-*.

Build SIR

• Open a command line and navigate to the directory .../52n-sir.
• Type mvn package. The build file will be found and the build process started. You should see the message "BUILD SUCCESS".
• The deployable war file including your settings is now available at .../SIR/52n-sir/target/SIR.war.

Create Database

When creating the database and the tables be sure to use the same account you use later to connect to the database, otherwise you might get problems with PostgreSQL priviliges.

• Use the pgAdmin III – Tool to connect to the database (in Windows XP: Start>Programms>PostgreSQL 8.x >pgAdmin III).
• You find your „PostgresSQL Database Server 8.x“ in the upper left corner of the window.
• Right click on the „PostgresSQL Database Server 8.x“ and choose „Connect“ in the pop up menu.
• Type in the name and password of the superuser you have chosen in the installation steps. Now the red cross over the icon of the server disappears and you are connected to the server. When you right click on “databases” choose “new databases”.
• In the opening window you can create the new database for your SIR (e.g. SIR_DATABASE) by adding the required information and setting the “template” field to “template_postgis”.

Create the table structure of the database

• Start the pgAdmin III (see former chapter).
• Select the created database and click on the button „Execute common SQL query“ in the toolbar. The query window of pgAdmin III appears.
• Download the file datamodel_sir.sql from the following URL https://svn.52north.org/svn/swe/incubation/SIR/trunk/52n-sir/src/main/resources/datamodel_sir.sql or from the folder .../52n-sir/src/main/resources/.
• Click the „Open file“ button and navigate to the folder with the downloaded file.
• Open the file datamodel_sir.sql. The SQL statements now appear in the query field.
• Click the „Execute query“ button to execute the statements in the downloaded file. In the lower field appears the message „Query was succesfull.“ The tables are created now.
• Close pgAdmin III.

Deploy

• Make sure that your Tomcat is installed and running.
• Navigate to the Tomcat Manager, e.g. http://localhost:8080/manager/html.
• Scroll down to the section “WAR file to deploy” and select the WAR file to install, i.e. the file your created in section "Build Application".
• Click on “deploy”. The new service instance will be shown in the application list.

Changing Settings

After installation you can change the mandatory settings and all advanged optional settings in the files in the folder [Tomcat Installation]/webapps/[webapp.name]/WEB-INF/conf, namely sir.config and dbsir.config. The latter contains all database related settings, the former everything else. If you deployed an unconfigured war file, please change at least the following settings, then restart the webapp for the changes to take effect.

Property	Explanation
sir.config	Set the correct SERVICEURL for the test clients and the capabilities file. Otherwise (test) clients will not work!
dbsir.config	Set the database settings, at least user and password.

All (other) settings should be handled with care! You can change the content of the capabilities document in the file .../WEB-INF/conf/sirCapabilitiesSkeleten.xml. Be aware of the content that is updated during runtime.

Tests

This section contains some basic tests to ensure your installation was successful.

Capabilities Request via HTTP GET

• Open your browser.
• Enter the following text into the address bar: http://localhost:8080/SIR/sir?REQUEST=GetCapabilities&SERVICE=SIR.
  • Optionally replace the localhost and port with the correct address of a remote server.
• The capabilities response document is now shown in your browser.

Requests via HTTP POST

• Start your internet browser (e.g. Mozilla Firefox).
• Open the SIR simple test client at http://localhost:8080/SIR/testClient.html. You find a simple GUI that allows you to try out some example requests by selection from the “Request examples” drop down list.
• Alternatively, use any programming language or environment that is able to issue HTTP POST request.
• Alternatively, you can use the more advanced SIR client at the URL http://localhost:8080/SIR/index.jsp to interactively create requests and inspect responses.

Troubleshooting

If you have any question concerning the installation and configuration process, feel free to contact the 52°North SWE mailing list at org. For more information visit http://52north.org/resources/mailing-list-and-forums/.

Issue No.	Question and Solution
0	Where do I find the administrator username and password of my Tomcat? The login datas are stored in the tomcat-users.xml in your Tomcat 6.0/conf Folder.

References

• S. Jirka and D. Nüst (2010): OGC Sensor Instance Registry Discussion Paper, Version 0.3.0, OGC document 10-171, download: http://portal.opengeospatial.org/files/?artifact_id=40609