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

== Status ==

||RFC Template Version||(1.0)||
||Submission Date||4 Aug 2020||
||Last Modified||12 Aug 2020||
||Author||Jackie Ng||
||RFC Status||adopted||
||Implementation Status||implemented||
||Proposed Milestone||4.0||
||Assigned PSC guide(s)||(when determined)||
||'''Voting History'''||(vote date)||
||+1||Jackie,Gordon,Reno||
||+0||||
||-0||||
||-1||||
||no vote|| ||

== Overview ==

This RFC proposes to add a new `MgInitializeLibrary` and `MgUnintializeLibrary` APIs for properly initializing and tearing down the MapGuide API respectively when used in a class library context.

== Motivation ==

Although an uncommon use case, it is possible to use the following parts of the MapGuide API in a context that is free of any dependencies to a MapGuide Server or Web Tier.

 * `Foundation` (exposed to .net via the `OSGeo.MapGuide.Foundation.dll` assembly)
 * `Geometry` (exposed to .net via the `OSGeo.MapGuide.Geometry.dll` assembly)
 * `PlatformBase` (exposed to .net via the `OSGeo.MapGuide.PlatformBase.dll` assembly)

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 `Foundation`/`Geometry`/`PlatformBase` subset.

== Proposed Solution ==

Add new `MgInitializeLibrary` and `MgUninitializeLibrary` APIs to `Foundation`

{{{

void MgInitializeLibrary(CREFSTRING stringResourcesPath, CREFSTRING locale);

void MgUnintializeLibrary();
}}}

The `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 `Foundation`/`Geometry`/`PlatformBase` subset is used with the ACE library already initialized

The `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 [https://trac.osgeo.org/mapguide/browser/sandbox/jng/library_init library_init sandbox]. Upon adoption of this RFC, it will be merged into trunk.

== Implications ==

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 `Foundation`/`Geometry`/`PlatformBase` subset, they must call this new `MgInitializeLibrary` API to ensure they get proper error messages in caught exceptions from the MapGuide API.

== Test Plan ==

Implement a standalone .net application that only references `Foundation`/`Geometry`/`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 ==

Community