= !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 [wiki:MapGuideRfcs 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.


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

{{{
    /// \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.