= !MapGuide RFC 46 - New Generate Filters 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||(your name here) [[Timestamp]]||
||Author||Ronnie Louie||
||RFC Status||draft||
||Implementation Status||pending||
||Proposed Milestone||2.1||
||Assigned PSC guide(s)||(when determined)||
||'''Voting History'''||(vote date)||
||+1||||
||+0||||
||-0||||
||-1||||
 
== Overview ==

This RFC is for adding a new API for generating filters from a selection.

== Motivation ==

The current MgSelectionBase::GenerateFilter() API returns a string representing a filter for a set of selected features.  

{{{
 STRING MgSelectionBase::GenerateFilter(MgLayerBase* layer, CREFSTRING className);
}}}

This filter string would look something like: "FeatId = 1109 OR FeatId = 1130 OR FeatId = 2065" such that each of the IDs of the selected features is explicitly specified.  The string is then passed as the filter to MgFeatureService::SelectFeatures() to query the datastore.   

A selection can contain an unlimited number of features, which means that the filter will contain an unlimited number of OR conditions.  However, most datastores have a finite number of OR's that can be supported, and some data sources, such as Access databases, are limited to a relatively small number or OR conditions.  

Results can be unpredictable when the limit is exceeded due to buffer overruns and/or memory corruption leading to instability in the MapGuide Server.  In an effort to improve stability, GenerateFilter() was modified to return a string representing a smaller, but incomplete subset of the total selected features.

== Proposed Solution ==

Exposing a new API to return a collection of smaller filters for a set of selected features will allow for querying of the datastore without compromising Server stability.

Proposed New API: 

{{{
 MgStringCollection* MgSelectionBase::GenerateFilters(MgLayerBase* layer, CREFSTRING className, INT32 selectionSize);
}}}

The selectionSize parameter specifies the maximum size for each of the individual filters in the collection.  For example, if selectionSize = 20, the maximum number of features represented by an individual filter is 20.  The collection could contain an unlimited number of filters to handle an unlimited number of features.

== Implications ==

Code that currently calls MgSelectionBase::GenerateFilter() should be updated to use MgSelectionBase::GenerateFilters() instead, and the caller will be required to process all the filters in the collection to correctly query the complete selection set.  

PHP code example using existing MgSelectionBase::GenerateFilter() API
{{{
            $filter = $sel->GenerateFilter($selLayer, $featureClassName);
            
            $query = new MgFeatureQueryOptions();
            $query->SetFilter($filter);
 
            $featureSource = new MgResourceIdentifier($selLayer->GetFeatureSourceId());
            $features = $featureSrvc->SelectFeatures($featureSource, $featureClassName, $query);
            if($features->ReadNext())
            {
                do
                {
                    AddFeatureToCollection($features->GetGeometry());
                }
                while($features->ReadNext());
                $features->Close();
            }
}}}

PHP code example using NEW MgSelectionBase::GenerateFilters() API
{{{
            $filterCollection = $sel->GenerateFilters($selLayer, $featureClassName, GetMaxSelectionSize());
            
            for ($filterIndex = 0; $filterIndex < $filterCollection->GetCount(), $filterIndex++)
            {
                $query = new MgFeatureQueryOptions();
                $query->SetFilter($filterCollection->GetItem($filterIndex));
 
                $featureSource = new MgResourceIdentifier($selLayer->GetFeatureSourceId());
                $features = $featureSrvc->SelectFeatures($featureSource, $featureClassName, $query);
                if($features->ReadNext())
                {
                    do
                    {
                        AddFeatureToCollection($features->GetGeometry());
                    }
                    while($features->ReadNext());
                    $features->Close();
                }
            }
}}}

In places where a relatively small number of features are expected in a selection (i.e. less than the value specified by SelectionFilterSize in serverconfig.ini/webconfig.ini), MgSelectionBase::GenerateFilter() can still be safely used to return correct results.

This is a new API which will need to be documented.

== Test Plan ==

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

== Funding/Resources ==

Autodesk to supply