.. $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 WFS Client HOWTO - Version 4.6
*****************************************************************************
:Author: Jean-François
:Contact: jdoyon@nrcan.gc.ca
:Author: Jeff McKenna
:Contact: jmckenna@dmsolutions.ca
:Revision: $Revision$
:Last Updated: $Date$
.. The next heading encountered becomes our H2
..
.. sectnum::
.. contents:: Table of Contents
:depth: 2
:backlinks: top
Introduction
============
A WFS ( Web Feature Service ) publishes feature-level geospatial data to the
web. This means that it is possible to use this data as a data source to
render a map. In effect, this is not unlike having a shapefile accessible
over the web, only it's not a shapefile, it's XML-Encoded geospatial data
(GML to be exact), including both geometry AND attribute information.
WFS-Related Information
-----------------------
Although in-depth understanding of WFS and GML is neither necessary nor
required in order to implement a MapServer application that reads remote
WFS data, it is recommended to at least get aquainted with the concepts and
basic functionality of both. Here are the official references (including a
newly added OGC workshop with MapServer):
- `OGC Web Feature Service Implementation Specification`_.
- `Geography Markup Language Implementation Specification`_.
- `MapServer OGC Web Services Workshop package`_.
.. _`OGC Web Feature Service Implementation Specification`: https://portal.opengeospatial.org/files/?artifact_id=7176
.. _`Geography Markup Language Implementation Specification`: https://portal.opengeospatial.org/files/?artifact_id=7174
.. _`MapServer OGC Web Services Workshop package`: http://devgeo.cciw.ca/ms_ogc_workshop/index.html
Software Requirements
---------------------
In order to enable MapServer to serve WFS, it MUST be compiled against certain librairies:
- PROJ.4: The reprojection library. Version 4.4.3 or greater is required.
- GDAL/OGR: I/O support librairies. Version 1.1.8 or greater is required.
- LibCURL: Used to help MapServer act as an HTTP client. Version 7.10 or greater is required.
Please see the MapServer UNIX Compilation and Installation HOWTO for detailed instructions
on compiling mapserver with support for these librairies and features. For Windows users,
look on the MapServer website to see if there are any binaries available that meet these
requirements.
Setting up a WFS-client Mapfile
===============================
Storing Temporary Files
-----------------------
You must set the IMAGEPATH_ parameter in your mapfile since MapServer uses this
directory to store temporary files downloaded from the remote WFS server.
.. _IMAGEPATH: http://mapserver.gis.umn.edu/doc/mapfile-reference.html#web
::
MAP
...
WEB
IMAGEPATH "/tmp/ms_tmp/"
IMAGEURL ...
END
...
END
WFS Layer
---------
A WFS layer is a regular mapfile layer, which can use CLASS objects, with
expressions, etc.
As of MapServer 4.4, the suggested method to define a WFS Client layer is through
the CONNECTION parameter and the layer's METADATA. The necessary mapfile parameters
are defined below:
- *CONNECTIONTYPE*: must be "wfs"
- *CONNECTION*: The URL to the WFS Server. e.g. http://www2.dmsolutions.ca/cgi-bin/mswfs_gmap?
The path to the mapfile on the WFS server is required if it was required in the
GetCapabilities request e.g. you would have to specify the MAP parameter in the
CONNECTION for the following server:
`http://map.ns.ec.gc.ca/MapServer/mapserv.exe?MAP=/mapserver/services/envdat/config.map`_
`&SERVICE=WFS&VERSION=1.0.0&REQUEST=GetCapabilities`_
- *METADATA*: The LAYER's must contain a METADATA object with the following parameters:
- *wfs_connectiontimeout* (optional): The maximum time to wait for a remote
WFS layer to load, set in seconds (default is 30 seconds). This metadata
can be added at the layer level so that it affects only that layer, or it
can be added at the map level (in the web object) so that it affects all of
the layers. Note that wfs_connectiontimeout at the layer level has priority
over the map level.
- *wfs_filter*: This can be included to include a filter encoding parameter
in the getFeature request (see the `Filter Encoding HOWTO`_ for more information
on filtering). The content of the wfs_filter is a valid filter encoding element.
.. _`http://map.ns.ec.gc.ca/MapServer/mapserv.exe?MAP=/mapserver/services/envdat/config.map`: http://map.ns.ec.gc.ca/MapServer/mapserv.exe?MAP=/mapserver/services/envdat/config.map&SERVICE=WFS&VERSION=1.0.0&REQUEST=GetCapabilities
.. _`&SERVICE=WFS&VERSION=1.0.0&REQUEST=GetCapabilities`: http://map.ns.ec.gc.ca/MapServer/mapserv.exe?MAP=/mapserver/services/envdat/config.map&SERVICE=WFS&VERSION=1.0.0&REQUEST=GetCapabilities
.. _`Filter Encoding HOWTO`: http://mapserver.gis.umn.edu/doc/filter-encoding-howto.html
::
...
METADATA
"wfs_filter" "POP_RANGE4
"
END
...
- *wfs_latlongboundingbox* (optional): The bounding box of this layer in
geographic coordinates in the format "lon_min lat_min lon_max lat_max". If
it is set then MapServer will request the layer only when the map view
overlaps that bounding box. You normally get this from the server's
capabilities output.
- *wfs_maxfeatures* (optional): Limit the number of GML features to return.
- *wfs_request_method* (optional): Can be set to "GET" to do a Get request
to WFS servers that do not support Post requests. The default method in
MapServer is Post.
::
...
METADATA
"wfs_filter" "GET"
END
...
- *wfs_typename* (required): the of the layer found in the GetCapabilities.
An example GetCapabilities request is:
`http://www2.dmsolutions.ca/cgi-bin/mswfs_gmap?SERVICE=WFS&VERSION=1.0.0&REQUEST=getcapabilities`__
__ http://www2.dmsolutions.ca/cgi-bin/mswfs_gmap?SERVICE=WFS&VERSION=1.0.0&REQUEST=getcapabilities
- *wfs_version* (required): WFS version, currently "1.0.0"
.. Note:: Each of the above metadata can also be referred to as 'ows_*' instead
of 'wfs_*'. MapServer tries the 'wfs_*' metadata first, and if not
found it tries the corresponding 'ows_*' name. Using this reduces
the amount of duplication in mapfiles that support multiple OGC
interfaces since "ows_*" metadata can be used almost everywhere for
common metadata items shared by multiple OGC interfaces.
Example WFS Layer
-----------------
::
LAYER
NAME park
TYPE POLYGON
STATUS ON
CONNECTIONTYPE WFS
CONNECTION "http://www2.dmsolutions.ca/cgi-bin/mswfs_gmap?"
METADATA
"wfs_typename" "park"
"wfs_version" "1.0.0"
"wfs_request_method" "GET"
"wfs_connectiontimeout" "60"
"wfs_maxfeatures" "1"
END
PROJECTION
"init=epsg:42304"
END
CLASS
NAME "Parks"
COLOR 200 255 0
OUTLINECOLOR 120 120 120
END
END # Layer
Connection - deprecated
-----------------------
As of MapServer v4.4 the method of specifying all of the connection information
in the CONNECTION parameter has beendeprecated. The preferred method is
mentioned above. If the metadata is not provided, VERSION, SERVICE, and
TYPENAME will be fetched from the CONNECTION, as shown below::
CONNECTION "http://www2.dmsolutions.ca/cgi-bin/mswfs_gmap?SERVICE=WFS&VERSION=1.0.0&TYPENAME=park"
TODO / Known Limitations
========================
1. Temporary WFS (gml) files are written to the IMAGEPATH directory, but this
could become a security concern since it makes the raw GML data downloadable
by someone who could guess the gml filename. We should consider having a
"wfs_cache_dir" metadata that, if it is set will define a directory where temp
files should be written. The default would still be to use the value of
IMAGEPATH if "wfs_tmpdir" is not set.
2. Xerces is an annoying dependency for GML support in OGR. There have been
discussions about modifying the OGR GML driver to use in internal XML parser
by default. This would save us from the Xerces dependency. There is no formal
plan for when this would happen yet.
About This Document
===================
Copyright Information
---------------------
Copyright (c) 2005, Jean-François Doyon, 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.