= !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 [wiki:MapGuideRfcs 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||Adopted||
||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 [http://trac.osgeo.org/fdo/wiki/FDORfc61 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.
== 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