Fork me on GitHub

SOS 4.x Documentation



help For Information about the former 52°North implementation, SOS 3.x, please see SensorObservationService for general information and for documentation.

Build status

Jenkins:
Travis:

Introduction

Scope

This document describes the architecture and the install process of the 52°North Sensor Observation Service (SOS).

Changes compared to previous versions

The 52°North SOS 4.x is a reimplementation of the 52°North SOS. Here are the biggest changes from the previous version 3.5.x:
  • SOS API
  • new database model: uses numerical identifiers, required to match the OGC SOS 2.0.0 spec properly
  • persistence framework Hibernate and Hibernate spatial
  • Java ServiceLoader concept for binding, de-/encoder and operations
  • binding/encoding/operation: develop a new feature against the SOS API without changing the core
  • Admin GUI: change the settings, de-/activate encodings and bindings
  • Installer GUI: configure the database connection, create database model, configure the settings

Some Words on SOS

The SOS aggregates readings from live, in-situ and remote sensors. The service provides an interface to make sensors and sensor data archives accessible via an interoperable web based interface. This 52°North SOS implementation supports the OGC SOS versions 1.0.0 and 2.0.

Specification v1.0.0

Four profiles are defined within the SOS OGC Sensor Observation Service version 1.0.0 specification (Na & Priest 2007): core, transactional, enhanced, and entire. The current release implements the core profile comprising of the mandatory operations:
  • GetCapabilities, for requesting a self-description of the service .
  • GetObservation, for requesting the pure sensor data encoded in Observation&Measurements (O&M).
  • DescribeSensor, for requesting information about the sensor itself, encoded in a Sensor Model Language (SensorML) instance document.
The recent development snapshot implements also the following optional operations:
  • GetFeatureOfInterest, for requesting the GML encoded representation of the feature that is the target of the observation.
For the future it is planned to support the followin optional operations:
  • RegisterSensor, for registering new sensors.
  • InsertObservation, for inserting new observations.

Specification v2.0

The OGC SOS 2.0 specification was adopted in 2012 and four extension are defined within the specification: Core, Enhanced, Transactional, and Result Handling.

Core Extension

  • GetCapabilities, for requesting a self-description of the service.

Enhanced Extension

  • GetFeatureOfInterest, for requesting the GML 3.2.1 encoded representation of the feature that is the target of the observation.

  • GetObservaitonById, for requesting the pure sensor data for a specific observation identifier

Transactional Extension

  • InsertSensor, for publishing new sensors.

  • UpdateSensorDescription, for updating the description of a sensor

  • DeleteSensor, for deleting a sensor

  • InsertObservation, for publishing observations for registered sensors.

Result Handling Extension

  • InsertResultTemplate, for inserting a result template into a SOS server that describes the structure of the values of a InsertResult of GetResult request.

  • InsertResult, for uploading raw values accordingly to the structure and encoding defined in the InsertResultTemplate request

  • GetResultTemplate, for getting the result structure and encoding for specific parameter constellations

  • GetResult, for getting the raw data for specific parameter constellations

For more information about the SOS 2.0 specification, see the official OGC SOS 2.0 tutorial

The OGC SOS version 2.0 specification defines a core and five extensions (in SOS 1.0.0 called profiles). The current release implements these operations:

Extension Operation Description KVP SOAP POX REST JSON EXI
Core
GetCapbilities
for requesting a self-description of the service
led-green
led-green
led-green
led-green
led-green
Core
GetObservation
for requesting the pure sensor data encoded in Observation&Measurements 2.0 (O&M 2.0).
led-green
led-green
led-green
led-green
led-green
Core
DescribeSensor
for requesting information about the sensor itself, encoded in a Sensor Model Language (SensorML) instance document.
led-green
led-green
led-green
led-green
led-green
Enhanced Operations
GetFeatureOfInterest
for requesting the features hosted by this SOS instance
led-green
led-green
led-green
led-green
led-green
Enhanced Operations
GetObservationById
for requesting a single observation instance by its id
led-yellow / led-red
led-green
led-green
led-green
led-green
Result Handling
InsertResultTemplate
for inserting a result template for later easy observation retrieval
led-red
led-green
led-green
led-green
led-green
Result Handling
InsertResult
for inserting results for a before registered result template
led-red
led-green
led-green
led-green
led-green
Result Handling
GetResultTemplate
for requesting a template of the result structure returned by a GetResult request
led-green
led-green
led-green
led-green
led-green
Result Handling
GetResult
for requesting results without observation metadata and information about the result structure
led-green
led-green
led-green
led-green
led-green
Transactional
InsertSensor
for adding a new sensor
led-red
led-green
led-green
led-green
led-green
Transactional
InsertObservation
for adding a new observation
led-red
led-green
led-green
led-green
led-green
Transactional
UpdateSensorDescription
for updating the description of an already inserted sensor
led-red
led-green
led-green
led-green
led-green
Transactional
DeleteSensor
for deleting a sensor/procedure and all related offerings, observations
led-green
led-green
led-green
led-green
led-green
Data Availability
GetDataAvailability
for requesting the data availability for certain configurations (not specified in the SOS 2.0)
led-green
led-green
led-green
led-green
led-green
Delete Observation
DeleteObservation
for deleting one single observation identified by id (not specified in the SOS 2.0)
led-green
led-green
led-green
led-green
led-green

led-green = implemented led-yellow = not implemented led-red = not specified

Bindings

[A binding] describe[s] how SOS 2.0 clients and servers can communicate with each other. (OGC#12-006)
  • KVP - Key Value Pair encoding of requests via HTTP GET.
  • SOAP - SOAP based encoding of all extensions via HTTP POST.
  • POX - XML based encoding of all extensions via HTTP POST ( without SOAP wrapping).
  • REST - RESTful binding for all useful operations of resources being available in the SOS. Link to documentation.
  • JSON - JSON based encoding of all extensions via HTTP POST.
  • EXI - Efficient XML Interchange (EXI) Format 1.0 based encoding of all extensions via HTTP POST and POX encoded request. SOAP requests are currently not supported via the EXI binding.

Architecture

This image describes the basic architecture ot the 52°North SOS 4.x.
sos_architecture.png
HELP Click to enlarge.

Installation

Requirements

This tutorial is based upon the following software which have to be downloaded and installed.
  • Java runtime environment (JRE) 7.0 or higher (or JDK 7.0 or higher if you want to build the SOS from source): Download
    • ALERT! The SOS 4.0.0 release does not work with Java 8.0. Please use Java 7.0 or B1) Building from Source where Java 8.0 is supported.
  • Java Servlet-API 2.5 compatible application server. E.g.:
    • Tomcat 6 or higher: Download
      • ALERT! Do not use Tomcat versions 8.0.8, 7.0.54 and 6.0.41 because is a known bug in these releases whereby the SOS installation fails. Please use an newer Tomcat release.
    • Jetty 6 or higher Download
    • Glassfish 3 or higher Download
  • Running Database Managment System
  • Apache Maven 3 or higher (if you want to build the SOS from source): Download

Supported Database Managment System

Storage Space requirements

HELP The values presented here are experienced data. If you have any additional observations, please share them with the community using the mailing list, for example.

Definition time series: A time series is a group of observations having the following parameters in common:
  • feature of interest
  • procedure/sensor
  • observed property/observable property
  • observation type (e.g. numeric)
Requirement per observation
1,36 mio observations = 750MB
1,36 mio observations = 786432000B
1 observation = 578B

⇒ A time series with a frequency of 1 observation per minute results in a storage requirement of

578B * 60 * 24 * 365 = 303796800B (= 289MB) per year per time series.

A1) Download the SOS WAR-File

If you want to build the SOS from source you can skip this point and proceed with B1) Building from Source.

Download package including the WAR file:

Since version 4.3 of the 52°North SOS we also provide a bundle package that includes the SWC REST-API and the JavaScript SOS Client. This package has bundle in the name.

Unzip the package and browse to UNZIPPED_PACKAGE/bin/52n-sos-webapp/target where the WAR FILE is located.

B1) Building from Source

If you want to use the binary distribution of the SOS you can skip this step and proceed with 2) Installing the Webapp.

Make shure you have all required Software installed.
  • Checkout the sources directly from our subversion repository
  • change to the directory where you've just checked out the source code
  • run mvn package to build the webapp.
    • The following profiles are not included because they require dependencies which are not publicly available (licensing) and must be independently activate. See Oracle and SQL Server support
      • oracle: enable the Oracle support (see below)
      • sqlserver: enable the Microsoft SQL Server support (see below)
  • copy webapp/target/52n-sos-webapp.war to a directory of your choice
    • Or the bundle can be found in her webapp-bundle/target/52n-sos-webapp.war

Oracle support

52n SOS supports either thin (pure java) or OCI (more performant, platform specific) Oracle 11g drivers. The thin driver is easier to use for building the project.

These drivers are not freely distributable, so they have to be downloaded from Oracle's website and installed manually.

Download the latest 11.2 driver ( ojdbc6.jar) and install the jar in your local repository:
mvn install:install-file -Dfile=ojdbc6.jar -DgroupId=com.oracle -DartifactId=ojdbc6 -Dversion=11.2.0 -Dpackaging=jar

Then you can build using the Oracle profile:
mvn package -P oracle

If the Oracle driver is not installed in Maven, the build will fail.

Also, the Oracle datasource project (hibernate/datasource/oracle) is ready for some unit testing related to database connectivity. Since it requires an existing Oracle database, tests are executed only if the environment variable SOS_TEST_CONF is defined. The value of this variable must be a valid path to a Java properties file. This file must contain the following keys:
  • oracle_host: Oracle DB host
  • oracle_port: Oracle DB port
  • oracle_user: Oracle DB user. This user must have permissions to create tables and sequence and, in general, be ready to use it for the 52N SOS server successfully.
  • oracle_pass: Oracle DB pass for the previously explained user.
  • oracle_user_no_rights: Oracle DB user. This user must NOT have permissions to create tables or sequences.
  • oracle_user_no_rights: Oracle DB pass for the previously explained user.
This is a sample file:
oracle_host=localhost
oracle_port=1521
oracle_user=oracle
oracle_pass=oracle
oracle_user_no_rights=sos_test_no_rights
oracle_pass_no_rights=sos

Microsoft SQL Server support

The Microsoft SQL Server driver is not freely distributable, so it has to be downloaded from Microsoft website and installed manually.

Download the latest driver (sqljdbc4.jar) and install the jar in your local repository:

mvn install:install-file -Dfile=sqljdbc4.jar -DgroupId=com.microsoft -DartifactId=sqljdbc4 -Dversion=4.0 -Dpackaging=jar

Then you can build using the SQL Server profile:

mvn package -P sqlserver

If the Microsoft SQL Server driver is not installed in Maven, the build will fail.

C1) Building a Preconfigured Service

If you don't want the built-in installer you also can configure the SOS while building it:
  • To define the database connection settings copy conf/datasource.properties.template to conf/datasource.properties and adjust it to your needs.
    • typically only the user name/password and URL properties have to be changed. While user name and password are quite self explanatory the URL is constructed like the following: jdbc:postgresql://$HOST:$PORT/$DATABASE_NAME
  • To adjust service settings open the copy the file db/default_settings.sql and edit to your needs and recreate conf/default_settings.db (e.g sqlite3 misc/conf/default_settings.db -init misc/db/default_settings.sql).
  • To build the project run mvn package -Pconfigure-datasource,use-default-settings[,additional-profiles]
    • to choose a different file than conf/datasource.properties pass it to Maven by specifying -DdatabaseConfigurationFile=ABSOLUTE_PATH_TO_FILE at the command line
    • to choose a different file than conf/default_settings.db pass it to Maven by specifying -DsqliteSettingDatabase=ABSOLUTE_PATH_TO_FILE at the command line
    • any profile of the standard build process (see above)
  • After building the preconfigured webapp is located at webapp/target/52n-sos-webapp.war

2) Installing the Webapp

PostgreSQL installation

  • Make sure your Tomcat and PostgreSQL are running.
  • Create a new PostgreSQL database with e.g. pgAdmin3 using the PostGIS template created during the PostGIS installation.
    • (for a short tutorial see for example here)
    • ALERT!If you update your SOS from Beta1 to Beta2 it is mandatory to delete clear the old database because there are changes in the database model.ALERT!
  • 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 which you've build or downloaded in the previous step.
  • Click on “deploy”. The new service instance will be shown in the application list.
  • Click on the service instance to navigate to your newly deployed SOS.
  • Follow the steps on the screen to configure your SOS instance (you don't have to do this if you've build the preconfigured webapp). More information about the settings can be found in the Configure/Administrate the SOS section of this page.
    • If you have installed the preconfigured webapp change the administrator password using the admin GUI. The default password is password and the default user name is admin.

Oracle installation

We assume that an Oracle 11g instance is already running and accessible through the network. You can find some instructions on how to install Oracle 11g on Ubuntu 12.04 here.

1. Create an Oracle user

We need to create an Oracle user with the following configuration:
  • Connect permission
  • Create table permission
  • Create sequence permission
  • Unlimited tablespace
  • Quota unlimited on users
To create a sos user with this configuration, you can use the following sqlplus commands:
> create user sos identified by *password*;
> alter user sos identified by *password* quota unlimited on users;
> grant connect, create table, create sequence to sos;
> grant unlimited tablespace to sos;

2. Get the Oracle Instant Client (OCI)

52n SOS supports either thin (pure java) or OCI (more performant, platform specific) Oracle 11g drivers. The OCI driver is recommended for production.

Get the platform specific Oracle Instant Client ( OCI) from Oracle's website: http://www.oracle.com/technetwork/database/features/instant-client/index-097480.html

Note: If the full Oracle 11g has been installed in the same machine, the Instant Client is already there.

3. Install and configure Tomcat

We'll need Tomcat 6 or above. Download it from Tomcat's website, or use the package manager from your Operating System.
  1. Make sure that Tomcat will have access to the OCI driver files.

    • LD_LIBRARY_PATH (unix) or PATH (windows) environment variable should point to the location where Oracle Instant Client is installed.
    • The ojdbc6.jar file in this same location should be included in tomcat's classpath. For instance, make a symbolic link to it in <TOMCAT_BASE>/lib.
      • Windows since Vista with OCI installed under C:\ and Apache Tomcat 7. ALERT! You need administration rights ALERT!
        • mklink "c:\Program Files\Apache Software Foundation\Tomcat 7.0\lib\ojdbc6.jar" c:\instantclient_12_1\ojdbc6.jar
  2. Copy your 52n-sos-webapp.war file into <TOMCAT_BASE>/webapps and start the Tomcat server. For Linux instance:
    sudo service tomcat6 start
4. First run: setup SOS server

Now you have 52N SOS running in your Tomcat server. To access it, open this URL in your browser:
http://localhost:8080/52n-sos-webapp

You will find the 52N SOS home page with the following message:
You first have to complete the installation process! Click here to start it.

Click here, press Start and select Oracle Spatial from the drop-down list. A database configuration form will appear below. Fill it with your database settings. For example, for the "sos" user created above, these will be the configuration values:
  • User Name: sos
  • Password: sos
  • Database: sos
  • Host: localhost
  • Database port: 1521
  • Schema: sos
  • Database concept: Select from dropdown
    • Old concept
    • Series concept (default)
    • eReporting concept (extended Series concept)
  • Multilingualism support: Unchecked
  • Transactional profile: Checked
  • Provided JDBC drive: Checked
  • Minimum ConnectionPool size: 10
  • Maximum ConnectionPool size: 30
  • Batch size: 20
  • Create tables: Checked
  • Delete existing tables: Unchecked
  • Force updating existing tables: Unchecked
Click Next and fill the Settings. For testing purposes it is possible to simply skip this process by clicking Next again.

Finally, set a user name and a password for the 52N SOS administrator and click Install.

Microsoft SQL Server installation

We assume that an Microsoft SQL Server 2012 instance is already running and accessible through the network.

1. Create an Microsoft SQL Server user

We need to create an Microsoft SQL Server user with permissions to create a new database and to write into the new database.

2. Install and configure Tomcat

We'll need Tomcat 7 or above. Download it from Tomcat's website, or use the package manager from your Operating System.

  1. Make sure that Tomcat will have access to the Microsoft SQL Server driver files.

    • LD_LIBRARY_PATH (unix) or PATH (windows) environment variable should point to the location where Microsoft SQL Server driver is installed.
    • The sqljdbc4.jar file in this same location should be included in tomcat's classpath. For instance, make a symbolic link to it in /lib.
      • mklink "c:\Program Files\Apache Software Foundation\Tomcat 7.0\lib\sqljdbc4.jar" "C:\SqlServer\Microsoft JDBC Driver 4.0 for SQL Server\sqljdbc_4.0\enu\sqljdbc4.jar"
  2. Copy your 52n-sos-webapp.war file into /webapps and start the Tomcat server. For Linux instance:
    sudo service tomcat6 start
3. First run: setup SOS server

Now you have 52N SOS running in your Tomcat server. To access it, open this URL in your browser:

http://localhost:8080/52n-sos-webapp

You will find the 52N SOS home page with the following message:

You first have to complete the installation process! Click here to start it.

Click here, press Start and select SQL Server from the drop-down list. A database configuration form will appear below. Fill it with your database settings. For example, for the "sos" user created above, these will be the configuration values:

  • User Name: sos
  • Password: sos
  • SQL Server instance: SQLEXPRESS
  • Database: sos
  • Host: localhost
  • Database port: 1433
  • Schema: dbo
  • Database concept: Select from dropdown
    • Old concept
    • Series concept (default)
    • eReporting concept (extended Series concept)
  • Multilingualism support: Unchecked
  • Transactional profile: Checked
  • Provided JDBC drive: Checked
  • Minimum ConnectionPool size: 10
  • Maximum ConnectionPool size: 30
  • Batch size: 20
  • Create tables: Checked
  • Delete existing tables: Unchecked
  • Force updating existing tables: Unchecked
Click Next and fill the Settings. For testing purposes it is possible to simply skip this process by clicking Next again.

Finally, set a user name and a password for the 52N SOS administrator and click Install.

Configure/Administrate the SOS

This section contains only the default settings of the SOS which can be supplemented by settings of an extensions.

Installation

During the installation you can configure the SOS by changing the following setting. These settings can be changed later with the administration interface.

  • Informative settings
    • Service Provier: change the provider information (Capabilities) of this service
    • Service Identification: change the identification infomation (Capabilities) of this service.
  • other
    • Transactional Security: Simple security for transactional operations
    • Service: Service relevant settings like URL, cache update interval, ...
    • Miscellaneous: Not assignable settings like separators, exception output
    • CRS: Default EPSG codes, axis order of the stored geometries, supports the datasource spatial queries.
    • RESTful Binding: Configure the RESTful binding
    • Procedure Description: Automatic procedure description generation and enrichment, e.g. featureOfInterest, discovery profile
    • EXI Bindind: Configure the EXI binding
    • Streaming: En-/disable XML response and/or datasource streaming
    • eReporting: Define prefixes, global namespace for AQD e-Reporting support
    • FlexibleIdentifier: En-/disable flexible identifier
    • I18N: Multilingualism defintion
    • INSPIRE: Define metadata for SOS as INSPIRE download service

Administration

With the SOS administration interface you can change the settings you've made during the installation and you can make additional settings, e.g. logging configuration, supported bindings. To access the administration interface go to [SOS_URL]/admin, e.g. http://localhost:8080/52n-sos-webapp/admin.

On the administration interface start page you can perform a reloading of the Capabilities cache (internal cache) or select the folloing submenues:
  • Datasource Maintenance: Get some raw SQL queries, clear the database or delete deleted observaitions (marked by DeleteObservation operation)
  • Cache summary: Get some statistics about the internal cache, e.g. number of procedure or temporal and spatial bboxes.
  • Reset: Resets the datasource configuration.
  • Settings: Change the settings you have made during the installation process.
The Settings submenue contains further submenues which are briefly explained:
  • Logging: Change the log level or show the latest log statements
  • Operations: En-/Disable supported operations
  • Encodings: En-/Disable supported encodings for observations and procedures
  • Bindings: En-/Disable supported bindigs, see Bindings above
  • Extensions: En-/Disable supported extensions for ExtendedCapabilities or Offering extensions, e.g. see the INSPIRE
  • Datasource: See the datasource configuration
  • Procedure Descriptions: Change or delete procedure descriptions
  • Capabilities Settings: Add/Change/remove static Capabilities, Capabilities and Offering extensions.
  • Observable Properties: Rename ObservableProperties.
  • I18N Settings: Create/Update/Delete multilingual data, see Multilingual support

Detailed information about the administration interface: SensorObservationServiceIVAdministratorInterface

Transactional operations

To avoid the unwanted manipulation of SOS data via the transactional operations in the default 52°North SOS, we have disabled the transactional operations and enabled the Transactional Security by default since 52°North SOS 4.2.

This affects the following operations:
  • InsertSensor
  • InsertObservation
  • InsertResultTemplate
  • InsertResult
  • UpdateSensorDescription
  • DeleteSensor
  • DeleteObservation

The transactional operations can be enabled via the admin GUI of the 52°North SOS. Go to the Operations submenue of the Admin -> Settings in the 52°North SOS web interface.

The Transactional Security is enabled by default and the Transactional allowed IPs is set to _127.0.0.1.

Updating the SOS

Save the settings

The 52°North SOS 4.x offers the possibility to export the settings.
  • Open a browser and enter the 52°North SOS 4.x URL, e.g. http://localhost:8080/52n-sos-webapp
  • Click the Admin tab and enter username and password
  • Move to the Admin tab and select Settings
  • Click the Export Settings button
  • A new browser tab opens with the JSON encoded settings, if the browser supports JSON files
  • Save the JSON file.
NOTE: The database settings are currently not exported. But there are plans to add this in the future.

Undeploy the old instance

There are two ways to undeploy the old instance:
  1. Via the Apache Tomcat HTML Manager by selecting undeploy
  2. Stopping the Aache Tomcat Server and delete the war file and the folder from [TOMCAT_HOME]/webapps

Deploy the new instance

Deploy the 52°North SOS 4.x war file as described in the Installation section.

On the installation page with the title 52°North SOS Installation Wizard you can find at the bottom the heading Upload a previous configuration file.

Here you can select the previously exported settings file to import the settings into the new instance.

Force updating existing tables - checkbox

The Force updating existing tables is an experimental functionality to update the exiting database model if needed. If this chekbox is selected, the 52°North SOS 4.x updates the database model during the installtion process.

There are also update scripts for the supported DBMS (PostgreSQL, Oracle, MySQL) available. These scripts are located in /misc/db/[DBMS]/[CONCEPT] of the sources.

We recommend to use the provided update scripts!

Changed Observation database model

HELP Since SVN revision 22188 the default observation concept/database model has been changed!

The new default observation concept/database model is the series concept which means that the featureOfInterest, procedure and observableProperty references have moved from the observation table to a series table and the series table is referenced in the observation table.

The old observation concept/database model is still supported by the 52°North SOS 4.x and can be selected during the installtion process by checking the Old observation concept checkbox.

There are also SQL scripts for PostgreSQL, Oracle and MySQL available to convert the old database model to the new series database model.

Database model changes from 4.0 to 4.1

Since the 52°North SOS 4.0 release have the following changes occurred:
  • The series table was extended with additional columns to integrate the REST-API in the future.
  • The procedure table was extended with an additional column to integrate the REST-API in the future.
  • The spatialFilteringProfile table was deleted and instead a samplingGeometry column was added to the observation table.
You can find an update script for these changes in /misc/db/[DBMS]/[CONCEPT] of the sources.

The update_spatialfilteringprofile_handling.sql script in /misc/db/[DBMS] copies the geometries from the spatialFilteringProfile table to the samplingGeometry column in the observation table and then deletes the spatialFilteringProfile table.

Database model changes from 4.1 to 4.2

Since the 52°North SOS 4.1 release have the following changes occurred:
  • The numericvalue.value, series.firstnumericvalue and series.lastnumericvalue types have been changed from BigDecimal to double.
  • The series table was extended with additional column published
    • Series with published = false are not returned in GetDataAvalability and GetObservations responses.
  • The tables observation, offering, procedure, observableproperty, and featureofinterest have been unified to support the multilingualism. The following columns have been unified:
    • identifier: unique identifier, used as request parameter
    • codespace: codespace of the identifier
    • name: object name
    • codespacename: codespace of the name
    • description: object description
  • The tables i18noffering, i18nprocedure, i18nobservableproperty, and i18nfeatureofinterest have been added to support multilingualism.

Due to the changes of the column types and the renaming of some columns the automatic database model update functionality of the installation wizard does not work. Hence we recommend to run the provides update scripts according to the used DBMS and the used database model/concept. The update scripts contain the string update_41_to_42.sql and can be found in /misc/db/[DBMS].

Operations

DescribeSensor

The DescribeSensor operation is defined in subclause 11 of the SWE Service Model Implementation Standard (OGC 09-001) and describes two mandatory parameter ( procedure, procedureDescriptionFormat) and the optional validTime parameter which is now supported by the 52°North SOS 4.o.o. This parameter allows to query all sensor descriptions for a procedure in the requested format which are valid at the requested time (TimeInstant) or in the requested period of time (TimePeriod). The response contains all valid sensor descriptions with the respective validity period or no sensor description if the requested validTime do not match. Here are some examples for the supported validTime.

For more details about the temporal relationships between validTime and exiting sensor descriptions read the subclause 11.1 of the SWE Service Model Implementation Standard (OGC 09-001). All possible cases, such as a query interval overlapping the valid time interval, or merely touching the valid time interval of a sensors, are covered in the specification.

How can you create sensor descriptions for a specific period of time?

The SWE service model defines quite complex rules how to handle sensor description updates with respect to the validTime contained in the updated sensor descriptions (see requirements 38 to 42). For the sake of simplicity we implemented only the behaviour of requirement 43 so far: if a sensor description is updated at point in time t1 then the validTime interval of the existing sensor description is updated to end at t1, and the new sensor description is valid from t1 on.

If an update sensor operation does contain a validTime element then the service currently throws and exception.

TimeInstant

The first example returns all sensor descriptions that match the specific date.

    1	<swes:validTime>
    2	    <gml:TimeInstant gml:id="validTime">
    3	        <gml:timePosition>2013-08-14T15:02:43.219</gml:timePosition>
    4	    </gml:TimeInstant>
    5	</swes:validTime>

The second example returns all sensor descriptions that are valid after the specific date, but several relative operators are possible. Valid indeterminatePosition values are:
  • after
  • before
  • now
  • unknow

    1	<swes:validTime>
    2	    <gml:TimeInstant gml:id="validTime">
    3	        <gml:timePosition indeterminatePosition="after">2013-08-14T15:00:00</gml:timePosition>
    4	    </gml:TimeInstant>
    5	</swes:validTime>

TimePeriod

This example returns all sensor descrptions that match the specific period of time.

    1	<swes:validTime>
    2	    <gml:TimePeriod gml:id="validTime">
    3	        <gml:beginPosition>2013-08-14T15:02:43.219</gml:beginPosition>
    4	        <gml:endPosition>2013-08-14t15:02:47</gml:endPosition>
    5	    </gml:TimePeriod>
    6	</swes:validTime>

GetObservation

The GetObservation operations supports the Spatial Filtering Profile

TemporalFilter

An O&M observation contains different time information like the phenomenonTime and the resultTime. To limit the time range of the returned observations, you can define temporalt filters in the GetObservation request. The SOS 2.0 specification defines as minimum requirement the support of the following two filters:
  • During with a time period
  • TEquals with a time instant
With the temporal filter valueReference you define the time information the filter should be apply to. But you can define more than one filter and in a request and how are they applied?

In the following matrix it is described how the filters are combined:

valueReference phenomenonTime resultTime
phenomenonTime
OR
AND
resultTime
AND
OR

GetResult

The GetResult operations supports the Spatial Filtering Profile

GetDataAvailability

The GetDataAvailability operation is defined in the OGC Discussion Paper: OGC Sensor Observation Service 2.0 Hydrology Profile

The current XML schema of this operation can be found here: http://waterml2.org/schemas/gda/1.0/gda.xsd

Optional count value

The optional count value in the response can be activated in two ways:
  • default activation via settings
    • You can find the "Should the SOS include value count in GetDataAvailability response?" in the Miscellaneous tab.
  • activation via the request in the swes:extension section:
    1	<swes:extension>
    2	    <swe:Boolean definition="ShowCount">
    3	        <swe:value>true</swe:value>
    4	    </swe:Boolean>
    5	</swes:extension>

Extended ResultTimes

The SOS supports the inclusion of the valid result times for each timeseries in the GetDataAvailability response. The result times are inlcuded in the gda:extension section as shown below:
    1	<gda:extension>
    2	        <swe:DataRecord definition="resultTime">
    3	                <swe:field name="resultTime14">
    4	                        <swe:Time>
    5	                                <swe:value>2010-03-25T00:00:00.000Z</swe:value>
    6	                                <swe:uom xlink:href="http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"/>
    7	                        </swe:Time>
    8	                </swe:field>
    9	                <swe:field name="resultTime15">
   10	                        <swe:Time>
   11	                                <swe:value>2010-03-25T06:00:00.000Z</swe:value>
   12	                                <swe:uom xlink:href="http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"/>
   13	                        </swe:Time>
   14	                </swe:field>
   15	                <swe:field name="resultTime16">
   16	                        <swe:Time>
   17	                                <swe:value>2010-03-25T12:00:00.000Z</swe:value>
   18	                                <swe:uom xlink:href="http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"/>
   19	                        </swe:Time>
   20	                </swe:field>
   21	                <swe:field name="resultTime17">
   22	                        <swe:Time>
   23	                                <swe:value>2010-03-25T18:00:00.000Z</swe:value>
   24	                                <swe:uom xlink:href="http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"/>
   25	                        </swe:Time>
   26	                </swe:field>
   27	                <swe:field name="resultTime18">
   28	                        <swe:Time>
   29	                                <swe:value>2010-03-26T00:00:00.000Z</swe:value>
   30	                                <swe:uom xlink:href="http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"/>
   31	                        </swe:Time>
   32	                </swe:field>
   33	        </swe:DataRecord>
   34	</gda:extension>

To activate the addition of the result times you can add the following to options to the swes:extension of the request:
  • add the flag
    1	<swes:extension>
    2	        <swe:Boolean definition="IncludeResultTimes">
    3	            <swe:value>true</swe:value>
    4	    </swe:Boolean>
    5	</swes:extension>
  • add a temporal filter for valueReference phenomenonTime to get the valid result times that match this filer
    1	<swes:extension>
    2	        <fes:During>
    3	                <fes:ValueReference>resultTime</fes:ValueReference>
    4	                <gml:TimePeriod gml:id="tp_1">
    5	                        <gml:beginPosition>2010-03-25T00:00:00.000Z</gml:beginPosition>
    6	                        <gml:endPosition>2010-03-27T00:00:00.000Z</gml:endPosition>
    7	                </gml:TimePeriod>
    8	        </fes:During>
    9	</swes:extension>

Features

Date and Time handling

Database

We have implemented the UtcTimestampType and UtcTimestampTypeDescriptor which forces all Timestamps queried from/inserted to the database to use UTC instead of the JVM's timezone.

Insert requests

Timestamps in insertion requests without a timezone are processed by the 52°North SOS as UTC times. This is not conform to ISO 8601 which defines that timestamps without timezone are in the local/system time.

Therefore, we recommend to use only timestamps with timezone to avoid problems.

Supported ProcedureDescriptionFormats

This sections describes the supported ProcedureDescriptionFormats for insertion and requesting.

Insertion

The supported ProcedureDescriptionFormats for InsertSensor and UpdateSensorDescription are:

URL MimeType
text/xml;subtype="sensorML/1.0.1"
text/xml;subtype="sensorml/2.0"

Requesting

Requesting means that the procedure description is stored as XML string in the database, as XML file or will be generated.

URL MimeType
text/xml;subtype="sensorML/1.0.1"
text/xml;subtype="sensorml/2.0"
-

Converting

The converting allows to convert a procedure description from one format to another format. This feature is used if the requested procedure is stored in another format as the requested format. If no converter is available, an exception will be thrown.

In the followin table you can find a list of the supported conversions.

from\to
-
led-green
led-green
led-green
-
led-red
led-red
led-red
-

led-green = supported led-red = not yet supported

Profiling

Profiling means that you can define the default behaviour of the SOS. For example, the default responseFormat if it is not requested or if the featureOfInterests should be encoded in the observations or only referenced.

A detailed description of this feature can be found here.

Features

The feature can be handled in different ways in the SOS. They can be
  • A contained hosted on the same service
  • B linked/referenced
    • B.1 internal hosted on the same service
    • B.2 external hosted by another service
You can register a feature only indirect using an InsertObservation request. Depending on the option you choose, the feature needs to be encoded in different ways in the request.

An example for option A:
    1	<sos:InsertObservation service="SOS" version="2.0.0"
    2	            xmlns:sos="http://www.opengis.net/sos/2.0"
    3	            xmlns:swe="http://www.opengis.net/swe/2.0"
    4	            xmlns:sml="http://www.opengis.net/sensorML/1.0.1"
    5	            xmlns:gml="http://www.opengis.net/gml/3.2"
    6	            xmlns:xlink="http://www.w3.org/1999/xlink"
    7	            xmlns:om="http://www.opengis.net/om/2.0"
    8	            xmlns:sams="http://www.opengis.net/samplingSpatial/2.0"
    9	            xmlns:sf="http://www.opengis.net/sampling/2.0">
   10	 <sos:offering>http://www.52north.org/test/offering/9</sos:offering>
   11	 <sos:observation>
   12	 <om:OM_Observation gml:id="o1">
   13	 [...]
   14	 <om:featureOfInterest>
   15	 <sams:SF_SpatialSamplingFeature gml:id="ssf_test_feature_9">
   16	 <gml:identifier codeSpace="">http://www.52north.org/test/featureOfInterest/9</gml:identifier>
   17	 <gml:name>52&#176;North</gml:name>
   18	 <sf:type xlink:href="http://www.opengis.net/def/samplingFeatureType/OGC-OM/2.0/SF_SamplingPoint"/>
   19	 <sf:sampledFeature xlink:href="http://www.52north.org/test/featureOfInterest/1"/>
   20	 <sams:shape>
   21	 <gml:Point gml:id="test_feature_9">
   22	 <gml:pos srsName="http://www.opengis.net/def/crs/EPSG/0/4326">51.9 7.6</gml:pos>
   23	 </gml:Point>
   24	 </sams:shape>
   25	 </sams:SF_SpatialSamplingFeature>
   26	 </om:featureOfInterest>
   27	 [...]
   28	 </om:OM_Observation>
   29	 </sos:observation>
   30	</sos:InsertObservation>

Already hosted features can be easily referenced (IDEA! This reduces the amount of data being transmitted). See the next example showing how to reference an feature ( B.1 internal hosted on the same service) using the feature id from an previous InsertObservation request:
    1	<sos:InsertObservation service="SOS" version="2.0.0" [...]>
    2	 <sos:offering>http://www.52north.org/test/offering/9</sos:offering>
    3	 <sos:observation>
    4	 <om:OM_Observation gml:id="o1">
    5	 [...]
    6	 <om:featureOfInterest xlink:href="http://www.52north.org/test/featureOfInterest/9" />
    7	 [...]
    8	 </om:OM_Observation>
    9	 </sos:observation>
   10	</sos:InsertObservation>

Example showing B.2 external hosted by another service:
    1	<sos:InsertObservation service="SOS" version="2.0.0" [...]>
    2	 <sos:offering>http://www.52north.org/test/offering/9</sos:offering>
    3	 <sos:observation>
    4	 <om:OM_Observation gml:id="o1">
    5	 [...]
    6	 <om:featureOfInterest xlink:href="http://example.com/wfs?service=WFS&amp;version=1.1.0
    7	                                                                             &amp;request=GetFeature&amp;typename=ns:Lakes
    8	                                                                             &amp;NAMESPACE=xmlns%28ns=http://dict.example.com/features%29&amp;featureid=9" />
    9	 [...]
   10	 </om:OM_Observation>
   11	 </sos:observation>
   12	</sos:InsertObservation>

The href for the referenced feature must be URL encoded.

A related feature is "[a] feature that is directly or indirectly observed/observable by the procedure; can be any feature which the requestor thinks the procedure can make valuable observations for" (Source: OGC#09-001).

The current implementation supports related features as references or instances. A related feature can be used in the context of the following operations:
  • InsertSensor with relatedFeature as href or instance
  • InsertObservation with relatedFeature as sampledFeature in featureOfInterest
  • GetObservation with relatedFeature as featureOfInterest filter value returning all observations that have relatedFeature as sampledFeature
  • GetFeatureOfInterest with relatedFeature as featureOfInterst filter value returning all feature that have relatedFeature as sampledFeature and the instance ← if used in InsertSensor
The request sequence could be the following:
  1. InsertSensor - Insert the procedure at the SOS with a list of related features.
  2. InsertObservation - Insert observations sampling one of the related features.
  3. GetObservation - Request all observations that are sampling one of the related features but having different features of interest.
  4. GetFeatureOfInterest - Request all features that sample one of the related features.
The following request exampled are reduced in length and therefor not directly working. They highlight the currently supported encoding of related features.

InsertSensor
    1	<!--?xml version="1.0" encoding="UTF-8"?--> http://www.opengis.net/sensorML/1.0.1 [...] [...] <!-- This FeatureRelationship shows how to encode the related feature as instance setting the sampledFeature to unknown --> http://example.com/relationships/observedArea http://www.52north.org/test/features/companies/52north 52&#176;North 51.935101100104916 7.651968812254194 <!-- This FeatureRelationship shows how to encode the related feature as reference --> http://example.com/relationships/observedArea [...] 
</sticky>

InsertObservation
    1	<!--?xml version="1.0" encoding="UTF-8"?--> http://www.52north.org/test/offering/9 2012-07-31T17:45:15.000+00:00 http://www.52north.org/test/featureOfInterest/9 52&#176;North <!-- this one references the related feature instance --> <!-- this one references the related feature reference --> <!-- <sf:sampledFeature xlink:href="http://www.52north.org/test/wfs?service=WFS&version=1.1.0&request=GetFeature&typename=ns:Lakes&NAMESPACE=xmlns%28ns=http://dict.example.com/features%29&featureid=9"/> --> 61.935101100104916 17.651968812254194 0.28 
</sticky>

GetObservation
    1	<!--?xml version="1.0" encoding="UTF-8"?--> <!-- <sos:featureOfInterest>http://www.52north.org/test/wfs?service=WFS&version=1.1.0&request=GetFeature&typename=ns:Lakes&NAMESPACE=xmlns%28ns=http://dict.example.com/features%29&featureid=9</sos:featureOfInterest> --> http://www.52north.org/test/features/companies/52north 
</sticky>

GetFeatureOfInterest
    1	<!--?xml version="1.0" encoding="UTF-8"?--> <!-- <sos:featureOfInterest>http://www.52north.org/test/wfs?service=WFS&version=1.1.0&request=GetFeature&typename=ns:Lakes&NAMESPACE=xmlns%28ns=http://dict.example.com/features%29&featureid=9</sos:featureOfInterest> --> http://www.52north.org/test/features/companies/52north 
</sticky>

Procedures

The SOS supports several reserved elements within the procedure description. With theses elements it is possible to provide faster and better access to observations and procedures. Some of the elements are used during procedure insertion, procedure retrieval, or both.

For more information about Procedure elements.

Procedure Descriptions

Since version 4.0, the SensorObservationService contains a feature to generate a generic but valid and usable procedure description and to enrich procedure descriptions with information used for sensor discovery.

For more information about Procedure descriptions.

Hierarchical Procedure

The hierarchical procedure feature offers the possibility to register and query not just individual single sensors but sensor networks.

For more information about Hierarchical Procedure.

NEW Procedure type support

Available since version: 4.4.0

The SOS supports the insertion and querying of procedure types. By 'type' a procedure is meant for which no observation can be inserted and which provides general information for procedure instances, procedures with observations.

For more information about Procedure type and instance.

Request Extensions

GetObservation

MergeObservationsIntoDataArray

The extension MergeObservationsIntoDataArray forces the SOS to merge all observations resulting from a GetObservation call. In detail, only observations which share the same constellation (having the same procedure, feature of interest, and observable property) are merged into a SweArrayObservation. This request extension can be used via the POX, SOAP, and KVP binding using specification version 2.0.0. The following examples show the difference of using the extension, or not.

Example KVP request
HELP Not URL encoded!
http://localhost:8080/sos-4.0/sos/kvp?service=SOS&version=2.0.0&request=GetObservation&MergeObservationsIntoDataArray=true&procedure=http://www.52north.org/test/procedure/8

Example Result
    1	<?xml version="1.0" encoding="UTF-8"?>
    2	<sos:GetObservationResponse [...]>
    3	  <sos:observationData>
    4	    <om:OM_Observation gml:id="o_1373376363586">
    5	      <om:type xlink:href="http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_SWEArrayObservation"/>
    6	      <om:phenomenonTime>
    7	        <gml:TimePeriod gml:id="phenomenonTime_1">
    8	          <gml:beginPosition>2012-11-19T14:00:00.000Z</gml:beginPosition>
    9	          <gml:endPosition>2012-11-19T14:09:00.000Z</gml:endPosition>
   10	        </gml:TimePeriod>
   11	      </om:phenomenonTime>
   12	      <om:resultTime>
   13	        <gml:TimeInstant gml:id="ti_F01129631ED34CE9FFAD3BA90C90F31AC11A8C99">
   14	          <gml:timePosition>2012-11-19T14:08:00.000Z</gml:timePosition>
   15	        </gml:TimeInstant>
   16	      </om:resultTime>
   17	      <om:procedure xlink:href="http://www.52north.org/test/procedure/8"/>
   18	      <om:observedProperty xlink:href="http://www.52north.org/test/observableProperty/8"/>
   19	      <om:featureOfInterest>
   20	        <sams:SFSpatialSamplingFeature xmlns:sams="http://www.opengis.net/samplingSpatial/2.0" xmlns:sf="http://www.opengis.net/sampling/2.0" gml:id="ssf_4778EDB2FC47A8593A5903CD1D2126B3C306E39B">
   21	          <gml:identifier codeSpace="">http://www.52north.org/test/featureOfInterest/8</gml:identifier>
   22	          <gml:name>DLZ-IT</gml:name>
   23	          <sf:type xlink:href="http://www.opengis.net/def/samplingFeatureType/OGC-OM/2.0/SF_SamplingPoint"/>
   24	          <sf:sampledFeature xlink:href="http://www.opengis.net/def/nil/OGC/0/unknown"/>
   25	          <sams:shape>
   26	            <gml:Point gml:id="pSsf_test_8">
   27	              <gml:pos srsName="http://www.opengis.net/def/crs/EPSG/0/4326">50.68606 10.94306000000006</gml:pos>
   28	            </gml:Point>
   29	          </sams:shape>
   30	        </sams:SFSpatialSamplingFeature>
   31	      </om:featureOfInterest>
   32	      <om:result xmlns:ns="http://www.opengis.net/swe/2.0" xsi:type="ns:DataArrayPropertyType">
   33	        <ns:DataArray>
   34	          <ns:elementCount>
   35	            <ns:Count>
   36	              <ns:value>10</ns:value>
   37	            </ns:Count>
   38	          </ns:elementCount>
   39	          <ns:elementType name="Components">
   40	            <ns:DataRecord>
   41	              <ns:field name="phenomenonTime">
   42	                <ns:Time definition="http://www.opengis.net/def/property/OGC/0/PhenomenonTime">
   43	                  <ns:uom xlink:href="http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"/>
   44	                </ns:Time>
   45	              </ns:field>
   46	              <ns:field name="http___www.52north.org_test_observableProperty_8">
   47	                <ns:Quantity definition="http://www.52north.org/test/observableProperty/8">
   48	                  <ns:uom code="test_unit_8"/>
   49	                </ns:Quantity>
   50	              </ns:field>
   51	            </ns:DataRecord>
   52	          </ns:elementType>
   53	          <ns:encoding>
   54	            <ns:TextEncoding blockSeparator=";" tokenSeparator=","/>
   55	          </ns:encoding>
   56	          <ns:values>
   57	            2012-11-19T14:00:00.000Z,1.20;2012-11-19T14:01:00.000Z,1.30;
   58	            2012-11-19T14:02:00.000Z,1.40;2012-11-19T14:03:00.000Z,1.50;
   59	            2012-11-19T14:04:00.000Z,1.60;2012-11-19T14:05:00.000Z,1.70;
   60	            2012-11-19T14:06:00.000Z,1.80;2012-11-19T14:07:00.000Z,1.90;
   61	            2012-11-19T14:08:00.000Z,2.00;2012-11-19T14:09:00.000Z,2.10
   62	           </ns:values>
   63	        </ns:DataArray>
   64	      </om:result>
   65	    </om:OM_Observation>
   66	  </sos:observationData>
   67	</sos:GetObservationResponse>

Example Result without merging
    1	<?xml version="1.0" encoding="UTF-8"?>
    2	<sos:GetObservationResponse [...]>
    3	  <sos:observationData>
    4	    <om:OM_Observation gml:id="o_1373376475717">
    5	      <om:type xlink:href="http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement"/>
    6	      <om:phenomenonTime>
    7	        <gml:TimeInstant gml:id="phenomenonTime_706">
    8	          <gml:timePosition>2012-11-19T14:05:00.000Z</gml:timePosition>
    9	        </gml:TimeInstant>
   10	      </om:phenomenonTime>
   11	      <om:resultTime xlink:href="#phenomenonTime_706"/>
   12	      <om:procedure xlink:href="http://www.52north.org/test/procedure/8"/>
   13	      <om:observedProperty xlink:href="http://www.52north.org/test/observableProperty/8"/>
   14	      <om:featureOfInterest>
   15	        <sams:SFSpatialSamplingFeature xmlns:sams="http://www.opengis.net/samplingSpatial/2.0" xmlns:sf="http://www.opengis.net/sampling/2.0" gml:id="ssf_14726DD6A045EC84DDB7C4041FE9FFD839C16472">
   16	          <gml:identifier codeSpace="">http://www.52north.org/test/featureOfInterest/8</gml:identifier>
   17	          <gml:name>DLZ-IT</gml:name>
   18	          <sf:type xlink:href="http://www.opengis.net/def/samplingFeatureType/OGC-OM/2.0/SF_SamplingPoint"/>
   19	          <sf:sampledFeature xlink:href="http://www.opengis.net/def/nil/OGC/0/unknown"/>
   20	          <sams:shape>
   21	            <gml:Point gml:id="pSsf_test_8">
   22	              <gml:pos srsName="http://www.opengis.net/def/crs/EPSG/0/4326">50.68606 10.94306000000006</gml:pos>
   23	            </gml:Point>
   24	          </sams:shape>
   25	        </sams:SFSpatialSamplingFeature>
   26	      </om:featureOfInterest>
   27	      <om:result xmlns:ns="http://www.opengis.net/gml/3.2" uom="test_unit_8" xsi:type="ns:MeasureType">1.7</om:result>
   28	    </om:OM_Observation>
   29	  </sos:observationData>
   30	  <sos:observationData>
   31	    <om:OM_Observation gml:id="o_1373376475736">
   32	      <om:type xlink:href="http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement"/>
   33	      <om:phenomenonTime>
   34	        <gml:TimeInstant gml:id="phenomenonTime_708">
   35	          <gml:timePosition>2012-11-19T14:07:00.000Z</gml:timePosition>
   36	        </gml:TimeInstant>
   37	      </om:phenomenonTime>
   38	      <om:resultTime xlink:href="#phenomenonTime_708"/>
   39	      <om:procedure xlink:href="http://www.52north.org/test/procedure/8"/>
   40	      <om:observedProperty xlink:href="http://www.52north.org/test/observableProperty/8"/>
   41	      <om:featureOfInterest xlink:href="#ssf_14726DD6A045EC84DDB7C4041FE9FFD839C16472"/>
   42	      <om:result xmlns:ns="http://www.opengis.net/gml/3.2" uom="test_unit_8" xsi:type="ns:MeasureType">1.9</om:result>
   43	    </om:OM_Observation>
   44	  </sos:observationData>
   45	  <sos:observationData>
   46	    <om:OM_Observation gml:id="o_1373376475748">
   47	      <om:type xlink:href="http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement"/>
   48	      <om:phenomenonTime>
   49	        <gml:TimeInstant gml:id="phenomenonTime_701">
   50	          <gml:timePosition>2012-11-19T14:00:00.000Z</gml:timePosition>
   51	        </gml:TimeInstant>
   52	      </om:phenomenonTime>
   53	      <om:resultTime xlink:href="#phenomenonTime_701"/>
   54	      <om:procedure xlink:href="http://www.52north.org/test/procedure/8"/>
   55	      <om:observedProperty xlink:href="http://www.52north.org/test/observableProperty/8"/>
   56	      <om:featureOfInterest xlink:href="#ssf_14726DD6A045EC84DDB7C4041FE9FFD839C16472"/>
   57	      <om:result xmlns:ns="http://www.opengis.net/gml/3.2" uom="test_unit_8" xsi:type="ns:MeasureType">1.2</om:result>
   58	    </om:OM_Observation>
   59	  </sos:observationData>
   60	  <sos:observationData>
   61	    <om:OM_Observation gml:id="o_1373376475750">
   62	      <om:type xlink:href="http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement"/>
   63	      <om:phenomenonTime>
   64	        <gml:TimeInstant gml:id="phenomenonTime_707">
   65	          <gml:timePosition>2012-11-19T14:06:00.000Z</gml:timePosition>
   66	        </gml:TimeInstant>
   67	      </om:phenomenonTime>
   68	      <om:resultTime xlink:href="#phenomenonTime_707"/>
   69	      <om:procedure xlink:href="http://www.52north.org/test/procedure/8"/>
   70	      <om:observedProperty xlink:href="http://www.52north.org/test/observableProperty/8"/>
   71	      <om:featureOfInterest xlink:href="#ssf_14726DD6A045EC84DDB7C4041FE9FFD839C16472"/>
   72	      <om:result xmlns:ns="http://www.opengis.net/gml/3.2" uom="test_unit_8" xsi:type="ns:MeasureType">1.8</om:result>
   73	    </om:OM_Observation>
   74	  </sos:observationData>
   75	  <sos:observationData>
   76	    <om:OM_Observation gml:id="o_1373376475752">
   77	      <om:type xlink:href="http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement"/>
   78	      <om:phenomenonTime>
   79	        <gml:TimeInstant gml:id="phenomenonTime_705">
   80	          <gml:timePosition>2012-11-19T14:04:00.000Z</gml:timePosition>
   81	        </gml:TimeInstant>
   82	      </om:phenomenonTime>
   83	      <om:resultTime xlink:href="#phenomenonTime_705"/>
   84	      <om:procedure xlink:href="http://www.52north.org/test/procedure/8"/>
   85	      <om:observedProperty xlink:href="http://www.52north.org/test/observableProperty/8"/>
   86	      <om:featureOfInterest xlink:href="#ssf_14726DD6A045EC84DDB7C4041FE9FFD839C16472"/>
   87	      <om:result xmlns:ns="http://www.opengis.net/gml/3.2" uom="test_unit_8" xsi:type="ns:MeasureType">1.6</om:result>
   88	    </om:OM_Observation>
   89	  </sos:observationData>
   90	  <sos:observationData>
   91	    <om:OM_Observation gml:id="o_1373376475753">
   92	      <om:type xlink:href="http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement"/>
   93	      <om:phenomenonTime>
   94	        <gml:TimeInstant gml:id="phenomenonTime_709">
   95	          <gml:timePosition>2012-11-19T14:08:00.000Z</gml:timePosition>
   96	        </gml:TimeInstant>
   97	      </om:phenomenonTime>
   98	      <om:resultTime xlink:href="#phenomenonTime_709"/>
   99	      <om:procedure xlink:href="http://www.52north.org/test/procedure/8"/>
  100	      <om:observedProperty xlink:href="http://www.52north.org/test/observableProperty/8"/>
  101	      <om:featureOfInterest xlink:href="#ssf_14726DD6A045EC84DDB7C4041FE9FFD839C16472"/>
  102	      <om:result xmlns:ns="http://www.opengis.net/gml/3.2" uom="test_unit_8" xsi:type="ns:MeasureType">2.0</om:result>
  103	    </om:OM_Observation>
  104	  </sos:observationData>
  105	  <sos:observationData>
  106	    <om:OM_Observation gml:id="o_1373376475755">
  107	      <om:type xlink:href="http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement"/>
  108	      <om:phenomenonTime>
  109	        <gml:TimeInstant gml:id="phenomenonTime_704">
  110	          <gml:timePosition>2012-11-19T14:03:00.000Z</gml:timePosition>
  111	        </gml:TimeInstant>
  112	      </om:phenomenonTime>
  113	      <om:resultTime xlink:href="#phenomenonTime_704"/>
  114	      <om:procedure xlink:href="http://www.52north.org/test/procedure/8"/>
  115	      <om:observedProperty xlink:href="http://www.52north.org/test/observableProperty/8"/>
  116	      <om:featureOfInterest xlink:href="#ssf_14726DD6A045EC84DDB7C4041FE9FFD839C16472"/>
  117	      <om:result xmlns:ns="http://www.opengis.net/gml/3.2" uom="test_unit_8" xsi:type="ns:MeasureType">1.5</om:result>
  118	    </om:OM_Observation>
  119	  </sos:observationData>
  120	  <sos:observationData>
  121	    <om:OM_Observation gml:id="o_1373376475756">
  122	      <om:type xlink:href="http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement"/>
  123	      <om:phenomenonTime>
  124	        <gml:TimeInstant gml:id="phenomenonTime_702">
  125	          <gml:timePosition>2012-11-19T14:01:00.000Z</gml:timePosition>
  126	        </gml:TimeInstant>
  127	      </om:phenomenonTime>
  128	      <om:resultTime xlink:href="#phenomenonTime_702"/>
  129	      <om:procedure xlink:href="http://www.52north.org/test/procedure/8"/>
  130	      <om:observedProperty xlink:href="http://www.52north.org/test/observableProperty/8"/>
  131	      <om:featureOfInterest xlink:href="#ssf_14726DD6A045EC84DDB7C4041FE9FFD839C16472"/>
  132	      <om:result xmlns:ns="http://www.opengis.net/gml/3.2" uom="test_unit_8" xsi:type="ns:MeasureType">1.3</om:result>
  133	    </om:OM_Observation>
  134	  </sos:observationData>
  135	  <sos:observationData>
  136	    <om:OM_Observation gml:id="o_1373376475758">
  137	      <om:type xlink:href="http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement"/>
  138	      <om:phenomenonTime>
  139	        <gml:TimeInstant gml:id="phenomenonTime_703">
  140	          <gml:timePosition>2012-11-19T14:02:00.000Z</gml:timePosition>
  141	        </gml:TimeInstant>
  142	      </om:phenomenonTime>
  143	      <om:resultTime xlink:href="#phenomenonTime_703"/>
  144	      <om:procedure xlink:href="http://www.52north.org/test/procedure/8"/>
  145	      <om:observedProperty xlink:href="http://www.52north.org/test/observableProperty/8"/>
  146	      <om:featureOfInterest xlink:href="#ssf_14726DD6A045EC84DDB7C4041FE9FFD839C16472"/>
  147	      <om:result xmlns:ns="http://www.opengis.net/gml/3.2" uom="test_unit_8" xsi:type="ns:MeasureType">1.4</om:result>
  148	    </om:OM_Observation>
  149	  </sos:observationData>
  150	  <sos:observationData>
  151	    <om:OM_Observation gml:id="o_1373376475759">
  152	      <om:type xlink:href="http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement"/>
  153	      <om:phenomenonTime>
  154	        <gml:TimeInstant gml:id="phenomenonTime_710">
  155	          <gml:timePosition>2012-11-19T14:09:00.000Z</gml:timePosition>
  156	        </gml:TimeInstant>
  157	      </om:phenomenonTime>
  158	      <om:resultTime xlink:href="#phenomenonTime_710"/>
  159	      <om:procedure xlink:href="http://www.52north.org/test/procedure/8"/>
  160	      <om:observedProperty xlink:href="http://www.52north.org/test/observableProperty/8"/>
  161	      <om:featureOfInterest xlink:href="#ssf_14726DD6A045EC84DDB7C4041FE9FFD839C16472"/>
  162	      <om:result xmlns:ns="http://www.opengis.net/gml/3.2" uom="test_unit_8" xsi:type="ns:MeasureType">2.1</om:result>
  163	    </om:OM_Observation>
  164	  </sos:observationData>
  165	</sos:GetObservationResponse></sos:GetObservationResponse>

InsertObservation

SplitDataArrayIntoObservations

The extension SplitDataArrayIntoObservations forces the SOS to split the incoming SweArrayObservation into single observations. One for each block in the data array. This request extension can be used via SOAP and POX binding using specification version 2.0.0. The following examples show how to use the extension. It requires an transactional instance of the SOS. In addition, a procedure must be inserted before having the observation type allowed that results from the interpretation of the elementType. The table shows how the current implementation matches swe types to observation types:
Swe Type Resulting observation type
Category
Category observation
Count
Count Observation
Boolean
Truth Observation
Quantity
Measurement
Text
Text Observation

Example InsertObservation request
    1	<?xml version="1.0" encoding="UTF-8"?>
    2	<sos:InsertObservation service="SOS" version="2.0.0" [...]>
    3	    <swes:extension>
    4	      <swe:Boolean definition="SplitDataArrayIntoObservations">
    5	        <swe:value>true</swe:value>
    6	      </swe:Boolean>
    7	    </swes:extension>
    8	    <sos:offering>http://www.52north.org/test/offering/6</sos:offering>
    9	    <sos:observation>
   10	        <om:OM_Observation gml:id="o1">
   11	            <om:type xlink:href="http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_SWEArrayObservation"/>
   12	            <om:phenomenonTime>
   13	                <gml:TimePeriod gml:id="phenomenonTime">
   14	                    <gml:beginPosition>2012-11-19T13:30:00+02:00</gml:beginPosition>
   15	                    <gml:endPosition>2012-11-19T13:44:00+02:00</gml:endPosition>
   16	                </gml:TimePeriod>
   17	            </om:phenomenonTime>
   18	            <om:resultTime>
   19	                <gml:TimeInstant gml:id="resultTime">
   20	                    <gml:timePosition>2012-11-19T13:50:00+02:00</gml:timePosition>
   21	                </gml:TimeInstant>
   22	            </om:resultTime>
   23	            <om:procedure xlink:href="http://www.52north.org/test/procedure/6"/>
   24	            <om:observedProperty xlink:href="http://www.52north.org/test/observableProperty/6"/>
   25	            <om:featureOfInterest>
   26	                <sams:SF_SpatialSamplingFeature gml:id="ssf_test_feature_6">
   27	                    <gml:identifier codeSpace="">http://www.52north.org/test/featureOfInterest/6</gml:identifier>
   28	                    <gml:name>52&#176;North</gml:name>
   29	                    <sf:type xlink:href="http://www.opengis.net/def/samplingFeatureType/OGC-OM/2.0/SF_SamplingPoint"/>
   30	                    <sf:sampledFeature xlink:href="http://www.52north.org/test/featureOfInterest/1"/>
   31	                    <sams:shape>
   32	                        <gml:Point gml:id="test_feature_6">
   33	                            <gml:pos srsName="http://www.opengis.net/def/crs/EPSG/0/4326">51.935101100104916 7.651968812254194</gml:pos>
   34	                        </gml:Point>
   35	                    </sams:shape>
   36	                </sams:SF_SpatialSamplingFeature>
   37	            </om:featureOfInterest>
   38	            <om:result xsi:type="swe:DataArrayPropertyType">
   39	                <swe:DataArray>
   40	                    <swe:elementCount>
   41	                        <swe:Count>
   42	                            <swe:value>15</swe:value>
   43	                        </swe:Count>
   44	                    </swe:elementCount>
   45	                    <swe:elementType name="defs">
   46	                        <swe:DataRecord>
   47	                            <swe:field name="phenomenonTime">
   48	                                <swe:Time definition="http://www.opengis.net/def/property/OGC/0/PhenomenonTime">
   49	                                    <swe:uom xlink:href="http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"/>
   50	                                </swe:Time>
   51	                            </swe:field>
   52	                            <swe:field name="test_observable_property_6">
   53	                                <swe:Quantity definition="http://www.52north.org/test/observableProperty/6">
   54	                                    <swe:uom code="test_unit_6"/>
   55	                                </swe:Quantity>
   56	                            </swe:field>
   57	                        </swe:DataRecord>
   58	                    </swe:elementType>
   59	                    <swe:encoding>
   60	                        <swe:TextEncoding tokenSeparator="#" blockSeparator="@"/>
   61	                    </swe:encoding>
   62	                    <swe:values>
   63	                      2012-11-19T13:30:00+02:00#159.15@2012-11-19T13:31:00+02:00#159.15@2012-11-19T13:32:00+02:00#159.85@
   64	                      2012-11-19T13:33:00+02:00#160.5@2012-11-19T13:34:00+02:00#160.9@2012-11-19T13:35:00+02:00#160.7@
   65	                      2012-11-19T13:36:00+02:00#160.5@2012-11-19T13:37:00+02:00#160.6@2012-11-19T13:38:00+02:00#160.5@
   66	                      2012-11-19T13:39:00+02:00#160.4@2012-11-19T13:40:00+02:00#160.34@2012-11-19T13:41:00+02:00#160.25@
   67	                      2012-11-19T13:42:00+02:00#159.79@2012-11-19T13:43:00+02:00#159.56@2012-11-19T13:44:00+02:00#159.25
   68	                    </swe:values>
   69	                </swe:DataArray>
   70	            </om:result>
   71	        </om:OM_Observation>
   72	    </sos:observation>
   73	</sos:InsertObservation>

Example GetObservation request for the inserted observations
    1	<?xml version="1.0" encoding="UTF-8"?>
    2	<sos:GetObservation service="SOS" version="2.0.0" [...]>
    3	  <sos:procedure>http://www.52north.org/test/procedure/9</sos:procedure>
    4	  <sos:offering>http://www.52north.org/test/offering/9</sos:offering>
    5	  <sos:observedProperty>http://www.52north.org/test/observableProperty/9_1</sos:observedProperty>
    6	  <sos:temporalFilter>
    7	    <fes:During>
    8	      <fes:ValueReference>phenomenonTime</fes:ValueReference>
    9	        <gml:TimePeriod gml:id="tp_1">
   10	          <gml:beginPosition>2012-11-19T13:29:00.000+02:00</gml:beginPosition>
   11	          <gml:endPosition>2012-11-19T13:45:00.000+02:00</gml:endPosition>
   12	        </gml:TimePeriod>
   13	      </fes:During>
   14	    </sos:temporalFilter>
   15	</sos:GetObservation>

Example response
    1	<?xml version="1.0" encoding="UTF-8"?>
    2	    <sos:GetObservationResponse [...]>
    3	      <sos:observationData>
    4	        <om:OM_Observation gml:id="o_1373381823207">
    5	          <om:type xlink:href="http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement"/>
    6	          <om:phenomenonTime>
    7	            <gml:TimeInstant gml:id="phenomenonTime_712">
    8	              <gml:timePosition>2012-11-19T11:43:00.000Z</gml:timePosition>
    9	            </gml:TimeInstant>
   10	          </om:phenomenonTime>
   11	          <om:resultTime>
   12	            <gml:TimeInstant gml:id="ti_9DF0600081E2BBB722ABD17B90C44ABAC62A70DA">
   13	              <gml:timePosition>2012-11-19T11:50:00.000Z</gml:timePosition>
   14	            </gml:TimeInstant>
   15	          </om:resultTime>
   16	          <om:procedure xlink:href="http://www.52north.org/test/procedure/9"/>
   17	          <om:observedProperty xlink:href="http://www.52north.org/test/observableProperty/9_1"/>
   18	          <om:featureOfInterest>
   19	            <sams:SF_SpatialSamplingFeature gml:id="ssf_C6320596900E2831298BB21FADCA4C7298CCA7D9">
   20	              <gml:identifier codeSpace="">http://www.52north.org/test/featureOfInterest/6</gml:identifier>
   21	              <gml:name>52&#176;North</gml:name>
   22	              <sf:type xlink:href="http://www.opengis.net/def/samplingFeatureType/OGC-OM/2.0/SF_SamplingPoint"/>
   23	              <sf:sampledFeature xlink:href="http://www.52north.org/test/featureOfInterest/1"/>
   24	              <sams:shape>
   25	                <gml:Point gml:id="test_feature_6">
   26	                  <gml:pos srsName="http://www.opengis.net/def/crs/EPSG/0/4326">51.935101100104916 7.651968812254194</gml:pos>
   27	                </gml:Point>
   28	              </sams:shape>
   29	            </sams:SF_SpatialSamplingFeature>
   30	          </om:featureOfInterest>
   31	          <om:result uom="test_unit_6" xsi:type="ns:MeasureType">159.56</om:result>
   32	        </om:OM_Observation>
   33	      </sos:observationData>
   34	      <sos:observationData>
   35	        <om:OM_Observation gml:id="o_1373381823216">
   36	          <om:type xlink:href="http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement"/>
   37	          <om:phenomenonTime>
   38	            <gml:TimeInstant gml:id="phenomenonTime_724">
   39	              <gml:timePosition>2012-11-19T11:41:00.000Z</gml:timePosition>
   40	            </gml:TimeInstant>
   41	          </om:phenomenonTime>
   42	          <om:resultTime>
   43	            <gml:TimeInstant gml:id="ti_1670BAE4EE79C4C207A368F3BFA245289F61D448">
   44	              <gml:timePosition>2012-11-19T11:50:00.000Z</gml:timePosition>
   45	            </gml:TimeInstant>
   46	          </om:resultTime>
   47	          <om:procedure xlink:href="http://www.52north.org/test/procedure/9"/>
   48	          <om:observedProperty xlink:href="http://www.52north.org/test/observableProperty/9_1"/>
   49	          <om:featureOfInterest xlink:href="#ssf_C6320596900E2831298BB21FADCA4C7298CCA7D9"/>
   50	          <om:result uom="test_unit_6" xsi:type="ns:MeasureType">160.25</om:result>
   51	        </om:OM_Observation>
   52	      </sos:observationData>
   53	      [...]
   54	      </sos:observationData>
   55	    </sos:GetObservationResponse>
   56	  </soap:Body>
   57	</soap:Envelope>

Spatial Filtering Profile

The Spatial Filtering Profile is specified in clause 12 of the SOS 2.0 specification (OGC 12-006). This profile restricts observations to spatial observations which provide a well-defined parameter for the observation location. This parameter carries the sampling geometry of the observation which represents the spatial extent where the observation result applies to and can be targeted by spatial filters. The “Spatial Observation” is defined in the Observation & Measurement 2.0 specification (OGC 10-025) subclause 7.13 and can contain any gml:AbstractGeometry types, such as points, lines or polygons.

If the SOS supports the Spatial Filtering Profile, the observedArea of ObservationOfferings provided in the Contents section of the Capabilities represents the minimum bounding box of the sampling geometries, not the bounding box of the features of interests. So client can detect whether the SOS supports the Spatial Filtering Profile by checking if the Profile http://www.opengis.net/spec/SOS/2.0/conf/spatialFilteringProfile appears in the ServiceIdentification section of the Capabilities.

The Spatial Filtering Profile restricts the observations to OM_SpatialObservation. This means that all observations must contain the well-defined parameter which carries the sampling geometry. Since this is not always wanted, the 52°North SOS 4.0.0 provides the ability to use the Spatial Filtering Profile less restrictive. In this case an observation must not contain a sampling geometry. This behaviour can be activated via a property (Service-Settings -> Should this SOS support strict Spatial Filtering Profile?) in the admin backend.
Configure/Administrate

Additional property in "Service" settings:
  • Should this SOS support strict Spatial Filtering Profile?
If this setting is activated, the SOS uses the FeatureOfInterest geometry as samplingGeometry inthe observation if no separate samplingGeometry is defined.

OM_SpatialObservation parameter definition for sampling geometry

The OM_SpatialObservation, defined in subclause 7.13 of Observation & Measurement 2.0 specification (OGC 10-025), can contain any gml:AbstractGeometry types, such as points, lines or polygons. To identify that the om:parameter carries a sampling geometry, the xlink:href attribute should contian the value http://www.opengis.net/def/param-name/OGC-OM/2.0/samplingGeometry in the om:name.

    1	<om:parameter>
    2	    <om:NamedValue>
    3	        <om:name xlink:href="http://www.opengis.net/def/param-name/OGC-OM/2.0/samplingGeometry" />
    4	        <om:value>
    5	            <gml:Point gml:id="SamplingPoint1">
    6	                <gml:pos srsName="http://www.opengis.net/def/crs/EPSG/0/4326">52.9 7.52</gml:pos>
    7	            </gml:Point>
    8	        </om:value>
    9	    </om:NamedValue>
   10	</om:parameter>

If the Spatial Filtering Profile is not supported and the om:Observsation contains a sampling geometry in the om:parameter element, an exception is thrown.

Spatial filter definition

For filtering the sampling geometry in the GetObservation and GetResult, the valueReference element should contain the value http://www.opengis.net/req/omxml/2.0/data/samplingGeometry. If this value is set, the spatial filter is targeted to the sampling geometries of the observations instead of the featureOfInterest geometries. Here is an exmaple for the spatial filter with sampling geometry valueRefernce

    1	<sos:spatialFilter>
    2	    <fes:BBOX>
    3	        <fes:ValueReference>http://www.opengis.net/req/omxml/2.0/data/samplingGeometry</fes:ValueReference>
    4	        <gml:Envelope srsName="http://www.opengis.net/def/crs/EPSG/0/4326">
    5	            <gml:lowerCorner>0 0</gml:lowerCorner>
    6	            <gml:upperCorner>60 60</gml:upperCorner>
    7	        </gml:Envelope>
    8	    </fes:BBOX>
    9	</sos:spatialFilter>

If the Spatial Filtering Profile is not supported and the spatial filter contains this URL in the valueReference, an exception is thrown.

Transactional Security

52n-sos_admin_tab_transactional-security_small.png For ensuring that only known parties are able to

  • insert new data (e.g. observations, sensors),
  • update existing (e.g. sensor descriptions),
  • and delete data (e.g. observations, sensors)
the SOS brings a build-in feature called Transactional Security. For enabling, just log-in to the administrator web application AdminSettings → select tab Transactional Security ( ../admin/settings#transactional_security). Ensure to check the Transactional security active setting and enter the IPs that should be allowed to execute transactional operations:
  • InsertSensor,
  • InsertObservation,
  • UpdateSensorDescription,
  • DeleteSensor,
  • DeleteObservation.
If you are running your service instance behind a proxy, be sure to add the IP of the proxy, too. In addition, the proxy should provide the following HTTP headers:
  • X-Forwarded-Host
  • X-Forwarded-Server
  • X-Forwarded-For
Another option is to use the HTTP header Authorization with a specified token.

A simple solution to secure the SOS via HTTP Basic Authentication can be found here.

Advanced security features including more control over the other operations can be established using the 52°North Web Security Service from our Security community. A documentation how to set up the 52°North Web Security Service can be found on the SecuringSOS wiki page.

Streaming

Available since version: 4.1.0

XML response streaming

XML response streaming means that no full XML DOM tree is built up. This feature uses JAVA XMLStreamWriter or XMLEventWriter to write the parts of the response directly to the OutputStream and used for some elements the already existing encoder. For example
  • the SOAP elements are created with a XMLStreamWriter implementation and the SOAPBody content is created with a default encoder, e.g. GetCapabilitiesResponseEncoderv2.
  • the SOS response envelope is created written with a XMLStreamWriter implementation and for the child elements, e.g. OM_Observation of a GetObservationResponse, the OMEncoder is used.
This feature can be activate in the Admin GUI under the tab Streaming if you check "Should this service stream the XML responses?".

Currently, XML writer exits for the following:
  • SOAP 1.2
  • SOS 2.0 response envelopes
  • O&M 2.0 observations
  • WaterML 2.0 TVP/TDR
The advantages of this feature:
  • the reponses can contain more data
  • less memory usage
The disadvantages of this feature:
  • no XML validation on server side
  • If an error occurs, the stream is broken and the exception handling does not meet the SOS 2.0 specification

Database streaming

Database streaming is currently only implemented for GetObservation responses. If this feature is activated, the observation metadata are queried from the datasource and the individual measured values are queried at the encoder level. There are two implementations how the measured values are queried from the database which can be selected in the Admin GUI.
Chunk

In this case definable number of measured values are queried, processed and the the next chunk is queried from the database.
Scrollable

In this case is iterated over a Hibernate ScrollbaleResult.

This feature can be activate in the Admin GUI under the tab Streaming if you check "Should this service stream datasource values (currently only GetObservation) to encoder?".

And with this setting "Should this service query the streaming datasource values (currently only GetObservation) as chunk of x (true) ora as scrollable values?" you can switch between the chunk and scrollable implementation. With "Number of chunk size" you can define the size of the chunks.

The advantages of this feature:
  • less memory usage
  • very low latency with XML response streaming
The disadvantages of this feature:
  • slower if XML response streaming is not activated
  • If an error occurs, the stream is broken and the exception handling does not meet the SOS 2.0 specification
TODO Add table to show the differences between the settings.

Multilingualism support

Available since version: 4.2.0

Multilingualism support means that you can send a request with the additional parameter language and in the response appropriate values are returned in the queried language. The language value should be of type ISO 639-2/B alpha 3 code or IETF RFC 5646 short/long, e.g. eng/en/en-GB for English, ger/de/de-DE for German, or ita/it/it-IT for Italian.

If the language parameter is absent in the request or the language parameter value is not supported, the default language is used.

This feature requires four additional tables to store the language related information for procedures, offerings, observedProperties, and featureOfInterest. The multilingualism data for the Capabilities are stored in the file database which is used for the settings

This feature is specified in the proposed update of the Technical Guidelines for INSPIRE Download Services which was developed in collaboration with the JRC.

The next subsection lists the operations and elements which are affected by the language parameter.
Capabilities
  • Titles
  • Abstracts
  • Descriptions
  • Offering names (ObservationOffering in the contents section)
Other operations

Other operations whose responses are affected by the requestes language parameter are currently:
  • DescribeSensor
  • GetObservation
  • GetFeatureOfInterest
  • GetObservationById.
All of the listed fields may apply to all mentioned SOS operations.
  • Descriptions
  • Titles
  • Abstracts
  • Observed Property names
  • Procedure names
  • Feature of Interest names
  • Textual quality descriptions
It may be that in the furture further operation responses and elements/fields are affected by the language parameter.

Installation

It is necessary to check the Multi language support checkbox in the Advanced Database Configuration of Datasource configuration installation page to support this feature.

Configure/Administrate

The SOS administration interface provides an easy way to add the multilingual information for each object which may be affected by the language parameter.

The default language (default = eng), which is used if no language parameter is requested, can be set in Admin -> Settings : I18N tab
Service Identification

In the Service Identification settings ( Admin -> Settings : Service Identification tab) the administrator can add and modify the multilingual information for the Capabilities. The currently affected elements of the Capabilities document are Title and Abstract. Here is a screenshot of the settings:

Multilingual_Capabilities_settings.png
I18N Settings

The mutlilingual relevant information for procedure, offering, observableProperty and featureOfInterest can be modified in the I18N Settings ( Admin -> Settings -> I18N settings). The administrator selects first a source and then the concrete object in the drop-down menue. Now he can add new entries by clicking plus, change entries or remove existing entries by clicking minus. Here is an example screenshot of the I18N settings for the offerings:

Multilingual_I18N_settings_Offering.png

You can add multilingual names and descriptions for offering, observableProperty and featueOfInterest.

For the procedure you can additionally add multilingual short name and long name valies.

CRS support

Available since version: 4.2.0

CRS support means that you can send a request with the additional parameter crs and in the response appropriate values are returned in the queried CRS.

The 52°North SOS supports the EPSG CRS and allows the following definitions as CRS request values: If the CRS parameter is absent in the request, the default CRS (configurable via settings), is used in the response. In the case of a not supported CRS in the request, a corresponding exception is thrown.

This feature is specified in the proposed update of the Technical Guidelines for INSPIRE Download Services which was developed in collaboration with the JRC.

In the next subsections the elements are listed which are affected by the CRS parameter.

ObservationOffering in the contents of the Capabilities

  • observedArea

Sensor description

  • sensor position/location
  • observedBBOX (Discovery Profile)

FeatureOfInterest

  • geometry

SamplingGeomentry in the observation (Spatial Filtering Profile)

  • samplingGeometry

Addtional CRS features

Additionalla the 52°North SOS provides the following CRS dependent features.
Spatial filter

The 52°North SOS supports to define a spatial filter geometry in any supported CRS. Internally the requested geometry is transformed into the stored CRS and applied to the data.
Transactional operation

The 52°North SOS supports to insert a geometry (of a featureOfInterest or the samplingGeometry of an observation) in any supported CRS. Internally the requested geometry is transformed into the stored CRS and inserted into the datastore.

Installation

During the installation process you can finde some settings in the CRS settings tab. If you use the 52°North SOS database model it is not necessary to make changes.

  • Datasource settings
    • Are the geometries stored in datasource with northing first: Indicator for the axis order of stored geomentries
    • Is datasource spatial enabled: Idicator if the underlying datasource supports spatial queries and geometry types. If not the SOS supports single column for longitude and latitude.
    • Storage EPSG Code: The EPSG code in which the geometries are stored or will be stored.
  • Query/Response settings
    • CRS authority: The CRS authority, currently is only EPSG supported
    • Default response EPSG Code: The default response EPSG code
    • Supported crs: Reduce the number of supported CRS
    • EPSG Codes with Switched Coordinates: EPSG codes for which the axis order should be switched. Some datasources supports only a certain axis order but the registry, e.g. EPSG registry, defines another axis order for the geometries CRS.

Configure/Administrate

The settings described in the previous Installation section can be changed via the administration interface.

NEW Bundle

Available since version: 4.3.0

The bundle contains in addition to the 52°North SOS the SWC REST-API and the JavaScript SOS Client.

The SWC REST-API uses the database settings defined during the installation of the 52°North SOS and has direct access to the database tables. This allows a fast access to the data for the JavaScript SOS Client.

The JavaScript SOS Client preconfigured to connect to the SWC REST-API provided by this bundle at localhost:8080/52n-sos-webapp. This works with the default WAR file name "52n-sos-webapp##.war", because Tomcat can use the file name for context configuration.

If you change the name of the war file you have to update the REST-API URL of the JavaScript SOS Client in the settings file: [TOMCAT_HOME]\webapps\[SOS_NAME]\static\client\jsClient\settings.json of the deployed SOS.

A precompiled bundle package can be downloaded from the 52°North download page.

To build the bundle package from sources, see B1) Building from Source section.

SOS version REST-API version JS-Client version
4.3.0
1.5.0
1.0.0

External cache reload

The 52°North SOS provides an automatic cache reloading which can be configured via the admin interface. But in some cases the automatic cache reload is performed at a bad time. In this case you can disable the automatic cache reload and trigger the cache reload externaly via curl request:

curl -X POST -u 'user:pass' 'http://[HOST]:[PORT]/[SOS_WEBAPP]/admin/cache/reload'

  • user: 52N SOS admin interface user name, e.g. admin
  • pass: 52N SOS admin interface password, e.g. password
  • [HOST]: Servlet container host name e.g. localhost
  • [PORT]: Servlet container port, e.g. 8080
  • [SOS_WEBAPP]: Name of the 52N SOS webapp, e.g. 52n-sos-webapp

NEW INSPIRE Specialised Observations

Available since version: 4.4.0

For more information see INSPIRE Specialised Observations

NEW Register binding

Available since version: 4.4.0

The register binding allows to register a new sensor directly with the sensor description.

For more information see Register Binding

Endpoints

The 52°North SOS 4.x supports different endpoints to which the client can send requests. In the earlier 4.x versions each binding had is own endpoint, e.g /sos/soap for SOAP requests or /sos/kvp for KVP requests. This behaviour was discussed on SensorObservationServiceIVEndpointsAndBindings and reported as a bug https://bugzilla.52north.org/show_bug.cgi?id=848.

Since the version 4.1 the 52°North SOS 4.x supports sending requests directly to the endpoint /sos and the additional endpoint /service. In this case the HTTP ContentType should be set. In the following matrix you can find the valid ContentType for each binding and the supported endpoints.

Binding ContentType /service /sos /xyz/kvp /xyz/soap /xyz/pox /xyz/json /xyz/rest xyz/exi xyz/register
KVP
application/x-kvp
led-green
led-green
led-green
led-red
led-red
led-red
led-red
led-red
led-red
SOAP
application/soap+xml
led-green
led-green
led-red
led-green
led-red
led-red
led-red
led-red
led-red
POX
application/xml
led-green
led-green
led-red
led-red
led-green
led-red
led-red
led-red
led-red
JSON
application/json
led-green
led-green
led-red
led-red
led-red
led-green
led-red
led-red
led-red
REST
application/xml
led-red
led-red
led-red
led-red
led-red
led-red
led-green
led-red
led-red
EXI
application/exi
led-green
led-green
led-red
led-red
led-red
led-red
led-red
led-green
led-red
REGISTER
application/xml
led-red
led-red
led-red
led-red
led-red
led-red
led-red
led-red
led-green

Where /xyz stands for /service or /sos

Extensions

  • Different types of extensions:
    • Decoder/Encoder: SosEncodings
    • Operation: Adding new functionality to the SOS like DeleteObservation operation
    • Binding: Providing different HTTP based protocols/ways to communicate with the SOS like SOAP, KVP, RESTful
  • Ideas for extensions: SensorObservationServiceExtensionIdeas

INSPIRE Download Service extension

Available in version: 4.2.0

52°North supports the JRC in developing an INSPIRE Download Service based on SOS which was announced in this blog post.

The INSPIRE Download Service based on SOS draft builds on the OGC SOS 2.0 specification and the development of the specification and implementation has not been completed.

This section of the 52°North SOS 4.x documentation already describes the necessary extensions for the INSPIRE Download Service. If the development process is finished, this extension will be added to the default 52°North SOS 4.x line.

This extension requires the Multilingual feature and the CRS feature

Configure/Administrate

Installation

Addtitional installation instructions to the default instructions.

  • Required:
    • Activate the Multilingual support: Check the Multi language support checkbox in the Advanced Database Configuration of Datasource configuration.
    • Activate strict Spatial Filtering Profile: Check Should this SOS support strict Spatial Filtering Profile? in Service setting.
  • Optional:
    • CRS settings: Change the default CRS and limit the supported CRS. dy definition, the default response EPSG code should be 4258 (ETRS89).
    • I18N settings: Set the default language as ISO 639-2/B alpha 3 code, default = eng.
    • INSPIRE settings: edit the information, see INSPIRE settings.
Administration

You can change the Optional settings from the previous Installation section, the multilingual relevant information as described in the feature section or the CRS settings as described in the CRS feature section.
INSPIRE settings

With the INSPIRE settings you can define some values which are used in the!ExtendedCapabilities or en-/disable this extension.
  • Enable INSPIRE extension: en-/disable the INSPIRE extension ( default = disabled)
  • ExtendedCapabilities settings
    • Show full INSPIRE ExtendedCapabilities: Should the Capabilities contain the minimal or the full INSPIRE ExtendedCapabilities
    • INSPIRE MetadataUrl: The Metadata URL
    • INSPIRE MetadataUrl MediaType: The Metadat MediaType
    • INSPIRE Conformity title: The Conformity title
    • INSPIRE Conformity date of creation: The date of creation for the Conformity
    • INSPIRE Metadata date: The Metadata date
    • Use authority as CRS prefix: Which CRS prefix should be use, authority (EPSG::) or OGC CRS URL (http://www.opengis.net/def/crs/EPSG/0/)?

Supported Operations and Bindings

The current draft of the INSPIRE Download Service based on SOS specification affects only the KVP binding and the following SOS 2.0 operations:
  • GetCapabilities
  • DescribeSensor
  • GetObservation
  • GetFeatureOfInterest
  • GetObservationById

Language support

See Multilingualism support.

For the INSPIRE Download Service based on SOS the language value should be of type ISO 639-2/B alpha 3 code , e.g. eng for English, ger for German, or ita for Italian.

CRS support

See CRS support.

By definition, the default CRS of responses should be ETRS89 (EPSG::4258) which can be set by the Default response EPSG Code CRS setting.

ExtendedCapabilities

The ExtendedCapabilities contains INSPIRE related metadata about the service. In addition to information about the service type, resource location, or PointOfContact, it provides information about the default response language and all supported languages by this service. Furthermore it shows the default response CRS and all supported CRSes.

The language and CRS metadata elements are also used in the offering extension, described in the next section.

Here is an example of the ExtendedCapabilities:

    1	<ows:ExtendedCapabilities>
    2	  <inspire_dls:ExtendedCapabilities xmlns:inspire_common="http://inspire.ec.europa.eu/schemas/common/1.0" xmlns:inspire_dls="http://inspire.ec.europa.eu/schemas/inspire_dls/1.0">
    3	    <inspire_common:ResourceLocator>
    4	      <inspire_common:URL>http://localhost:8080/52n-sos-webapp/service/kvp?request=GetCapabilities&amp;service=SOS</inspire_common:URL>
    5	      <inspire_common:MediaType>application/xml</inspire_common:MediaType>
    6	    </inspire_common:ResourceLocator>
    7	    <inspire_common:ResourceType>service</inspire_common:ResourceType>
    8	    <inspire_common:TemporalReference/>
    9	    <inspire_common:Conformity>
   10	      <inspire_common:Specification>
   11	        <inspire_common:Title>OGC SOS 2.0 for Inspire</inspire_common:Title>
   12	        <inspire_common:DateOfCreation>2008-06-01T00:00:00.000Z</inspire_common:DateOfCreation>
   13	      </inspire_common:Specification>
   14	      <inspire_common:Degree>notEvaluated</inspire_common:Degree>
   15	    </inspire_common:Conformity>
   16	    <inspire_common:MetadataPointOfContact>
   17	      <inspire_common:OrganisationName>52North</inspire_common:OrganisationName>
   18	      <inspire_common:EmailAddress>info@52north.org</inspire_common:EmailAddress>
   19	    </inspire_common:MetadataPointOfContact>
   20	    <inspire_common:MetadataDate>2008-06-01T00:00:00.000Z</inspire_common:MetadataDate>
   21	    <inspire_common:SpatialDataServiceType>download</inspire_common:SpatialDataServiceType>
   22	    <inspire_common:MandatoryKeyword>
   23	      <inspire_common:KeywordValue>infoFeatureAccessService</inspire_common:KeywordValue>
   24	    </inspire_common:MandatoryKeyword>
   25	    <inspire_common:SupportedLanguages>
   26	      <inspire_common:DefaultLanguage>
   27	        <inspire_common:Language>eng</inspire_common:Language>
   28	      </inspire_common:DefaultLanguage>
   29	      <inspire_common:SupportedLanguage>
   30	        <inspire_common:Language>ger</inspire_common:Language>
   31	      </inspire_common:SupportedLanguage>
   32	      <inspire_common:SupportedLanguage>
   33	        <inspire_common:Language>ita</inspire_common:Language>
   34	      </inspire_common:SupportedLanguage>
   35	      <inspire_common:SupportedLanguage>
   36	        <inspire_common:Language>eng</inspire_common:Language>
   37	      </inspire_common:SupportedLanguage>
   38	    </inspire_common:SupportedLanguages>
   39	    <inspire_common:ResponseLanguage>
   40	      <inspire_common:Language>eng</inspire_common:Language>
   41	    </inspire_common:ResponseLanguage>
   42	    <inspire_common:MetadataUrl>
   43	      <inspire_common:URL>http://myserver.org/</inspire_common:URL>
   44	      <inspire_common:MediaType>application/xml</inspire_common:MediaType>
   45	    </inspire_common:MetadataUrl>
   46	    <inspire_dls:SpatialDataSetIdentifier>
   47	      <inspire_common:Code>http://gdi.inspire.jrc.eu.net/stations/jrc-ws-0815</inspire_common:Code>
   48	    </inspire_dls:SpatialDataSetIdentifier>
   49	    <inspire_dls:SupportedCRS>
   50	      <inspire_dls:DefaultCRS>http://www.opengis.net/def/crs/EPSG/0/4258</inspire_dls:DefaultCRS>
   51	      <inspire_dls:OtherCRS>http://www.opengis.net/def/crs/EPSG/0/4326</inspire_dls:OtherCRS>
   52	      <inspire_dls:OtherCRS>http://www.opengis.net/def/crs/EPSG/0/4979</inspire_dls:OtherCRS>
   53	      <inspire_dls:OtherCRS>http://www.opengis.net/def/crs/EPSG/0/31466</inspire_dls:OtherCRS>
   54	      <inspire_dls:OtherCRS>http://www.opengis.net/def/crs/EPSG/0/31467</inspire_dls:OtherCRS>
   55	    </inspire_dls:SupportedCRS>
   56	  </inspire_dls:ExtendedCapabilities>
   57	</ows:ExtendedCapabilities>

Offering extension

The extension elements in the ObservationOfferings contains the supported languages and the CRSes for this specific offering. The element content is of type inspire_common:SupportedLanguages for the languages and inspire_dls:SupportedCRS for the CRSes. See ExtendedCapabilities

Spatial Filtering Profile

The INSPIRE Download Service based on SOS specification demands the support of the OGC SOS 2.0 Spatial Filtering Profile. For detailed information about the OGC SOS 2.0 Spatial Filtering Profile read chapter 12 of the OGC SOS 2.0 specification or read this documentation.

NEW Air Quality Data e-Reporting extension

Available since version: 4.3.0

For more information see Air Quality Data e-Reporting extension

NEW Flexible identifier extension

Available since version: 4.3.0

For more information see flexible identifier extension

Administrator Interface

SensorObservationServiceIVAdministratorInterface

Frequently Asked Questions

See SosFAQ
Topic attachments
I Attachment Action Size Date Who Comment
52n-sos_admin_tab_transactional-security.pngpng 52n-sos_admin_tab_transactional-security.png manage 121 K 29 Jan 2014 - 10:21 EikeJuerrens  
52n-sos_admin_tab_transactional-security_small.pngpng 52n-sos_admin_tab_transactional-security_small.png manage 53 K 29 Jan 2014 - 10:21 EikeJuerrens  
Multilingual_I18N_settings_Offering.pngpng Multilingual_I18N_settings_Offering.png manage 53 K 30 Jun 2014 - 12:46 CarstenHollmann Multilingual I18N settings for Offerings
sos_architecture.graphmlgraphml sos_architecture.graphml manage 32 K 28 May 2015 - 09:48 EikeJuerrens Created with yEd: http://www.yworks.com/en/products_yed_download.html
sos_architecture.pngpng sos_architecture.png manage 81 K 21 Apr 2015 - 13:54 EikeJuerrens new coloured 4.0er SOS diagram
Topic revision: r133 - 11 Nov 2016 10:05:43, CarstenHollmann
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