MapGuide RFC 78 - Enhance transaction capability to Feature Service

This page contains an change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the 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	(pending)
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(); 

Timeout configuration for MgTransaction

If an MgTransaction has been started but hasn't been committed or rollbacked within the timeout, the transaction will be automatically rollbacked. If you call Commit() or Rollback() after timeout, an exception will be thrown reminding that the transaction has been timeout.

Bind MgTransaction to FDO connection

The transaction has to be bound with the underlying FDO connection where it starts from during its life circle. The underlying FDO connection will be kept used by the transaction until the call of either Commit() or Rollback().

Implications

This is the new API, so API documentation need to be updated. However, it will not affect the existing application if you don't use it at all.

As noted in the above example, if you use it along with UpdateFeatures(), additional attention should be paid not to pass in true for useTransaction. Otherwise, it will incur a nested transaction which is currently not supported by FDO.

Test Plan

A new unit test similar to the above example will be added into the existing Feature Service unit tests.

Funding/Resources

Supplied by Autodesk.