MapGuide RFC 185 - Use vanilla SWIG to generate API bindings

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	7 Jul 2022
Last Modified	16 Sep 2022
Author	Jackie Ng
RFC Status	adopted
Implementation Status	completed
Proposed Milestone	4.0
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1	Jackie,Gordon,Crispin
+0
-0
-1
no vote

Overview

This RFC proposes to adopt using the latest un-modified version of SWIG to generate our API bindings for .net, Java and PHP.

Motivation

For the longest time now, MapGuide has been shackled to PHP 5.6 which has been out of support for a long time. It is not a good look for us security-wise to ship new releases of MapGuide that bundle a long out-of-date version of PHP.

The reason we haven't upgraded our bundled copy of PHP is because PHP has changed the internal zend extension APIs for PHP 7+ in such a breaking manner that it is not possible to generate API bindings with our internal (heavily-modified) copy of SWIG that will work with the currently supported version of PHP (8.1.x)

The current version of SWIG (4.0) supports generating bindings for PHP 7 and the current git master supports generating bindings for PHP 7/8.

To finally be able to bundle the latest version of PHP with our MapGuide releases, we need to be able to generate functional MapGuide API bindings for PHP using the official version of SWIG instead of our ancient and heavily-modified internal copy in Oem/SwigEx. In the process, we might as well also be using official SWIG to try and generate functional MapGuide API bindings for .net and Java as well.

Proposed Solution

We will use the current git master of swig at ​https://github.com/swig/swig to generate MapGuide API bindings for .net, Java and PHP. The rest of this RFC will refer to this version of SWIG as "vanilla SWIG"

The PHP binding targets PHP 8.1, and we will be bundling PHP 8.1 with the MapGuide install packages.

A new top-level Bindings subdirectory and solution will house the various API binding projects and supporting tools/libraries.

The following projects/directories will be removed as a result of being obsoleted by this new bindings:

• Oem/SwigEx (SWIG will now be acquired externally through official channels and is assumed to exist before building)
• Oem/SQLite (Proof-of-concept SWIG binding to SQLite and legacy Web API test administration tools)
• BuildTools/CC.Net (unused CI configuration)
• BuildTools/WebTools/IMake (relocated to new top-level Bindings directory)
• Web/src/JavaApi (legacy "crufty" Java binding)
• Web/src/JavaApiEx (legacy "non-crufty" Java binding)
• Web/src/PhpApi (legacy PHP 5.6 binding)
• Web/src/PhpMapGuideApiEnvConfig (support library for the legacy PHP 5.6 binding)

Vanilla SWIG is now a build requirement. On Windows, pre-compiled binaries of the expected version of SWIG will be provided for convenience. On Linux, the build scripts will acquire and build SWIG source from the github repo if the expected version of SWIG is not present.

Fusion and all existing web tier applications (eg. AJAX Viewer, Site Administrator) will be migrated across to work against these new API bindings.

The existing web tier test suite will also be migrated across to work against these new API bindings.

These changes have been implemented in the ​vanilla_swig sandbox for MapGuide.

A compatible version of Fusion that works against the PHP 8 binding has been implemented in the ​php8 sandbox branch in the Fusion repo.

Upon the adoption of this RFC, these changes will be merged into trunk in their respective repos.

The implementation of this RFC does not include updates to the Windows installer and does not include the tarball for PHP 8.1 (to avoid svn merge problems). Such items will be addressed after RFC adoption and trunk merges.

Impact summary of API changes

To support generating functional API bindings for .net/Java/PHP with vanilla SWIG, we had to make a few changes to our C++ API surface to facilitate/accommodate the code generation needs of vanilla SWIG.

Such changes are detailed below.

General (all languages)

• The exception hierarchy has been flattened to now be just MgException. All existing sub-classes of MgException have been removed. A new GetExceptionCode() method is available to fetch the appropriate error classification. The available classifications are simply the names of all the removed sub-classes and whose names are now contained in a new MgExceptionCodes string constant class.
  • This was done to avoid having to deal with MgException polymorphism in a consistent manner across our 3 SWIG language targets.
  • If you used to catch specific MgException subclass types, refer to the example below for how to migrate your exception handling code for your target language

Before (PHP):

try {
    ...
} catch (MgUnauthorizedAccessException $e) {
    ...
}

After (PHP):

try {
    ...
} catch (MgException $e) {
    if ($e->GetExceptionCode() == MgExceptionCodes::MgUnauthorizedAccessException) {
        ...
    }
}

Before (Java):

try {
    ...
} catch (MgUnauthorizedAccessException e) {
    ...
}

After (Java):

try {
    ...
} catch (MgException e) {
    if (e.getExceptionCode() == MgExceptionCodes.MgUnauthorizedAccessException) {
        ...
    }
}

Before (C#/.net):

try {
    ...
} catch (MgUnauthorizedAccessException e) {
    ...
}

After (C#/.net):

try {
    ...
} catch (MgException e) {
    if (e.GetExceptionCode() == MgExceptionCodes.MgUnauthorizedAccessException) {
        ...
    }
}

After (C#/.net alternative method):

try {
    ...
} catch (MgException e) when (e.GetExceptionCode() == MgExceptionCodes.MgUnauthorizedAccessException) {
    ...
}

• The constant members of the MgResourcePermission class are prefixed with Permission. For example MgResourcePermission::ReadOnly is now MgResourcePermission::PermissionReadOnly
  • This was done to prevent reserved name collisions in PHP where readonly is now a reserved keyword and cannot be used as a static member name.

PHP specific notes

• constants.php is no longer required! All constants of the MapGuide API are now baked into the PHP zend extension, eliminating the need for this file. When migrating, remove all include/require references to this file.
• The MgPlotSpecification constructor now requires you to specify all 4 margin parameters . If you don't need a margin, or need to set it later on (with the SetMargins() method), you can pass 0.0 for all 4 arguments.
• PHP 8 is more strict about data types and attempting to do things like assigning int to double and vice-versa and will generally error out in such cases.
  • This strictness will generally arise in calls to APIs like MgRenderingService::RenderMap where there is a mixture of int and double parameters in the method signature.
  • To ensure the correct data types are passed in, wrap expected int parameters with intval() and expected double parameters with doubleval()

In addition to the above changes, several public APIs are renamed specifically in the PHP binding to avoid incompatible signatures due to how overloaded/inherited methods are handled in PHP 8.

MgCoordinateSystemMeasure

The following method signatures in MgCoordinateSystemMeasure are renamed with a Simple suffix added.

• double GetDistance(double x1, double y1, double x2, double y2) (now called GetDistanceSimple)
• double GetAzimuth(double lon1, double lat1, double lon2, double lat2) (now called GetAzimuthSimple)
• MgCoordinate GetCoordinate(double lon, double lat, double azimuth, double distance) (now called GetCoordinateSimple)

MgMap

The new overload of Create introduced in MapGuide RFC 157 has been renamed to CreateStateless

Java specific notes

The new Java binding carries all the enhancements from the previous MapGuideJavaApiEx binding, whose changes will be repeated here:

All method names now adopt camelCase instead of PascalCase to match Java naming conventions.

Proxies for various collection classes implement the java.util.Collection interface allowing for greater interoperability with existing Java code that works with such interfaces:

These classes include:

• MgClassDefinitionCollection (as Collection<MgClassDefinition>)
• MgFeatureSchemaCollection (as Collection<MgFeatureSchema>)
• MgPropertyDefinitionCollection (as Collection<MgPropertyDefinition>)
• MgPropertyCollection (as Collection<MgProperty>)
• MgStringCollection (as Collection<java.lang.String>)
• MgLayerCollection (as Collection<MgLayerBase>)
• MgLayerGroupCollection (as Collection<MgLayerGroup>)

The following collection classes do not implement the java.util.Collection interface due to disparity in interface and implementation

• MgIntCollection (int is not an object in Java)
• MgBatchPropertyCollection (can't implement as Collection<MgPropertyCollection> due to a different contains() API)

The following proxy classes implement java.util.Iterable

• MgReadOnlyLayerCollection

Classes that implement java.util.Collection or java.lang.Iterable can be iterated with java's enhanced for loop like so:

MgClassDefinitionCollection classes = ...
for (MgClassDefinition clsDef : classes) {
    ...
}

As a result of adopting camelCase naming conventions along with some classes implementing special Java interfaces, various methods in the MapGuide API have been renamed specifically for Java:

• The converted MgException.getStackTrace() conflicts with java.lang.Throwable.getStackTrace()
• The converted MgPropertyDefinition.delete() conflicts with the SWIG-generated delete() method for finalization
• The converted MgClassDefinition.delete() conflicts with the SWIG-generated delete() method for finalization
• The converted MgFeatureSchema.delete() conflicts with the SWIG-generated delete() method for finalization
• The converted add() method of any MapGuide collection class conflicts with the add() method as specified in the java.util.Collection interface (MapGuide's add() returns void, java.util.Collection's add() returns boolean)

The conflicting methods are renamed in the wrapper as so:

• MgException::getStackTrace() will become MgException.getExceptionStackTrace()
• MgPropertyDefinition.delete() will become MgPropertyDefinition.markAsDeleted()
• MgClassDefinition.delete() will become MgClassDefinition.markAsDeleted()
• MgFeatureSchema.delete() will become MgFeatureSchema.markAsDeleted()
• The add() method of any MapGuide collection class implementing java.util.Collection will become addItem()

MapGuideApiEx.jar is no longer generated and bundled.

Java 8 or higher is required to create/run Java MapGuide applications.

.net specific notes

This wrapper is now provided as a set of NuGet packages targeting netstandard2.0

• OSGeo.MapGuide.Foundation
• OSGeo.MapGuide.Geometry
• OSGeo.MapGuide.PlatformBase
• OSGeo.MapGuide.MapGuideCommon
• OSGeo.MapGuide.Web

Being a netstandard2.0 package, you can use this in:

• Your existing (legacy) ASP.net WebForms/MVC application targeting (legacy) .net Framework 4.8
• A greenfield ASP.net application targeting .net Core/.net 5+

Refer to deployment impact summary below for remarks around .net deployment.

As part of this RFC, we will offer experimental support to target [.net Core/.net 5+] on Linux. This is achieved by adding support in our Linux build system for building the "common libs subset". This subset consists of:

• Internal Thirdparty Libraries
  • ACE
  • GEOS
  • JsonCpp
  • Xerces-C
  • CS-Map
• MapGuide Common Libraries
  • Foundation
  • Geometry
  • PlatformBase
  • MapGuideCommon
• Web Tier common libraries
  • HttpHandler
  • WebApp
  • WebSupport

Along with the .net SWIG interop glue libraries. Once this subset is built, all the .so library files will be copied over to a Windows build environment, where such files will be bundled into the resulting NuGet packages we create for the MapGuide API for .net

For maximum portability on Linux, the "common libs subset" should be built against internal Thirdparty libraries on a Linux distro with the oldest supported version of glibc. On adoption of this RFC, is is expected that this subset will be built in a CentOS 7 environment.

For a full end-to-end build of MapGuide for both Windows/Linux, the recommended build order will be:

1. Common libs subset on a CentOS 7 environment
2. Copy/transfer the compiled .so libraries from the CentOS 7 environment to the Windows environment
3. Build MapGuide on Windows
4. Build MapGuide on supported Linux distros

Despite now being a netstandard2.0 library, Mac OSX is not (and will not be) a supported runtime environment

Impact summary for deployments (Windows)

PHP

The PHP binding is built for the Non-Thread-Safe (NTS) profile. This means that we no longer configure PHP support in Apache via mod_php. Instead PHP support in Apache is now configured via FastCGI through mod_fcgid. This allows us to bundle/ship one set of PHP NTS binaries that can correctly work in both IIS and Apache configurations on Windows. Previously, we did the incorrect thing of bundling the Thread-Safe (TS) PHP binaries and used it for both Apache (supported) and IIS (un-supported).

Barring the required migrations in your PHP codebase, the deployment process/experience should remain the same.

Java

The bundled version of Tomcat is 9.0.37. Refer to the Tomcat documentation for any migration/configuration/breaking changes from previous Tomcat versions

.net

The MapGuide web tier installation will still assume the default of IIS and .net Framework 4.8 for the .net configuration.

If you are intending to deploy an ASP.net core MapGuide application to your MapGuide Web Tier, refer to the ​Microsoft-recommended deployment process for deploying to IIS

Impact summary for deployments (Linux)

PHP

Bundled PHP support does not use FastCGI like Windows. It still uses mod_php

Java

The bundled version of Tomcat is 9.0.37. Refer to the Tomcat documentation for any migration/configuration/breaking changes from previous Tomcat versions

.net

If you are intending to take advantage of the experimental Linux support of the .net binding, you should follow the ​Microsoft-recommended deployment process for deploying an ASP.net core application to Linux with Apache as the web server, and make the necessary adjustments so that any part of the documentation that refers to Apache httpd refers to the copy bundled with the MapGuide installation.

Test Plan

Ensure the migrated web tier test suites pass against the new bindings.

Ensure AJAX viewer for all 3 languages are functional with these new bindings.

Ensure all code samples work under these new bindings.

Ensure Fusion is functional with these new bindings.

Ensure Site Administrator is functional.

Ensure Schema Report is functional.

Funding / Resources

Community