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.

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 ​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