MapGuide RFC 9 - Add Convenience Methods to MgLayerBase

This page contains an 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 10, 2007
Last Modified	Bob Bray Timestamp
Author	Bob Bray
RFC Status	draft
Implementation Status	pending
Proposed Milestone	1.2
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1
+0
-0
-1

Overview

In writing sample applications for MapGuide I have noticed a few reoccurring patterns in the application code. In particular when querying or updating feature data typically you have to get the feature source information from the MgLayer and then turn around and pass all of that information on to Feature Service operations. This RFC aims to clean up this particular reoccurring pattern.

Motivation

Here is a simplified pattern that occurs frequently in MapGuide applications:

$resourceService = $site->CreateService(MgServiceType::ResourceService);
$featureService = $site->CreateService(MgServiceType::FeatureService);

$map = new MgMap();
$map->Open($resourceService, $_POST['MAPNAME']);
$layer = $map->GetLayers()->GetItem($_POST['LAYERNAME']);

$resId = new MgResourceIdentifier($layer->GetFeatureSourceId());
$featureClass = $layer->GetFeatureClassName();

$featureService = $this->site->CreateService(MgServiceType::FeatureService);

$reader = $featureService->SelectFeatures($resId, $featureClass, null);

With the API enhancements recommended by this RFC, a more convenient and compact form might be written like this:

$map = new MgMap($site);
$map->Open($_POST['MAPNAME']);
$layer = $map->GetLayers()->GetItem($_POST['LAYERNAME']);

$reader = $layer->SelectFeatures(null);

Proposed Solution

The following methods will be added to MgLayerBase and exposed in the public API.

/// <summary>                                                                                                       
/// Gets the class definition for the feature class of the layer.  If the                                           
/// feature class of the layer is extended with properties from other feature                                       
/// classes, then all those properties are also contained in the returned                                           
/// class definition.                                                                                               
/// </summary>                                                                                                      
/// <returns>                                                                                                       
/// Returns an MgClassDefinition instance for the specified / class name.                                           
/// </returns>                                                                                                      
virtual MgClassDefinition* GetClassDefinition();                                                                    
                                                                                                                        
/// <summary>                                                                                                       
/// Selects features from a feature source according to the                                                         
/// criteria set in the MgFeatureQueryOptions argument The                                                          
/// criteria are applied to all of the features in the feature                                                      
/// source. If you want to apply the criteria to a subset of the                                                    
/// features, use the MgLayerBase::SelectAggregate Method.                                                          
/// </summary>                                                                                                      
/// <param name="options">                                                                                          
/// MgFeatureQueryOptions instance containing all required filters for                                              
/// this select operation.                                                                                          
/// </param>                                                                                                        
/// <returns>                                                                                                       
/// Returns an MgFeatureReader containing the set of selected                                                       
/// features.                                                                                                       
/// </returns>                                                                                                      
virtual MgFeatureReader* SelectFeatures(MgFeatureQueryOptions *options);                                            
                                                                                                                        
/// <summary>                                                                                                       
/// Selects groups of features from a feature source and applies                                                    
/// filters to each of the groups according to the criteria set                                                     
/// in the MgFeatureAggregateOptions argument. If you want to                                                       
/// apply the criteria to all features without grouping them, use                                                   
/// the MgLayerBase::SelectFeatures Method.                                                                         
/// </summary>                                                                                                      
/// <param name="options">                                                                                          
/// An MgFeatureAggregateOptions instance containing all the criteria and                                           
/// filters required for this select operation.                                                                     
/// </param>                                                                                                        
/// <returns>                                                                                                       
/// Returns an MgDataReader containing the group values.                                                            
/// </returns>                                                                                                      
virtual MgDataReader* SelectAggregate(MgFeatureAggregateOptions* options);                                          
                                                                                                                        
/// <summary>                                                                                                       
/// Executes the MgDeleteFeatures, MgInsertFeatures,                                                                
/// MgUpdateFeatures, MgLockFeatures or MgUnlockFeatures commands                                                   
/// contained in the given MgFeatureCommandCollection object.                                                       
/// </summary>                                                                                                      
/// <param name="commands">A collection of feature commands to be                                                   
/// executed.</param>                                                                                               
/// <returns>                                                                                                       
/// Returns an MgPropertyCollection object. Each property in the                                                    
/// collection corresponds to a command in the MgFeatureCommandCollection                                           
/// argument. The property name is the index of the command in the feature                                          
/// command collection.                                                                                             
/// </returns>                                                                                                      
virtual MgPropertyCollection* UpdateFeatures(MgFeatureCommandCollection* commands);                                 

To provide these methods with access to a MgFeatureService instance a new constructor will need to be added to MgMap that takes an MgSiteConnection. Once MgMap has an MgSiteConnection instance we can also offer simplified forms of Open and Create. Here is the compete list of proposed additions to MgMap.

/// <summary>                                                                                                       
/// Constructor for the MgMap object that takes an MgSiteConnection instance.                                                                         
/// </summary>                                                                                                      
/// <param name="siteConnection">                                                                                          
/// An MgSiteConnection instance the MgMap object can use to
/// allocate service instances.                                                                     
/// </param>                                                                                                        
MgMap(MgSiteConnection* siteConnection);

/// <summary>                                                                                                       
/// Initializes a new MgMap object given a map definition
/// and a name for the map. This method is used for
/// MapGuide Viewers or for offline map production.
/// </summary>                                                                                                      
/// <param name="mapDefinition">                                                                                          
/// An MgResourceIdentifier that specifies the map definition.                                      
/// </param>                                                                                                        
/// <param name="mapName">                                                                                          
/// A string that specifies a name for the map.
/// allocate service instances.                                                                     
/// </param>                                                                                                        
virtual void Create(MgResourceIdentifier* mapDefinition, CREFSTRING mapName);

/// <summary>                                                                                                       
/// Loads the map object from a session repository.
/// </summary>                                                                                                      
/// <param name="mapName">                                                                                          
/// A string that specifies the name of the map to load.
/// allocate service instances.                                                                     
/// </param>                                                                                                        
virtual void Open(CREFSTRING mapName);

Implications

Because these are additions to the API no compatibility issues exist. However in order to take advantage of the new methods users will need to call the new MgMap constructor. If they do not the new methods will throw an exception. To further direct developers to these new methods the following MgMap methods will be depreciated:

MgMap();

virtual void Create(MgResourceService* resourceService, MgResourceIdentifier* mapDefinition, CREFSTRING mapName);

virtual void Open(MgResourceService* resourceService, CREFSTRING mapName);

Note that depreciation means that these methods will still exist and function as before, but the documentation will be updated to declare them as depreciated and point to the new/appropriate methods to use.

Test Plan

API Unit Tests will be added to test the new MgMap and MgLayerBase methods.

Funding/Resources

Autodesk will supply the resources to implement this RFC.