MapGuide RFC 86 - The Bound FDO Connection

This page contains a 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	Sept. 25, 2009
Last Modified	(Leaf Li) Timestamp
Author	(Leaf Li)
RFC Status	Read for review
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 extend MapGuide Feature Service so that calls to Feature Service can use the same FDO connection to avoid some unexpected errors. The solution is to add two methods BindConnection(MgResourceIdentifier featureSourceId) and UnbindConnection(MgResourceIdentifier featureSourceId) so that users are able to bind/unbind an FDO connection to the current user session.

Motivation

Currently MapGuide Server maintains an FDO connection pool in order to improve performance. Once MapGuide Server receives a request to access data in a feature source, it will try to find an available FDO connection in FDO connection pool. It avoids exhausting FDO connections to the underlying RDBMS and improves performance of MapGuide Server when many users use MapGuide Server in the same time. However, it means that one user session may use the different FDO connection for the same feature source at the different time. Sometimes, it will result in some unexpected errors. Let’s take a look at one example.

In the example above, it is possible that FDO connections used by executing SQL statements "SAVEPOINT X", "ROLLBACK TO X" and "COMMIT" are completely different FDO connections. If so, it will result in an error when executing SQL statement "ROLLBACK TO X" or "COMMIT". Sometimes, it can be resolved by passing an MgTransaction instance when executing SQL statements because MapGuide Server will guarantee that operations in the same transaction use the same FDO connection. However, it still has the following two issues.

• There are only three methods supporting transaction, MgFeatureSerive::UpdateFeatures, MgFeatureSerive::ExecuteSqlQuery and MgFeatureSerive::ExecuteSqlNoQuery.
• MgFeatureSerive::BeginTransaction will do something on the DRBMS serverwhen opening a transaction. This has consequences such as updates are only visible in this transaction, and data gets locked.

Another issue is that it may result in a whole bunch of connections are open when using MgFeatureReader, MgDataReader or MgSqlDataReader. Each reader will use an FDO connection exclusively. So in the example below, it will have all of a sudden a whole bunch of admin connections open when you open a connection with admin rights.

    MgSqlDataReader reader1 = featureService.ExecuteSqlQuery(featureSourceId, commandText, mgParameters, null);
    while (reader1.ReadNext())
    {
        MgSqlDataReader reader2 = featureService.ExecuteSqlQuery(featureSourceId, commandText, mgParameters, null);
        while (reader2.ReadNext())
        {
            ......
        }
        reader2.Close();
        reader2.Dispose();
    }
    reader1.Close();
    reader1.Dispose();

So we need a mechanism to bind an FDO connection to one user session. Then MapGuide always uses this bound FDO connection when executing any FDO commands for the same feature source in this session. Moreover, we need provide a mechanism to unbind the FDO connection which is bound to one user session so that FDO connection is available for other user sessions after the user doesn’t need to bind the FDO connection to his session.

Proposed Solution

In this RFC, we extend Feature Service to add the ability to use the same FDO connection for calls to Feature Service. The following two methods will be added to class MgFeatureService to allow users to bind/unbind an FDO connection to the current session. Method BindConnection(...) will select an FDO connection from FDO connection pool for the specified feature source if there is one FDO connection available. Otherwise, create a new FDO connection and add it to FDO connection pool. Then this FDO connection is bound to current session. It means this FDO connection becomes an exclusive connection and can’t be used by other sessions. Since then, any call to Feature Service for the feature source and the session, which needs an FDO connection, will always use the bound FDO connection till users call method UnbindConnection(...) to unbind this FDO connection or current session is time-out. By default, one session will be time-out after 20 minutes. Users can modify this setting through property [SiteServiceProperties]->SessionTimeOut in MapGuide Server configuration file "serverconfig.ini".

    /// \brief
    /// Bind FDO connection to current session for a feature source. 
    /// 
    /// \param featureSourceId (MgResourceIdentifier)
    /// A resource identifier referring to a feature source.
    ///
    /// \return
    /// Returns nothing.
    ///    
    void BindConnection(MgResourceIdentifier featureSourceId) = 0;

    /// \brief
    /// Unbind FDO connection bound to current session for the specified feature
    /// source. 
    /// 
    /// \param featureSourceId (MgResourceIdentifier)
    /// A resource identifier referring to a feature source.
    ///
    /// \return
    /// Returns nothing.
    ///
    void UnbindConnection(MgResourceIdentifier featureSourceId) = 0;

Some of methods in MgFeatureService don’t depend on an existing feature source and an FDO connection. So this change will not affect them. For example, MgFeatureService::GetFeatureProviders, MgFeatureService::XmlToSchema, and so on.

Implications

This is new API only. There will be no effect on existing applications. However, API documentation needs to be updated.

Test Plan

Add unit tests for those new methods into the existing Feature Service unit tests.

Funding/Resources

Supplied by Autodesk.