52°North SOS Tutorial for v3.x

ALERT! How to install, deploy and use the 52°North Sensor Observation Service 4.x is described here.

The installation, deployment and use of the 52°North Sensor Observation Service 3.x is described in the following sections. It depends on the current SVN trunk version (3.6.x) of the 52°North SOS. The downloadable source and binary releases (http://52north.org/downloads/sensor-web/sos 52north download page) have their own installation guides, shipped with the package.

It can be that this tutorial is not up-to-date with the current SVN trunk version of the 52°North SOS, but we are keen to keep it up-to-date.

The current 52°North SOS 3.x implements the OGC SOS implementation specification version 1.0.0 (OGC 06-009r6) and the some operations of the OGC SOS 2.0 standard (OGC 12-006 ) (both available at http://www.opengeospatial.org/standards/sos).

The 52°North SOS supports the three SOS 1.0.0 core operations GetCapabilities, GetObservation and DescribeSensor as well as the additional operations GetFeatureOfInterest, GetFeatureOfInterestTime, GetObservationById 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.

The supported operations of SOS 2.0 are GetCapabilities, GetObservation, DescribeSensor and GetFeatureOfInterest.

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 or higher: 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 or higher: Download Apache Maven from http://maven.apache.org/download.html and follow the instuructions given there.

PostgreSQL DBMS 8.4 or higher: 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/.

Installing PostreSQL and PostGIS

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 x.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 x.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

Downloading the SOS

  • You can check out the currrent sources from the SVN repository as described in the SvnSos.

Configuration of the pom.xml (optional)

  • Open the main pom.xml-file in the SOS folder and edit the properties in the <properties> section. In Table 1 all changeable properties from the pom.xml are listed.
Property Description
The following properties must (MANDATORY), can (OPTIONAL) be changed.
conf.sos.name Name of SOS, change to your preferred name (OPTIONAL)
conf.sos.buil.properties Default path and name for the build.properties file, can be set to a customized file (OPTIONAL)
project.build.sourceEncoding Source encoding during build process !!! DO NOT CHANGE !!!
n52.common.xml.version Version definition of the used 52N common XML dependenvies !!! DO NOT CHANGE !!!
  • Save changes.

Configuration of the build.properties (required)

ALERT! This section is currently not up to date. Please read the section 3.5 in the Installation guide of the sources.

  • Open the build.properties file in SOS 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 2 all changeable properties from the build.properties are listed. At the beginning of the table, you find properties you have to change (MANDATORY) or you can change (OPTIONAL).

Property Description
The following properties must (MANDATORY), can (OPTIONAL) be changed.
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).
conf.sos.service.url URL of SOS web application, change if not localhost:8080. This URL is set in the testClient. (MANDATORY)
The following properties are for advanced users
conf.sos.supported.versions Select the supported version(s)Select the supported version(s)
0 = SOS 1.0.0 and SOS 2.0 (default)
1 = only SOS 1.0.0
2 = only SOS 2.0
(ADVANCED)
conf.sos.configFile.path Path to the configuration files for extended modules with additional properties (ADVANCED)
conf.sos.configFile.map Configuration files and the file identifier (List: IDENTIFIER FILENAME;IDENTIFIER2 FILENAME2; ...) (ADVANCED)
conf.sos.enableAdminApi Enable/Disable the admin API (default true) (ADVANCED)
conf.sos.getObs.maxResults Maximum number of GetObservation results (0 or blank for unlimited) (ADVANCED)
conf.sos.response.compression.minSize Minimum size of a response which should be compressed if supported by client (default = 1048576) (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.capabilitiesCacheControler Class of capabilities cache controller (ADVANCED)
conf.sos.capabilitiesCacheUpdateIntervall Capabilities Cache Update Interval in minutes (0 = no automatic update) (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.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.10.omEncoder SOS 1.0.0 Implementation of IOMEncoder used to encode observations (has to be reimplemented, if new observation types should be supported) (ADVANCED)
conf.sos.10.gmlEncoder SOS 1.0.0 GMLEncoder implementation (implementation of IGMLEncoder) (ADVANCED)
conf.sos.10.featureEncoder SOS 1.0.0 FeatureEncoder implementation (implementation of IFeatureEncoder) (ADVANCED)
conf.sos.10.owsEncoder SOS 1.0.0 OWSEncoder implementation (implementation of IOWSEncoder) (ADVANCED)
conf.sos.10.postRequestDecoder SOS 1.0.0 HttpPostRequestDecoder implementation (implementation of IhttpPostRequestDecoder) (ADVANCED)
conf.sos.10.getRequestDecoder SOS 1.0.0 HttpGetRequestDecoder implementation (implementation of IhttpGetRequestDecoder) (ADVANCED)
conf.sos.10.requestDecoder SOS 1.0.0 RequestEncoderimplementation (implementation of IRequestEncoder) (ADVANCED)
conf.sos.10.getResponseEncoder SOS 1.0.0 ResponseEncoder implementation (implementation of IResponseEncoder) (ADVANCED)
conf.sos.10.sensorMLEncoder SOS 1.0.0 SensorMLEncoder implementation (implementation of ISensorMLEncoder) (ADVANCED)
conf.sos.10.sensorMLDecoder SOS 1.0.0 SensorMLDecoder implementation (implementation of ISensorMLDecoder) (ADVANCED)
conf.sos.showFullOperationsMetadata4Observations Property indicates, whether OperationMetadata for GetObservation in GetCapabilities response contains only property names or property names and allowed values for FeatureOfInterest, Procedure and ObservedProperty(default = true) (ADVANCED)
conf.sos.showFullOperationsMetadata Property indicates, whether OperationMetadata in GetCapabilities response contains only property names or property names and allowed values (default = true) (ADVANCED)
conf.sos.skipDuplicateObservations Property indicates whether duplicate observations should be skipped silently when inserted by batch (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.10.srs.prefix SOS 1.0.0 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.foiListedInOfferings Property indicates, whether to include list of FOI IDs in offerings (default = true) (ADVANCED)
conf.sos.childProceduresEncodedInParentsDescribeSensor Property indicates, whether the SOS encodes the complete sensor description of a child procedure in the parent procedure description (default = false) (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.capabilities.acceptformats Accepted formats for capabilities (ADVANCED)
conf.sos.capabilities.sections Allowed sections in a GetCapabilities request (ADVANCED)
conf.sos.logger.fileappender.filepath Location where the log files should be stored (OPTIONAL)
conf.sos.logger.fileappender.filename Name of the log file (OPTIONAL)
conf.sos.logger.level 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.

ERROR
WARN
INFO
DEBUG
TRACE
(OPTIONAL)
conf.sos.logger.history.max Define how many history log files should be stored (OPTIONAL)
conf.sos.supportDynamicLocation Indicator of support for dynamic locations as spatial values (default=false). (ADVANCED)
conf.sos.dynamicLocation.observableProperty Definition of the observable property for dynamic locations. Must be set if conf.sos.supportDynamicLocation=true. (ADVANCED)
conf.sos.setFoiLocationDynamically Indicator for dynamic location setting of featureOfInterest. If true, conf.sos.supportDynamicLocation=true must be true (default=false). (ADVANCED)
conf.sos.prefix.default.offering The default prefix for an auto generated offering (if not defined in RegisterSensor request) (ADVANCED)
conf.sos.prefix.default.procedure The default prefix for an auto generated procedure (if not defined in RegisterSensor request) (ADVANCED)
conf.sos.eachProcFirstLatest Indicator for the used GetFirst/GetLatest operation (default = false) (ADVANCED)
conf.sos20.om2Encoder SOS 2.0.0 Implementation of IOMEncoder used to encode observations (has to be reimplemented, if new observation types should be supported) (ADVANCED)
conf.sos20.gml321Encoder SOS 2.0.0 GMLEncoder implementation (implementation of IGMLEncoder) (ADVANCED)
conf.sos20.featureEncoder4SosV2 SOS 2.0.0 FeatureEncoder implementation (implementation of IFeatureEncoder) (ADVANCED)
conf.sos20.owsEncoder4SosV2 SOS 2.0.0 OWSEncoder implementation (implementation of IOWSEncoder) (ADVANCED)
conf.sos20.postRequestDecoder SOS 2.0.0 HttpPostRequestDecoder implementation (implementation of IhttpPostRequestDecoder) (ADVANCED)
conf.sos20.getRequestDecoder SOS 2.0.0 HttpGetRequestDecoder implementation (implementation of IhttpGetRequestDecoder) (ADVANCED)
conf.sos20.sensorMLEncoder SOS 2.0.0 SensorMLEncoder implementation (implementation of ISensorMLEncoder) (ADVANCED)
conf.sos20.srs.prefix SOS 2.0.0 prefix URN for the spatial reference system (ADVANCED)

In the following table 3 the properties for the service identification and service provider information are listed. These information are displayed in the Capabilities document.

Property Description
Serivce identification information
conf.sos.capabilities.identification.title Service title(OPTIONAL)
conf.sos.capabilities.identification.abstract Service abstract(OPTIONAL)
conf.sos.capabilities.identification.keywords Service keywords as lsit, separated by comma. Dynamically set as single keywords by the SOS.(OPTIONAL)
conf.sos.capabilities.identification.servicetype Service tpye(OPTIONAL)
conf.sos.capabilities.identification.fees Service fees(OPTIONAL)
conf.sos.capabilities.identification.accessconstrains Access constraints information(OPTIONAL)
conf.sos.serviceidentificationfile Path to the service identification file. The previous values are set in the file during the build process.(OPTIONAL)
Service provider information
conf.sos.capabilities.provider.name Provider name(OPTIONAL)
conf.sos.capabilities.provider.site Provider web page(OPTIONAL)
conf.sos.capabilities.provider.individual.name Contact person(OPTIONAL)
conf.sos.capabilities.provider.position.name Position of the contact persion(OPTIONAL)
conf.sos.capabilities.provider.phone Phone number(OPTIONAL)
conf.sos.capabilities.provider.address Address(OPTIONAL)
cconf.sos.capabilities.provider.city City(OPTIONAL)
conf.sos.capabilities.provider.zip ZIP code(OPTIONAL)
conf.sos.capabilities.provider.state State(OPTIONAL)
conf.sos.capabilities.provider.country Country(OPTIONAL)
conf.sos.capabilities.provider.email eMail address(OPTIONAL)
conf.sos.serviceproviderfile Path to the service provider file. The previous values are set in the file during the build process.(OPTIONAL)

  • 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.

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
  • LOOK OUT!
    The sensors described in the SensorML documents are not directly registered in the SOS. To register the Sensors insert your data (mainly the procedures) into the database (for the examples execute the file test.sql (SOS/db) in the pgAdmin as described in chapter 3.4) and reload the SOS (e.g. Tomcat HTML-manager).
[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.

build the web application

  • 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:
  • The SOS is build and the WAR file is located in [SOS_HOME]\52n-sos-service\target\SOS_NAME.war, e.g. C:\SOS\52n-sos-webapp\target\52n-sos-webapp.war .

Deploy the web application

  • Make sure that your Tomcat and your Postgres are started.
  • 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 the web application".
  • Click on “deploy”. The new service instance will be shown in the application list.

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

Capabilities Request via HTTP POST

  • Open your Internet Browser (e.g. Mozilla Firefox). You can find the SOS Test Client under http://localhost:8080/52n-sos-webapp/testClient.html. (Make sure that your Apache 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.

Sending Generic Requests

You can send a any requests to the SOS via HTML POST with different types of software. Some examples are:
  • the Firefox Add-on Poster
  • the software SoapUI
  • HTTP clients in the programming language of your choice, such as Java (without any libraries see here), Python or the command line using cURL
When you use a 52North SOS, you can most easily use the test client form available at http://your-server.tld/your-webapp-name/, for example http://sensorweb.demo.52north.org/52nSOSv3.2.1/, as described above.

Other tests

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

Update from older SOS version.

To update the SOS from an older release, you have to update the SOS database schema. Run the following sql scripts (located in SOS/db/changes) in PostgreSQL for you SOS database.
  • del_trigger_and_unused_offering_columns.sql
  • update_DB_for_new_valueTypes.sql
  • del_observation_offering.sql
then you can undeploy you old SOS version and deploy the new one.

-- CarstenHollmann - 30 Mar 2010
Topic revision: r43 - 09 Aug 2016 09:07:42, EikeJuerrens
This site is powered by FoswikiCopyright &© by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding Wiki? Send feedback