Repository files navigation

A Server implementation of the OGC SensorThings API. TheFRaunhoferOpensourceSensorThings-Serveris the first complete, open-source implementation of the OGC SensorThings API Part 1: Sensing.

We have extended the official test suit with extra tests that can be foundhere.The official test suit is fully passed.See the wiki pagefeatures for more details.

See thewiki for longer installation instructions.

1. Checkout the project from github:git clone https://github.com/FraunhoferIOSB/FROST-Server.git
2. Go to the project root (The top-most directory with a pom.xml)cd FROST-Server
3. Give the commandmvn clean installThis should build the war file inFROST-Server.HTTP/target/

1. create PostgreSQL database for the data
2. install the postgis extensions in this database (CREATE EXTENSION postgis;)

The database connection is configured from theContextentry either in server.xml, in$CATALINA_BASE/conf/[enginename]/[hostname]/appname.xmlor in/META-INF/context.xml inside the war file. If you are running the applicationfrom your IDE, it is easiest to change the context.xml file in the war file.

1. Copy thePostgres JDBC jarand thepostgis jarto$CATALINA_HOME/lib.

2. Configure the database resource. Either in the Context, or elsewhere in server.xml:

    <Resource     name="jdbc/sensorThings" auth="Container"     type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"     url="jdbc:postgresql://localhost:5432/sensorthings"     username="sensorthings" password="ChangeMe"     maxTotal="20" maxIdle="10" maxWaitMillis="-1"/>

1. Choose which backend to use, by configuring the persistence.persistenceManagerImplementationClass option:
   • Default value, using Long values for entity ids, generated in sequence: de.fraunhofer.iosb.ilt.sta.persistence.postgres.longid.PostgresPersistenceManagerLong
   • Using String values for entity ids, with new values generated using uuid_generate_v1mc(): de.fraunhofer.iosb.ilt.sta.persistence.postgres.stringid.PostgresPersistenceManagerString
   • Using uuid values for entity ids, with new values generated using uuid_generate_v1mc(): de.fraunhofer.iosb.ilt.sta.persistence.postgres.uuidid.PostgresPersistenceManagerUuid
2. Browse tohttp://localhost:8080/FROST/DatabaseStatus

This should initialise/update the database to the latest version and the serviceshould be ready for use.

By default, only primary and foreign keys have indices on them. If your database grows largeand you notice a significant slowdown, you should check which queries you use most, andadd indices for those queries. A very common one is probably forDatastreams(x)/observations?$orderby=phenomenonTime desc

CREATE INDEX "OBS-DS_ID-PHTIME_SE-O_ID"  ON "OBSERVATIONS"  USING btree  ("DATASTREAM_ID", "PHENOMENON_TIME_START" DESC, "PHENOMENON_TIME_END" DESC, "ID");

The server is configured from theContextentry either in server.xml, in$CATALINA_BASE/conf/[enginename]/[hostname]/appname.xmlor in/META-INF/context.xml inside the war file. If you are running the applicationfrom your IDE, it is easiest to change the context.xml file in the war file. It hasthe following options:

• SensorThings API settings
  • serviceRootUrl: The base URL of the SensorThings Server without version.
  • defaultCount: The default value for the $count query option.
  • defaultTop: The default value for the $top query option.
  • maxTop: The maximum allowed value for the $top query option.
  • useAbsoluteNavigationLinks: If true, navigationLinks are absolute, otherwise relative.
• MQTT settings
  • mqtt.mqttServerImplementationClass: The java class used for running the MQTT server (must implement MqttServer interface)
  • mqtt.Enabled: Specifies wether MQTT support will be enabled or not.
  • mqtt.Port: The port the MQTT server runs on.
  • mqtt.QoS: Quality of Service Level for MQTT messages.
  • mqtt.SubscribeMessageQueueSize: Queue size for messages to be pubslihed via MQTT.
  • mqtt.SubscribeThreadPoolSize: Number of threads use to dispatch MQTT notifications.
  • mqtt.CreateMessageQueueSize: Queue size for create observation requests via MQTT .
  • mqtt.CreateThreadPoolSize: Number of threads use to dispatch observation creation requests.
  • mqtt.Host: The external IP address or host name the MQTT server should listen on. Set to 0.0.0.0 to listen on all interfaces.
  • mqtt.internalHost: The internal host name of the MQTT server.
  • mqtt.WebsocketPort: The port the MQTT server is reachable via WebSocket.
• persistence settings
  • persistence.persistenceManagerImplementationClass: The java class used for persistence (must implement PersistenceManaher interface)
  • persistence.alwaysOrderbyId: Always add an 'orderby=id asc' to queries to ensure consistent paging.
  • persistence.db_jndi_datasource: JNDI data source name

There's also the possibility to run FROST-Server and the needed database inside a Docker container.This dependency is specified inside thedocker-compose.yaml file.

You can use the prebuilddocker image byrunningdocker-compose up. This will download the latest version of the FROST-Server and starts ittogether with the needed database. You can access the server by openinghttp://localhost:8080/FROST-Server/ in your browser.

If you want to build your own docker image, you can do this by callingmvn dockerfile:build -pl FROST-Server.HTTP.

All data is stored inside the PostGIS database. To keep this state there's a volume automatically mapped to the PostGIS container.For more information see thedocker-compose.yaml file and thePostGIS container documentation

To have a proper configuration of your server you need to create your owncontext.xml file.You can useFROST-Server.HTTP/src/main/webapp/META-INF/context.xml as template.Make sure your adapted file is located in$CATALINA_HOME/conf/Catalina/localhost/FROST-Server.xml.

If you prefer to not use Tomcat,Kinota Server is aSpring Boot application that makes it easy to run Fraunhofer IOSB FROST-Server in cloud environments.

If you prefer not to use Tomcat butWildfly it is possible to run FROST-Server on it.

Create a directory $WILDFLY_HOME/modules/org/postgresql/main and add bothPostgres JDBC jarand thepostgis jar to it. Create a file named module.xml and add the following:

<?xml version="1.0" encoding="UTF-8"?><modulexmlns="urn:jboss:module:1.0"name="org.postgresql">  <resources>    <resource-rootpath="postgresql-9.4.1212.jar"/>    <resource-rootpath="postgis-jdbc-2.2.1.jar"/>  </resources>  <dependencies>    <modulename="javax.api"/>    <modulename="javax.transaction.api"/>  </dependencies></module>

Add a datasource to $WILDFLY_HOME/standalone/configuration/[standalone.xml]Example:

<subsystemxmlns="urn:jboss:domain:datasources:4.0">  <datasources>    <datasourcejta="true"jndi-name="java:/comp/env/jdbc/sensorThings"pool-name="Sensorthings"enabled="true"use-ccm="true">        <connection-url>jdbc:postgresql://localhost:5432/sensorthings</connection-url>        <driver-class>org.postgresql.Driver</driver-class>        <driver>postgres</driver>        <security>          <user-name>sensorthings</user-name>          <password>ChangeMe</password>        </security>        <validation>        <valid-connection-checkerclass-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"/>          <background-validation>true</background-validation>          <exception-sorterclass-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"/>        </validation>    </datasource>  </datasources></subsystem>

Hylke van der Schaafhylke.vanderschaaf@iosb.fraunhofer.de

Michael Jacobymichael.jacoby@iosb.fraunhofer.de

Copyright (C) 2016 Fraunhofer Institut IOSB, Fraunhoferstr. 1, D 76131Karlsruhe, Germany.

This program is free software: you can redistribute it and/or modifyit under the terms of the GNU Lesser General Public License as published bythe Free Software Foundation, either version 3 of the License, or(at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See theGNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public Licensealong with this program. If not, seehttp://www.gnu.org/licenses/.