Plugins for an SPS 1.0

Overview

There is a wide variety of sensor types which could be tasked. The SPS offers a welldefined interface to deal with this heterogeneity. With this it is possible to task an arbitrary sensor in the same way. How to implement a plugin for an SPS is described in HowTo-Plugins_SPS.pdf (currently a draft version). A step-by-step description and an FAQ is available below and will be updated continuously.

Available Plugins

We developed several plugins for the SPS which are described each on their own project site. Currently the following plugins are available:

CITE TestPlugin		Since the SPS is not operational when no plugin instance is registered at the service, the CITETestPlugin comes with every distribution to test your installation. You can use the TEAM Engine of the OWS-5 for testing. Just register and type your SPS URL. A lot of tests are done through it, so it might take a while. For a more detailed view at the plugin (in general, behaviour, parameters, etc.) have a look at the CITE plugin deciption site.
AXIS (TM) camera plugin		The AxisCameraPlugin tasks an AXIS(TM) P(an)T(ilt)Z(oom) camera as real sensor. It is a more complex one, which is able to deal with time intervals and tasks which lay in the future. The plugin uses the WNS interface of the SPS to receive asynchronous messages.
AXIS (TM) System		The AxisSystem is kind of a wrapper plugin which serves as a more abstract layer to the AXIS (TM) camera plugin. The system encapsulates the PTZ controls of the camera and offers more context related input parameters like a WGS84 coordinate where to the camera shall look at (Instead of sending absolute pan/tilt values).
MSP2 plugin		The MobileSensorPlatform (MSP2) is a track vehicle which can be populated with small sensor assets. For now the plugin can task each chain so a remote navigation is possible. It's planned to extend the implementation to task some real sensors on the sensor platform (e.g. a camera, a light sensor, etc.). A more detailed description can be found on the MSP2Workshop page.

For installing and registering refer to the installing instructions of the SPS.

How to develop a plugin for the SPS

Step by step

Prerequirements:

1. Running database (either eXist or postgresql – see SPS manual for further details).
2. Tomcat Servlet Engine available on your machine (we suggest the .zip version for development).

For the SPS project do the following steps:

1. First of all you have to install an 52nSPS as developer version into your eclipse workspace. Alternatively you can check out the SPS from scratch by typing e.g.
   svn co https://svn.52north.org/svn/swe/main/SPS/Services/tags/52N-swe-sps-1.0.1 ~/workspace/SPS
   on your console. Note: You can choose another folder than ''SPS'' certainly, but then you'll have to change some URLs in the config files before running the SPS within eclipse.
2. Import the SPS project into your workspace as an existing project.
   
3. To mark the SPS project as a WTP project, open the project's preferences and go to the Project Facets entry. Mark the Java and the Dynamic Web Module.
4. Go to the Targeted Runtimes entry and either choose an existing tomcat runtime engine (if there is one) or create a new one.
5. Go to the Java Build Path entry and check, if Web App Libraries, Apache Tomcat vX.Y and an appropriate JRE System Library are available in the Libraries tab.

The plugin project needs the following steps:

1. Now, create a new Java project for your plugin
2. Open the project's preferences and go to the Java Build Path entry. Select the Libraries tab and add/create an SPS user library (the plugin will run within the AM module, thus it can use the AM's libraries). These libraries can be shared by the SPS once, so you avoid copying these libraries into each plugin project (e.g. the log4j.jar):
   1. Click on Add Library => User Library => Next => User Libraries...
      
   2. Create a new library and give it a name, e.g. sps-libs. Now add the following libraries
      • 52nAMv1XBs.jar, 52nCommonV1XBs.jar, 52nSweCommon-1.0.jar
      • joda-time-1.4.jar
      • jsr173_1.0_api.jar
      • log4j-1.2.13.jar
      • ogcGmlXBs-1.0.jar, ogcOwsXBs-1.0.jar, ogcSpsXBs-1.0.jar, ogcSweXBs-1.0.jar, ogcWnsXBs-0.0.9.jar
      • resolver.jar
      • xbean.jar, xbean_xpath.jar, xercesImpl.jar, xmlbeans-qname.jar, xmlpublic.jar
3. As next step, copy the 52nSpsCommon-v100.jar from the SPS/lib folder into your plugin's lib folder and add it to the build path. This library contains common classes of the SPS and is used only for building issues (these classes will be shared by the AM module only at runtime).
4. Now you have to make the plugin project known to the SPS (i.e. put the plugin on the SPS' runtime classpath). Open Debug Configurations ... and select the Classpath tab of your, e.g. Apache Tomcat Debug entry. Mark the plugin project in the Java EE Module Dependencies in the SPS's preferences.

Note: if you use external libs unknown to the SPS, you have to add them here as well!

1. Now you can create the first plugin class. This class must implement the abstract org.n52.sps.common.SPSSensor class and will be used be the framework as central plugin class. (Note: you have to implement the mandatory classes). A minimum plugin with no logic but correct structure would look like this one:

package test;

import net.opengis.sps.x10.SubmitDocument;
import net.opengis.sps.x10.SubmitRequestResponseDocument;

import org.n52.sps.common.PMAgent;
import org.n52.sps.common.SPSSensor;
import org.n52.sps.common.SensorIDGenerator;
import org.n52.sps.common.WNSHandler;
import org.n52.sps.common.exception.SensorConfigurationException;
import org.n52.sps.common.exception.ServiceException;
import org.x52North.sps.v1.ProfileInformationDocument;
import org.x52North.sps.v1.SensorConfigurationDocument;

public class TestPlugin extends SPSSensor {

   public TestPlugin(String externalSensorID, SensorIDGenerator idGenerator,
         PMAgent agent, WNSHandler wnsHandler) {
      super(externalSensorID, idGenerator, agent, wnsHandler);
      // TODO Auto-generated constructor stub
   }

   @Override
   public void configure(SensorConfigurationDocument arg0)
         throws SensorConfigurationException {
      // TODO Auto-generated method stub

   }

   @Override
   public ProfileInformationDocument getProfileInformation() {
      // TODO Auto-generated method stub
      return null;
   }

   @Override
   public SubmitRequestResponseDocument submit(SubmitDocument arg0)
         throws ServiceException {
      // TODO Auto-generated method stub
      return null;
   }
}

Further methods can be implemented optionally. The following subsections describe the mandatory and further optional methods in more detail.

Mandatory methods (must be implemented)

The following methods has to be implemented so the SPS can control the plugin appropriately.

configure()

This method will be called by the SPS during instantiation to configure the sensor. A certain sensor might use the configuration to restore a certain state (e.g. the last state before a service shutdown). Each implementing class must overwrite this method and guarantee that the configuration was successfull if no exception was thrown.

getProfileInformation()

Use this method to get the ProfileInformation for this sensor. The AM will use this method when a new sensor has been added to the service in order to register its SensorProfile at the PM if this has not been done before (maybe the sensor is just reinitiated after a service shutdown).

You have to create a ProfileInformationDocument for your plugin. Such documents describe the meta information for each plugin instance (the SPS needs such information to create the SensorOfferings in the capabilities file). A SensorProfile contains information about

• AreaOfService Contains the geometry of the area that a certain sensor is theoretically able to collect data fom. As it is not possible to declare the exact geometry of such an area at any time (at least for mobile sensors), this geometry should be treated as a hint for discovering sensors that can be tasked to collect data from a certain position or area.
• Phenomenon Defines the phenomenon measured by the sensor.
• SensorDescription Contains the URL to the SensorML description so that it can be downloaded by the PM or contains the document itself. Note: Contains the document itself only while registering. After registering the SensorProfile contains the link to the location, where the SensorML document could be downloaded from (maybe from the PM itself).
• InputDescriptor Defines the input required to task a sensor.
• SensorInformation Contains data access services:
  • DefaultDataService Provides the services (given by service URL and service type) which will be returned upon DescribeResultAccess with sensorID. This information is pure meta information about which services (URLs) of which type will most likely store the information gathered by the sensor. This allews clients to determine in advance wether they are capable of accessing the sensor data or not.
  • TaskDataAccess Contains information where the data gathered by a sensor in a certain task can be accessed from. If the DataServices element is omitted then the default services for that sensor serve the data of the task.

submit()

Performs the SPS Submit operation.

Within this method you can unpack the sent tasking parameters from the given SubmitDocument argument and resolve them via InputResolver of the SPS.

Optional methods

The following methods are optional and implementation can be opmitted if the functionality will not be needed.

getAvailableFeasibilityIDs()

Use this method to determine which cached feasibility request data is currently available. The service will use this method at startup to initialize the RequestMapper.

This method does not have to be overwritten if the sensor does not cache feasibility information from past GetFeasibility requests.

getAvailableTaskIDs()

Use this method to determine which tasks are currently available. The service will use this method at startup to initialize the RequestMapper.

This method does not have to be overwritten if the sensor does not cache task information from past Submit requests.

getFeasibility()

Performs the SPS GetFeasibility operation.

This method has to be implemented according to SPS specification unless the operation itself is not supported by the sensor. Default behaviour is to return a ServiceException that contains an OGC Exception with exceptionCode NoApplicableCode as well as a textual description which indicates that the operation is not supported by the sensor.

getIdGenerator()

Gets the ID generator this sensor uses to create new taskIDs and feasibilityIDs.

getStatus()

Perform the SPS GetStatus operation.

This method has to be implemented according to SPS specification unless the operation itself is not supported by the sensor.

Default behaviour is to return a ServiceException that contains an OGC Exception with exceptionCode NoApplicableCode as well as a textual description which indicates that the operation is not supported by the sensor.

getSensorConfiguration()

The sps, this sensor is running in will use this method to retrieve a xml encoded configuration file. This file contains all information necessary to restore the current state of this sensor. The format of the configuration file is up to the implementer of the implementing class. The file could contain full configuration information or just point to where to get more information (e.g. the location of the classes properties file or a database).

This method will most probably be called before the SPS is shut down so that the services state can be persisted and be restored at next startup.

This method does not need to be overwritten if the sensor does not need a configuration file for performing its tasks.

Default behaviour is to return null.

getSensorStatus()

Used to receive status information about this sensor.

This method does not need to be overwritten if the sensor does not save any information about submitted tasks.

Default behaviour is to return null.

prepareShutdown()

Calling this method indicates that the service is about to be shut down.

The sensor is responsible to block the creation of new tasks (i.e. to deem all incoming feasibility requests as not feasible, as well as all incoming submit requests) and delay all ongoing tasks. The sensor shall state "SPS service was shut down" when notifying the user of a task that is about to be delayed now.

The sensor should release all resources that might remain in memory if not being explicitly released (e.g. threads that have been started and are not daemons).

This method does not need to be overwritten if there is no need to perform special actions before shutdown.

Default behaviour is to ignore the request.

update()

Performs the SPS Update operation.

This method has to be implemented according to SPS specification unless the operation itself is not supported by the sensor.

Default behaviour is to return a ServiceException that contains an OGC Exception with exceptionCode NoApplicableCode as well as a textual description which indicates that the operation is not supported by the sensor.

updateSensor()

This operation is performed if the service provider wants to update an SPSSensor.

Overwrite if the sensor supports an update of its internal configuration.

If not needeed, null must be returned.

WNS methods (optional)

getWNSHandler()

handleCommunicationMessage()

handleCommunicationMessage()

handleMessage()

handleNotificationMessage() (overloaded)

handleReplyMessage() (overloaded)

FAQ

We want a table of contents for the FAQ. To get rid of a confusing and overloaded table of contents the FAQ gets its own

• FAQ page