r18 - 13 Jul 2010 - 13:32:55 - CarstenHollmannYou are here: TWiki >

Sensornet Web > SensorObservationService > SosTutorial

52°North SOS Tutorial

NOTE: This site is currently under construction and not finished yet!

52°North SOS Tutorial

The installation, deployment and use of the 52°North Sensor Observation Service on a Windows XP machine is described in the following sections. The current 52°North SOS implements the OGC SOS implementation specification version 1.0 (OGC 06-009r6, available at http://www.opengeospatial.org/standards/sos). The 52°North SOS supports the three core operations GetCapabilities, GetObservation and DescribeSensor as well as the additional operations GetFeatureOfInterest and GetResult. If you want to insert measurements using the SOS interface, you can use the operations of the transactional profile (RegisterSensor and InsertObservation) which are also supported by the SOS implemenation.

First Step: Identify the data, which should be provided by your 52°North SOS instance

The most important step when installing and providing a sensor observation service, is to identify the data items you want to publish and to map this onto the datamodel and concepts used by the 52°North SOS. A detailed discussion could be found on the SosDataModeling site.

Second Step: Download and install the required software

Downloading the required Software

This tutorial is based upon the following software:

Java SDK 6.0: You can download the Java SDK at http://java.sun.com/javase/downloads/index.jsp.

Apache Tomcat 6.0: The Apache Tomcat could be downloaded at http://tomcat.apache.org/download-60.cgi. Some hints on Apache Tomcat installation using Windows 7 (64 Bit) can be found at the side ApacheTomcatWindows

Apache Maven 2.2.1: Download Apache Maven from http://maven.apache.org/download.html and follow the instuructions given there.

PostgreSQL DBMS 8.4: The PostgreSQL database management system could be downloaded at http://www.postgresql.org/download/.

Postgis 1.4 or 1.5: The PostGIS spatial extension could be found at http://www.postgis.org/download/.

Configure Maven

Edit the settings.xml from your conf folder located under the Maven install folder. Make the following additions.
Under the tag insert the path to your local repository:

 
<localRepository>
   [YourPathTo]\.m2\repository
</localRepository>

Check in your file browser if the path in correct! Under the tag insert the following profile:

<profile>
    <id>52n-start</id>
    <repositories>
        <repository>
                <id>n52-releases</id>
                <name>52n Releases</name>
            <url>http://52north.org/maven/repo/releases</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
        <repository>
            <id>geotools</id>
            <name>Geotools repository</name>
            <url>http://maven.geotools.fr/repository</url>
        </repository>
        <repository>
            <id>Refractions</id>
            <name>Refractions repository</name>
            <url>http://lists.refractions.net/m2</url>
        </repository>
        <repository>
            <id>Apache</id>
            <name>Apache repository</name>
            <url>http://repo1.maven.org/maven2</url>
        </repository>
    </repositories>
</profile>

And after the Section insert the following active profile:

<activeProfiles>
    <activeProfile>52n-start</activeProfile>
</activeProfiles>

Installing PostreSQL 8.4 and PostGIS 1.x

Install PostgreSQL as descibed in the PostgreSQL manual available at http://www.postgresql.org/docs/manuals/
Install PostGIS as descibed in the PostGIS documentation available at http://postgis.org/documentation/

Creating a PostGIS Database and SOS table structure

Use the pgAdmin III – Tool. Start and connect to the database with pgAdmin (in Windows XP: Start > Programms > PostgreSQL 8.x > pgAdmin III). The following window appears:

Figure 1:

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.

Figure 2:

When you right click on “databases” choose “new databases”. In the opening window (Figure 3) you can create the new database for your SOS (e.g. SosDatabase) typing the needed information and set the “template” field to “template_postgis”.

Figure 3:

Now click on the button „Execute common SQL query“ in the toolbar. The query window of pgAdmin III appears.
Click the „Open file“ button and navigate to the db-folder of your zip file. Open the file datamodel_postgres83.sql. The SQL statements now appear in the query field.

Figure 4:

Now click the „Execute query“ button to execute the table. In the lower field appears the message „Query was succesfull.“ The tables are created now.
Close the pgAdmin.

Third Step: Downloading and installing the SOS v 3.1.0

Downloading the SOS

To download the SOS there are two possibilities:

You can either download the zip File containing the latest stable release from 52north download page or you can check out the currrent sources from the SVN repository as described in the SvnSos. If you decided for the zip-File you have to Unzip it to your Harddisk (to C:\SOS e.g.).

Configuration of the build.properties

Open the build.properties file in SOS/conf and edit the properties followed by
#############################################################
##SOME OF THE FOLLOWING PROPERTIES HAVE TO BE CHANGED!!! ##
#############################################################
The properties followed by
####################################################################
##FOLLOWING PROPERTIES ONLY TO BE CHANGED FOR ADVANCED USERS!!! ##
####################################################################
are for advanced users.
The properties in the build.properties look like the following example:

      property.name = value

In Table 1 all changeable properties from the build.properties are listed. You find the different properties listed in Table 1. At the beginning of the table, you find properties you have to change (MANDATORY) or you can change (OPTIONAL). After this section the properties for advanced users are described.

Property	Description
*The following properties must (MANDATORY), can (OPTIONAL) be changed.*
`conf.sos.name`	In the profiles section. Profile with id with-deploy. The name of the web application (which is 52nSOSv3 by default). If you preferanother name you can change the name. (OPTIONAL)
`deploy.target.host`	DNS name or IP of the target host (OPTIONAL if necessary)
`deploy.target.port`	Port of the target host (OPTIONAL if necessary)
`deploy.tomcat.manager.url`	URL pointing to Tomcat Manager (NO CHANGES)
`deploy.tomcat.manager.username`	Tomcat Manager username (MANDATORY)
`deploy.tomcat.manager.password`	Tomcat Manager password (MANDATORY)
`deploy.tomcat.home`	installation directory of the tomcat servlet engine (MANDATORY)
`conf.sos.ds.connectionstring`	The connection string to your database. (e.g. jdbc:postgresql://localhost:5432/SosDB for PostgreSQL)(MANDATORY)
`conf.sos.ds.user`	The user name for your access to the database server (MANDATORY).
`conf.sos.ds.password`	The password for your access to the database server (MANDATORY).
*The following properties are for advanced users*
`conf.sos.capabilitiesCacheControler`	Class of capabilities cache controller (ADVANCED)
`conf.sos.capabilitiesCacheUpdateIntervall`	Capabilities Cache Update Interval in minutes (0 = no automatic update) (ADVANCED)
`conf.sos.ds.daofactory`	In the profiles section. Profile with id with-deploy. Class name of the data access object factory, including the package name (e.g. org.n52.sos.ds.pgsql.PGSQLDAOFactory).The SOS realizes the data access object pattern and therefore uses a factory for the data access objects. Change this only if you are an advanced user and you are using another data source! (ADVANCED)
`conf.sos.ds.driver`	The database jdbc driver (e.g. for PostgreSQL org.postgresql.Driver) Change this if you use another database system.(ADVANCED)
`conf.sos.ds.initcon`	Initial number of connections of the connection pool the SOS uses. It is not recommended to change this.(OPTIONAL)
`conf.sos.ds.maxcon`	Maximal number of connections of the connection pool the SOS uses. It is not recommended to change this.(OPTIONAL)
`conf.sos.listeners`	Comma separated list of the request listeners which are implemented (without white space!). Change this only if you have implemented further request listeners to support further operations. Following listeners are implemented GetCapabilitiesListener GetObservationListener GetObservationByIdListener DescribeSensorListener DescribeFeatureTypeListener DescribeObservationTypeListener GetResultListener GetFeatureOfInterestListener GetFeatureOfInterestTimeListener InsertObservationListener RegisterSensorListener (ADVANCED)
`conf.sos.skeletonfile`	Absolute path and name of the skeleton file for the capabilities document. Change this only, if you want to store the file in another directory. (ADVANCED)
`conf.sos.skeletonfilemobile`	Absolute path and name of the mobile skeleton file for the capabilities document. Change this only, if you want to store the file in another directory. (ADVANCED)
`conf.sos.sensordir`	The directory where the SensorML documents for each sensor (procedure) are stored. Change this only, if you want to store them in another directory. (ADVANCED)
`conf.sos.omEncoder`	Implementation of IOMEncoder used to encode observations (has to be reimplemented, if new observation types should be supported) (ADVANCED)
`conf.sos.gmlEncoder`	GMLEncoder implementation (implementation of IGMLEncoder) (ADVANCED)
`conf.sos.postRequestDecoder`	HttpPostRequestDecoder implementation (implementation of IhttpPostRequestDecoder) (ADVANCED)
`conf.sos.getRequestDecoder`	HttpGetRequestDecoder implementation (implementation of IhttpGetRequestDecoder) (ADVANCED)
`conf.sos.getResponseEncoder`	ResponseEncoder implementation (implementation of IResponseEncoder) (ADVANCED)
`conf.sos.sensorMLEncoder`	SensorMLEncoder implementation (implementation of ISensorMLEncoder) (ADVANCED)
`conf.sos.loglevel`	The level which determines which log messages will be written into the log file. The standard is INFO. Below is a listing which levels are possible. It is not recommended to change the level. SEVERE (highest value) WARNING INFO CONFIG FINE FINER FINEST (lowest value) (OPTIONAL)
`conf.sos.mobileEnabled`	Property indicates, whether SOS supports mobile requests ; (default := true) (ADVANCED)
`conf.sos.gmlDateFormat`	gml date format: yyyy-MM-dd'T'HH:mm:ssZ (ADVANCED)
`conf.sos.characterEncoding`	Character encoding for response documents (ADVANCED)
`conf.sos.srs.prefix`	prefix URN for the spatial reference system (ADVANCED)
`conf.sos.supportsQuality`	Property indicates, whether SOS supports quality informations in observations or not; (default := false) (ADVANCED)
`conf.sos.switchCoordinatesForEPSG`	property keeps a list of all EPSG codes for which the SOS has to switch coordinates from long/lat to lat/long; PostgreSQL users please read the important note in section 4! (ADVANCED)
`conf.sos.foiEncodedInObservation`	Property indicates, whether SOS encodes the complete FOI-instance within an Observation instance or just the FOI id; (default := true) (ADVANCED)
`conf.sos.logdir`	The directory where the log file will be stored. (ADVANCED)
`conf.sos.result.lease`	Time of lease for result template in getResult operation (in minutes) (ADVANCED)
`conf.sos.result.tokenseperator`	Token seperator in result element (ADVANCED)
`conf.sos.result.tupleseperator`	Tuple seperator in result element (ADVANCED)
`conf.sos.result.decimalSeperator`	Decimal separator in result element (ADVANCED)
`conf.sos.result.nodatavalue`	No data value for result string containing the values in common observation and getResult response (ADVANCED)
`conf.sos.serviceversion`	The version of this SOS. (DO NOT CHANGE!)
`conf.sos.service.url`	URL of SOS web application
`dssos.config.file.name`	In the profiles section. Profile with id with-deploy. Sets the config file for database connection and tables. (DO NOT CHANGE!)

Save changes

Building the web application

In the following subsections we will define the capabilities skeleton and the sensor descriptions. As final step we will create the web application.

Adjust the capabilities skeleton

Navigate to the web/WEB-INF/conf/capabilities-directory of your SOS-directory. Open the capabilities_skeleton.xml file with an editor and change the following sections:
ServiceIdentification: change the title of the SOS.
ServiceProvider: change all data of the service provider.
Save your changes.
The time ranges, list of procedure Ids as well as phenomenon Ids and the whole contents section will be updated automatically by the SOS.

Provide Sensor-Descriptions

This step can be skipped if you want to use only the example sensor "Ifgi-sensor-1" which comes with the SOS installation

Create an SensorML instance document for each sensor. Refer to the SensorML specification 1.0.1 (Botts 2007) for further information on SensorML.
Store the instance documents in the web/WEB-INF/conf/sensors directory of your SOS directory.
Make sure that the names of the documents are the same as the last part of their URNs. These URNs correspond to the procedure Ids in our data model (e.g. Name the SensorML file „ifgi-sensor-1a.xml“ if the URN is „urn:ogc:def:procedure:ifgi-sensor-1a“).
The maven-script will copy the sensor descriptions to the [Tomcat Home]/webapps/[webapp.name]/WEB-INF/conf/sensors directory. If the sensor description has to be modified, change the SensorML document in the

[Tomcat Home]/webapps/[webapp.name]/WEB-INF/conf/sensors directory.

Ifgi-sensor-1.xml is an example sensor description for a simple water level station.

Deploy the web application

Make sure that your Tomcat and your Postgres are started.
Assume your main directory of your local SOS repository ist C:\SOS
Open a command line and go to the project's folder
Type the following command line expression:
- mvn -Pwith-deploy install
- if the building fails, proceed to the TroubleShooting page.
The SOS is now available.

Forth Step:Testing the SOS

This step is to perform some requests on the SOS to test if it is working properly. The GetCapabilities-Request is the only request which is possible to be sent via HTTP GET- and HTTP POST-Request. The SOS-Webclient (see below) is attached to enable POST Request to the SOS. Make sure that you have executed the file test.sql in the pgAdmin.

Capabilities-Request via HTTP GET

Open your browser. Type in http://localhost:8080/52nSOSv3/sos?REQUEST=GetCapabilities&SERVICE=SOS&ACCEPTVERSIONS=1.0.0
The capabilities response document is now shown in your browser.
You can extend the request above through appending the optional parmeters SECTIONS, ACCEPTFORMATS and UPDATESEQUENCE. Look at the SOS specification for more details.

Capabilities Request via HTTP POST

Open your Internet Browser (e.g. Mozilla Firefox). You can find the SOS Test Client under http://localhost:8080/52nSOSv3/testClient.html. (Make sure that your tomcat is running)
Open the GetCapabilities.xml file from the xml folder of your SOS directory with an editor.
Copy the content into the Request field of the SOS Test Client.

Screenshot of the SOS test client for capabilities request:

Click the „Send“-Button. The capabilities response xml-document is now shown in your browser.

Other tests

You can try the other xml request files in the xml-folder analogous to the HTTP Post based GetCapabilities request.

-- CarstenHollmann - 30 Mar 201

Sensornet

Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback