= 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 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 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 insertCommand; FdoPtr 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 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 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.