MapGuide RFC 114 - Extend MapGuide API to Support Save Points

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	June 14, 2011
Last Modified	Sam Wang, June 14, 2011
Author	Sam Wang
RFC Status	Ready for review
Implementation Status	Not started
Proposed Milestone	2.3
Assigned PSC guide(s)	Bruce Dechant
Voting History	(vote date)
+1
+0
-0
-1
no vote

Overview

This RFC proposes a solution to extend MapGuide transaction API to support save points.

Motivation

Due to the constraint of FDO transaction, MapGuide does not support save points or nested transaction. Thus it is impossible to partially roll back the work of a transaction. Now with ​FDO RFC 61 adopted, we can take advantage of these new APIs and enhance MapGuide feature transaction API to control the commit or rollback of a transaction at a lower level.

Proposed Solution

The current "MgTransaction" interface can add the following methods to support save points which keeps consistency with FDO transaction API.

/////////////////////////////////////////////////////////////////
/// \brief
/// MgTransaction represents a transaction to be performed in a DataStore.
/// If the transaction is time out, commit or rollback a transaction will
/// result in one exception MgFeatureServiceException thrown.
class MG_PLATFORMBASE_API MgTransaction : public MgSerializable
{
PUBLISHED_API:
......

    /// \brief
    ///  Create a save point in this transaction.
    /// 
    /// \param suggestName
    /// Suggested save point name.
    /// 
    /// \returns 
    /// The actual name used
    virtual STRING AddSavePoint(CREFSTRING suggestName) = 0;

    /// \brief
    ///  Release a specific save point.
    /// 
    /// \param savePointName 
    /// Save point name.
    /// 
    /// \returns 
    /// Returns nothing
 
    virtual void ReleaseSavePoint(CREFSTRING savePointName) = 0;
    
    /// \brief
    ///  Rollback the transaction to a specified save point.
    /// 
    /// \param savePointName 
    /// Save point name.
    /// 
    /// \returns 
    /// Returns nothing 
    virtual void Rollback(CREFSTRING savePointName) = 0;
......
}

Typically, the implementation of these API methods would forward the call request and parameters to corresponding FDO API.

And also "MgFeatureService" interface has to be updated to reflect this change:

class MG_PLATFORMBASE_API MgFeatureService : public MgService
{
INTERNAL_API:
......

    /// \brief
    ///  Create a save point in this transaction.
    /// 
    /// \param suggestName
    /// Suggested save point name.
    /// 
    /// \returns 
    /// The actual name used
    virtual STRING AddSavePoint(CREFSTRING transactionID, CREFSTRING suggestName) = 0;

    /// \brief
    ///  Release a specific save point.
    /// 
    /// \param savePointName 
    /// Save point name.
    /// 
    /// \returns 
    /// Returns nothing
 
    virtual void ReleaseSavePoint(CREFSTRING transactionID, CREFSTRING savePointName) = 0;
    
    /// \brief
    ///  Rollback the transaction to a specified save point.
    /// 
    /// \param savePointName 
    /// Save point name.
    /// 
    /// \returns 
    /// Returns nothing 
    virtual void RollbackSavePoint(CREFSTRING transactionID, CREFSTRING savePointName) = 0;
......
}

Implications

This is a new API, so API documentation need to be updated. However, it will not affect the existing application if you don't use it at all. This API could be used to implement nested transaction, each logically nested transaction could be marked as a save point, and the roll back of this nested transaction is exactly the roll back to the correspoding save point.

Test Plan

Existing MapGuide existing feature service unit tests will be expanded to test the proposed enhancements defined above.

Funding / Resources

Autodesk to provide funding/resources