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