This repository contains an open source reference implementation of STAplus as a plugin for FROST-Server v2.5.0-SNAPSHOT.
NOTE: This implementation is still work in progress. The source code is already available in this repository to give you the opportunity to follow along or actually contribute.
IMPORTANT: Do not yet use in production!
STAplus is an OGC Implementation Standard that extends the suite of OGC SensorThings API v1.0 and v1.1 Standards.
"STAplus - SensorThings API extension PLUS - defines a SensorThings data model extension to improve FAIR principles when exchanging sensor data including licensing and ownership information. The STAplus extension is fully backwards compatible to the existing OGC SensorThings API Part 1: Sensing Version 1.0 and 1.1 and thereby offers existing deployments to easily upgrade to STAplus."1
The following UML diagrams illustrate the data model extension towards SensorThings API Datastream and MultiDatastream.
NOTE: The yellow colored classes belong to the SensorThings API data model.
This repository contains an open source reference implementation of STAplus as a FROST-Server plugin.
This implementation supports the conformance classes Core, Authentication and Business Logic as defined in the STAplus Standard. The API conformance class is already supported by the FROST-Server implementation.
This implementation enforces the concept of ownership as explained in detail below. Please see Business Logic for more details.
The deployment of the STAplus plugin can be integrated into a working deployment of the FROST-Server. You can follow the FROST-Server documentation to run your instance.
Clone this directory via git clone -b FROST-Server.v2.x https://github.com/securedimensions/FROST-Server-PLUS.git. Then cd FROST-Server-PLUS and mvn install. To run the tests at the end of the mvn install you need to have Docker running.
Make sure you copy the FROST-Server-2.5.0-SNAPSHOT.Plugin.STAplus-1.0.1.jar file to the appropriate FROST-Server directory and apply the STAplus specific settings below. Then restart FROST-Server.
Use git clone -b v2.x https://github.com/FraunhoferIOSB/FROST-Server.git FROST-Server to create the FROST-Server directory structure.
Then cd FROST-Server/Plugins and git clone -b develop https://github.com/securedimensions/FROST-Server-PLUS.git STAplus.
Add the STAplus plugin to the FROST-Server/Plugins/pom.xml.
<modules>
<module>Actuation</module>
<module>BatchProcessing</module>
<module>CoreModel</module>
<module>FormatCsv</module>
<module>FormatDataArray</module>
<module>FormatGeoJson</module>
<module>ModelLoader</module>
<module>MultiDatastream</module>
<module>OData</module>
<module>OpenApi</module>
<module>STAplus</module>
</modules>Then follow the FROST-Server documentation applicable to your deployment strategy.
Different features of the STAplus plugin can be activated / deactivated using FROST-Server alike configuration variables:
As described in the FROST-Server Plugin documentation, you need to add the plugin to the list of plugins to be loaded.
-
plugins.plugins: A comma-separated list of class names, listing additional plugins to load.
Add the class
de.securedimensions.frostserver.plugin.staplus.PluginPLUSto have the plugin loaded -
plugins.staplus.enable:
Set totrueto activate the STAplus plugin. Default:false.
- plugins.staplus.idType.observation_group:
The type of the primary key column of the ObservationGroups table. Defaults to the value of plugins.coreModel.idType. - plugins.staplus.idType.license:
The type of the primary key column of the Licenses table. Defaults to the value of plugins.coreModel.idType. - plugins.staplus.idType.campaign:
The type of the primary key column of the Campaigns table. Defaults to the value of plugins.coreModel.idType. - plugins.staplus.idType.relation:
The type of the primary key column of the Relations table. Defaults to the value of plugins.coreModel.idType.
NOTE: The type of the primary key column of the Party table (plugins.staplus.idType.party) is set to UUID by the implementation. This setting cannot be changed!
The activation of the Enforcement of Ownership allows to operate the STAplus endpoint in multi-user-CRUD mode. However, it requires to enable authentication using one of the existing plugins.
Each acting user is identified via a unique UUID, based on the username (REMOTE_USER) provided by the authentication plugin. The REMOTE_USER value is used to identify the user. In case the REMOTE_USER value is not in UUID format, this plugin will create a UUIDv4 from the REMOTE_USER value! This UUID value is used for the Party.@iot.id and Party.authId property. When creating a Party object, the value for the authId property can be omitted. If you set the authId value in the request, it must match the UUIDv4 representation for the REMOTE_USER. All other values are rejected by the implementation and will result in a response with HTTP status code 400.
The classes Thing, MultiDatastream, Datastream and ObservationGroup are directly associated to a Party. Objects of class Observation are linked to the owning Party object via the (Multi)Datastream. Objects of class Relation are linked to the Party object via the Subject property.
When activating the Concept of Ownership, the implementation enforces the multiplicity [1] on the association of these classes to Party. Therefore, creating objects of class Thing, MultiDatastream, Datastream or ObservationGroup require the association with the Party object that represents the acting user.
A user can update or delete any object owned. However, the user cannot delete the own Party. This requires admin access.
plugins.staplus.enable.enforceOwnership:
Set to true to enable the enforcement of ownership. Default: false.
This STAplus implementation creates a Party entity for the acting user if the Authentication conformance class is enabled. To prevent that the implementation creates a new Party entity for each request, it is IMPORTANT to allow client-side id generation. The id generation is controlled via this general setting:
<Parameter override="false" name="persistence.idGenerationMode" value="ServerGeneratedOnly" />P L E A S E make sure that you include the following configuration to ensure that a Party entity exists only once per user:
<Parameter override="false" name="persistence.idGenerationMode.Party" value="ClientGeneratedOnly" />This configuration overwrites the id generation for the Party entity only.
According to the STAplus Data Model, a Datastream, ObservationGroup and Campaign may have a License association. In order to ensure the use of compatible licenses, this implementation generates a given set of configured licenses.
A user can clone a global license to set the attributionText and associate that license to a Datastream or MultiDatestream. But, when creating a new License, the definition URI must remain the same.
The file resources/tables.xml contains as the last constructor for table generation the entry
<include relativeToChangelogFile="true" file="insertCCLicenes.xml" />The file insertCCLicenses.xml contains the set of licenses that are generated by the implementation.
You can change this configuration accordingly to load a different set of licenses.
plugins.staplus.enable.enforceLicensing:
Set to true to enable the enforcement of licensing. Default: false.
NOTE: This is not yet implemented.
When adding (an) Observation(s) to an ObservationGroup, the Enforcement of Licensing ensures that the License, associated to (an) Observation(s) is compatible to the License associated to an ObservationGroup.
When activating the Enforcement of Licensing, the plugin enforces licenses compatibility based on the Creative Commons v3 licensing model and the license compatibility according to the official cart.
See https://wiki.creativecommons.org/wiki/Wiki/cc_license_compatibility for more information.
The plugin creates the different Creative Commons Licenses in read-only mode as "system-wide" globals. An application cannot create new License objects nor can it update or delete the existing ones. An application can obtain a list of the "system-wide" licenses via the /Licenses path.
plugins.staplus.enable.enforceObservationGroupLicensing:
Set to true to enable the enforcement of licensing on ObservationGroup entity. Default: false.
Work on this implementation has being funded by the European Commission.