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.

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.

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 an additional parameter. 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* geometry,
                                     INT32 selectionVariant, 
                                     INT32 maxFeatures,
                                     bool bIgnoreScaleRange);

 MgBatchPropertyCollection* QueryFeatureProperties(MgMap* map,
                                                   MgStringCollection* layerNames,
                                                   MgGeometry* geometry,
                                                   INT32 selectionVariant, 
                                                   INT32 maxFeatures,
                                                   bool bIgnoreScaleRange);

Updated HTTP operation QUERYMAPFEATURES:

The existing HTTP operation QUERYMAPFEATURES will be updated to support the following additional parameter if it is specified.

 IGNORESCALE=0
 * With the value of 0 this operation behaves exactly as the original QUERYMAPFEATURES operation.
   
 IGNORESCALE=1
 * With the value of 1 this operation will allow querying of data regardless of visibility at the current map scale.

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