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	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();
                }
            }

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