.. $Id$
===========================================================================
Copyright (c) 2005 Jeff McKenna, 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.
===========================================================================
..
*****************************************************************************
MapServer Filter Encoding (FE) HOWTO - Version 4.6
*****************************************************************************
:Author: Jeff McKenna
:Contact: jmckenna@dmsolutions.ca
:Author: Yewondwossen Assefa
:Contact: assefa@dmsolutions.ca
:Revision: $Revision$
:Last Updated: $Date$
.. The next heading encountered becomes our H2
..
.. sectnum::
.. contents:: Table of Contents
:depth: 2
:backlinks: top
Introduction
============
This document describes the procedures for taking advantage of the Filter
Encoding (FE) support in WFS GetFeature requests, which was added to
MapServer in version 4.2.
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. Links to the
MapServer WFS documents are included in the next section.
Links to SLD-related Information
--------------------------------
- `Filter Encoding Implementation Specification`_.
- `MapServer WFS Client HOWTO`_.
- `MapServer WFS Server HOWTO`_.
- `Open GIS Consortium (OGC) home page`_.
.. _`Filter Encoding Implementation Specification`: http://www.opengeospatial.org/docs/02-059.pdf
.. _`MapServer WFS Client HOWTO`: http://ms.gis.umn.edu/docs/howto/wfs_client
.. _`MapServer WFS Server HOWTO`: http://ms.gis.umn.edu/docs/howto/wfs_server
.. _`Open GIS Consortium (OGC) home page`: http://www.opengeospatial.org
Currently Supported Features
============================
The following table lists the currently supported features for FE.
**Table 1. Currently Supported Features**
+----------------------+-------------------------------------+
| Feature Set | Feature |
+======================+=====================================+
| Spatial Capabilities | |
+----------------------+-------------------------------------+
| | BBox |
| +-------------------------------------+
| | Intersects |
| +-------------------------------------+
| | DWithin |
+----------------------+-------------------------------------+
| Scalar Capabilities | |
+----------------------+-------------------------------------+
| | |
+----------------------+-------------------------------------+
| Logical Operators | |
+----------------------+-------------------------------------+
| | And |
| +-------------------------------------+
| | Or |
| +-------------------------------------+
| | Not |
+----------------------+-------------------------------------+
| Comparison Operators | |
+----------------------+-------------------------------------+
| | PropertyIsNotEqualTo (<>) |
| +-------------------------------------+
| | PropertyIsLessThan (<) |
| +-------------------------------------+
| | PropertyIsGreaterThan (>) |
| +-------------------------------------+
| | PropertyIsLessThanOrEqualTo (<=) |
| +-------------------------------------+
| | PropertyIsGreaterThanOrEqualTo (>=) |
| +-------------------------------------+
| | PropertyIsLike |
| +-------------------------------------+
| | PropertyIsBetween (range) |
+----------------------+-------------------------------------+
Get and Post Requests
=====================
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".
Use of Filter Encoding in MapServer
===================================
This section describes how to use FE on both the server and client sides.
Server Side
-----------
To be able to use Filter Encoding, you need to create a valid WFS server using
MapServer. Please refer to the `WFS Server HOWTO`_ for specifics.
.. _`WFS Server HOWTO`: http://ms.gis.umn.edu/docs/howto/wfs_server
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:
::
MapServer WFS
GMap WMS Demo Server
http://localhost/cgi-bin/mapserv.exe?map=
c:/msapps/wfs_filter/htdocs/ns_wfsserver.map&
...
...
Client Side
-----------
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_version" "1.0.0"
"wfs_typename" "popplace"
"wfs_filter" "POP_RANGE
4"
END
TYPE POINT
STATUS ON
PROJECTION
"init=epsg:42304"
END
CONNECTIONTYPE WFS
CONNECTION "http://www2.dmsolutions.ca:8090/cgi-bin/mswfs_filter?"
LabelItem "Name"
CLASSITEM "Capital"
CLASS
SYMBOL 2
SIZE 8
NAME "Cities"
LABEL
COLOR 255 0 0
FONT fritqat-italic
TYPE truetype
SIZE 8
POSITION AUTO
OUTLINECOLOR 255 255 255
FORCE TRUE
END
COLOR 0 0 0
END
END # Layer
*Note:*
- The filter given as a value of the wfs_filter metadata should not contain
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.
Limitations
===========
- A limited set of spatial operators are supported.
Tests
=====
Here are some test URLs for the different supported filters:
- `PropertyIsEqualTo`_
::
http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&
TYPENAME=popplace&Filter=NAME
Digby
- `PropertyIsNotEqualTo`_
::
http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&
TYPENAME=popplace&Filter=NAME
Digby
- `PropertyIsLessThan`_
::
http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&
TYPENAME=popplace&Filter=POP_RANGE
2
- `PropertyIsGreaterThan`_
::
http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&
TYPENAME=popplace&Filter=POP_RANGE
5
- `PropertyIsLessThanOrEqualTo`_
::
http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&
TYPENAME=popplace&Filter=POP_RANGE
2
- `PropertyIsGreaterThanOrEqualTo`_
::
http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&
TYPENAME=popplace&Filter=POP_RANGE
5
- `PropertyIsBetween`_
::
http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&
TYPENAME=popplace&Filter=POP_RANGE
56
- `PropertyIsLike`_
::
http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&
TYPENAME=popplace&Filter=
NAMESyd*
- `Logical operator OR`_
::
http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&
TYPENAME=popplace&Filter=NAME
SydneyNAME
Digby
- `Logical operator AND`_
::
http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&
TYPENAME=popplace&Filter=
NAMESyd*
POP_RANGE4
- `Logical operator NOT`_
::
http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&
TYPENAME=popplace&Filter=POP_RANGE
2POP_RANGE
3
- `Spatial operator BBOX`_
::
http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&
Filter=Name>NAME
2518000,150000 2918000,450000
- `Spatial operator Dwithin`_
::
http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&Filter=
Geometry2587598.000000,404010.531250
1000
- `Spatial operator Intersects`_
::
http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&Filter=
Geometry
2488789,289552 2588789,289552 2588789,389552 2488789,389552 2488789,289552
.. _`PropertyIsEqualTo`: http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&Filter=NAMEDigby
.. _`PropertyIsNotEqualTo`: http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&Filter=NAMEDigby
.. _`PropertyIsLessThan`: http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&Filter=POP_RANGE2
.. _`PropertyIsGreaterThan`: http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&Filter=POP_RANGE5
.. _`PropertyIsLessThanOrEqualTo`: http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&Filter=POP_RANGE2
.. _`PropertyIsGreaterThanOrEqualTo`: http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&Filter=POP_RANGE5
.. _`PropertyIsBetween`: http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&Filter=POP_RANGE56
.. _`PropertyIsLike`: http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&Filter=NAMESyd*
.. _`Logical operator OR`: http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&Filter=NAMESydneyNAMEDigby
.. _`Logical operator AND`: http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&Filter=NAMESyd*POP_RANGE4
.. _`Logical operator NOT`: http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&Filter=POP_RANGE2POP_RANGE3
.. _`Spatial operator BBOX`: http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&Filter=Name>NAME2518000,150000%202918000,450000
.. _`Spatial operator Dwithin`: http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&Filter=Geometry2587598.000000,404010.5312501000
.. _`Spatial operator Intersects`: http://www2.dmsolutions.ca/cgi-bin/mswfs_filter?&VERSION=1.0.0&SERVICE=WFS&REQUEST=GetFeature&TYPENAME=popplace&Filter=Geometry2488789,289552%202588789,289552%202588789,389552%202488789,389552%202488789,289552
- 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)**
======== ========================================================= ========== =================
Test # 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`_.
.. _`OGC Cite portal`: http://cite.occamlab.com/test_engine/wfs_1_0_0/wfs_1_0_0.html
Following are some MapServer specific notes on this test suite:
1. *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.
2. *Tests number 1.3.2 and 1.3.3*:
- Not supported.
3. *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.
4. *Test number 1.3.4.10*:
- This property is not supported in MapServer.
5. *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.
6. *Test number 2*:
- The transaction requests are not supported.
About This Document
===================
Copyright Information
---------------------
Copyright (c) 2005, Yewondwossen Assefa, Jeff McKenna.
This documentation is covered by the same Open Source license as the MapServer
software itself. See MapServer's `License and Credits`__ page for the complete
text.
__ http://mapserver.gis.umn.edu/license.html
Disclaimer
----------
No liability for the contents of this document can be accepted.
Use the concepts, examples and other content at your own risk.
As this is a new edition of this document, there may be errors
and inaccuracies that may be damaging to your system.
Although this is highly unlikely, the author(s) do not take any
responsibility for that: proceed with caution.