= FDO RFC 60 - Extend FDO API to support save point =

This page contains a request for comments document (RFC) for the FDO Open Source project.  
More FDO RFCs can be found on the [wiki:FDORfcs RFCs] page.

== Status == 
 
||RFC Template Version||1.1||
||Submission Date||May 13, 2011||
||Last Modified||Sam Wang, May 13, 2011||
||Author||Sam Wang||
||RFC Status||Draft||
||Implementation Status||Not Started||
||Proposed Milestone||3.7.0.0||
||Assigned PSC guide(s)||Orest Halustchak||
||'''Voting History'''||(vote date)||
||+1||||
||+0||||
||-0||||
||-1||||
 
== Overview ==
This RFC proposes an extended FDO transaction capability to support save point. 


== Motivation ==
FDO currently does not support starting another transaction (i.e. a sub transaction) inside a transaction that has already been started, or divide a transaction into smaller parts that can be independently submit or rolled back. The consequence of this is that for a complicated transaction (may be time consuming), the overall effort will be rolled back if a little error occurs at some point. Thus we need to extend the FDO transaction API to support save point. The purpose of this RFC is to provide a solution for such extension.

== Proposed Solution ==

Since most FDO data providers which natively support save point mark save points by name, I propose we can add the following interface method to “FdoITransaction” interface.
{{{

class FdoSavePoint;

class FdoITransaction : public FdoIDisposable
{
    ......
    /// \brief
    ///  Creates a save point in this transaction.
    /// 
    /// \param savePointName 
    /// Save point name.
    /// 
    FDO_API virtual void AddSavePoint(FdoString* savePointName) = 0;

    /// \brief
    ///  Rollbacks the transaction to the specified save point.
    /// 
    /// \param savePointName 
    /// Save point name.
    /// 
    FDO_API virtual void Rollback(FdoString* savePointName) = 0;

    typedef  FdoNamedCollection<FdoSavePoint, FdoException> FdoSavePointCollection;

    /// \brief
    /// Get currently available save points.
    /// 
    /// \return 
    /// Save point collection.
    /// 
    FDO_API virtual FdoSavePointCollection GetAvailableSavePoints() = 0;
    ......
}

class FdoSavePoint:  public FdoIDisposable
{
     public:
        FdoSavePoint( FdoStringP name, int rank );
        int GetRank()
        void SetRank(int rank); 
        FdoStringP GetName(); 

        // Indicates that this object does not allow its name
        // to change. Not allowing name change allows more efficient 
        // random access to FdoDictionary.
        virtual FdoBoolean CanSetName()
        {
            return false;
        }

    protected:
        FdoSavePoint() {}
        virtual ~FdoSavePoint() {}
        virtual void Dispose();

    private:
        int mRank;
        FdoStringP mName;
};
}}}
“!AddSavePoint” method is used to add a save point with a specific name which can later be rolled back to without affecting the work done prior to the save point. “Rollback” method rolls back to a named save point. 
  A new class named "FdoSavePoint" is needed to represent a FDO save point, which has a name and a rank value to indicate the order defined in current transaction. 

The “FdoIConnectionCapabilities” interface also has to be extended to enable query for this capability:

{{{
class FdoIConnectionCapabilities : public FdoIDisposable
{
    ......
    /// \brief
    /// Returns whether the current connection supports save point.
    /// 
    /// \return
    /// Returns true if the current connection supports save point, false otherwise.
    /// 
    FDO_API virtual bool SupportsSavePoint() = 0;
    ......
}
}}}


== Managed FDO API ==

The FDO Managed Interfaces will be updated in a similar manner to reflect the proposed changes.

== Provider Implementation ==

All providers that natively support save point should return true in FdoIConnectionCapabilities::!SupportsSavePoint and implement new methods in “FdoITransaction” interface to support save point.

== Test Plan ==

Existing FDO core unit tests will be expanded to test the proposed enhancements defined above. 
Provider specific unit tests will be added to test the proposed enhancements defined above. 

== !Funding/Resources ==

Autodesk to provide funding/resources.