= !MapGuide RFC 61 - !GetSpatialContexts cleanup =

This page contains a 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||April 5, 2009||
||Last Modified||Steve Dang [[Timestamp]]||
||Author||Steve Dang||
||RFC Status||draft (draft, proposed, frozen for vote, adopted, retracted, or rejected)||
||Implementation Status||pending (pending, under development, completed)||
||Proposed Milestone||2.2||
||Assigned PSC guide(s)||Tom Fukushima||
||'''Voting History'''||(vote date)||
||+1|| ||
||+0|| ||
||-0|| ||
||-1|| ||
||no vote|| ||

== Overview ==

This RFC is to deprecate the Spatial Context active flag that is obsolete and no longer in use by:

 * The !GetSpatialContexts API (to retrieve the spatial contexts in the feature source).
 * The !MgSpatialContextReader class (to retrieve the spatial context data).

== Motivation ==

 * Make the !GetSpatialContexts API consistently reliable across all providers.
 * Clean up legacy code and make existing code more readable.
 * Reduce memory usage and improve performance in the Feature Service cache which only needs to save all of the spatial contexts available in the feature source.

== Proposed Solution ==

 * Update the documentation on the following APIs (including C++/Java/PHP/.NET), indicating they will be deprecated in the future:

{{{
    virtual MgSpatialContextReader* MgFeatureService::GetSpatialContexts(MgResourceIdentifier* resource, bool activeOnly) = 0;

    bool MgSpatialContextReader::IsActive();
}}}
 
 * Update the documentation on the !FdoSpatialContextList-1.0.0.xsd schema, indicating the Spatial Context active flag is obsolete and no longer in use, and will be deprecated in the future.
 * Add a new !GetSpatialContexts API to the Feature Service:

{{{
    ///////////////////////////////////////////////////////////////////////////
    /// \brief
    /// Gets all of the spatial contexts available in the feature source.
    ///
    /// \remarks
    /// The \link FdoSpatialContextList_schema FdoSpatialContextList \endlink XML schema contains
    /// a specification of the content of the spatial context
    /// information returned in the MgSpatialContextReader object.
    ///
    /// <!-- Syntax in .Net, Java, and PHP -->
    /// \htmlinclude DotNetSyntaxTop.html
    /// virtual MgSpatialContextReader GetSpatialContexts(MgResourceIdentifier resource);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual MgSpatialContextReader GetSpatialContexts(MgResourceIdentifier resource);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual MgSpatialContextReader GetSpatialContexts(MgResourceIdentifier resource);
    /// \htmlinclude SyntaxBottom.html
    ///
    /// \param resource (MgResourceIdentifier)
    /// A resource identifier identifying a feature source in the repository.
    ///
    /// \return
    /// Returns an MgSpatialContextReader object.
    ///
    /// \exception MgFeatureServiceException
    /// \exception MgInvalidArgumentException
    /// \exception MgInvalidOperationException
    /// \exception MgFdoException
    ///
    virtual MgSpatialContextReader* GetSpatialContexts(MgResourceIdentifier* resource) = 0;
}}}

 * Replace calls to the old !GetSpatialContexts API with the new ones.
 * Update existing code to discontinue usages of the obsolete Spatial Context active flag where applicable.

== Implications ==

 * Avoid using the APIs listed above as they will be deprecated in the future.

== Test Plan ==

 * The old !GetSpatialContexts API should work as before.
 * Existing unit tests will be updated to utilize the new !GetSpatialContexts API and re-tested.

== Funding/Resources ==

Autodesk