= !MapGuide RFC 78 - Add transaction support to FeatureService =

This page contains an change request (RFC) for the !MapGuide Open Source project.
More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.


== Status ==

||RFC Template Version||(1.0)||
||Submission Date||(Date/Time submitted)||
||Last Modified||(Klain Qin) (Thu Jul 9 22:18:19 2009)||
||Author||(Klain Qin)||
||RFC Status||(draft)||
||Implementation Status||(not ready for review)||
||Proposed Milestone||(2.2)||
||Assigned PSC guide(s)||(Tom Fukushima)||
||'''Voting History'''||(vote date)||
||+1||||
||+0||||
||-0||||
||-1||||
||no vote|| ||

== Overview ==

This proposal is to enhance the transaction capability of MapGuide Feature Service to support executing not only a sequence of standard commands(delete/update/insert) but also a sequence of sql statements within a single transaction. 

== Motivation ==

Currently MapGuide Feature Service supports executing a sequence of standard commands within a single transaction through the API illustrated below. The standard commands are delete/update/insert. If you pass in true for useTransaction, the API will start a transaction and commit(or rollback) it at the end. Thus all command execution will reside inside a single transaction. 
{{{
virtual MgPropertyCollection* UpdateFeatures( MgResourceIdentifier* resource,
                                              MgFeatureCommandCollection* commands,
                                              bool useTransaction ) = 0;
}}}
However, MapGuide Feature Service also provides another two APIs to execute sql statements as illustrated below, where a database transaction will internally be started and committed befor and after the sql statement execution. Here the capability of executing a sequence of sql statements within a single transaction is missing. 
{{{
virtual INT32 ExecuteSqlNonQuery( MgResourceIdentifier* resource,
                                  CREFSTRING sqlNonSelectStatement ) = 0;
virtual MgSpatialContextReader* GetSpatialContexts( MgResourceIdentifier* resource,
                                                    bool bActiveOnly) = 0;
}}}
This proposal is to extend Feature Service to support executing a sequence of sql statements within a single transaction. 

== Proposed Solution ==

A new class of MgTransaction will be added to represent a transaction to be performed in a data store. 
{{{
/// \brief
/// MgTransaction represents a transaction to be performed in a DataStore.
/// If the transaction is time out, commit or rollback a transaction will
/// result in one exception MgFeatureServiceException thrown.
class MgTransaction : public MgGuardDisposable
{
PUBLISHED_API:
    /// \brief
    /// Commit the transaction.
    ///
    virtual void Commit() = 0;

    /// \brief
    /// Rollback the transaction.
    ///
    virtual void Rollback() = 0;

    /// \brief
    /// Get the identifier of feature source associated with the transaction.
    ///
    /// \return
    /// Returns the identifier of feature source associated with the transaction.
    ///
    virtual MgResourceIdentifier* GetFeatureSource() = 0;
};
}}}

Changes to Feature Service
{{{
/// \brief
/// Provides an abstraction layer for the storage and retrieval
/// of feature data in a technology-independent way. The API
/// lets you determine what storage technologies are available
/// and what capabilities they have. Access to the storage
/// technology is modeled as a connection. For example, you can
/// connect to a file and do simple insertions or connect to a
/// relational database and do transaction-based operations.
class MgFeatureService : public MgService 
{
PUBLISHED_API:
    /// \brief
    /// Begins a transaction and return it.
    ///
    /// \param resource (MgResourceIdentifier)
    /// A resource identifier referring to a feature source.
    ///
    /// \return
    /// Returns an MgTransaction instance.
    ///
virtual MgTransaction* BeginTransaction(MgResourceIdentifier* resource) = 0;
};
}}}

One example using the new API
{{{
MgTransaction tran = AcMapFeatureService::StartTransaction(resourceId);
AcMapFeatureService::ExecuteSql(resourceId, sql statement1); 
AcMapFeatureService::ExecuteSql(resourceId, sql statement2); 
AcMapFeatureService::UpdateFeatures(resourceId, standard commands, false);  // NOTE: you have to pass in false for useTransaction here.
tran->Commit() // or tran->Rollback(); 
}}}


== Implications ==

This section allows discussion of the repercussions of the change, such as whether there will be any breakage in backwards compatibility, if documentation will need to be updated, etc.

== Test Plan ==

How the proposed change will be tested, if applicable.  New unit tests should be detailed here???

== Funding/Resources ==

This section will confirm that the proposed feature has enough support to proceed.  This would typically mean that the entity making the changes would put forward the RFC, but a non-developer could act as an RFC author if they are sure they have the funding to cover the change.