MapGuide RFC 182 - Library initialization entry point
This page contains a change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.
|RFC Template Version||(1.0)|
|Submission Date||4 Aug 2020|
|Last Modified||12 Aug 2020|
|Assigned PSC guide(s)||(when determined)|
|Voting History||(vote date)|
This RFC proposes to add a new
MgUnintializeLibrary APIs for properly initializing and tearing down the MapGuide API respectively when used in a class library context.
Foundation(exposed to .net via the
Geometry(exposed to .net via the
PlatformBase(exposed to .net via the
An example of this usage is FDO Toolbox, where this subset of the MapGuide API is used to provide coordinate system lookup and transformation services through the
MgCoordinateSystem family of APIs.
However, usage of the MapGuide API in this context reveals a major teething issue around exceptions. Namely any exceptions thrown in this context will not have localizable error messages because the MapGuide API has not initialized with an appropriate string bundle. As a result, exceptions thrown from the MapGuide API in this particular context will not contain any useful error messages.
There is also the risk that we may be using code that uses the ACE library in an un-initialized state
Normal MapGuide web applications do not have this problem as they call
MgInitializeWebTier that will set up the localizable strings among other things. This API however, only exists in the
WebSupport (exposed to .net via the
OSGeo.MapGuide.Web.dll assembly) and is not available to applications using the
MgUninitializeLibrary APIs to
void MgInitializeLibrary(CREFSTRING stringResourcesPath, CREFSTRING locale); void MgUnintializeLibrary();
MgInitializeLibrary API will initialize the MapGuide API with the given path to the localized string bundle.
To address (https://trac.osgeo.org/mapguide/ticket/1368), this API will also call
ACE::init() to make sure any usage of ACE in the
PlatformBase subset is used with the ACE library already initialized
MgUnitializeLibrary API will call
ACE::fini() to make sure the ACE library is properly torn down. Calling this API from .net is optional and is provided for completeness.
These APIs will be exposed to .net as:
static void OSGeo.MapGuide.FoundationApi.MgInitializeLibrary(string stringResourcesPath, string locale)
static void OSGeo.MapGuide.FoundationApi.MgUnitializeLibrary()
This is already implemented in the library_init sandbox. Upon adoption of this RFC, it will be merged into trunk.
None. These are new APIs and only for the .net variant of the MapGuide API
For normal MapGuide web applications, they can (and are expected to) still call
MgInitializeWebTier as normal and do not have to call this new API.
For applications using the
PlatformBase subset, they must call this new
MgInitializeLibrary API to ensure they get proper error messages in caught exceptions from the MapGuide API.
Implement a standalone .net application that only references
PlatformBase subset that calls this new API
Verify any API that would throw an exception produces localizable error messages when inspecting the caught exception
Funding / Resources