MapGuide RFC 15 - New Query Features API

This page contains a change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	February 2, 2007
Last Modified	Bruce Dechant Timestamp
Author	Bruce Dechant
RFC Status	adopted
Implementation Status	completed
Proposed Milestone	1.2
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1	Andy, Bob, Bruce, Paul, Tom
+0
-0	Jason
-1

Overview

The current Rendering Service APIs QueryFeatures() and QueryFeatureProperties() are restricted to only querying data for map layers that are visible at the current map scale. However, there are certain situations where you may wish to query data on the map layers regardless of whether they are currently visible at the current map scale. There are also situations where it is desirable to filter the results using a list of feature IDs.

Motivation

With the current QueryFeatures() and QueryFeatureProperties() APIs it is not possible to query for specific features if the layer they exist on is not currently visible at the current map scale.

Example:

You have a map of Canada that contains a "parcels" layer that is currently not visible at the current map scale because you are just wanting to have a country overview display. You now wish to view all parcels with a certain size across Canada. If you tried to use the QueryFeatures() and QueryFeatureProperties() APIs on your "parcels" layer the results would not be displayed because the "parcels" layer is not currently visible at the current map scale. You could zoom in until the "parcels" layer is visible, but you would not be able to see all the parcels you are interested in across Canada very easily.

Also, when a feature is selected in the MapGuide Viewer using the Search command, a susequent QueryFeatures() request is made to the MapGuide Server in order to retrieve the properties for the selected feature. Any properties that are available are displayed in the viewer's property pane. The QueryFeatures() request is made using a spatial filter based on the geometry of the selected feature, with a MaxFeatures value of 1. Thus, the properties that are displayed are those for the first feature that intersects the geometry of the selected feature. Unfortunately, this means that the properties that are retrieved are sometimes those of an adjacent feature instead of the selected feature. For this reason, it is desirable to be able to specify one or more feature IDs to be used to filter the results of the QueryFeatures() and QueryFeatureProperties() methods.

Proposed Solution

The solution to this is to add 2 NEW APIs that essentially are identical to the already existing QueryFeatures() and QueryFeatureProperties() APIs except that they add additional parameters. The reason for the NEW APIs is so as not to break backward compatibility with the already existing APIs.

Proposed New APIs:

 MgFeatureInformation* QueryFeatures(MgMap* map,
                                     MgStringCollection* layerNames,
                                     MgGeometry* filterGeometry,
                                     INT32 selectionVariant,
                                     CREFSTRING featureFilter,
                                     INT32 maxFeatures,
                                     INT32 layerAttributeFilter);

 MgBatchPropertyCollection* QueryFeatureProperties(MgMap* map,
                                                   MgStringCollection* layerNames,
                                                   MgGeometry* filterGeometry,
                                                   INT32 selectionVariant,
                                                   CREFSTRING featureFilter, 
                                                   INT32 maxFeatures,
                                                   INT32 layerAttributeFilter);

Updated HTTP operation QUERYMAPFEATURES:

The existing HTTP operation QUERYMAPFEATURES will be updated to support the following additional parameters, if specified:

 LAYERATTRIBUTEFILTER
 * This is an integer bitmask value. The bit values have the following meanings:
   1 = Only query features for layers that are visible
   2 = Only query features for layers that are selectable
   4 = Only query features for layers that have tooltips

   If this parameter is not specified, the default value used is 3 (corresponding to options 1 and 2 above), which gives the same result as the old version of QUERYMAPFEATURES.
   In the query used to generate tooltips, a value of 5 will be used (options 1 and 4), which allows the retrieval of tooltips even for layers that are not selectable.

 FEATUREFILTER=<XML Selection String>
 * The XML Selection String format is used by the existing MgSelection class, and contains the required feature IDs, and information about the layer that contains them.

A request may contain a FEATUREFILTER parameter or a spatial filter, or both. To specify only a spatial filter, the featureFilter can be an empty string. To specify only a feature filter, the geometry can be NULL.

An example feature filter string is as follows:

<?xml version="1.0" encoding="UTF-8"?><FeatureSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="FeatureSet-1.0.0.xsd"><Layer id="434f06ea-0000-1000-8000-005056c00008"><Class id="SHP_Schema:Parcels"><ID>wykAAA==</ID></Class></Layer></FeatureSet>

Implications

AJAX Viewer behavior will change slightly with this RFC. If the user selects one or more features on a layer, and then zooms out to a scale where that layer is not visible, the selected features will still be visible (even though other features on that layer are not). This is desirable because you can zoom out and then generate a large scale buffer around the selected feature(s) and immediately see the result.

The NEW APIs will be documented the same way as the existing APIs. Backwards compatibility is maintained because these are NEW APIs.

Test Plan

Test existing APIs to ensure functionality does not change. Test NEW APIs functionality.

Funding/Resources

Autodesk to supply

Addendum

In order to allow for reverting back to the original AJAX viewer behavior the following additional changes were made:

1) Updated the following HTTP operations with an optional parameter - KEEPSELECTION. Default value is 1 (true). Setting this to 0 will revert to the original AJAX behavior.

• GETDYNAMICMAPOVERLAYIMAGE
• GETMAPIMAGE

2) Added the following overloaded web tier APIs to support the "KeepSelection" behavior.

• RenderDynamicOverlay
• RenderMap

Addendum 2

1) Added the additional featureFilter parameter to Server APIs.

2) Added the FEATUREFILTER parameter to the HTTP QUERYMAPFEATURES request.

Addendum 3

1) Added the additional bIgnoreSelectability parameter to Server APIs.

2) Added the IGNORESELECTABILITY parameter to the HTTP QUERYMAPFEATURES request.

The QUERYMAPFEATURES request is used to retrieve information used to generate tooltips in the AJAX viewer. The viewer will specify IGNORESELECTABILITY=1 so that tooltips can be displayed even for features that are not selectable.

Addendum 4

Following user feedback, removed use of individual parameters for ignoring scale ranges and selectability, and replaced with a bitmask value. This provides a cleaner implementation and leaves room for future enhancements (using new bit values) without modifying the API.