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