Introducing: New experimental bindings for the MapGuide API

I haven't been quiet on the MapGuide front. I've just been deeply entrenched in my lab conducting an important experiment whose results are finally coming into fruition that I am back here to make this exciting announcement.

That experiment was: Can we generate bindings for the MapGuide API using a vanilla version of SWIG? Yes we can!

Background

This is an important question that we needed an answer for and we wanted that answer to be "Yes". 

We currently provide bindings for the MapGuide API in:

• Java
• PHP 5.x
• .net (full framework)

However, we currently use an ancient and heavily modified version of SWIG, whose unclear audit trail of modifications and changes means that being able to support newer versions of PHP (ie. PHP 7.x) or variants of .net like .net Core is nigh-impossible, which puts us in a bit of a pickle because:

• PHP 5.6 (our current bundled version of PHP) will be end-of-life on December 2018. Bundling and targeting an EOL version of PHP is not a good look. To bundle the current version of PHP (7.x) we need to be able to generate a compatible PHP extension for it. We can't do that with current internal copy of SWIG as the zend extension APIs have massively breaking changes from PHP5 to PHP7.
• .net Core is where the action is at in the .net space, and not having a presence in this space diminishes our story of being able to build MapGuide applications in .net because as time goes on, that definition of ".net" will assume to mean both the (windows-only) full framework and (cross-platform) .net core.
• We may want to add support for additional programming languages in the future. Can't do it with our super-modified copy of SWIG again because of the unclear history of changes made to this tool.

Given these factors, and the untenable situation we currently find ourselves in technology-wise, we needed to explore the possibility of generating the bindings using a vanilla (un-modified) version of SWIG. If we're going to go vanilla, we want the latest and greatest, which supports generating bindings for PHP7, and can support .net core with the right amount of SWIG typemap elbow-grease, so all the more motivation to get this working!

What we now have

2 months since the decision to embark on this journey, the mission to get functional MapGuide bindings using vanilla SWIG has been a success! We now have the following bindings for the MapGuide API:

• A Java binding modeled on the non-crufty official Java binding. Requires Java 7 or higher.
• A (currently windows-only) PHP extension for PHP 7.1
• A netstandard2.0-compatible binding for .net that works on both .net Core and full framework and is also cross-platform for platforms where both .net Core and official MapGuide binary packages are available for. For Linux, that means this .net binding works in Ubuntu 14.04 64-bit (where .net Core also has packages available). The nuget package for this binding is fully self-contained and includes the necessary native dependencies (both 32 and 64-bit) needed for the .net library to work. For .net full framework, it includes an MSBuild .targets file to ensure all the required native dependencies are copied out to your application's output directory.

Where to get it

You can grab the bits from the releases page of the mapguide-api-bindings GitHub repo.

For .net, you will have to setup a local package source and drop the nuget package there in order to consume in your library/application.

You will need MapGuide Open Source 3.1.1 installed as this is the only version of MapGuide I am generating these bindings for and testing against. Please observe the current supported platform matrix to see what combinations of technology stacks work with this new set of bindings. Please also observe the respective notes on the .net, PHP and Java bindings to observe what changes and adjustments you need to make in your MapGuide application should you want to try out these bindings.

Sample applications (to make sure this stuff works)

As proof that these bindings work, here's a sample asp.net core application using the new MapGuide .net binding. As a testament to what targeting .net Core gives us, you could bypass building the sample application from source and perhaps give the self-contained package a go. Thanks to the powerful publishing capabilities provided by the dotnet CLI, we can publish a self-contained .net core application with zero external dependencies. In the case of this sample application, you can download the zip, extract it to a windows or Ubuntu 14.04 64-bit machine with a standard MapGuide Open Source 3.1.1 install, run the MvcCoreSample executable within, go to http://localhost:5000 and your MapGuide application is up and running!

For Java and PHP, I'm still cooking up some sample applications in the same vein as the asp.net core one (ie. Porting across the MapGuide Developer's Guide samples), but for now the only verification that these bindings work is that our current binding test suite run to completion (with some failures, but these failures are known failures that are also present in our current bindings).

Where to from here?

I intend for the mapguide-api-bindings project to serve as an incubation area where we can iron out any show-stopping problems before planning for the eventual inclusion into MapGuide proper and supplementing (and in the case of PHP, replacing) our current bindings because eventually, we have to. We cannot keep bundling and targeting PHP 5.x forever. We need to be able to target newer versions of these programming languages, and maybe in some cases new programming languages.

mapguide-api-bindings project repo
asp.net core sample application repo

Announcing: MapGuide Maestro 6.0m9

Here's a new milestone release of MapGuide Maestro. Here's what's new in this release.

mapguide-react-layout support

One of the design goals of mapguide-react-layout viewer was to be highly compatible with existing Web and Flexible layout documents ensuring for the same authoring experience as the existing AJAX and Fusion viewer offerings.

However, the authoring experience in Maestro knows nothing about mapguide-react-layout, so any authoring experience still assumes the use of AJAX or Fusion viewers.

With this release, we have a new preference for specifying the base URL of a mapguide-react-layout installation.

Once this is set, the Web and Flexible Layout editors light up with additional viewer URLs allowing you to load the Web/Flexible Layout with a mapguide-react-layout template of your choice. 

Since the UI for this has changed from a read-only text box to a combo box, once cannot easily select the URL to copy/paste. To workaround this, a convenience "Copy to Clipboard" button is included to easily copy the current viewer URL for pasting elsewhere.

The other authoring experience change is that a new Flexible Layout will no longer include Fusion widgets that are not supported by mapguide-react-layout. These widgets are really esoteric ones, so most authors won't probably notice any differences.

MgTileSeeder improvements

The new MgTileSeeder tool has been improved with the following changes:

• A new --failed-requests parameter for specifying a log file to log failed requests to
• A new --max-parallelism parameter for controlling the max degreee of parallelism when sending tile requests
• New xyz_replay and mapguide_replay commands for re-requesting failed requests from a log file previously logged via the new --failed-requests parameter

Improved OGR Feature Source support

The OGR provider has been the primary recipient of my continued developer attention since the release of MapGuide Open Source 3.1.1 as there are many things in the provider with room for improvement. Given this, it was time to also give the OGR provider equivalent treatment in Maestro, so with this release, feature sources using the OGR provider now has its own specialized editor.

Most of the UI here should be self-explanatory, but the Other Properties section deserves some explanation. This is a future-proof data grid for editing connection properties that may be introduced in future builds/releases of the OGR provider.

Another case where the OGR provider gets better treatment is the support in the SHP feature source editor to convert it across to use the OGR provider. 

This feature was added to improve the SHP story for MapGuide on 64-bit Linux where the current dedicated SHP provider has unresolved 64-bit portability problems making it unusable. However, the OGR provider has no such issues making it a viable alternative FDO provider for SHP files on 64-bit Linux. This conversion feature helps facilitate this transition in an easy manner. However, there's still some glaring problems with the converted OGR feature source, such as the FDO provider using a hard-coded schema name of "OGRSchema". Nothing some python scripting elbow grease can't fix afterwards. Or you can watch this space :)

Other fixes/changes

• Fix: Rename resource with "update references" checked will disregard overwrite flag
• Fix: NullReferenceException when ticking a new geometry type and adding a rule to the grid for the first time in Layer Definition editor
• Fix: MgInvalidRepositoryTypeException when validating layers. Previous workaround was to disable validation on save. With this release you can safely re-enable this if you so choose.
• Fix: Editing default path in line usage context in Symbol Definition editor does nothing
• Fix: Cannot browse symbol definiton parameters in any field of the Path editor dialog 

Download 
Project Web Site

Some patches and fixes of MapGuide Open Source 3.1.1

Barely a week after releasing MapGuide Open Source 3.1.1, I've added some patches that may be of use for some of you out there.

Firstly, I've uploaded a newer release of Fusion that includes a fix for an issue with Google Maps support discovered after the 3.1.1 release. If you downloaded Fusion with the updated Bing Maps support in the past, this release is packaged in the same fashion: Download, extract and overwrite the existing Fusion installation.

Secondly, for those that use Oracle and have been clamoring for 12c support. I've uploaded experimental King Oracle FDO provider dlls that have been built against the Oracle 12c instant client SDK. These providers have not yet been fully tested against Oracle 12c and has been made available for you to provide any feedback or report any issues regarding 12c support.

If either one of these patches is of interest to you, grab them from the updated 3.1.1 release notes page.

Announcing: mg-desktop and MapGuide nuget packages for 3.1.1

It's been so long since putting out the last release of MapGuide that you sometimes forget that there are also supplemental build artifacts that tail off of the main MapGuide build process that need to be released as well!

In our case, that would be new nuget packages for the MapGuide .net API and mg-desktop.

The new mg-desktop binaries are also available as plain zip packages, should the NuGet way of acquiring not work out for you.

Announcing: MapGuide Open Source 3.1.1

I am pleased to announce the final release of MapGuide Open Source 3.1.1

The only changes from the Release Candidate are:

• A fix in the AJAX viewer to prevent clicks in interactive tooltip content from falling through (possibly accidentally triggering map selections as a result).
• Permission fixes for the windows installer and linux install scripts so that the Fusion QuickPlot widget can work out of the box.

Download/Release Notes

Announcing: mapguide-react-layout 0.11.2

This is another small bugfix release that updates OpenLayers to 4.6.5 and fixes the following:

• More scalable vertical text CSS for sidebar template
• Fix QuickPlot not working without toggling print box first

Project Home Page
Download
mapguide-react-layout on npm

Making Immutable.JS objects easier to work with in TypeScript: TypeScript 2.8 edition

TypeScript 2.8 was released today and one of the new touted features is conditional types.

With the introduction of condition types, it was worth revisiting an older post of mine about making immutable.js easier to use in TypeScript and see how one would solve this problem with TypeScript 2.8.

For reference, consider these interfaces:

1 2 3 4 5 6 7 8 9 10

interface IGeographicCoordinate { lat: number; lng: number; } interface IPlacemark { id: number; coordinate: IGeographicCoordinate; name: string; }

At the time of that post (this was before the revolutionary TypeScript 2.0 release), this was the best I could do to work with the immutable.js versions objects that adhered to the shape of the above interfaces.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

type GeographicCoordinateProperties = "lat" | "lng"; type PlacemarkProperties = "id" | "coordinate" | "name"; interface IGeographicCoordinateImmutable { get(key: GeographicCoordinateProperties): any; get(key: "lat"): number; get(key: "lng"): number; } interface IPlacemarkImmutable { get(key: PlacemarkProperties): any; get(key: "id"): number; get(key: "coordinate"): IGeographicCoordinateImmutable; get(key: "name"): string; }

Notice we had to manually write "immutable" equivalents of every interface and we didn't have constructs like keyof to auto-deduce all the allowed property names. We also had to manually spell out all the specific return types for each property name due to mapped types not existing yet at that point in time.

With TypeScript 2.8, we can leverage conditional types and features from earlier versions of TypeScript to create this majestic piece of generic and type-safe beauty:

1 2 3 4 5 6 7 8 9 10 11

interface ImmutableObject<T> { get<P extends keyof T>(key: P): T[P] extends Array<infer U> ? ImmutableList<U> : T[P] extends object ? ImmutableObject<T[P]> : T[P]; } interface ImmutableList<T> { count(): number; get(index: number): T extends object ? ImmutableObject<T> : T; } // The immutable.js fromJS() API declare function fromJS<T>(obj: T): ImmutableObject<T>;

So how does this work? To illustrate, lets update our example interfaces to include a 3rd interface

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

interface IGeographicCoordinate { lat: number; lng: number; } interface IPlacemark { id: number; coordinate: IGeographicCoordinate; name: string; } interface ISearchResult { query: string; results: IPlacemark[]; }

Then let's start with the get method of ImmutableObject<T>

The fragment P extends keyof T describes the type placeholder P on this method that is any variable that is a valid member name of type T. Using our above interfaces as an example, keyof IPlacemark is the type equivalent of:

 "id" | "coordinate" | "name"

The type of key parameter of the get method is constrained to any of the member names in T (auto-deduced via the keyof operator), thus you cannot plug in names of members that are not part of T.

The return type T[P] is a mapped type that gives the corresponding type based on the value you put in for the key parameter. If we use IPlacemark as an example:

• Calling get with "id" will deduce T[P] to the type: number
• Calling get with "coordinate" will deduce T[P] to the type: IGeographicCoordinate
• Calling get with "name" will deduce T[P] to the type: string

We then leverage the new conditional types feature to conditionally deduce the appropriate return type based on properties of T[P] that we can ask of through the conditional types feature:

• If the mapped type is an array (T[P] extends Array) resolve the return type to ImmutableList of the inferred type U. The infer U fragment defines an ad-hoc type placeholder U that will resolve to the item type of the array.
• Otherwise, if it is an object (T[P] extends object) resolve the return type to ImmutableObject of the mapped type
• Otherwise, it will resolve the return type to the mapped type.

To illustrate with ISearchResult as an example:

• Calling get with "query" will deduce a return type of: string
• Calling get with "results" will deduce a return type of: ImmutableList<IPlacemark>

Now on to the get method of ImmutableList<T>

ImmutableList<T> is a immutable collection wrapper. The get method here simply returns the item of type T at the specified index. Once again we leverage conditional types to ask some questions of the type T to deduce the correct return type.

• If T is an object (T extends object), resolve the return type to: ImmutableObject<T>, making this mapped type fully recursive all the way down however many levels it needs to go
• Otherwise T must only be a primitive type, so resolve the return type as-is.

Now how do we know this actually works and is not some abstract piece of theory?

See for yourself on the TypeScript playground (NOTE: If the code fragment doesn't load in the playground, you can copy/paste the code from this gist I've prepared earlier)

No red squiggles! Also, put your mouse over every variable, you will see the type matches the type specified in the respective end-of-line comment.

Hopefully this post has shed some light on how powerful this new conditional types feature of TypeScript 2.8 really is