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 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