= FDO RFC 61 - 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 30, 2011||
||Author||Sam Wang||
||RFC Status||Adopted||
||Implementation Status||In Progress||
||Proposed Milestone||3.7.0.0||
||Assigned PSC guide(s)||Orest Halustchak||
||'''Voting History'''||June 2, 2011 ||
||+1||Orest, Greg, Haris, Jackie||
||+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 FdoITransaction : public FdoIDisposable
{
    ......
    /// \brief
    ///  Create a save point in this transaction.
    /// 
    /// \param suggestName
    /// Suggested save point name.
    /// 
    /// \returns 
    /// The actual name used by the provider 
    FDO_API virtual FdoString* AddSavePoint(FdoString* suggestName) = 0;

    /// \brief
    ///  Release a specific save point.
    /// 
    /// \param savePointName 
    /// Save point name.
    /// 
    /// \returns 
    /// Returns nothing
 
    FDO_API virtual void ReleaseSavePoint(FdoString* savePointName) = 0;
    
    /// \brief
    ///  Rollback the transaction to a specified save point.
    /// 
    /// \param savePointName 
    /// Save point name.
    /// 
    /// \returns 
    /// Returns nothing 
    FDO_API virtual void Rollback(FdoString* savePointName) = 0;
    ......
}
}}}
"!AddSavePoint" method is used to add a save point with a suggest name which can later be rolled back to without affecting the work done prior to the save point. The suggested name is not necessarily the provider will use beacuse the provider would make sure that the name used to mark the save point is unique. 
"!ReleaseSavePoint" method releases a save point from the save point stack as if this save point never exists. Note that since "RELEASE" command is not available for all RDBMS, some providers like Oracle will leave implementation of this method blank.
"Rollback" method rolls back to a specific named save point.

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

The follwing code illustrates how to add a save point, release a save point and rollback to a save point
{{{
FdoPtr<FdoIInsert> insertCommand;
FdoPtr<FdoITransaction> transaction = connection->BeginTransaction();
FdoStringP spName1 = transaction->AddSavePoint(L"Save_point_1");
FdoStringP spName2 = transaction->AddSavePoint(L"Save_point_2");
try{
......
    FdoIFeatureReader* reader = insertCommand->Execute();
......
}
catch(FdoException* e)
{
    e->Release();
    transaction->Rollback(spName1);
}
transaction->ReleaseSavePoint(spName2);
FdoStringP spName3 = transaction->AddSavePoint(L"Save_point_3");
FdoPtr<FdoIDelete> deleteCommand;
try{
......
    int num = deleteCommand->Execute();
......
}
catch(FdoException* e)
{
    e->Release();
    transaction->Rollback(spName3);
}
transaction->Commit();
}}}

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