| Author: | Jean-François Doyon |
|---|---|
| Contact: | jdoyon at nrcan.gc.ca |
| Author: | Jeff McKenna |
| Contact: | jmckenna at gatewaygeomatics.com |
| Revision: | $Revision: 8376 $ |
| Date: | $Date: 2009-01-02 07:13:17 -0800 (Fri, 02 Jan 2009) $ |
| Last Updated: | 2006/10/13 |
Contents
A WFS ( Web Feature Service ) publishes feature-level geospatial data to the web. This means that instead of returning an image, as MapServer has traditionally done, the client now obtains fine-grained information about specific geospatial features of the underlying data, at both the geometry AND attribute levels. As with other OGC specifications, this interface uses XML over HTTP as it’s delivery mechanism, and, more precisely, GML (Geography Markup Language), which is a subset of XML.
In order to enable MapServer to serve WFS, it MUST be compiled against certain librairies:
Please see the MapServer UNIX Compilation and Installation HowTo for detailed instructions on compiling mapserver with support for these libraries and features. For Windows users, the MS4W installer comes ready to serve both WFS and WMS.
Much as in the WMS support, WFS publishing is enabled by adding certain magic METADATA keyword/value pairs to a MapFile.
MapServer will serve and include in its WFS capabilities only the layers that meet the following conditions:
Data source is of vector type (Shapefile, OGR, PostGIS, SDE, SDO, ...)
LAYER NAME must be set. Layer names must start with a letter when setting up a WFS server (layer names should not start with a digit or have spaces in them).
LAYER TYPE is one of: LINE, POINT, POLYGON
LAYER DUMP parameter set to TRUE
The “wfs_onlineresource” metadata:
The wfs_onlineresource metadata is set in the map’s web object metadata and specifies the URL that should be used to access your server. This is required for the GetCapabilities output. If wfs_onlineresource is not provided then MapServer will try to provide a default one using the script name and hostname, but you shouldn’t count on that too much. It is strongly recommended that you provide the wfs_onlineresource metadata.
See section 12.3.3 of the WFS 1.0.0 specification for the whole story about the online resource URL. Basically, what you need is a complete HTTP URL including the http:// prefix, hostname, script name, potentially a “map=” parameter, and and terminated by “?” or “&”.
Here is a valid online resource URL:
http://my.host.com/cgi-bin/mapserv?map=mywfs.map&
By creating a wrapper script on the server it is possible to hide the “map=” parameter from the URL and then your server’s online resource URL could be something like:
http://my.host.com/cgi-bin/mywfs?
This is covered in more detail in the “More About the Online Resource URL” section of the WMS Server document.
The following is an example of a bare minimum WFS Server mapfile. Note the comments for the required parameters.
NAME "WFS_server"
STATUS ON
SIZE 400 300
SYMBOLSET ../etc/symbols.sym
EXTENT -2200000 -712631 3072800 3840000
UNITS METERS
SHAPEPATH "../data"
IMAGECOLOR 255 255 255
FONTSET ../etc/fonts.txt
WEB
IMAGEPATH "/ms4w/tmp/ms_tmp/"
IMAGEURL "/ms_tmp/"
METADATA
"wfs_title" "GMap WFS Demo Server" ## REQUIRED
"wfs_onlineresource" "http://127.0.0.1/cgi-bin/mapserv.exe?" ## Recommended
"wfs_srs" "EPSG:42304 EPSG:42101 EPSG:4269 EPSG:4326" ## Recommended
"ows_schemas_location" "http://ogc.dmsolutions.ca" ## Optional
END
END
PROJECTION
"init=epsg:42304"
END
LAYER
NAME "province"
METADATA
"wfs_title" "Provinces" ## REQUIRED
"gml_featureid" "ID" ## REQUIRED
"gml_include_items" "all" ## Optional (serves all attributes for layer)
END
TYPE POLYGON
STATUS ON
DATA province
PROJECTION
"init=epsg:42304"
END
DUMP TRUE ## REQUIRED
CLASS
NAME "Canada"
STYLE
COLOR 200 255 0
OUTLINECOLOR 120 120 120
END
TEMPLATE "ttt_query.html"
END
END # Layer
END # Map File
Contrary to WMS, the OGC WFS specification doesn’t allow a layer (feature type) to be advertised in more than one SRS. Also, there is no default SRS that applies to all layers by default in the OGC WFS spec. However, it is possible to have every layer in a WFS server advertised in a different SRS.
Here is how MapServer decides the SRS to advertise and use for each layer in your WFS:
Note that at the map top-level the “wfs_srs” metadata value takes precedence over the contents of the PROJECTION block.
At the layer level, if both the wfs_srs metadata and the PROJECTION object are set to different values, then the wfs_srs metadata defines the projection to use in advertising this layer (assuming there is no top-level map SRS), and the PROJECTION value is assumed to be the projection of the data. So this means that the data would be reprojected from the PROJECTION SRS to the one defined in the wfs_srs metadata before being served to WFS clients.
Confusing? As a rule of thumb, simply set the wfs_srs at the map level (in web metadata) and never set the wfs_srs metadata at the layer level and things will work fine for most cases.
OK, now that we’ve got a mapfile, we have to check the XML capabilities returned by our server to make sure nothing is missing.
Using a web browser, access your server’s online resource URL to which you add the parameter “REQUEST=GetCapabilities” to the end, e.g.
http://www2.dmsolutions.ca/cgi-bin/mswfs_gmap?SERVICE=WFS&VERSION=1.0.0&REQUEST=getcapabilities
If everything went well, you should have a complete XML capabilities document. Search it for the word “WARNING”... MapServer inserts XML comments starting with “<!–WARNING: ” in the XML output if it detects missing mapfile parameters or metadata items. If you notice any warning in your XML output then you have to fix all of them before you can register your server with a WFS client, otherwise things are likely not going to work.
Note that the SERVICE parameter is required for all WFS requests. When a request happens, it is passed through WMS, WFS, and WCS in MapServer (in that order) until one of the services respond to it.
OK, now that we know that our server can produce a valid XML GetCapabilities response we should test the GetFeature request. Simply adding “SERVICE=WFS&VERSION=1.0.0&REQUEST=GetFeature&TYPENAME=yourlayername1,yourlayername2” to your server’s URL should return the GML associated with those layers.
If you have access to a WFS client, then register your new server’s online resource with it and you should be off and running.
If you don’t have your own WFS client installed already, here are a few pointers:
Starting from version 4.2 MapServer supports XML-encoded POST requests and GET requests. The default in MapServer is POST.
Starting from version 4.2 MapServer supports Filter Encoding (FE) in WFS GetFeature requests. For more information on the server side of Filter Encoding see the Filter Encoding HowTo.
The following metadata are available in the setup of the WFS Server mapfile:
Note
Each of the metadata below 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.
ows_updatesequence
ows_schemas_location
wfs_abstract
wfs_accessconstraints
wfs_encoding
wfs_fees
wfs_keywordlist
wfs_maxfeatures
wfs_namespace_prefix
wfs_namespace_uri
wfs_onlineresource
wfs_service_onlineresource
Description: (Optional) Top-level onlineresource URL. MapServer uses the onlineresource metadata (if provided) in the following order:
- wfs_service_onlineresource
- ows_service_onlineresource
- wfs_onlineresource (or automatically generated URL, see the onlineresource section of this document)
wfs_title
wfs_srs
wfs_feature_collection
gml_exclude_items
Description: (Optional) A comma delimited list of items to exclude. As of MapServer 4.6, you can control how many attributes (fields) you expose for your data layer with metadata. The previous behaviour was simply to expose all attributes all of the time. The default is to expose no attributes at all. An example excluding a specific field would be:
"gml_include_items" "all"
"gml_exclude_items" "Phonenum"
gml_featureid
gml_groups
gml_[group name]_group
Description: (Optional) A comma delimited list of attributes in the group. Here is an example:
"gml_include_items" "all"
"gml_groups" "display"
"gml_display_group" "Name_e,Name_f"
gml_include_items
Description: (Optional) A comma delimited list of items to include, or keyword “all”. As of MapServer 4.6, you can control how many attributes (fields) you expose for your data layer with this metadata. The previous behaviour was simply to expose all attributes all of the time. You can enable full exposure by using the keyword “all”, such as:
"gml_include_items" "all"
You can specify a list of attributes (fields) for partial exposure, such as:
"gml_include_items" "Name,ID"
The new default behaviour is to expose no attributes at all.
gml_[item name]_alias
Description: (Optional) An alias for an attribute’s name. The served GML will refer to this attribute by the alias. Here is an example:
"gml_province_alias" "prov"
gml_[item name]_type
gml_xml_items
gml_geometries
gml_[name]_type
Description: When employing gml_geometries, it is also necessary to specify the geometry type of the layer. This is accomplished by providing a value for gml_[name]_type, where [name] is the string value specified for gml_geometries, and a value which is one of:
- point
- multipoint
- line
- multiline
- polygon
- multipolygon
gml_[name]_occurances
wfs_abstract
wfs_extent
wfs_featureid
wfs_keywordlist
wfs_metadataurl_format
wfs_metadataurl_href
wfs_metadataurl_type
wfs_srs
wfs_title