MapGuide RFC 46 - New Generate Filters 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	(Date/Time submitted)
Last Modified	(your name here) Timestamp
Author	Ronnie Louie
RFC Status	retracted
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();
                }
            }

The old GenerateFilter() API should be deprecated. 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() may 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