DAC installation guide (final).doc
The Tomcat WaterML2 service is hosted in a Tomcat service container. This service allows REST clients to interact with a WaterML2 service that is connected to a FEWS system through the FEWS DataAccessComponent. With this API the REST client can retrieve data from the FEWS system. Before a client application can access the FEWS system there is some configuration work that needs to be done.
http://localhost:8081/WaterMlService/waterml?request=GetCapabilities |
The GetCapabilities request returns a document describing the operations supported by this webservice.
<?xml version="1.0" encoding="UTF-8"?> <sos:Capabilities xmlns:sos="http://www.opengis.net/sos/2.0" xmlns:oost="http://www.oostethys.org/schemas/0.1.0/oostethys" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ows="http://www.opengis.net/ows/1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:gml="http://www.opengis.net/gml" xmlns:swe="http://www.opengis.net/swe/1.0.1" xmlns:ogc="http://www.opengis.net/ogc" xsi:schemaLocation="http://www.opengis.net/sos/1.0 http://schemas.opengis.net/sos/2.0.0/sosGetCapabilities.xsd" version="2.0.0"> <ows:ServiceIdentification> <ows:Title></ows:Title> <ows:ServiceType>OGC:SOS</ows:ServiceType> <ows:ServiceTypeVersion>2.0.0</ows:ServiceTypeVersion> <ows:Fees>None</ows:Fees> <ows:AccessConstraints>None</ows:AccessConstraints> </ows:ServiceIdentification> <ows:ServiceProvider> <ows:ProviderName></ows:ProviderName> <ows:ProviderSite xlink:href=""/> <ows:ServiceContact> <ows:IndividualName></ows:IndividualName> <ContactInfo> <ows:Address> <ows:DeliveryPoint></ows:DeliveryPoint> <ows:City></ows:City> <ows:PostalCode></ows:PostalCode> <ows:Country></ows:Country> <ows:ElectronicMailAddress></ows:ElectronicMailAddress> </ows:Address> </ContactInfo> </ows:ServiceContact> </ows:ServiceProvider> <ows:OperationsMetadata> <ows:Operation name="GetCapabilities"> <ows:DCP> <ows:HTTP> <ows:Get xlink:href="http://localhost:8081/WaterMlService/waterml?request=GetCapabilities"/> </ows:HTTP> </ows:DCP> <ows:Parameter name="service"> <ows:AllowedValues> <ows:Value>SOS</ows:Value> </ows:AllowedValues> </ows:Parameter> <ows:Parameter name="version"> <ows:AllowedValues> <ows:Value>1.0.0</ows:Value> </ows:AllowedValues> </ows:Parameter> </ows:Operation> <ows:Operation name="GetFeature"> <ows:DCP> <ows:HTTP> <ows:Get xlink:href="http://localhost:8081/WaterMlService/waterml?request=GetFeature"/> </ows:HTTP> </ows:DCP> <ows:Parameter name="service"> <ows:AllowedValues> <ows:Value>SOS</ows:Value> </ows:AllowedValues> </ows:Parameter> <ows:Parameter name="version"> <ows:AllowedValues> <ows:Value>1.0.0</ows:Value> </ows:AllowedValues> </ows:Parameter> </ows:Operation> <ows:Operation name="GetObservation"> <ows:DCP> <ows:HTTP> <ows:Get xlink:href="http://localhost:8081/WaterMlService/waterml?request=GetObservation"/> <ows:Post xlink:href="http://localhost:8081/WaterMlService/waterml?request=GetObservation"/> </ows:HTTP> </ows:DCP> <ows:Parameter name="service"> <ows:AllowedValues> <ows:Value>SOS</ows:Value> </ows:AllowedValues> </ows:Parameter> <ows:Parameter name="version"> <ows:AllowedValues> <ows:Value>1.0.0</ows:Value> </ows:AllowedValues> </ows:Parameter> <ows:Parameter name="request"> <ows:AllowedValues> <ows:Value>GetObservation</ows:Value> </ows:AllowedValues> </ows:Parameter> <ows:Parameter name="featureId"> <ows:AllowedValues> <ows:Value>0</ows:Value> <ows:Value>1</ows:Value> <ows:Value>2</ows:Value> <ows:Value>3</ows:Value> <ows:Value>4</ows:Value> <ows:Value>5</ows:Value> <ows:Value>6</ows:Value> <ows:Value>7</ows:Value> </ows:AllowedValues> </ows:Parameter> <ows:Parameter name="observedProperty"> <ows:AllowedValues> <ows:Value>Parameter</ows:Value> <ows:Value>T.for</ows:Value> </ows:AllowedValues> </ows:Parameter> <ows:Parameter name="beginPosition"> <ows:AllowedValues> <ows:AnyValue/> </ows:AllowedValues> </ows:Parameter> <ows:Parameter name="endPosition"> <ows:AllowedValues> <ows:AnyValue/> </ows:AllowedValues> </ows:Parameter> <ows:Parameter name="analysisTime"> <ows:AllowedValues> <ows:AnyValue/> </ows:AllowedValues> </ows:Parameter> </ows:Operation> </ows:OperationsMetadata> </sos:Capabilities> |
http://localhost:8081/WaterMlService/waterml?request=GetFeature |
The GetFeature request returns a document containing a list of feature members supported by the webservice. A feature member corresponds to what is know in FEWS as Location.
<?xml version="1.0" encoding="UTF-8"?> <wfs:FeatureCollection xmlns:wfs="http://www.opengis.net/wfs/2.0" xmlns:gml="http://www.opengis.net/gml/3.2" xmlns:gsml="urn:cgi:xmlns:CGI:GeoSciML:2.0" xmlns:om="http://www.opengis.net/om/2.0" xmlns:sa="http://www.opengis.net/sampling/2.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wml2="http://www.opengis.net/waterml/2.0" xmlns:gmd="http://www.isotc211.org/2005/gmd" xmlns:sf="http://www.opengis.net/sampling/2.0" xmlns:sams="http://www.opengis.net/samplingSpatial/2.0" xsi:schemaLocation="http://www.opengis.net/om/2.0 ../observation.xsd http://www.opengis.net/gml/3.2 http://schemas.opengis.net/gml/3.2.1/gml.xsd http://www.opengis.net/sampling/2.0 ../samplingFeature.xsd http://www.opengis.net/waterml/2.0 ../waterml2.xsd http://www.opengis.net/swe/2.0 http://schemas.opengis.net/sweCommon/2.0/swe.xsd"> <wfs:member> <om:featureOfInterest> <wml2:WaterMonitoringPoint gml:id="0"> <sf:parameter> <om:NamedValue> <om:name xlink:title="Location name"/> <om:value>0</om:value> </om:NamedValue> </sf:parameter> <sams:shape> <gml:Point gml:id="0"> <gml:pos srcName="Rijks Driehoekstelsel">53.64671168116518 5.175518773508316</gml:pos> </gml:Point> </sams:shape> </wml2:WaterMonitoringPoint> </om:featureOfInterest> </wfs:member> <wfs:member> <om:featureOfInterest> <wml2:WaterMonitoringPoint gml:id="1"> <sf:parameter> <om:NamedValue> <om:name xlink:title="Location name"/> <om:value>1</om:value> </om:NamedValue> </sf:parameter> <sams:shape> <gml:Point gml:id="1"> <gml:pos srcName="Rijks Driehoekstelsel">53.3835058954904 4.560651062185197</gml:pos> </gml:Point> </sams:shape> </wml2:WaterMonitoringPoint> </om:featureOfInterest> </wfs:member> <wfs:member> <om:featureOfInterest> <wml2:WaterMonitoringPoint gml:id="2"> <sf:parameter> <om:NamedValue> <om:name xlink:title="Location name"/> <om:value>2</om:value> </om:NamedValue> </sf:parameter> <sams:shape> <gml:Point gml:id="2"> <gml:pos srcName="Rijks Driehoekstelsel">52.48257667744973 4.283120419290973</gml:pos> </gml:Point> </sams:shape> </wml2:WaterMonitoringPoint> </om:featureOfInterest> </wfs:member> <wfs:member> <om:featureOfInterest> <wml2:WaterMonitoringPoint gml:id="3"> <sf:parameter> <om:NamedValue> <om:name xlink:title="Location name"/> <om:value>3</om:value> </om:NamedValue> </sf:parameter> <sams:shape> <gml:Point gml:id="3"> <gml:pos srcName="Rijks Driehoekstelsel">51.493692036021535 3.0541898956873954</gml:pos> </gml:Point> </sams:shape> </wml2:WaterMonitoringPoint> </om:featureOfInterest> </wfs:member> <wfs:member> <om:featureOfInterest> <wml2:WaterMonitoringPoint gml:id="4"> <sf:parameter> <om:NamedValue> <om:name xlink:title="Location name"/> <om:value>4</om:value> </om:NamedValue> </sf:parameter> <sams:shape> <gml:Point gml:id="4"> <gml:pos srcName="Rijks Driehoekstelsel">50.99065599128154 3.0796721627765615</gml:pos> </gml:Point> </sams:shape> </wml2:WaterMonitoringPoint> </om:featureOfInterest> </wfs:member> <wfs:member> <om:featureOfInterest> <wml2:WaterMonitoringPoint gml:id="5"> <sf:parameter> <om:NamedValue> <om:name xlink:title="Location name"/> <om:value>5</om:value> </om:NamedValue> </sf:parameter> <sams:shape> <gml:Point gml:id="5"> <gml:pos srcName="Rijks Driehoekstelsel">51.01107956492021 4.6177610376887515</gml:pos> </gml:Point> </sams:shape> </wml2:WaterMonitoringPoint> </om:featureOfInterest> </wfs:member> <wfs:member> <om:featureOfInterest> <wml2:WaterMonitoringPoint gml:id="6"> <sf:parameter> <om:NamedValue> <om:name xlink:title="Location name"/> <om:value>6</om:value> </om:NamedValue> </sf:parameter> <sams:shape> <gml:Point gml:id="6"> <gml:pos srcName="Rijks Driehoekstelsel">50.59113044096123 5.4719202115344</gml:pos> </gml:Point> </sams:shape> </wml2:WaterMonitoringPoint> </om:featureOfInterest> </wfs:member> <wfs:member> <om:featureOfInterest> <wml2:WaterMonitoringPoint gml:id="7"> <sf:parameter> <om:NamedValue> <om:name xlink:title="Location name"/> <om:value>7</om:value> </om:NamedValue> </sf:parameter> <sams:shape> <gml:Point gml:id="7"> <gml:pos srcName="Rijks Driehoekstelsel">50.58761564487022 6.290845285636415</gml:pos> </gml:Point> </sams:shape> </wml2:WaterMonitoringPoint> </om:featureOfInterest> </wfs:member> </wfs:FeatureCollection> |
The GetObservations call supports two types of requests:
The HTTP-GET option supports the following URL parameters
http://localhost:8081/WaterMlService/waterml?request=GetObservation&featureId=1&observedProperty=Parameter&beginPosition=2013-02-01T00:00:00%2B01:00&endPosition=2013-03-01T00:00:00%2B01:00&analysisTime=2013-02-01T00:00:00%2B01:00 |
The HTTP-POST option is passed as a XML document containing the following elements:
featureOfInterest = This corresponds to the 'featureId' of the HTTP-GET request. It is possible to enter multiple location ids by entering multiple instances of item featureOfInterest.
observedProperty = This corresponds to the 'observedProperty' of the HTTP-GET request. It is possible to enter multiple parameter ids by entering multiple instances of item observedProperty.
<?xml version="1.0" ?> <sos:GetObservation version="2.0.0" service="SOS" maxFeatures="3" xmlns:sos="http://schemas.opengis.net/sos/2.0.0/" xmlns:wfs="http://www.opengis.net/wfs" xmlns:ogc="http://www.opengis.net/ogc" xmlns:gml="http://www.opengis.net/gml/3.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:om="http://www.opengis.net/om/2.0" xmlns:fes="http://www.opengis.net/fes/2.0" xmlns:xlink="http://www.w3.org/1999/xlink" xsi:schemaLocation="http://www.opengis.net/sos/2.0 http://schemas.opengis.net/sos/2.0.0/sos.xsd"> <sos:featureOfInterest>0</sos:featureOfInterest> <sos:observedProperty>T.for</sos:observedProperty> <sos:temporalFilter> <fes:During> <fes:ValueReference>phenomenonTime</fes:ValueReference> <gml:TimePeriod gml:id="tp_1"> <gml:beginPosition>2013-02-15T01:00:00.000+01:00</gml:beginPosition> <gml:endPosition>2013-03-01T01:00:00.000+01:00</gml:endPosition> </gml:TimePeriod> </fes:During> </sos:temporalFilter> <sos:temporalFilter> <fes:TEquals> <fes:ValueReference>analysisTime</fes:ValueReference> <gml:TimeInstant gml:id="ti_2"> <gml:timePosition>2013-03-02T00:00:00.000+01:00</gml:timePosition> </gml:TimeInstant> </fes:TEquals> </sos:temporalFilter> </sos:GetObservation> |
Secondly the HTTP-POST request where the request is written as a XML document.
Returns a pi timeseries xml file containing the timeseries data belonging to the filter defined by the 'filterId'.
The 'convertDatum' argument is to allow timeseries that support a global datum to have their values converted from a value relative to the location height to an absolute value.
The PiVersion defines the format of the return file content. If omitted the latest version of the Pi file format will be used. (Expected 1.9 or higher).
QueryParameters is defined by following schema definition:
<xs:complexType name="queryParameters"> <xs:sequence> <xs:element name="convertDatum" type="xs:boolean"></xs:element> <xs:element name="endCreationTime" type="xs:dateTime" minOccurs="0"></xs:element> <xs:element name="endTime" type="xs:dateTime" minOccurs="0"></xs:element> <xs:element name="filterId" type="xs:string" minOccurs="0"></xs:element> <xs:element name="forecastTime" type="xs:dateTime" minOccurs="0"></xs:element> <xs:element name="locationIds" type="xs:string" nillable="true" minOccurs="0" maxOccurs="unbounded"></xs:element> <xs:element name="omitMissing" type="xs:boolean"></xs:element> <xs:element name="onlyHeaders" type="xs:boolean"></xs:element> <xs:element name="parameterIds" type="xs:string" nillable="true" minOccurs="0" maxOccurs="unbounded"></xs:element> <xs:element name="piVersion" type="xs:string" minOccurs="0"></xs:element> <xs:element name="showThresholds" type="xs:boolean"></xs:element> <xs:element name="startCreationTime" type="xs:dateTime" minOccurs="0"></xs:element> <xs:element name="startTime" type="xs:dateTime" minOccurs="0"></xs:element> <xs:element name="useDisplayUnits" type="xs:boolean"></xs:element> </xs:sequence> </xs:complexType> |
Returns a pi timeseries xml file containing the timeseries data belonging to the query parameters defined in the query parameters object.
The PiVersion defines the format of the return file content. If omitted the latest version of the Pi file format will be used. (Expected 1.9 or higher).
void putTimeSeriesForFilters(String clientId, String piTimeSeriesXmlContent, byte[] piTimeSeriesBinaryContent, boolean convertDatum); |
Write timeseries data to the FEWS system using the timeseries sets defined by the filters.
For performance reasons it is possible to split the timeseries header information from the timeseries data. The header information is stored in the piTimeSeriesXmlContent and the timeseries data is stored in the piTimeSeriesBinaryContent. If both header information and data is stored in the XML content the the 'piTimeSeriesBinaryContent' argument can be null.
The 'convertDatum' argument is to allow timeseries that support a datum to have their values converted to a value
relative to the location height. If values are already relative to location then enter FALSE or omit.
The file DAC installation guide (final).doc describes how to install a Tomcat instance containing a DataAccessComponent instance. Once these steps are completed the FewsPiService.WAR can be deployed using a context xml file such as FewsPiService.xml
The are two levels of configuration. The first is the DataAccessComponent which is a FEWS client hosted as a GlobalResource in Tomcat. The DataAccessComponent uses the regular FEWS configuration which falls outside the scope of this documentation. The second level of configuration is what is used by the FewsPiService webservice which has been deployed in Tomcat. To deploy this webservice a context XML file is required which looks like this:
<?xml version="1.0" encoding="UTF-8"?> <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> <!-- Location of specific AI war file. (Can be a symlink) --> <Context docBase="${catalina.home}/fews/FewsPiService.war" antiJARLocking="true" crossContext="true" > <!—- 'clientConfigFileId' points to a FEWS configuration file in de FEWS configuration directory 'PiClientConfigFiles'. --> <Parameter name="clientConfigFileId" value="FewsPiService.properties" override="false"/> <!—- resourceId must match the 'name' of 'ResourceLink' below --> <Parameter name="resourceId" value="DAC" override="false"/> <Parameter name="serviceName" value="FewsPiServiceImpl" override="false"/> <Parameter name="namespaceUri" value="http://fewpiservice.wldelft.nl" override="false"/> <Parameter name="portName" value="FewsPiServiceImplPort" override="false"/> <!—- 'fewspi_config_naam' must match the file name of this configuration file without the XML extension. --> <Parameter name="wsdl" value="http://localhost:8080/FewsPiService/fewspiservice?wsdl" override="false"/> <!—- Global 'fews_dac' must be the same as the DAC resource name in the file 'server.xml'--> <ResourceLink name="DAC" global="fews_dac" type="nl.wldelft.fews.system.data.dac.DataAccessComponent"/> <Loader loaderClass="nl.wldelft.fews.system.data.dac.DacClassLoader" delegate="true"/> </Context> |
In the above configuration example you see a number of 'Parameter' values which will be explained below:
The next parameters have been added for the FewsPiService test page. This is the page that appears when browsing to the root URI of the FewsPiService. Technically these parameters would not be required, but because it is a 'test' page, the configuration has not been optimized yet.
This is a simple text configuration file that is located in the FEWS configuration in the directory:
%REGION_HOME%/Config/PiClientConfigFiles/FewsPiService.properties |
In the above example the clientConfigFileId would be FewsPiService.properties.
This properties file can contain the following configuration items:
\# This file must be placed in the FEWS configuration folder Config/PiClientConfigFiles. \# It is referenced by the FewsPiService webservice through the parameter 'clientConfigFileId' in the service context.xml file. \# Note that all id references are case sensitive. \# This element defines the root filter id for the webservice (type = string). \# If omitted the FewsPiService will try to retrieve the defaultFilterId from the Filters.xml. FILTER_ID=My_FilterId \# Identifier of the flag conversion file to use when extracting timeseries from the FewsPiService (type = string). \# If omitted no flag conversion takes place EXPORT_FLAGCONVERSION_ID=My_Export_FlagConversion \# Identifier of the unit conversion file to use when extracting timeseries from the FewsPiService (type = string). \# If omitted no unit conversion takes place EXPORT_UNITCONVERSION_ID=My_Export_UnitConversion \# Identifier of the id map file to use when extracting timeseries from the FewsPiService (type = string). \# If omitted no id mapping takes place \#EXPORT_IDMAP_ID=My_Export_IdMap \# Identifier of the unit conversion file to use when writing timeseries to the FewsPiService (type = string). \# If omitted no unit conversion takes place IMPORT_UNITCONVERSION_ID=My_Import_UnitConversion \# Identifier of the id map file to use when writing timeseries to the FewsPiService (type = string). \# If omitted no id mapping takes place IMPORT_IDMAP_ID=My_Import_IdMap \# Export missing value. All internal NaN values will be mapped to this value (type = float). \# If omitted the default value \-999 will be used. MISSING_VALUE=-999 \# Option to skip the export of missing values when reading timeseries from the FewsPiService (type = true/false). \# If omitted the default value 'true' is used. OMIT_MISSING_VALUES=true \# Default time zone. \# If omitted the computer time zone is used. TIME_ZONE=GMT |
Here follows a explanation of these parameters. By the way everything is case sensitive:
See soap-example-calls.zip for examples SOAP client calls.