= !MapGuide RFC 15 - New Query Features API =

This page contains an change request (RFC) for the !MapGuide Open Source project.  
More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.


== Status == 
 
||RFC Template Version||(1.0)|| 
||Submission Date||(Date/Time submitted)||
||Last Modified||Bruce Dechant [[Timestamp]]||
||Author||Bruce Dechant||
||RFC Status||draft||
||Implementation Status||pending||
||Proposed Milestone||1.2||
||Assigned PSC guide(s)||(when determined)||
||'''Voting History'''||(vote date)||
||+1||Bob, Andy, Haris||
||+0||Paul||
||-0||Tom, Bruce||
||-1||Jason (troublemaker)||
 
== 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 ==

The NEW APIs will be documented the same way as the already 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