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;
typedef  FdoNamedCollection<FdoSavePoint, FdoException> FdoSavePointCollection;

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

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

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

class FdoSavePoint:  public FdoIDisposable
{
     public:
        FdoSavePoint( FdoStringP name);
        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:
        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 contains a name that has to be unique within the 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;
    ......
}

How to use this API

Add a save point/Rollback to a save point:

FdoPtr<FdoIInsert> insertCommand;
FdoPtr<FdoITransaction> transaction = connection->BeginTransaction();
transaction->AddSavePoint(L"Save_point_1");
try{
......
    insertCommand->SetTransaction(transaction)
    FdoIFeatureReader* reader = insertCommand->Execute();
......
}
catch(FdoException* e)
{
    e->Release();
    transaction->RollBack(L"Save_point_1");
}
transaction->AddSavePoint(L"Save_point_2");
FdoPtr<FdoIDelete> deleteCommand;
try{
......
    deleteCommand->SetTransaction(transaction)
    int num = deleteCommand->Execute();
......
}
catch(FdoException* e)
{
    e->Release();
    transaction->RollBack(L"Save_point_2");
}
transaction->Commit();

Check if a save point is available:

FdoPtr<FdoITransaction> transaction;
......
FdoSavePointCollection* savePointCollection = transaction->GetAvailableSavePoints();
if(NULL != savePointCollection->FindItem(L"My_Save_Point"))
{
    ......
}

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.