== FDO Connection Pooling ==


=== Introduction ===

Clients such as Autodesk Map and OSGeo !MapGuide !OpenSource have experienced the need to manage the number of FDO connection objects that are being created within their applications. Continuously creating, initializing and releasing connections has been costly with a noticeable degradation in memory usage and performance.

This document describes an enhancement to the FDO API to enable connection pooling and connection reuse within the implementation of the FDO API. This implementation will provide a common standard for all applications implementing support for FDO. 

The FDO API will be enhanced to allow creation of FdoIConnection objects based on a series of connection parameters including provider name, connection string, configuration document and long transaction name. Applications requesting an FDO connection using these parameters will be returned a newly created connection if a previous connection has not already been created with identical parameters. If an existing connection interface had previously been created and is not currently in use by another process, it will be returned to the calling application. 

=== Design ===

The following new unmanaged class will be added to support connection pooling progress.

1) Class !FdoConnectionCacheEntry[[BR]]
2) Class !FdoConnectionCache[[BR]]
3) Class !FdoConnectionCachePair[[BR]]

To support connection pooling, the following unmanaged interfaces and classes will be modified.

1) Interface FdoIReader[[BR]]
2) Interface FdoIConnection[[BR]]
3) Interface IConnectionManager[[BR]]
4) Class !FdoConnectionManager[[BR]]

To support connection pooling, the following managed interfaces and classes will be modified.

1) Interface OSGeo.FDO.Commands.Feature.IReader [[BR]]
2) Interface OSGeo.FDO.Connections.IConnection[[BR]]
3) Interface OSGeo.FDO.IConnectionManager[[BR]]
4) Class OSGeo.FDO.Connections.IConnectionImp[[BR]]
5) Class OSGeo.FDO.!ClientServices.!ConnectionManager[[BR]]

==== API ====

===== Unmanaged API =====

====== Class !FdoConnectionCacheEntry (new) ======

{{{
/// \brief
///  
/// FdoConnectionCacheEntry is a cache entry class that enables 
/// FdoIConnection objects to be cached and exposed through FdoConnectionManager. 
/// Instances of FdoConnectionCacheEntry are stored in an instance of
/// FdoConnectionCache and are accessible using an instance of 
/// FdoConnectionCachePair.
///
class FdoConnectionCacheEntry
{
public:
    /// \brief
    ///  
    /// Constructs a default instance of a FdoConnectionCacheEntry object.
    FdoConnectionCacheEntry(void);

    /// \brief
    ///  
    /// Default destructor for FdoConnectionCacheEntry objects.
    virtual ~FdoConnectionCacheEntry(void);

public:
    /// \brief
    /// Determines if the cached FdoIConnection instance is being
    /// used by a client application
    /// 
    /// \return
    /// Returns true if the cached connection is in use, otherwise false.
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual FdoBoolean InUse(void);

    /// \brief
    /// Retrieves the FdoIConnection object contained in the cache entry object
    /// 
    /// \return
    /// Returns the FdoIConnection object attached to the cahe entry. The
    /// returned connection object's reference count will be incremented. 
    /// Callers are expected to Release the connection once finished with it.
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual FdoIConnection* GetConnection(void);

    /// \brief
    /// Sets the FdoIConnection object contained in the cache entry object
    /// 
    /// \param fdoConnection
    /// The FdoIConnection object to be attached to the cahe entry. The
    /// set connection object's reference count will be incremented by 1. The
    /// connection object will be Released once the the cache entry is deleted.
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    /// \return
    /// Returns nothing. 
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual void SetConnection(FdoIConnection* fdoConnection);

    /// \brief
    /// Gets the date and time the FdoIConnection object contained in the 
    /// cache was last accessed from the cache. The DateTime will be used 
    /// to determine when the connection has timed out and can be released 
    /// from the cache.
    /// 
    /// \return
    /// Returns an instance of FdoDateTime containing the date and time the 
    /// FdoIConnection object was last accessed from the cache. 
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual FdoDateTime GetLastTimeUsed(void);

    /// \brief
    /// Sets the date and time the FdoIConnection object contained in the 
    /// cache was last accessed from the cache. The DateTime will be used 
    /// to determine when the connection has timed out and can be released 
    /// from the cache.
    /// 
    /// \param time
    /// An instance of FdoDateTime containing the date and time the 
    /// FdoIConnection object was last accessed from the cache. 
    /// Throws an instance of FdoClientServicesException * if an error occurs.
    /// 
    /// \return
    /// Returns nothing. 
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual void SetLastTimeUsed(FdoDateTime time);

    /// \brief
    /// Gets the connection string used to initialize and identify the FdoIConnection 
    /// when it was created and added to the cache.
    /// 
    /// \return
    /// Returns an FdoString containing the connectionString used to initialize 
    /// the FdoIConnection object and uniquely identify it in the cache. 
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual FdoString* GetConnectionString(void);

    /// \brief
    /// Sets the connection string used to initialize and identify the FdoIConnection 
    /// when it was created and added to the cache.
    /// 
    /// \param time
    /// An instance of FdoString containing the connection string used to initialize 
    /// the FdoIConnection object and uniquely identify it in the cache. 
    /// 
    /// \return
    /// Returns nothing. 
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual void SetConnectionString(FdoString* connectionString);

    /// \brief
    /// Gets the configuration used to initialize and identify the FdoIConnection 
    /// when it was created and added to the cache.
    /// 
    /// \return
    /// Returns an FdoString containing the configuration string used to initialize 
    /// the FdoIConnection object and uniquely identify it in the cache. 
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual FdoString* GetConfiguration(void);

    /// \brief
    /// Sets the configuration used to initialize and identify the FdoIConnection 
    /// when it was created and added to the cache.
    /// 
    /// \param time
    /// An instance of FdoString containing the configuration string used to initialize 
    /// the FdoIConnection object and uniquely identify it in the cache. 
    /// 
    /// \return
    /// Returns nothing. 
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual void SetConfiguration(FdoString* configuration);

    /// \brief
    /// Gets the long transaction name used to initialize and identify the FdoIConnection 
    /// when it was created and added to the cache.
    /// 
    /// \return
    /// Returns an FdoString containing the long transaction name used to  
    /// initialize the FdoIConnection object and uniquely identify it in the cache. 
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual FdoString* GetLongTransactionName(void);

    /// \brief
    /// Sets the long transaction name used to initialize and identify the FdoIConnection 
    /// when it was created and added to the cache.
    /// 
    /// \param time
    /// An instance of FdoString containing the long transaction name used to initialize 
    /// the FdoIConnection object and uniquely identify it in the cache. 
    /// 
    /// \return
    /// Returns nothing. 
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual void SetLongTransactionName(FdoString* longTransaction);

private:
    FdoIConnection* m_fdoConnection;
    FdoStringP m_connectionString;
    FdoStringP m_configuration;
    FdoStringP m_longTransactionName;
    FdoDateTime m_lastUsed;
};
}}}

====== Class !FdoConnectionCache (new) ====== 

{{{
/// \brief
///  
/// The FdoConnectionCache class provides the storage mechanism for a map 
/// of cached FdoIConnection objects. The Standard Template Library multimap 
/// class is used for the storage and retrieval of data from a collection in which the 
/// each element is a pair that has both a data value and a sort key. The value of the 
/// key does not need to be unique and is used to order the data automatically. 
/// The value of an element in a multimap, but not its associated key value, may be 
/// changed directly. Instead, key values associated with old elements must be deleted 
/// and new key values associated with new elements inserted.
///
/// Refer to http://msdn2.microsoft.com/en-us/library/1ka6hya8.aspx
/// for a detailed description of the std::multimap class.
///
typedef std::multimap<std::wstring, FdoConnectionCacheEntry*> FdoConnectionCache;
}}}

====== Class !FdoConnectionCachePair (new) ====== 

{{{
/// \brief
///  
/// The FdoConnectionCachePair class provides the std pair object inserted into 
/// the FdoConnectionCache. The Standard Template Library pair class provides for 
/// the ability to treat two objects as a single object.
///
/// Refer to http://msdn2.microsoft.com/en-us/library/t9zb6cdt.aspx
/// for a detailed description of the std::pair class.
///
typedef std::pair<std::wstring, FdoConnectionCacheEntry*> FdoConnectionCachePair;
}}}

====== Interface IConnectionManager (modified) ====== 

The IConnectionManager Interface will be modified to support caching of FdoIConnection objects.

{{{
/// \brief
///  
/// The IConnectionManager interface supports dynamic creation of connection objects 
/// given a provider name, connection string, configuration and long transaction name. Newly
/// created connection objects will be initialized with the parameters supplied to the 
/// CreateConnection methods. 
///
/// If required, connections can be pooled and reused by the the calling application.
/// Applications requesting an FDO connection using the above connection
/// parameters will be returned a newly created connection if a previous connection has
/// not already been created with identical parameters. If an existing connection interface had
/// previously been created and is not currently in use by another process, it will be returned
/// to the calling application.
///
/// \remarks
///  
/// In order for dynamic creation to work, each dynamic link library, shared library, 
/// or assembly that implements a provider must supply a well-defined entry point function that 
/// takes as input a provider name and returns an FdoIConnection instance. The definition of the 
/// entry point function is language and platform dependent. For this release of FDO, on the 
/// Windows platform, windows libraries supporting FDO providers will be expected to support the 
/// following well-known entry point function which will create and returns an unitialized 
/// connection object.
///
///         FdoIConnection * CreateConnection();
///
class IConnectionManager : public FdoIDisposable
{
public:
    /// \brief
    /// Ebables the caching of FDO Connections. If caching has previously been enabled, 
    /// and the poolSize is greater than the previous value used to initialze the pool, 
    /// the cache will be re-initialized with the new poolSize. If caching has previously 
    /// been enabled, the value of timeout shall replace the previous value used to initialize 
    /// the cache.
    /// 
    /// \param poolSize 
    /// Input The size of the FDO connection cache pool
    /// 
    /// \param timeout 
    /// Input The length of time in seconds a connection may remain unused before it is removed from 
    /// the connection cache 
    /// 
    /// \return
    /// Returns nothing. Throws an instance of FdoClientServicesException * if an error occurs.
    /// 
    FDO_API virtual void EnableCaching(FdoInt32 poolSize, FdoInt32 timeout) = 0;

    /// \brief
    /// Disables the caching of FDO Connections. All FDO Connections will be removed from the cache.
    /// 
    /// \return
    /// Returns nothing. Throws an instance of FdoClientServicesException * if an error occurs.
    /// 
    FDO_API virtual void DisableCaching() = 0;

    /// \brief
    /// Creates an unitialized connection object given the provider name. The connection 
    /// can optionally be initialized with a connectionString.
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \param connectionString 
    /// Input The connectionString that will be used to configure the FDO connection 
    /// 
    /// \return
    /// Returns an instance of an FdoIConnection object. Throws an instance of 
    /// FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual FdoIConnection* CreateConnection(FdoString* providerName, 
                                                     FdoString* connectionString = NULL) = 0;
	
    /// \brief
    /// Creates a connection object given the provider name and configuration document. 
    /// The connection can optionally be initialized with a connectionString and long 
    /// transaction name.
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \param configStream 
    /// Input The XML configuration stream that will be used to configure the FDO connection 
    /// 
    /// \param connectionString 
    /// Input The connectionString that will be used to configure the FDO connection 
    /// 
    /// \param longTransactionName 
    /// Input The longTransactionName that will be used to configure the FDO connection 
    /// 
    /// \return
    /// Returns an instance of an FdoIConnection object. 
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual FdoIConnection* CreateConnection(FdoString* providerName, 
                                                     FdoIoStream* configStream, 
                                                     FdoString* connectionString = NULL, 
                                                     FdoString* longTransactionName = NULL) = 0;

    /// \brief
    /// Finds a cached connection in the connection pool by name.
    /// 
    /// \param connectionName 
    /// Input The name of the connection.
    /// 
    /// \return
    /// Returns an instance of an FdoIConnection if the named connection 
    /// exists in the connection pool. Throws an instance of 
    /// FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual FdoIConnection* FindConnection(FdoString* connectionName) = 0;

    /// \brief
    /// Frees cached FDO connections that are not currently in use. The cleanup 
    /// can be localized to freeing connections corresponding to providers identified 
    /// by a combination of their provider name and connection string
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \return
    /// Returns nothing. Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual void FreeCachedConnections(FdoString* providerName = NULL) = 0;

    /// \brief
    /// Frees all cached FDO connections that have expired pass their timeout value
    /// 
    /// \return
    /// Returns nothing. Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual void FreeExpiredConnections() = 0;

    /// \brief
    /// Frees a connection library reference given the provider name.
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \return
    /// Returns nothing. Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual void FreeLibrary(FdoString* providerName) = 0;
};
}}}

====== Class !FdoConnectionManager (modified) ====== 

The !FdoConnectionManager class, implmenets !IConnectionManager will be modified to implement support for caching of FdoIConnection objects within the FDO API. This implementation will be available to all FDO clients.

{{{
/// \brief
///  
/// The FdoConnectionManager class supports dynamic creation of connection objects 
/// given a provider name, connection string, configuration and long transaction name. Newly
/// created connection objects will be initialized with the parameters supplied to the 
/// CreateConnection methods. 
///
/// If required, connections can be pooled and reused by the the calling application.
/// Applications requesting an FDO connection using the above connection
/// parameters will be returned a newly created connection if a previous connection has
/// not already been created with identical parameters. If an existing connection interface had
/// previously been created and is not currently in use by another process, it will be returned
/// to the calling application.
///
/// \remarks
/// 
/// In order for dynamic creation to work, each dynamic link library, shared library, 
/// or assembly that implements a provider must supply a well-defined entry point function that 
/// takes as input a provider name and returns an FdoIConnection instance. The definition of the 
/// entry point function is language- and platform-dependent. For this release of FDO, the 
/// windows libraries supporting FDO providers will be expected to support the following well-known 
/// entry point function, which will create and return an unitialized connection object:
///
///        IConnection * CreateConnection();
///
class FdoConnectionManager : public IConnectionManager
{
    /// \brief
    /// Instances of interface FdoFeatureAccessManager are responsible for the 
    /// lifespan of FdoConnectionManager
    /// 
    friend class FdoFeatureAccessManager;

protected:
    /// Constructs a default instance of a FdoProviderRegistry object.
    FdoConnectionManager();

    /// Default destructor for FdoProviderRegistry object.
    virtual ~FdoConnectionManager();

    /// Deletes instance of FdoConnectionManager. Called only when reference count equals 0
    virtual void Dispose();

public:
    /// \brief
    /// Ebables the caching of FDO Connections. If caching has previously been enabled, 
    /// and the poolSize is greater than the previous value used to initialze the pool, 
    /// the cache will be re-initialized with the new poolSize. If caching has previously 
    /// been enabled, the value of timeout shall replace the previous value used to initialize 
    /// the cache.
    /// 
    /// \param poolSize 
    /// Input The size of the FDO connection cache pool
    /// 
    /// \param timeout 
    /// Input The length of time in seconds a connection may remain unused before it is removed from 
    /// the connection cache 
    /// 
    /// \return
    /// Returns nothing..
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual void EnableCaching(FdoInt32 poolSize, FdoInt32 timeout);

    /// \brief
    /// Disables the caching of FDO Connections. All FDO Connections will be removed from the cache.
    /// 
    /// \return
    /// Returns nothing. 
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual void DisableCaching();

    /// \brief
    /// Creates an unitialized connection object given the provider name. The connection 
    /// can optionally be initialized with a connectionString.
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \param connectionString 
    /// Input The connectionString that will be used to configure the FDO connection 
    /// 
    /// \return
    /// Returns an instance of an FdoIConnection object. 
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual FdoIConnection* CreateConnection(FdoString* providerName, 
                                                     FdoString* connectionString = NULL);
	
    /// \brief
    /// Creates a connection object given the provider name and configuration document. 
    /// The connection can optionally be initialized with a connectionString and long 
    /// transaction name.
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \param configStream 
    /// Input The XML configuration stream that will be used to configure the FDO connection 
    /// 
    /// \param connectionString 
    /// Input The connectionString that will be used to configure the FDO connection 
    /// 
    /// \param longTransactionName 
    /// Input The longTransactionName that will be used to configure the FDO connection 
    /// 
    /// \return
    /// Returns an instance of an FdoIConnection object. 
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual FdoIConnection* CreateConnection(FdoString* providerName, 
                                                     FdoIoStream* configStream, 
                                                     FdoString* connectionString = NULL, 
                                                     FdoString* longTransactionName = NULL);

    /// \brief
    /// Finds a cached connection in the connection pool by name.
    /// 
    /// \param connectionName 
    /// Input The name of the connection.
    /// 
    /// \return
    /// Returns an instance of an FdoIConnection if the named connection 
    /// exists in the connection pool. Throws an instance of 
    /// FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual FdoIConnection* FindConnection(FdoString* connectionName) = 0;

    /// \brief
    /// Frees cached FDO connections that are not currently in use. The cleanup 
    /// can be localized to freeing connections corresponding to providers identified 
    /// by a combination of their provider name and connection string
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \return
    /// Returns nothing. 
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual void FreeCachedConnections(FdoString* providerName = NULL);

    /// \brief
    /// Frees all cached FDO connections that have expired pass their timeout value
    /// 
    /// \return
    /// Returns nothing. 
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual void FreeExpiredConnections();

    /// \brief
    /// Frees a connection library reference given the provider name 
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \return
    /// Returns nothing. 
    /// Throws an instance of FdoClientServicesException if an error occurs.
    /// 
    FDO_API virtual void FreeLibrary(FdoString* providerName);

private:
    /// Provider library reference map
    FdoModuleMap m_moduleMap;

    /// Cache of Provider connection objects
    FdoConnectionCache m_connectionCache;
};
}}}

====== Interface FdoIConnection (modified) ====== 

A new property 'name' will be added to the FdoIConnection interface. This property will be accessible through !GetName() and !SetName methods.  These methods will allow clients to retrieve pooled connection interfaces through the !IConnectionManager. 

{{{
/// \brief
/// Gets the optional name associated to the connection. The connection name
/// can be used to enhance re-use of connection objects through connection pooling.
/// Connection pooling is implemented through the FDO IConnectionManager interface. 
/// Named pooled connections can be retrieved through the use of 
/// IConnectionManager::FindConnection(FdoString* connectionName)
/// 
/// \return
/// Returns the name of the connection
/// 
FDO_API virtual FdoString* GetName(void) = 0;

/// \brief
/// Sets an optional name that will be associated to the connection. The connection 
/// name can be used to enhance re-use of connection objects through connection pooling.
/// Connection pooling is implemented through the FDO IConnectionManager interface. 
/// Named pooled connections can be retrieved through the use of 
/// IConnectionManager::FindConnection(FdoString* connectionName)
/// 
/// \param connectionName 
/// Input the name to be associated to the connection
/// 
/// \return
/// Returns nothing
/// 
FDO_API virtual void SetName(FdoString* connectionName) = 0;
}}}

====== Interface FdoIReader (modified) ====== 

A new !GetConnection() method will be added to the FdoIReader that will allow clients to retrieve the connection interface that corresponds to a cached reader in their applications. 

{{{
/// \brief
/// Gets the connection object associated to the reader. The returned connection
/// will be the owner connection that created the reader interface. 
/// 
/// \return
/// Returns the instance of IConnection associated to the Reader
/// 
FDO_API virtual FdoIConnection* GetConnection() = 0;
}}}

===== Managed API =====

====== Interface OSGeo.FDO.Commands.Feature.IReader (modified) ====== 

A new !GetConnection() method will be added to the FdoIReader that will allow clients to retrieve the connection interface that corresponds to a cached reader in their applications. 

{{{
/// \brief
/// Gets the connection associated to the reader. The returned connection
/// will be the owner connection that created the reader interface. 
/// 
/// \return
/// Returns the instance of IConnection associated to the Reader
/// 
NAMESPACE_OSGEO_FDO_CONNECTIONS::IConnection* GetConnection();
}}}

====== Interface OSGeo.FDO.Connections.IConnection (modified) ======

A new property 'name' will be added to the FdoIConnection interface. This property will be accessible through !GetName() and !SetName methods.  These methods will allow clients to retrieve pooled connection interfaces through the IConnectionManager. 

{{{
/// \brief
/// Gets the optional name associated to the connection. The connection name
/// can be used to enhance re-use of connection objects through connection pooling.
/// Connection pooling is implemented through the FDO IConnectionManager interface. 
/// Named pooled connections can be retrieved through the use of 
/// IConnectionManager::FindConnection(FdoString* connectionName)
/// 
/// \return
/// Returns the name of the connection
/// 
__property System::String* get_Name();

/// \brief
/// Sets an optional name that will be associated to the connection. The connection 
/// name can be used to enhance re-use of connection objects through connection pooling.
/// Connection pooling is implemented through the FDO IConnectionManager interface. 
/// Named pooled connections can be retrieved through the use of 
/// IConnectionManager::FindConnection(FdoString* connectionName)
/// 
/// \param connectionName 
/// Input the name to be associated to the connection
/// 
/// \return
/// Returns nothing
/// 
__property System::Void set_Name(System::String* connectionName);
}}}

====== Class OSGeo.FDO.Connections.IConnectionImp (modified) ======

A new property 'name' will be added to the FdoIConnectionImp class. This property will be accessible through !GetName() and !SetName methods.  These methods will allow clients to retrieve pooled connection interfaces through the IConnectionManager. 

{{{
/// \brief
/// Gets the optional name associated to the connection. The connection name
/// can be used to enhance re-use of connection objects through connection pooling.
/// Connection pooling is implemented through the FDO IConnectionManager interface. 
/// Named pooled connections can be retrieved through the use of 
/// IConnectionManager::FindConnection(FdoString* connectionName)
/// 
/// \return
/// Returns the name of the connection
/// 
__property System::String* get_Name();

/// \brief
/// Sets an optional name that will be associated to the connection. The connection 
/// name can be used to enhance re-use of connection objects through connection pooling.
/// Connection pooling is implemented through the FDO IConnectionManager interface. 
/// Named pooled connections can be retrieved through the use of 
/// IConnectionManager::FindConnection(FdoString* connectionName)
/// 
/// \param connectionName 
/// Input the name to be associated to the connection
/// 
/// \return
/// Returns nothing
/// 
__property System::Void set_Name(System::String* connectionName);
}}}

====== Interface OSGeo.FDO.IConnectionManager (modified) ======

The IConnectionManager Interface will be modified to support caching of FdoIConnection objects.

{{{
/// \brief
///  
/// The IConnectionManager interface supports dynamic creation of connection objects 
/// given a provider name, connection string, configuration and long transaction name. Newly
/// created connection objects will be initialized with the parameters supplied to the 
/// CreateConnection methods. 
///
/// If required, connections can be pooled and reused by the the calling application.
/// Applications requesting an FDO connection using the above connection
/// parameters will be returned a newly created connection if a previous connection has
/// not already been created with identical parameters. If an existing connection interface had
/// previously been created and is not currently in use by another process, it will be returned
/// to the calling application.
///
/// \remarks
/// 
/// In order for dynamic creation to work, each dynamic link library, shared library, 
/// or assembly that implements a provider must supply a well-defined entry point function that 
/// takes as input a provider name and returns an IConnection instance. The definition of the 
/// entry point function is language- and platform-dependent. For this release of FDO, the 
/// windows libraries supporting FDO providers will be expected to support the following well-known 
/// entry point function, which will create and return an unitialized connection object:
///
///        IConnection * CreateConnection();
///
public __gc __interface IConnectionManager : public System::IDisposable
{
public:
    /// \brief
    /// Ebables the caching of FDO Connections. If caching has previously been enabled, 
    /// and the poolSize is greater than the previous value used to initialze the pool, 
    /// the cache will be re-initialized with the new poolSize. If caching has previously 
    /// been enabled, the value of timeout shall replace the previous value used to initialize 
    /// the cache.
    /// 
    /// \param poolSize 
    /// Input The size of the FDO connection cache pool
    /// 
    /// \param timeout 
    /// Input The length of time in seconds a connection may remain unused before it is removed from 
    /// the connection cache 
    /// 
    /// \return
    /// Returns nothing.
    /// 
    System::Void EnableCaching(System::Int32 poolSize, System::Int32 timeout);

    /// \brief
    /// Disables the caching of FDO Connections. All FDO Connections will be removed from the cache.
    /// 
    /// \return
    /// Returns nothing. 
    /// 
    System::Void DisableCaching();

    /// \brief
    /// Creates an unitialized connection object given the provider name.
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \return
    /// Returns an instance of an IConnection interface. 
    /// 
    NAMESPACE_OSGEO_FDO_CONNECTIONS::IConnection* CreateConnection(String* providerName);

    /// \brief
    /// Creates an unitialized connection object given the provider name. The connection 
    /// can optionally be initialized with a connectionString.
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \param connectionString 
    /// Input The connectionString that will be used to configure the FDO connection 
    /// 
    /// \return
    /// Returns an instance of an IConnection interface.
    /// 
    NAMESPACE_OSGEO_FDO_CONNECTIONS::IConnection* CreateConnection(
                                String* providerName,
                                String* connectionString);

    /// \brief
    /// Creates a connection object given the provider name and configuration document. 
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \param configStream 
    /// Input The XML configuration stream that will be used to configure the FDO connection 
    /// 
    /// \return
    /// Returns an instance of an IConnection interface. 
    /// 
    NAMESPACE_OSGEO_FDO_CONNECTIONS::IConnection* CreateConnection(
                                String* providerName,
                          	NAMESPACE_OSGEO_COMMON_IO::IoStream* configStream);

    /// \brief
    /// Creates a connection object given the provider name and configuration document. 
    /// The connection can optionally be initialized with a connectionString.
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \param configStream 
    /// Input The XML configuration stream that will be used to configure the FDO connection 
    /// 
    /// \param connectionString 
    /// Input The connectionString that will be used to configure the FDO connection 
    /// 
    /// \return
    /// Returns an instance of an IConnection interface. 
    /// 
    NAMESPACE_OSGEO_FDO_CONNECTIONS::IConnection* CreateConnection(
                                String* providerName,
                                NAMESPACE_OSGEO_COMMON_IO::IoStream* configStream,
                                String* connectionString);

    /// \brief
    /// Creates a connection object given the provider name and configuration document. 
    /// The connection can optionally be initialized with a connectionString and long 
    /// transaction name.
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \param configStream 
    /// Input The XML configuration stream that will be used to configure the FDO connection 
    /// 
    /// \param connectionString 
    /// Input The connectionString that will be used to configure the FDO connection 
    /// 
    /// \param longTransactionName 
    /// Input The longTransactionName that will be used to configure the FDO connection 
    /// 
    /// \return
    /// Returns an instance of an IConnection interface. 
    /// 
    NAMESPACE_OSGEO_FDO_CONNECTIONS::IConnection* CreateConnection(
                                String* providerName,
                                NAMESPACE_OSGEO_COMMON_IO::IoStream* configStream,
                                String* connectionString,
                                String* longTransactionName);

    /// \brief
    /// Finds a cached connection in the connection pool by name.
    /// 
    /// \param connectionName 
    /// Input The name of the connection.
    /// 
    /// \return
    /// Returns an instance of an IConnection if the named connection exists in the connection pool. 
    /// 
    NAMESPACE_OSGEO_FDO_CONNECTIONS::IConnection* FindConnection(System::String* connectionName);
    
    /// \brief
    /// Frees cached FDO connections that are not currently in use. The cleanup 
    /// can be localized to freeing connections corresponding to providers identified 
    /// by a combination of their provider name and connection string
    /// 
    /// \return
    /// Returns nothing..
    /// 
    System::Void FreeCachedConnections();

    /// \brief
    /// Frees cached FDO connections that are not currently in use. The cleanup 
    /// can be localized to freeing connections corresponding to providers identified 
    /// by a combination of their provider name and connection string
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider . This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \return
    /// Returns nothing.
    /// 
    System::Void FreeCachedConnections(System::String* providerName);

    /// \brief
    /// Frees all cached FDO connections that have expired pass their timeout value
    /// 
    /// \return
    /// Returns nothing.
    /// 
    System::Void FreeExpiredConnections();

    /// \brief
    /// Frees a connection library reference given the provider name.
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \return
    /// Returns nothing. 
    /// 
   System::Void FreeLibrary(System::String* providerName);
};
}}}
 
====== Class OSGeo.FDO.!ClientServices.!ConnectionManager (modified) ======

The !ConnectionManager class, implmenets IConnectionManager will be modified to implement support for caching of Connection objects within the FDO API. This implementation will be available to all FDO clients.

{{{
/// \brief
///  
/// The ConnectionManager class supports dynamic creation of connection objects 
/// given a provider name, connection string, configuration and long transaction name. Newly
/// created connection objects will be initialized with the parameters supplied to the 
/// CreateConnection methods. 
///
/// If required, connections can be pooled and reused by the the calling application.
/// Applications requesting an FDO connection using the above connection
/// parameters will be returned a newly created connection if a previous connection has
/// not already been created with identical parameters. If an existing connection interface had
/// previously been created and is not currently in use by another process, it will be returned
/// to the calling application.
///
/// \remarks
/// 
/// In order for dynamic creation to work, each dynamic link library, shared library, 
/// or assembly that implements a provider must supply a well-defined entry point function that 
/// takes as input a provider name and returns an IConnection instance. The definition of the 
/// entry point function is language- and platform-dependent. For this release of FDO, the 
/// windows libraries supporting FDO providers will be expected to support the following well-known 
/// entry point function, which will create and return an unitialized connection object:
///
///        IConnection * CreateConnection();
///
public __sealed __gc class ConnectionManager : 
        public NAMESPACE_OSGEO_RUNTIME::Disposable, 
        public NAMESPACE_OSGEO_FDO::IConnectionManager
{
public:
    /// \brief
    /// Ebables the caching of FDO Connections. If caching has previously been enabled, 
    /// and the poolSize is greater than the previous value used to initialze the pool, 
    /// the cache will be re-initialized with the new poolSize. If caching has previously 
    /// been enabled, the value of timeout shall replace the previous value used to initialize 
    /// the cache.
    /// 
    /// \param poolSize 
    /// Input The size of the FDO connection cache pool
    /// 
    /// \param timeout 
    /// Input The length of time in seconds a connection may remain unused before it is removed from 
    /// the connection cache 
    /// 
    /// \return
    /// Returns nothing.
    /// 
    System::Void EnableCaching(System::Int32 poolSize, System::Int32 timeout);

    /// \brief
    /// Disables the caching of FDO Connections. All FDO Connections will be removed from the cache.
    /// 
    /// \return
    /// Returns nothing. 
    /// 
    System::Void DisableCaching();

    /// \brief
    /// Creates an unitialized connection object given the provider name.
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \return
    /// Returns an instance of an IConnection interface. 
    /// 
    NAMESPACE_OSGEO_FDO_CONNECTIONS::IConnection* CreateConnection(System::String* providerName);

    /// \brief
    /// Creates an unitialized connection object given the provider name. The connection 
    /// can optionally be initialized with a connectionString.
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \param connectionString 
    /// Input The connectionString that will be used to configure the FDO connection 
    /// 
    /// \return
    /// Returns an instance of an IConnection interface.
    /// 
    NAMESPACE_OSGEO_FDO_CONNECTIONS::IConnection* CreateConnection(System::String* providerName, System::String* connectionString);

    /// \brief
    /// Creates a connection object given the provider name and configuration document. 
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \param configStream 
    /// Input The XML configuration stream that will be used to configure the FDO connection 
    /// 
    /// \return
    /// Returns an instance of an IConnection interface. 
    /// 
    NAMESPACE_OSGEO_FDO_CONNECTIONS::IConnection* CreateConnection(
                                System::String* providerName,
                                NAMESPACE_OSGEO_COMMON_IO::IoStream* configStream);


    /// \brief
    /// Creates a connection object given the provider name and configuration document. 
    /// The connection can optionally be initialized with a connectionString.
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \param configStream 
    /// Input The XML configuration stream that will be used to configure the FDO connection 
    /// 
    /// \param connectionString 
    /// Input The connectionString that will be used to configure the FDO connection 
    /// 
    /// \return
    /// Returns an instance of an IConnection interface. 
    /// 
    NAMESPACE_OSGEO_FDO_CONNECTIONS::IConnection* CreateConnection(
                                System::String* providerName,
                                NAMESPACE_OSGEO_COMMON_IO::IoStream* configStream,
                                System::String* connectionString);


    /// \brief
    /// Creates a connection object given the provider name and configuration document. 
    /// The connection can optionally be initialized with a connectionString and long 
    /// transaction name.
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \param configStream 
    /// Input The XML configuration stream that will be used to configure the FDO connection 
    /// 
    /// \param connectionString 
    /// Input The connectionString that will be used to configure the FDO connection 
    /// 
    /// \param longTransactionName 
    /// Input The longTransactionName that will be used to configure the FDO connection 
    /// 
    /// \return
    /// Returns an instance of an IConnection interface. 
    /// 
    NAMESPACE_OSGEO_FDO_CONNECTIONS::IConnection* CreateConnection(
                                System::String* providerName,
                                NAMESPACE_OSGEO_COMMON_IO::IoStream* configStream,
                                System::String* connectionString,
                                System::String* longTransactionName);

    /// \brief
    /// Finds a cached connection in the connection pool by name.
    /// 
    /// \param connectionName 
    /// Input The name of the connection.
    /// 
    /// \return
    /// Returns an instance of an IConnection if the named connection exists in the connection pool. 
    /// 
    NAMESPACE_OSGEO_FDO_CONNECTIONS::IConnection* FindConnection(System::String* connectionName);
 
    /// \brief
    /// Frees cached FDO connections that are not currently in use. The cleanup 
    /// can be localized to freeing connections corresponding to providers identified 
    /// by a combination of their provider name and connection string
    /// 
    /// \return
    /// Returns nothing.
    /// 
    System::Void FreeCachedConnections();

    /// \brief
    /// Frees cached FDO connections that are not currently in use. The cleanup 
    /// can be localized to freeing connections corresponding to providers identified 
    /// by a combination of their provider name and connection string
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider . This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \return
    /// Returns nothing.
    /// 
    System::Void FreeCachedConnections(System::String* providerName);

    /// \brief
    /// Frees all cached FDO connections that have expired pass their timeout value
    /// 
    /// \return
    /// Returns nothing.
    /// 
    System::Void FreeExpiredConnections();

    /// \brief
    /// Frees a connection library reference given the provider name.
    /// 
    /// \param providerName 
    /// Input The unique name of the feature provider. This name should be of the form 
    /// [Company].[Provider].[Version].
    /// 
    /// \return
    /// Returns nothing.
    /// 
    System::Void FreeLibrary(System::String* providerName);
};
}}}