Revision History | ||
---|---|---|
Revision 1.00 | 2004-03-10 | YA |
initial draft | ||
Revision 1.01 | 2004-03-12 | DR |
edit and DocBook translation |
Abstract
This document describes the procedures for taking advantage of the Filter Encoding (FE) support in WFS GetFeature requests that has been added to MapServer 4.1.
Last Updated: 2004-03-12
Table of Contents
"A filter expression is a construct used to constraints the property values of an object type for the purpose of identifying a subset of object instances to be operated upon in some manner...For example, a web feature service may use the XML filter encoding in a GetFeature operation to define query constraints." | ||
--Filter Encoding Implementation Specification, OGC |
This document assumes that you are already familiar with the following aspects of MapServer:
MapServer application development and setting up .map files.
Familiarity with the WFS specification would be an asset. A link to the WFS specification document is included in the Links to FE-Related Information section below.
Filter Encoding Implementation Specification at http://www.opengis.org/docs/02-059.pdf.
Open GIS Consortium (OGC) home page at http://www.opengis.org/.
MapServer WFS Server HOWTO at http://mapserver.gis.umn.edu/doc40/wfs-server-howto.html.
The following table lists the currently supported features for FE.
Table 1. Currently Supported Features
Feature Set | Feature |
---|---|
Spatial Capabilities | BBox |
Scalar Capabilities | |
Logical Operators | And |
Or | |
Not | |
Comparison Operators | PropertyIsEqualTo (=) |
PropertyIsNotEqualTo (<>) | |
PropertyIsLessThan (<) | |
PropertyIsGreaterThan (>) | |
PropertyIsLessThanOrEqualTo (<=) | |
PropertyIsGreaterThanOrEqualTo (>=) | |
PropertyIsLike | |
PropertyIsBetween (range) |
MapServer already has the capability to receive and parse Get requests and URL-encoded Post requests. The ability for MapServer to be able to receive Post requests with XML-encoded information sent in the body of the request has been added. Also, the ability to generate XML-encoded Post requests for WFS layers has been added.
Both Get and Post request are now supported for all WFS requests:
GetCapabilities
GetFeatures
DescribeFeatureType
Supporting these WFS requests in Post was implemented to keep consistency between all supported WFS requests.
When sending requests, the default request method used is Post. To change this behavior, we have introduced a layer level meta data, wfs_request_method, which can be set to "GET".
This section describes how to use FE on both the server and client sides.
To be able to use Filter Encoding, you need to create a valid WFS server using MapServer. Please refer to the WFS HowTo for specifics.
There is nothing special that should be added to a WFS server for Filter Encoding, but you should note that, when requesting the capabilities of your WFS server, the document returned should contain the supported filters. Here is part of a Capabilities document as well as the Post support:
<?xml version='1.0' encoding="ISO-8859-1" ?> <WFS_Capabilities version="1.0.0" updateSequence="0" xmlns="http://www.opengis.net/wfs" xmlns:ogc="http://www.opengis.net/ogc" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.opengis.net/wfs http://ogc.dmsolutions.ca/wfs/1.0.0/WFS-capabilities.xsd"> <!-- MapServer version 4.1 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP OUTPUT=PDF OUTPUT=SWF SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT INPUT=POSTGIS INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE --> <Service> <Name>MapServer WFS</Name> <Title>GMap WMS Demo Server</Title> <OnlineResource>http://localhost/cgi-bin/mapserv.exe?map= c:/msapps/wfs_filter/htdocs/ns_wfsserver.map&</OnlineResource> </Service> <Capability> <Request> <GetCapabilities> <DCPType> <HTTP> <Get onlineResource="http://localhost/cgi-bin/mapserv.exe?map= c:/msapps/wfs_filter/htdocs/ns_wfsserver.map&" /> </HTTP> </DCPType> <DCPType> <HTTP> <Post onlineResource="http://localhost/cgi-bin/mapserv.exe?map= c:/msapps/wfs_filter/htdocs/ns_wfsserver.map&" /> </HTTP> </DCPType> </GetCapabilities> ... </Request> </Capability> ... <Filter_Capabilities> <Spatial_Capabilities> <Spatial_Operators> <Intersect/> <DWithin/> <BBOX/> </Spatial_Operators> </Spatial_Capabilities> <Scalar_Capabilities> <Logical_Operators /> <Comparison_Operators> <Simple_Comparisons /> <Like /> <Between /> </Comparison_Operators> </Scalar_Capabilities> </Filter_Capabilities> </WFS_Capabilities>
To be able to generate a Filter to a WFS server, a layer level metadata called wfs_filter has been added, which should contain the filter to be sent to the server. Following is an example of a valid WFS client layer with a filter:
LAYER NAME popplace METADATA "wfs_filter" "<PropertyIsGreaterThan><PropertyName>POP_RANGE</PropertyName><Literal>4 </Literal></PropertyIsGreaterThan>" END TYPE POINT STATUS ON PROJECTION "init=epsg:42304" END CONNECTIONTYPE WFS CONNECTION "http://www2.dmsolutions.ca:8090/cgi-bin/mswfs_filter?SERVICE=WFS&VERSION=1.0.0 &TYPENAME=popplace" LabelItem "Name" # LabelItem "Pop_range" CLASSITEM "Capital" CLASS TEMPLATE "ttt_query.html" SYMBOL 2 SIZE 8 NAME "Cities" LABEL COLOR 255 0 0 FONT fritqat-italic TYPE truetype SIZE 8 POSITION AUTO #PARTIALS FALSE OUTLINECOLOR 255 255 255 FORCE TRUE END COLOR 0 0 0 END TOLERANCE 5 END # Layer
Things to note:
The filter given as a value of the wfs_filter metadata should not contain <Filter> start and end tags.
The CONNECTION points to a valid WFS server supporting filters
The returned shapes will be drawn using the class defined in the layer.
A few limitations have been introduced due to compatibility issues during implementation:
BBOX and PropertyIsLike filters: currently these filters are only valid if they are used by themselves or with a logical operator AND. For example valid filters are:
<BBOX><PropertyName>Name>NAME</PropertyName><Box+srsName='EPSG:42304'><coordinates>1998000, -93300+2950396,547400</coordinates></Box></BBOX>
<AND><BBOX><PropertyName>Name>NAME</PropertyName><Box+srsName='EPSG:42304'><coordinates>1998000, -93300+2950396,547400</coordinates></Box></BBOX><PropertyIsEqual><PropertyName> NAME</PropertyName><Literal>Digby</Literal></PropertyIsEqual></AND>
<PropertyIsLike%20wildCard="*"%20singleChar="."%20escapeChar="!"><PropertyName> NAME</PropertyName><Literal>Syd*</Literal></PropertyIsLike>
<AND><BBOX><PropertyName>Name>NAME</PropertyName><Box+srsName='EPSG:42304'><coordinates>1998000, -93300+2950396,547400</coordinates></Box></BBOX><PropertyIsLike%20wildCard="*"%20singleChar="." %20escapeChar="!"><PropertyName>NAME</PropertyName><Literal>Syd*</Literal></PropertyIsLike></AND>
Tests using MapServer as a WFS client and a WFS server are available at http://www2.dmsolutions.ca/msapps/wfs_fe/.
The OGC conformance tests (http://cite.occamlab.com/tsOGC/) have been run on the FE support. The following table and notes reflect the current status.
Table 2. WFS OGC test suite (over the HTTP Get and Post method)
# | Description | # of Tests | # of Failed Tests |
---|---|---|---|
1 | Basic WFS tests over the HTTP Get and Post method | 402 | 281 |
1.1 | GetCapabilities | 16 | 0 |
1.2 | DescribeFeatureType | 18 | 0 |
1.3 | GetFeature | 368 | 281 |
1.3.1 | Basic WFS tests | 20 | 1 |
1.3.2 | Complex WFS tests | 18 | 18 |
1.3.3 | Arithmetic filter WFS tests | 8 | 8 |
1.3.4 | Comparison WFS tests | 50 | 26 |
1.3.4.1 | GetFeature PropertyIsGreaterThanOrEqualTo filter | 2 | 0 |
1.3.4.2 | GetFeature PropertyIsBetween filter | 6 | 2 |
1.3.4.3 | GetFeature PropertyIsEqualTo filter | 4 | 0 |
1.3.4.4 | GetFeature PropertyIsGreaterThan filter | 4 | 2 |
1.3.4.5 | GetFeature PropertyIsGreaterThanOrEqualTo filter | 6 | 6 |
1.3.4.6 | GetFeature PropertyIsLessThan filter | 6 | 4 |
1.3.4.7 | GetFeature PropertyIsLessThanOrEqualTo filter | 6 | 4 |
1.3.4.8 | GetFeature PropertyIsLike filter | 2 | 0 |
1.3.4.9 | GetFeature PropertyIsNotEqualTo filter | 6 | 0 |
1.3.4.10 | GetFeature PropertyIsNull filter | 8 | 8 |
1.3.5 | Logical WFS test | 20 | 0 |
1.3.5.1 | GetFeature AND PropertyIsEqualTo PropertyIsEqualTo filter | 8 | 0 |
1.3.5.2 | GetFeature OR PropertyIsEqualTo PropertyIsEqualTo filter | 8 | 0 |
1.3.5.3 | GetFeature NOT PropertyIsNotEqualTo filter | 4 | 0 |
1.3.6 | Spatial operator WFS test | 252 | 228 |
1.3.6.1 | GetFeature BBOX filter | 36 | 12 |
1.3.6.2 | GetFeature with other filter types | 216 | 216 |
2 | Transactional WFS test | 69 | 69 |
The OGC Cite WFS test suite can be found on the OGC Cite portal (The Open Group; (2002), Test Requirements and Assertions for WFS 1.0.0).
A extensive description of the tests can also be found on the OGC portal (The Open Group; (2003), How to test a Web Feature Service 1.0.0 service).
Test number 1.3.1:
There is a contradiction between the wfs/1.0.0/basic/getfeature/post/3 assertion and the XPath expected value of the test. The assertion says: "Test that a GetFeature request with no output format defined returns a wfs:FeatureCollection with GML data." and the expected XPath value for this request: "boolean(/ogc:ServiceExceptionReport)" is supposed to be true. So, the assertion means that when a WFS server receives a request which contains an undefined output format or no output format at all, the WFS server must return a WFS collection containing GML data. The XPath expected value means that when a WFS server receives a request with an undefined output format or no output format at all, the WFS server must return a service exception report.
Tests number 1.3.2 and 1.3.3:
Not supported.
Tests number 1.3.4.2, 1.3.4.4 to 1.3.4.7 (see bug 461 on MapServer Web site):
The string comparison is not supported using >, <, >=, <=.
The date comparison is not supported.
Test number 1.3.4.10:
This property is not supported in MapServer.
Test number 1.3.6.1 (see bug 461 on MapServer Web site):
The returned feature xml won't validate because the validation is done against a specific xsd (geomatry.xsd).
The data conversion on multipoints and multilayers are not supported within gdal.
Test number 2:
The transaction requests are not supported.
Copyright (c) 2004, Yewondwossen Assefa, DM Solutions Group Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.