= 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 26, 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.