The Map Guy(de)

Updated OSGeo Nabble archive link

2012-01-24T00:55:00.002+11:00

Those of you who prefer a forum-based frontend to the mapguide-users and other OSGeo mailing lists probably had warning about the migration of the OSGeo mailing list archives by nabble.

Well, in addition to breaking every existing mailing list link (I bet you all the nabble posts I've linked from this blog are completely broken now!), the old archive no longer gives you the link to the new archive location. Real smart move by Nabble!

Well in case anyone is wondering, here's the new link before nabble took it down along with the old archive: http://osgeo-org.1560.n6.nabble.com/

What's even funny is the notice at the top of the new archive location

We have moved the OSGeo.org archives to this location. Please update your bookmarks.

And just who is going to be able to read that? Certainly not the people who have been inconvenienced by this ill-thought out move!

/rant

How to: Use mg-desktop in your own .net applications

2012-01-23T23:49:00.001+11:00

Here I am, talking about mg-desktop and how it's the next best thing since sliced bread, but I haven't even explained how you can go about using it in your own .net applications! This post aims to rectify this problem.

This post will aim to show you how to create a simple .net WinForms application that displays a map from the Sheboygan sample data set with a basic selection handler. The final application will look like so:

Before we get started, make sure you have the following:

Visual Studio 2008 or newer (I'm using the express edition for this post)
The latest binary release of mg-desktop

Knowledge of the official MapGuide .net API is also assumed here because most of what you know about the official API is equally applicable to mg-desktop.

So fire up Visual Studio and let's get started!

1. Download mg-desktop

Download the latest binary release of mg-desktop and extract this archive to a directory of your choice. We will be referring to files in this location for the rest of this post.

2. Set up the Visual Studio Toolbox

In order to facilitate drag-and-drop of the map viewer component, we need to register the mg-desktop viewer component into the Visual Studio Toolbox. To do this, right click the toolbox and select Choose Items

This will bring up the Choose Toolbox Items dialog, click the browse button

Browse to the directory you extracted mg-desktop into and select the OSGeo.MapGuide.Viewer.dll assembly. This will add our viewer components to the list of available components.

The components for reference, are:

MgMapViewer - This is the map viewer component
MgLegend - This is the legend component which can control the display and visibility of layers in the map viewer. This component is optional
MgPropertyPane - This is the component for displaying attributes of selected features on the map viewer. This component is optional
MgDefaultToolbar - This is a component containing a common list of functions for interacting with the map viewer (zoom, pan, select, etc). This component is optional. You can roll your own map viewer toolbar, but that requires a lot of boilerplate to set up. This component is provided for convenience.

Ensure these components are ticked and click OK to add these components to the Visual Studio Toolbox.

3. Create a new WinForms project

NOTE: The mg-desktop map viewer is a WinForms component. You can technically use this component in a WPF application using the WPF-WinForms interop libraries, but that is beyond the scope of this tutorial.

Now we create our WinForms application. Select File - New Project and select the Windows Forms Application template.

4. Build our main form

If you look at the Visual Studio Toolbox, your components should now be visible whenever the WinForms designer is active

Drag and drop the MgDefaultToolbar component into the main form

Now drag and drop a StatusStrip component into the main form.

Add 4 labels to this status strip. These labels will be used to show the following:

The current mouse coordinates
Any status messages sent by the viewer
The current scale
The size of the map

Now add a SplitContainer to the main part of the form

Add a second SplitContainer to the left side of this form with horizontal orientation

Now we can drag and drop the remaining components. Set all components to Dock = Fill to occupy the full space of its container

Drag and Drop the MgLegend to the top-left panel
Drag and Drop the MgPropertyPane to the bottom-left panel
Finally, drag and drop the MgMapViewer to the main panel

Modify the properties of the lblMessage label as such:

Spring = true
TextAlign = MiddleLeft

This will ensure this label takes the maximum space in the status bar

Now we need to write some code.

5. Wire-up the viewer components

Now switch to the code view for Form1. Start by adding importing the OSGeo.MapGuide.Viewer namespace

   1:  using OSGeo.MapGuide.Viewer;

To show map viewer status messages, we need this form to implement the IMapStatusBar interface. This adds the following methods to our form

   1:  public void SetCursorPositionMessage(string message)

   2:  {

3:

   4:  }

5:

   6:  public void SetFeatureSelectedMessage(string message)

   7:  {

8:

   9:  }

10:

  11:  public void SetMapScaleMessage(string message)

  12:  {

13:

  14:  }

15:

  16:  public void SetMapSizeMessage(string message)

  17:  {

18:

  19:  }

These methods should be self explanatory. Simply connect the message parameter to its respective label

   1:  public void SetCursorPositionMessage(string message)

   2:  {

   3:      lblCoordinates.Text = message;

   4:  }

5:

   6:  public void SetFeatureSelectedMessage(string message)

   7:  {

   8:      lblMessage.Text = message;

   9:  }

10:

  11:  public void SetMapScaleMessage(string message)

  12:  {

  13:      lblScale.Text = message;

  14:  }

15:

  16:  public void SetMapSizeMessage(string message)

  17:  {

  18:      lblSize.Text = message;

  19:  }

Now how do we tie all of these components (viewer, toolbar, legend, property pane) together? We use a MapViewerController to do this. Override the OnLoad method like so:

   1:  protected override void OnLoad(EventArgs e)

   2:  {

   3:      new MapViewerController(mgMapViewer1,          //The MgMapViewer

   4:                              mgLegend1,             //The MgLegend

   5:                              this,                  //The IMapStatusBar

   6:                              mgPropertyPane1,       //The MgPropertyPane

   7:                              mgDefaultToolbar1);    //The MgDefaultToolbar

   8:  }

That one line (5 if you want to be pedantic), magically ties all our viewer components together. The MapViewerController basically handles all the plumbing so that your viewer components will properly communicate with each other. Some examples, include:

Selecting an object in the MgMapViewer will populate the MgPropertyPane with attributes of the selected feature
Ticking a layer on/off in the MgLegend will trigger a refresh of the MgMapViewer

The MapViewerController automagically sets up all of this for you.

Now we have a viewer that's all set up, now to load some data into it.

6. Code - Initialization

Before we show you how to do this, let's take a segway for a moment. Because we need to cover an important aspect of the mg-desktop API.

Like the official API, the mg-desktop API is driven by service classes. In mg-desktop, the following services are provided:

MgdResourceService (inherits from MgResourceService)
MgdFeatureService (inherits from MgFeatureService)
MgRenderingService
MgDrawingService
MgTileService

In the official API, you would access these services via a MgSiteConnection object. For mg-desktop we use the MgServiceFactory class to create instances of these services. For example, here's how you would create an instance of MgdFeatureService

   1:  MgServiceFactory factory = new MgServiceFactory();

   2:  MgdFeatureService featureService = (MgdFeatureService)factory.CreateService(MgServiceType.FeatureService);

Other service classes are created in a similar fashion. You would then use these service classes in the same fashion as you would with the official API.

Also like the official API, we need to initialize the whole thing through a config file first before we can use any of the classes in the API. In our case, the file is Platform.ini, and we initialize like so:

   1:  MgPlatform.Initialize("Platform.ini");

With that out of the way, we can start writing some code. First we need to add some references to the project. Add the following references from your mg-desktop directory

OSGeo.MapGuide.Foundation.dll
OSGeo.MapGuide.Geometry.dll
OSGeo.MapGuide.PlatformBase.dll
OSGeo.MapGuide.Desktop.dll
OSGeo.MapGuide.Viewer.Desktop.dll

Be sure to set these references (and OSGeo.MapGuide.Viewer) to (Copy Local = false)

Now in our application's entry point, insert our call to initialize the API. Also hook the application's exit event to MgPlatform.Terminate(), which does some library cleanup. Program.cs should look like this

   1:  using System;

   2:  using System.Collections.Generic;

   3:  using System.Linq;

   4:  using System.Windows.Forms;

   5:  using OSGeo.MapGuide;

6:

   7:  namespace MgDesktopSample

   8:  {

   9:      static class Program

  10:      {

  11:          /// <summary>

  12:          /// The main entry point for the application.

  13:          /// </summary>

  14:          [STAThread]

  15:          static void Main()

  16:          {

  17:              MgPlatform.Initialize("Platform.ini");

  18:              Application.ApplicationExit += new EventHandler(OnApplicationExit);

  19:              Application.EnableVisualStyles();

  20:              Application.SetCompatibleTextRenderingDefault(false);

  21:              Application.Run(new Form1());

  22:          }

23:

  24:          static void OnApplicationExit(object sender, EventArgs e)

  25:          {

  26:              MgPlatform.Terminate();

  27:          }

  28:      }

  29:  }

7. Code - Load a package and map

Now back in our main form, we modify the overridden OnLoad to do the following:

Check the existence of the map we want to load - Library://Samples/Sheboygan/Maps/Sheboygan.MapDefinition
If it doesn't exist, prompt the user for the Sheboygan.mgp package and load this package

   1:  MgServiceFactory factory = new MgServiceFactory();

   2:  MgdResourceService resSvc = (MgdResourceService)factory.CreateService(MgServiceType.ResourceService);

   3:  MgResourceIdentifier mapDefId = new MgResourceIdentifier("Library://Samples/Sheboygan/Maps/Sheboygan.MapDefinition");

   4:  //If this map definition doesn't exist, we ask the user to

   5:  //load the Sheboygan package

   6:  if (!resSvc.ResourceExists(mapDefId))

   7:  {

   8:      using (OpenFileDialog diag = new OpenFileDialog())

   9:      {

  10:          diag.Filter = "MapGuide Packages (*.mgp)|*.mgp";

  11:          if (diag.ShowDialog() == DialogResult.OK)

  12:          {

  13:              MgByteSource source = new MgByteSource(diag.FileName);

  14:              MgByteReader reader = source.GetReader();

  15:              resSvc.ApplyResourcePackage(reader);

  16:          }

  17:          else

  18:          {

  19:              //No map, nothing to do here

  20:              Application.Exit();

  21:          }

  22:      }

  23:  }

At this point, the map definition exists. So we can create a runtime map and load it into the viewer like so:

   1:  //Create our runtime map

   2:  MgdMap map = new MgdMap(mapDefId);

   3:  //We need a rendering service instance

   4:  MgRenderingService renderSvc = (MgRenderingService)factory.CreateService(MgServiceType.RenderingService);

   5:  //Create our viewer provider

   6:  MgMapViewerProvider provider = new MgDesktopMapViewerProvider(map, resSvc, renderSvc);

   7:  //Initialize our viewer with this provider

   8:  mgMapViewer1.Init(provider);

The final OnLoad method for our form looks like so:

   1:  protected override void OnLoad(EventArgs e)

   2:  {

   3:      new MapViewerController(mgMapViewer1,          //The MgMapViewer

   4:                              mgLegend1,             //The MgLegend

   5:                              this,                  //The IMapStatusBar

   6:                              mgPropertyPane1,       //The MgPropertyPane

   7:                              mgDefaultToolbar1);    //The MgDefaultToolbar

8:

   9:      MgServiceFactory factory = new MgServiceFactory();

  10:      MgdResourceService resSvc = (MgdResourceService)factory.CreateService(MgServiceType.ResourceService);

  11:      MgResourceIdentifier mapDefId = new MgResourceIdentifier("Library://Samples/Sheboygan/Maps/Sheboygan.MapDefinition");

  12:      //If this map definition doesn't exist, we ask the user to

  13:      //load the Sheboygan package

  14:      if (!resSvc.ResourceExists(mapDefId))

  15:      {

  16:          using (OpenFileDialog diag = new OpenFileDialog())

  17:          {

  18:              diag.Filter = "MapGuide Packages (*.mgp)|*.mgp";

  19:              if (diag.ShowDialog() == DialogResult.OK)

  20:              {

  21:                  MgByteSource source = new MgByteSource(diag.FileName);

  22:                  MgByteReader reader = source.GetReader();

  23:                  resSvc.ApplyResourcePackage(reader);

  24:              }

  25:              else

  26:              {

  27:                  //No map, nothing to do here

  28:                  Application.Exit();

  29:              }

  30:          }

  31:      }

32:

  33:      //Create our runtime map

  34:      MgdMap map = new MgdMap(mapDefId);

  35:      //We need a rendering service instance

  36:      MgRenderingService renderSvc = (MgRenderingService)factory.CreateService(MgServiceType.RenderingService);

  37:      //Create our viewer provider

  38:      MgMapViewerProvider provider = new MgDesktopMapViewerProvider(map, resSvc, renderSvc);

  39:      //Initialize our viewer with this provider

  40:      mgMapViewer1.Init(provider);

  41:  }

7. Set up post-build and other loose ends

Now if you've worked with the official MapGuide .net API (and this whole post assumes you do), you know that referencing the MapGuide .net assemblies does not instantly give you a working MapGuide application. That's because those .net assemblies are managed wrappers around unmanaged dlls, so you need them as well. So for the official API, you would copy all the dlls from mapviewernet into your application's output directory so that all dependencies are met.

For mg-desktop, we pretty much do the same thing, we copy everything from our mg-desktop directory to our application's output directory. Or to automate this, include an xcopy command as part of your project's post build event. Assuming you extracted the mg-desktop binaries to C:\mg-desktop, and example post build command would be like so:

This will copy all mg-desktop files (dlls, FDO, CS-Map dictionaries, etc, etc) to your application's output directory with the source directory structure intact, which is important because the default paths in Platform.ini are all relative.

If you are on a 64-bit machine, you will also need to explicitly set the CPU type of the application to x86 instead of Any CPU. If you don't do this, you will get a BadImageFormatException thrown at your face as your executable will default to 64-bit and will attempt to load a 32-bit assembly. Actually, you should do this anyway to ensure the application works on both 32-bit and 64-bit windows.

Once this is all set up, you can compile and run your application!

Go on. Have a play around. It is now a fully functional map viewer application!

8. Custom selection handling

One of the things you would probably want to do in your application is to listen for selection changes and run code in response to such changes. The MgMapViewer component exposes a SelectionChanged event for this very purpose.

So to display the address of a selected parcel, the event handler code would look like this:

   1:  private void mgMapViewer1_SelectionChanged(object sender, EventArgs e)

   2:  {

   3:      MgSelectionBase selection = mgMapViewer1.GetSelection();

   4:      MgReadOnlyLayerCollection layers = selection.GetLayers();

   5:      if (layers != null)

   6:      {

   7:          for (int i = 0; i < layers.GetCount(); i++)

   8:          {

   9:              MgLayerBase layer = layers.GetItem(i);

  10:              if (layer.Name == "Parcels") //The selected layer is parcels

  11:              {

  12:                  //Check that we only have one selected object

  13:                  int count = selection.GetSelectedFeaturesCount(layer, layer.FeatureClassName);

  14:                  if (count == 1)

  15:                  {

  16:                      MgFeatureReader reader = null;

  17:                      try

  18:                      {

  19:                          reader = selection.GetSelectedFeatures(layer, layer.FeatureClassName, false);

  20:                          if (reader.ReadNext())

  21:                          {

  22:                              //Address is in the RPROPAD property

  23:                              if (reader.IsNull("RPROPAD"))

  24:                                  MessageBox.Show("Selected parcel has no address");

  25:                              else

  26:                                  MessageBox.Show("Address: " + reader.GetString("RPROPAD"));

  27:                          }

  28:                      }

  29:                      finally //You must always close all readers, otherwise connections will leak

  30:                      {

  31:                          reader.Close();

  32:                      }

  33:                  }

  34:                  else

  35:                  {

  36:                      MessageBox.Show("Please select only one parcel");

  37:                  }

  38:                  break;

  39:              }

  40:          }

  41:      }

  42:  }

Which would result in this behaviour when selecting a parcel

Selecting multiple parcels gives you the following:

Wrapping up

Hopefully this should give you a comfortable introduction to mg-desktop and its viewer component. Where you go from here is completely up to you.

The source code for this example is available for download here

mg-desktop has moved

2012-01-19T04:53:00.000+11:00

With the implementation of MapGuide RFC117, I have finally migrated the source code for mg-desktop from its current home at Google Code to the official MapGuide Subversion repository

This migration allows for the mg-desktop codebase to better integrate with the MapGuide source that it builds on top of, and allows mg-desktop to receive upstream component fixes and updates much faster and allows for sharing of component dlls with future releases of MapGuide.

Also with everything together in one place, I can finally tackle some of the more interesting things like 64-bit and Linux builds and support for the VS2010 compiler.

The existing Google Code site will remain for archival purposes, but all mg-desktop development will now take place on the official MapGuide repo.

Since we're on the subject of mg-desktop, I might as well show you a visual changelog of the changes and features added to mg-desktop since I first announced it. Most of these changes I am showing in this post are centered on the map viewer component (otherwise there wouldn't be much to show :-)). So without much further ado:

1. Tooltip queries can slow down map interaction, so the default viewer toolbar now includes a command allowing you to toggle display of feature tooltips.

2. The viewer supports customizable selection color

3. To facilitate rapid development, the viewer component works with the Visual Studio designer infrastructure. Viewer properties and behaviour can be modified like you would any other form or control. The OSGeo.MapGuide.Viewer.dll must be registered with the Visual Studio Toolbox to support this workflow.

4. The default viewer toolbar has more useful commands such as:

Copying the current view of the map to the clipboard (as an image)
Selecting by radius and polygon

5. The legend control now functions like the one in the AJAX or Fusion viewer. Supporting display of themes, and having the ability to apply theme compression (because it too has problems with processing ridiculously large themes)

6. Layer and Group items in the legend control can have context menus attached to them

7. Like the AJAX and Fusion viewers, the property pane supports scrolling through the results of a selection set and zooming into individual results

At this point we have something approaching 90% of the functionality of the AJAX and Fusion viewers. The missing 10% are apparent once you see it:

No support for tiled maps. The viewer control has a property that allows tiled maps to be treated as regular groups of dynamic layers as a workaround. The math to calculate what tiles to fetch escapes me right now.
No mouse wheel zoom. The math to do this also escapes me right now.

If these items aren't dealbreakers for you, then mg-desktop is a more than suitable platform for building disconnected desktop mapping applications using the same MapGuide and FDO technology that you are all familiar with.

Some useful tools for debugging your MapGuide Applications

2012-01-19T03:47:00.001+11:00

A common problem with MapGuide development is trying to dig into the state of the runtime map, especially when trying to figure out why the new layer you've added to your runtime map is not showing. Here's some useful tools to help you peek into the runtime map.

1. mapinfo.aspx

Get the script here (you will also need the supporting viewresourcecontent.aspx script as well)

This was a script I wrote while porting over the MapGuide Developer's Guide samples to .net (which will be bundled with the next MapGuide Open Source release in *all* languages, instead of just PHP) to help me debug a mysterious bug where newly added layers are shown on the map, but not in the viewer legend. The script accepts two URL parameters:

MAPNAME - The name of the runtime map
SESSION - The current session id

Invoking this script, gives you a nice detailed view about the state of the given runtime map

You'll notice that the resource ids are hyperlinked. These links call into viewresourcecontent.aspx, which basically shows you the resource content of the hyperlinked resource id.

To set this up, drop mapinfo.aspx and viewresourcecontent.aspx into a directory of your choice. Set this directory up as an application in IIS, then create a bin directory and drop in the MapGuide dlls from your mapviewernet directory.

Then to invoke this script, enter http://url-to-your-directory/mapinfo.aspx?MAPNAME=theMapName&SESSION=your-mapguide-session-id

Because this script takes a MAPNAME and a SESSION parameter. It can automatically be used as an Invoke URL command in your Web Layout. Just create an Invoke URL command that points to mapinfo.aspx, attach it to a toolbar or menu and it is ready to be used in your Web Layout for instant debugging!

2. Runtime Map Inspector

Coming in the next release of Maestro, is a Runtime Map Inspector tool which fulfils the same purpose as mapinfo.aspx. Invoking the tool will bring up the familiar Maestro login (which you are advised to use the Administrator login as that can peek into any user's session repository). Once logged in, a new window will appear where you can fill in the required Map Name and Session ID and then click the Load Map button to bring up the runtime map.

The Runtime Map Inspector will be available in the next release under Tools - Runtime Map Inspector, or by running the RtMapInspector.exe

Hopefully, these new tools will make your MapGuide development experience that much more simpler (if it isn't already!)

My MapGuide/FDO wishlist for 2012

2011-12-31T16:42:00.003+11:00

Might as well get this in before the last day of the year ticks over

Here's a list of what I'm hoping for MapGuide/FDO in 2012 (or is this my personal to-do list? :-)).

FDO

1. Raster support for the PostGIS provider

The best open source spatial extension just recently had support for raster imagery. Wouldn't it be nice, to have all your vector and raster data in one centralised database that is accessible via FDO?

2. A more FDO-capable OGR provider

Like the ODBC provider, the OGR provider is a quick and easy way to tap into the vast array of data formats out there which do not have a dedicated FDO provider (most notably, MapInfo). However the OGR provider itself could do with some improvements to better support the FDO-isms like:

Supporting the ability to create data stores (ie. Mapping FdoICreateDataStore to OGR's CreateDataSource)
Ability to sort. The OGR SQL dialect supports ORDER BY clauses, so this should be possible. Sortability greatly improves Feature Join performance
FDO Join support. The OGR SQL dialect supports JOIN statements as well (only LEFT JOIN, but still a FDO supported join type)

3. FDO Join support for other FDO RDBMS providers

For the best Feature Join performance scenarios, all RDBMS-based providers should support this new API. Given the SQL Server provider (which supports FDO joins) is derived from a common base that all other FDO RDBMS providers come from, I'd gather that adding support for would be a case of flipping a few bits here and there.

MapGuide

1. Improve MapGuide's standing as a geospatial services platform

Or to put it in one word: Interoperability. Currently, MapGuide has excellent data interoperability (due to FDO) but has weak service interoperability. It only does WFS/WMS and not much else. Talking to a MapGuide Server and tapping into the services available still requires specialized and dedicated client code or software and not something that can work via one or more OGC standards.

OGC standards is the glue by which geospatial software and services (Closed or Open Source) can talk to each other. So we should support as many of them as we can! Here's a few worth supporting:

2. Native support for PDF output

Let's face it, nobody really plots to DWF. Everybody wants PDF, and it's easier to tell users to download/install a 5MB PDF reader application instead of Autodesk Design Review. The current solutions that are out there only embed an rendered map image to the PDF instead of rendering directly to the PDF. The easiest way to implement such support would be to implement a new MapGuide renderer with a Cairo backend. The upside of using Cairo is that it supports SVG output as well, so we can support an additional output format for free!

So there you have it, a much shorter list this time round because from an internal perspective, MapGuide has reached a point where it is a solid web mapping platform on most fronts. However if you take an outsider's perspective, there's still room for improvement.

Happy New Year everybody. Here's to a wonderful 2012!

New Year's Edit: Inflated the list slightly.

Announcing: MapGuide Maestro 4.0 Final + SDK

2011-12-23T17:58:00.001+11:00

I'm pleased to announce the availability of MapGuide Maestro 4.0 and SDK, just in time for Christmas!

Here's a rundown of the major changes since Maestro 3.5

You can now work with multiple site connections in the same application
A new local connection mode, backed by the new mg-desktop library
A new way to load really large package files
An easy way to translate your MapGuide applications
Brought back the Package Editor, missing since Maestro 2.1
A whole load of bugfixes and minor enhancements since Maestro 3.5 (all of which you can find in changelog.txt in your Maestro installation)

The Maestro API has also undergone some major changes, bringing back some of the niceties that have been missing since Maestro 2.1. A special thanks goes out to the following people who've helped make the Maestro API into a more developer-friendly experience:

Hans Milling
Gunter Becker
Crispin Hoult

The job's not finished on this front. There is still many things that can be done to improve the Maestro API developer experience even further. We'll leave that for next year :-)

Download

Improving the Feature Join Experience (or: Sort all the things!)

2011-12-15T03:56:00.000+11:00

Remember this screenshot?

Here's the current numbers as of right now

How did we achieve such godly performance numbers from a provider (SDF) that cannot take advantage of the recently implemented Feature Join optimization shortcut yet produces numbers just a tad higher than the new shortcut?

The answer: The existing Feature Join engine can actually perform well, it just picked the absolutely wrong join algorithm to do the join!

As explained previously, the GWS Query Engine "joins" two input feature readers (from both sides of the join) and returns a merged feature reader. Depending on the capabilities of both sides of the join, the following join algorithms are employed:

Nested Loops (both sides do not support ordering)
Nested block join and sorted block (left side supports ordering, right side does not)
Sort-Merge (both sides support ordering)
Batch Sorted block (left side does not support ordering, right side does)

Sort-Merge is the best algorithm of the lot here because it does not need to re-iterate any side of the join to process all the results. The new performance numbers in the second screenshot is due to the use of the Sort-Merge algorithm.

The reason we got such terrible numbers in the first screenshot is because Nested Loops was the algorithm chosen by the GWS Query Engine. It chose this algorithm because it determined that the SDF provider could not support ordered results.

This is actually incorrect because both SDF and SHP can actually produce sorted results, but can only sort on a single property (which I would wager is the standard Feature Join use case. Joining on multiple properties would be quite uncommon). It turns out that the GWS Query Engine fails to notice this when selecting the join algorithm to use.

So after tweaking the sortability check in the GWS Query Engine, the existing Feature Join performs slightly slower than the optimization shortcut, which brings up another interesting point: Aside from some obscure providers (OGR, WFS), nearly all the vector FDO providers support ordering, meaning now there is a very high chance that the feature joins you set up will have both sides as sortable, and thus the most optimal join algorithm (Sort-Merge) will almost always be used.

So with Sort-Merge being the most likely algorithm being used with this new modification, performance then boils down to how fast we can read the rows of data and in this arena, SQLite is the king. Another reason why SQLite should be the default format of choice for your spatial data.

So in summary: For best feature join performance, use SQLite or data formats that can be sorted by MapGuide (which will be nearly everything with this patch)

My 2010 MapGuide/FDO Wishlist: Revisited

2011-12-14T22:56:00.000+11:00

Around this same time last year, I made a wishlist for MapGuide and FDO. As this year has passed along, that wishlist somehow slowly transformed into my personal to-do list :P So how did things turn out 365 days later?

MapGuide

1. A desktop-based variant of the Geospatial Platform API

Yep, and mg-desktop is it's name. Last year, I had a faint idea of how this would flesh out. Now it's fully realized.

2. A HTML5/Flash/Silverlight vector viewer with offline support

My desire for this type of viewer at the time was predicated on the lack of a viewer like in MapGuide 6.5 that can operate with limited to no MapGuide Server connectivity. mg-desktop has solved this particular need for me, so my desire for such a viewer is no longer there.

Still if we want to have a HTML5 viewer, this may be a good starting point. The examples work on local SHP files (Sheboygan Parcels actually renders quite snappy), but this can probably be extended to a common feature model (allowing support for other spatial data formats) and then start trickling in support for MapGuide's rendering/stylization rules.

As for Flash or Sliverlight, I'm not even gonna go there. HTML5 is capable enough IMO. A plugin-free world is a beautiful one.

3. A scalable Fusion Legend widget

Yep, Fusion no longer sucks

4. A way to preserve tile sets

Still not there, but anyone affected by this problem knows about it and has probably come to accept it as a minor inconvenience.

5. Feature Write capabilities for the mapagent

GeoREST is still the way to go here. Given this is part of AIMS 2012 as a technology preview, perhaps this will be integrated into MapGuide proper in the future?

6. A DWG FDO Provider

Still nothing here sadly.

FDO

1. A way to use the FDO API in languages other than C++/.net in a multi-platform manner

In my current line of thinking, mg-desktop is the way to go. It already uses/wraps FDO and is already developed in a way that facilitates easy generation of SWIG bindings. I just have to overcome my fear of gcc and automake and their cryptic error messages :P

2. Champion SQLite as the goto flat-file format for FDO

An emphatic yes on this one. The SQLite FDO provider is getting all the new FDO goodies nowadays. It was the first provider to get the new FDO Join APIs, thus allowing the Feature Join optimization shortcut to become possible.

3. A FDO provider for MapGuide

Nothing's changed here.

4. Consistent Schema Naming Conventions

This leaky abstraction is a small annoyance for anyone who wants to write provider independent code. If you have to write provider-specific code paths (FDO Toolbox had to employ quite a few), it just highlights some of the failings of FDO as an abstraction layer for spatial data access. Sadly, nothing's changed here.

5. Parametric Capabilities

Still nothing's changed here. Of course if ODBC and OGR don't expose capabilities of their own that are translatable to FDO's capabilities, then this leaky abstraction is one we'll just have to live with.

6. Android/iPhone support

Given Autodesk's recent focus on having mobile versions of everything known to man, this may look like a possibility. But you know Autodesk, I'm just staring at an opaque crystal ball here :-)

FDO Toolbox 1.0 (yes that's right!)

2011-12-06T21:28:00.001+11:00

3 years and 1251 revisions in the making. The 1.0 final version of FDO Toolbox is finally here.

This release includes some small bugfixes from 1.0 RC1

Download

Is this be the end of FDO Toolbox as I proclaimed some time ago? Probably.

I'll still probably put out occasional releases to coincide with newer versions of FDO but other than that, FDO Toolbox has fulfilled all my needs (and I'm sure many of your needs as well). So I'll guess it's time to put this project into semi-retirement.

Fusion is actually usable now

2011-12-06T02:42:00.001+11:00

I am going to call it right now. If you've been holding back from moving to Fusion due to the assortment of bugs and performance problems, then the version of Fusion that will appear in the next version of MapGuide Open Source and Autodesk Infrastructure Map Server will be the one which will finally sway you across.

Thanks to funding from Hume City Council, we have finally tackled most of the deal-breaking issues which have made Fusion unsuitable for production use for many years ... Until now.

What issues in particular? Read on below.

Legend Performance

This is the number one showstopper to wider adoption. The root problem with the legend widget performance is that each icon in the legend requires an individual http GETLEGENDIMAGE icon request to the mapagent. Now suppose you have a layer with a 900-rule theme, attempting to preview this layer will grind your browser and the MapGuide Server to 100% CPU usage, because it will fire off 900 individual icon requests (yes you heard that right!). And that's just for one single user!

We solved this problem through a multi-pronged approach:

1. To speed up the server-side initialization, we use the new GetResourceContents API introduced in MapGuide Open Source 2.2 to fetch all our required layer definitions in a single batch. Performance gains will be readily apparent for really chunky Map Definitions with lots (in the 100s) of layers

2. We exploit the data URI feature that supported by most modern browsers. We pre-cache icons by generating the legend icons server-side and embedding them as base64 encoded data URIs as part of the json content that is returned to the legend widget for initialization. Each legend icon represented as a data URI will eliminate a mapagent icon request that would have to be executed. We use a metric of pre-caching 25 layer icons per scale range. For an average Map Definition (like the Sheboygan sample data set) no icon requests are ever made through this optimization. Now for those primitive browsers from Redmond that don't support data URIs, have no fear. Because there is also the next optimization.

3. The theme compression logic that is used by the AJAX viewer now also exists in Fusion. We use that same number (25) to determine the number of style rules that must be exceeded for a theme to be compressed. Compressed themes in Fusion look like so:

And like the AJAX viewer, you have the option of expanding compressed themes. To avoid unnecessarily expanding say: a 900-rule themed layer, we prompt for confirmation. So the choice to flood a mapguide server with icon requests will be yours and yours alone to make ;-). Even if your browser doesn't support data URIs (It means you are using IE6/7. Don't deny it!), the theme compression means that icon requests will be capped at a certain level by default, just like the AJAX viewer.

So with these changes, our map with the 900-rule themed layer now loads just slightly slower than the AJAX viewer, which is a major improvment from never.

Support for Map Definitions with Tiled and Dynamic Layers

This one wasn't our doing, but Autodesk themselves have finally addressed the other long-standing complaint of not being able to view a map that contains a combination of tiled and dynamic layers.

And as an added bonus, if you are using commerical underlays your tiles can also line up with the Google/Bing/Yahoo/OSM tiles if your Map Definition uses a Google-compatible finite scale list (and is using the WGS84.PseudoMercator coordinate system of course). In anticipation of supporting this new feature, I've added support for generating this Google-compatible scale list in the final release of MapGuide Maestro 4.0 which will be coming out soon.

Redlining

Ever used the Fusion redline widget? Me neither.
So what do you do with the downloaded redline GML file? Hell if I know!
What about if I want to plot the map with the redlines? Dream on. You can't do that!

When the redline widget was first introduced with the query and theme widgets, I was personally surpised that they didn't base the redline widget from the same sample the query and theme widgets were derived from: The Generic Tasks AJAX viewer sample.

So we've thrown out this useless widget and replaced it with one based from the Generic Tasks sample, giving us a redline widget that is much more powerful and useful:

If you've used the Generic Tasks markup sample, this redline widget functions almost the same. For those unfamiliar with the Generic Tasks markup sample, here's what the new Redline widget can do:

Configure redline layers with support for labels using the same MapGuide stylization rules
Add, Create, Remove and Manage redline layers with respect to the current map
Draw geometries using the same digitizing tools provided by OpenLayers
Your redlines will be part of the whatever plotting or rendering operation you do on the current map.
Redline feature sources can be downloaded as SDF files, allowing for overlaying in AutoCAD Map3D and other Autodesk Geospatial products.

Quick Plot

The Quick Plot widget has improved reliability. This is due to the widget now using the actual MapGuide Rendering APIs to grab the initial un-rotated image and dumping that to a temp file, where the PHP gd library is then used to rotate the image and outputted back to the user. This approach is a more memory efficient use of the PHP gd library, and as a result should result in significantly less occurrences of this useless message:

ProTip: If you get this message, it's due to a failure of some sort in GeneratePicture.php. Inspecting the GeneratePicture.php request in Firebug should give you more information. As there was no mechanism in place to propagate back error messages, GeneratePicture.php fails silently at least from a user perspective. The QuickPlot changes improve memory efficiency and should result in signifcantly reduced (can we say no?) occurrences of this message.

The widget itself can now also have customizable paper and scale lists, which will require hacking the widget's extension XML element.

One small note: If you planning to wedge fusion trunk into an existing MGOS 2.2 installation, this widget will break because it uses APIs introduced in the next version of MGOS/AIMS. Other widgets should work just fine.

General Usability

Having tackled the major showstoppers, I became comfortable enough with the fusion framework to address a whole bunch of bugs and usability issues with other widgets. The Search, Measure and Query widgets have gotten a bunch of bugfixes.

Wrapping things up

All these changes have already landed in Fusion trunk (some have for quite some time now). Given this is usually branched off at some point, where it is then used by the Open and Commerical versions of MapGuide, you can expect these drastic Fusion improvements to a MapGuide release near you.

As a small aside. Many thanks to Hume City Council for providing the funding for us to implement these long overdue improvements. If you went to AU 2011, you may have seen some of our handiwork on display (including our Fusion work) in this presentation.

As a second small aside, if you have to use Internet Explorer, use Internet Explorer 9. Fusion absolutely FLIES in IE9 and even outperforms Firefox/Chrome in some cases! (yes, I am shocked)

轻松翻译使用 MapGuide Maestro *

2011-12-01T00:58:00.001+11:00

* I trust Google Translate translated the above blog title correctly :D

Not everyone speaks English, so neither should your MapGuide Applications.

Currently, the process of translating your MapGuide Application is to hunt down all the english strings in your Basic or Flexible Web Layout XML document and manually replace each string with your translations. This is a slow and painstaking process.

The final release of MapGuide Maestro 4.0 will include a new convenient command to assist with the translation of Basic and Flexible Web Layouts.

Clicking the Translate button will bring up a dialog containing all the localizable strings (Maestro searches for all known XML elements that can contain localizable text). From here, tick the strings that require translation and give your provided translation. I did a quick and dirty french translation via Google Translate for this example.

Once you have completed your translation, click Apply to apply these translations to the affected strings. The editor will reload itself with the translated strings. Previewing the layout will show your translated layout.

The final release of MapGuide Maestro 4.0 (which will include this feature) will be arriving shortly. Doing a lot of API cleanup and documentation.

Improving the Feature Join experience

2011-11-21T22:59:00.001+11:00

So what was this screenshot all about?

Time for an explanation. This screenshot was the result of an experimental mg-desktop addition to make feature joins perform much faster (around 100 times faster as evidenced by the screenshot), by taking advantage of new FDO Join APIs that were recently introduced with the 3.6 release. Why does the FDO Join APIs perform so much faster? Time for a little backstory...

Why Feature Joins suck (performance wise)

Feature Joins are performed by the GWS Query Engine component of MapGuide. From a high-level overview, this component takes two input iterators (with interfaces similar to a FDO/MG Feature Reader), and depending on the capabilities of the left and right sides of the join a "merged" feature reader is returned that will loop the two iterators in the following fashion:

Nested Loops (both sides do not support ordering)
Nested block join and sorted block (left side supports ordering, right side doesn't)
Sort-Merge (both sides support ordering)
Batch Sorted Block (left side does not support ordering, right side doesn't)

Now these join algorithms themselves are also sensitive to the data you're working with. For example, any sorted block algorithm is going to perform bad on datasets with high-spread of join key values (low-spread of join keys means lots of sorted duplicate joins values which can be skipped). Sort merge has issues regarding case-sensitivity of key values (though this may be a bug in the implementation). Nested Loops is obviously terrible if both sides are large (as is the case of a SDF to SDF join as per the above screenshot)

MapGuide in its current form is not aware of join factors which impact performance:

The size of both sides of the join (Nested loops is obviously bad, but the inability to determine size means this can't be avoided if this is the designated algorithm)
The spread of join key values (Sorted blocks work best on lookup-value type spreads not foreign-key type spreads)

It is all of the above factors which make having good performing feature joins a difficult proposition. ^

The FDO Join API (or: Let the data store figure it out)

So it's clear that MapGuide does a terrible and/or erratic job as a query optimizer, so assuming we want respectable performance of joined data, you would've probably avoided Feature Joins altogether and have the bits you want to join in question residing in the same centralised RDBMS, do the joins at the database level and wrap the result in a database view.

This approach is a good solution in terms of performance because figuring out the best way to join data is now a data store responsibility, and you can apply a whole assortment of indexes and other DBMS performance improvements that MapGuide is not aware of. From MapGuide's perspective all it sees is a table/view and it just queries that. But this approach presents its own problems:

The need for metadata hacks for views to be properly recognised as a feature class (eg. SDO_GEOM_METADATA in Oracle)
The type of view affecting selectability (eg. SQL Server, which requires schema overrides to work around)

With the introduction of FDO Join APIs, it allows us to do these type of joins in an ad-hoc fashion without needing to wrap our joined data into database views. Joining data with the FDO Join APIs is basically the equivalent of doing a SQL SELECT query with JOIN clauses. In other words, the FDO Join APIs lets you delegate join optimization to the data store and let it figure out the best performing way to do it.

Taking advantage of FDO Joins in MapGuide (with RFC123)

So as already explained, work on bringing support for this into MapGuide started with mg-desktop. Being essentially a self-contained version of MapGuide meant that mg-desktop was a nice sandbox for playing and experimenting with new features. So once support was built into mg-desktop, bringing it over to MapGuide proper was quite an easy affair.

So how does mg-desktop and MapGuide take advantage of FDO Joins?

We use the existing Extended Feature Class mechanism to construct an equivalent FDO Join select query, applying the proper property/class aliasing to ensure that the reader that is returned presents the same property list as a default feature join query.

When querying an Extended Feature Class, MapGuide does several checks to see if the FDO Join optimization path can be taken. These checks include:

Does the underlying FDO provider for the Feature Source support FDO Joins? (obvious one!)
Does the primary and joined feature classes of this Extended Feature Class originate from the same feature source? (this is important, because FDO Joins work within the context of the same connection, thus the classes we are joining must come from the same source)
A whole bunch of other minor conditions which your Extended Feature Class will most likely satisfy (detailed in the RFC)

If the Extended Feature Class being queried passes the above checks, MapGuide takes the FDO Join path, which as seen from the screenshot above, can be up to 100 times faster than the regular Feature Join approach.

Additionally, Extended Feature Classes also double up as the metadata. You don't need to do SDO_GEOM_METADATA hacks or FDO Schema Overrides for these classes to be recognised. Because MapGuide already understands these elements out of the box!

Also, in case you're wondering, the performance numbers in MapGuide are even better than mg-desktop (up to 1s faster than the numbers in the above screenshot) due to connection pooling and object caching mechanisms present in the MapGuide Server code.

Conditions Apply

Now as you can see, only certain Extended Feature Classes can take advantage of this optimization. The other limitation is FDO provider support. As of writing this post, the following providers implement the FDO Join APIs:

SQL Server
SQLite

Given the high usage of these providers (you are using SQLite for all your spatial data aren't you?), there is a good chance of this optimization path being used.

The beauty of FDO is that as soon as an FDO provider implements the FDO Join APIs (like King.Oracle wink, wink, nudge, nudge), such configured Extended Feature Classes in MapGuide can automatically take advantage of this optimization path.

So there you have it. 100x faster feature joins if your data ticks all the boxes.

^ There is a 5th type of join algorithm that is (suprisingly) not implemented by the GWS Query Engine: Hash Joins. Though probably the most memory intensive join algorithm (due to needing to store one side of the join in a hash-table), this should always perform better than the default nested loops. Anyway, it's 2011. Memory is cheap! Having this join type implemented should improve the Feature Join user story even further. Guess that's another item on the TODO list.

Announcing: A fixed installer for MapGuide Maestro 4.0 RC1

2011-11-11T12:59:00.001+11:00

Oops!

It turns out that as far back as the first beta release of Maestro 3.0, that the window installers I've been making did not include the XML schema files required for validating XML content.

So I've posted an updated 4.0 RC1 installer with the missing XML schema files. Note that this is only applicable if you've been downloading the windows installer package. If you have been using the zip packages, the XML schema files have always been in there, so everything's ok on that front.

To make sure that the XML schema files are properly set up, go to Tools - Options and check that the XML schema path is configured to point to the Schemas directory under your MapGuide Maestro installation directory

Or, you can click Reset and Maestro will reset all preferences to default values and auto-discover all the required paths.

Update: OSGeo is back in order. So the fixed 4.0 RC1 installer is available for download from here

Announcing: MapGuide Maestro 4.0 RC1

2011-11-09T03:27:00.000+11:00

Here's another RC coming your way.

This release re-introduces the Package Editor feature, which has been missing since Maestro 2.1 and includes a big bucket of fixes and small improvements since beta 2.

One particular improvement which I'm proud of finally implementing can be summarised with this screenshot:

Yep, I finally figured out how do do it!

Download (back at OSGeo)

Announcing: FDO Toolbox 1.0 RC1

2011-10-26T23:51:00.000+11:00

About time I started to get this thing to the 1.0 final release.

New Features

Now using FDO 3.6.0 final release.
Data Preview now supports the new FDO Join APIs
You can now dump the contents of a Feature Class in the Object Explorer to SDF/SQLite via the context menu.

Also included is plenty of bug fixes and small improvments

Come and get it

Report Issues/Enhancements

A screenshot to tide you over

2011-10-21T03:04:00.001+11:00

Stay tuned for more information :)

Announcing: MapGuide Maestro 4.0 beta 2

2011-09-21T02:40:00.000+10:00

I am happy to announce the 2nd beta of MapGuide Maestro 4.0

The major new feature of this release is non-transactional package loading, which greatly improves the reliability of loading very large package files, at the small cost of losing the repository ACID-ity of the official approach. Should you encounter any failed operations during the package loading, Maestro will give you the ability to retry these failed operations until all failed operations are accounted for, or you choose to abort yourself.

Also included in this release is:

Fixes for defects brought on by the new multi-site support
Editor support for FDO expressions in color editor properties
Updated to the latest mg-desktop binaries for Local Connection mode

Once again, this beta is available in the fat NSIS installer or the lean zip package (which excludes local connection mode). Users of non-windows operating systems will have to download the zip package.

Download (temporarily hosted on the mg-desktop site)

Introducing non-transactional package loading

2011-09-16T03:57:00.001+10:00

The next beta of MapGuide Maestro 4.0 will feature a new way of loading packages which I call "non-transactional" package loading.

Normally the package loading process in Maestro is as follows.

Select the package file
Maestro invokes APPLYRESOURCEPACKAGE on the MapGuide Server and uploads the package file
Twiddle your thumbs, because there is no way to know how long this operation will take
The operation being transactional means that the operation will wholly suceeed or wholly fail.

Loading a package several hundred MBs in size only to be told that the entire operation failed at the end is needless to say, a very frustrating experience.

Non-transactional package takes a different approach. It eschews using the APPLYRESOURCEPACKAGE API (the cause of the thumb twiddling and waiting because there is no way to track progress) for an approach that allows progress to be measured. At the heart of a MapGuide Package is the resource package manifest, which is simply a list of resource service operations to execute on the MapGuide Server, which are generally a mixture of:

SETRESOURCE
SETRESOURCEDATA
DELETERESOURCE

The existing approach executes all these operations on the server-side under one big transaction, the new approach executes all these operations one at a time from the client side and because we know how many operations need to be executed, we can measure the entire progress of the package loading operation.

Now when you load a package, you will be asked to choose the method of uploading:

Choosing the Transactional method will load the package in the existing fashion. Choosing the other option will use the non-transactional method and because this approach is measurable, we get a nice meaningful progress dialog to relay the upload progress.

So in what cases would you use non-transactional package loading over the default transactional one? Here's a few I've thought of:

The package file is several hundred MBs in size
The package file contains hundreds of resources to be loaded
The package file is not loadable via the transactional method, which is generally the result of any of the above items.

Finally, because it's non-transactional if one operation fails it will keep continuing with the upload of the others, failed operations are logged. As a result, the upload can partially succeed and fail. Should the operation partially fail, it is planned to re-use the list of failed operations to allow you to re-run the package upload, but to skip all the successful operations, thus turning a partially failed upload to a fully successful one.

I've received some test packages which completely failed to load under the official package loading methods. These packages loaded without issues in the non-transactional mode. So no matter low large or small your data packages are, Maestro can upload it for you. One way or another.

Announcing: MapGuide Maestro 4.0 beta 1

2011-09-08T09:32:00.000+10:00

I'm happy to announce the first beta release of MapGuide Maestro 4.0

This first beta contains 2 new groundbreaking features, which have already been covered previously:

Support for connecting to multiple sites
Support for a new connection type backed by the new mg-desktop library. Unfortunately, this feature is windows only and thus is only included in the windows installer. This feature is omitted from the zip distribution.

The multi-site feature majorly affects most workflows in Maestro and as a result of the yet-to-be-stabilized nature of this new feature, I will only recommend you download this release for testing and feedback purposes only

You may also notice a significant increase in the windows installer size (84MB). This is due to the inclusion of the full set of CS-Map coordinate system dictionary files that is required by the new local connection mode feature. I wish CS-Map stored its thousands of coordinate systems in a more space-efficient manner! Anyway, I am pondering whether to offer the new local connection feature as a separate download or keep it bundled it with the NSIS installer as I have done for this beta release. Let me know what you think.

This beta can reside side-by-side with older versions. The new local connection mode also shouldn't conflict or clash with any existing MapGuide Open Source or AIMS installations

Download

Taking MapGuide beyond the Server and Web right into your desktop

2011-09-05T01:15:00.000+10:00

Previously, I briefly mentioned how the new Local Connection mode in the next release of Maestro was backed by a new desktop implementation of the MapGuide API. This (lengthy) post covers this

Preface

Let's start with a little personal backstory of mine.

Remember this software?

The MapGuide ActiveX viewer (source: Directions Magazine)

Now truth be told. I was not a major fan of Autodesk MapGuide 6.5. I guess that could be attributed to the following:

I was just getting started not only with Autodesk products and technologies, but also on the basic concepts, practices and workflows of GIS systems. So for all intents and purposes, I was a total noob at the time.
Windows only. Ewwwwww!
The viewer is an ActiveX control that can only be embedded in Internet Explorer. Ewwwwwww!

Now the first time I got acquainted with MapGuide was in 2005 with the 6.5 version. It was also the time at my first ADN event when I heard about Autodesk's next version of MapGuide. Seeing the demos of this next version in action was quite a mind-blowing experience, given my not-so-positive experience with MapGuide 6.x.

The AJAX-based viewer, multi-platform support, purty looking maps, flexible data access through this mysterious (at the time, to me) FDO technology and the list goes on. It just ticked all the boxes of what a modern, open-ended web mapping system should be. But then came the biggest bomb-shell of them all: It will all be open source!* So then several months later, the very first version of MapGuide Open Source was released and the rest (as they say) was history.^

Now despite my less-than-flattering opinion about MapGuide 6.x. It did have some very unique qualities to it that has yet to be replicated in MGOS/AIMS. Its map viewer, due to being based on ActiveX meant it could be embedded into .net applications. The second quality was that MWF files can contain static layers. This combination meant that it was possible to build mobile and disconnected MapGuide applications in .net or any other windows technology that supports COM (Component Object Model)

And it is in this respect that MGOS/AIMS has nothing comparable in its technological offerings.

Disconnected? Not a chance! Client applications must be connected at all times. No server connectivity = no maps for you! Even the latest mobile extension for AIMS still requires constant connectivity.
Mobility? You could have a full blown MGOS/AIMS installation on localhost, which your windows application can communicate via an embedded Internet Explorer. A functional, but very inelegant configuration. Nothing approaches the simplicity of a windows application + static MWF + 3mb ActiveX control configuration that was possible with MapGuide 6.x

So while MGOS/AIMS does most things leaps and bounds better than MapGuide 6.x, there are some other things where it pales in comparison.

Enter the MapGuide Desktop API (hereby known as mg-desktop for the rest of this post). mg-desktop is a desktop implementation of the MapGuide Platform API allowing for the same feature data access, map rendering/stylization functionality as the MapGuide Server, but without needing a MapGuide Server installed on your machine!

Genesis

The seeds of the MapGuide Desktop API were planted with this groundbreaking AU 2009 presentation. This presentation, for those unable to access that link showed how MapGuide Open Source actually has lots of shared components that can actually be re-used outside of the MapGuide Server and Web tiers.

The main example from that presentation was a simple snapshot application that can produce a rendered map image or DWF file from a list of named Layer Definition documents without ever needing to contact a MapGuide Server ever! The first thought I had after seeing that presentation, was simply: Can't we just use a Map Definition to drive all this?

The second thought was, that AutoCAD Map already proved that the MapGuide API can be taken in a different direction, away from the MapGuide Server/Web Tier to become a API inside AutoCAD Map

So couldn't we have another implementation that makes it a fully self-contained framework that is usable by any desktop application, taking the concepts proven feasible by that AU presentation to its logical conclusion? mg-desktop is my answer to that question.

mg-desktop is a desktop implementation of the Geospatial Platform API, with its own implementation of the core platform classes, as shown below:

Where the MapGuide API operates in the context of the MapGuide Server/Web Tier and the AutoCAD Map Platform API operates in the context of inside AutoCAD Map, mg-desktop operates in a standalone context, with no dependencies on any particular application. It provides a suitable foundation for creating your own desktop-based MapGuide application.

In addition to implementing the core classes and services of the Geospatial Platform API, it also includes some of the additional service APIs provided by the MapGuide API, such as:

MgRenderingService
MgDrawingService
MgTileService

mg-desktop also supports loading of MapGuide Packages (*.mgp). So you can transfer data and resources from a MapGuide Server to an mg-desktop installation.

Key Differences from the MapGuide API

Because mg-desktop is a desktop implementation of the Geospatial Platform API, some concepts which were applicable in MapGuide and/or AutoCAD Map no longer apply in mg-desktop:

There is no session expiry :D Session resources still exist as a way to have temporary resources
There is no resource security model
On the same subject, there is no authentication required for access to services.
There is no need to open/save runtime map state. Everything operates off of the current state of the runtime map in memory.

The mg-desktop implementation of MgResourceService wraps a pre-defined directory on the file system. Folders and resources in the mg-desktop repository conceptually map to files and folders in the file system.

The mg-desktop implementation of MgFeatureService is a thin wrapper around FDO. Each service API maps to a corresponding FDO command. All FDO types that would be returned are wrapped up and/or converted to their corresponding Mg* counterparts.

Aside from these differences, it's the same MapGuide API that you've come to know all along.

Unique APIs

mg-desktop not only just implements the abstract classes in the Geospatial Platform API, but extends them with our own additional APIs to correct my perceived shortcomings of the current MapGuide APIs. Here's an overview of the unique APIs of mg-desktop.

MgdFeatureService

MgdFeatureService is the desktop implementation of MgFeatureService and includes the following extra methods:

RegisterProvider - Registers a new FDO provider into the provider registry by its library path
UnregisterProvider - Removes a registered FDO provider from the provider registry by its provider name
InsertFeatures - Allows for individual insertion of features into a feature class, instead of having to use the monolithic UpdateFeatures
DeleteFeatures - Allows for individual deletion of features in a feature class, instead of having to use the monolithic UpdateFeatures
UpdateFeatures - Although it unfortunately shares the same name as the monolithic method it's trying to replace, this allows for individual updates of features in a feature class.
SelectFeaturesExtended - Almost identical to SelectFeatures, except this returns a scrollable feature reader that behaves similarly to the FDO scrollable feature reader

MgdLayer

MgdLayer is the desktop implementation of MgLayerBase which adds extra convenience methods, allowing you to operate on the layer itself instead of needing to obtain an MgFeatureService reference and the layer's feature source id and class name:

BeginTransaction - Convenience form of MgFeatureService.BeginTransaction
SelectFeaturesExtended - Convenience form of MgdFeatureService.SelectFeaturesExtended
InsertFeatures - Convenience form of MgdFeatureService.InsertFeatures
DeleteFeatures - Convenience form of MgdFeatureService.DeleteFeatures
UpdateFeatures - Convenience form of MgdFeatureService.UpdateFeatures

The Map Viewer Component

So having a reusable library to build your own geospatial applications is good and all, but is there something out-of-the-box like a map viewer that we can embed in a .net application? The answer is an emphatic yes. mg-desktop includes an embeddable map viewer component!

This is not some trick of embedding a web browser to use the AJAX viewer to talk to a local or remote MapGuide Server, this is all native .net WinForms controls and using the same self-contained MapGuide rendering and stylization services provided by the mg-desktop library and it does pretty much everything you can do in the AJAX/Fusion viewer.

What about more complex stuff like digitizing and redlining? No problem. It can do that too!

And all of this is functionality is contained in one single sub-100kb dll! (OSGeo.MapGuide.Viewer.dll). The next release of Maestro will be using this viewer component for previewing Feature Sources, Layer Defintions, Watermarks and Map Definitions in the new Local Connection mode

In Closing...

I have submitted a pending RFC to have this included in the official MapGuide source tree, which would greatly improve integration, code re-use and ability to receive fixes and enhancements to upstream components.

The source and binaries# for the mg-desktop library (and map viewer) are available from the Google Code project home page. Note that FDO that is included with the binaries is a partial distribution (because I lack the ability to build certain FDO providers). You will need a Mercurial client to checkout the source code.

If you want to build the source, you will need to do a full svn checkout of MapGuide Open Source and FDO trunk. Then you will need to build FDO and the MapGuide Oem components first before you can finally build mg-desktop. The hg clone needs to reside in a Desktop subdirectory under MgDev in your MapGuide svn working copy. There is currently no 64-bit or Linux targets yet, so feel free to submit any patches.

* Let's give credit where it's due here. mg-desktop, Maestro and FDO Toolbox would not exist if it weren't for Autodesk open sourcing the MapGuide product and FDO technology. Similarly, my knowledge of MapGuide and FDO wouldn't have reached encyclopedic levels that they are today if these technologies were not open sourced.

^ As most of us found out, v1.0.0 of MapGuide Open Source turned out to be pretty rough round the edges and performance of Feature Joins (which 6.x handled brilliantly) was absolutely woeful and buggy, which sadly is still applicable to this very day. But this is a known problem with a known workaround, which is to have all the data in a centralised, spatially-enabled RDBMS, which you should be already doing in the first place.

# To reduce download size, mg-desktop contains a reduced distribution of CS-Map. If there are problems due to missing coordinate systems, download the country-specific grid files here and drop them into the Dictionaries directory.

Something (even more) revolutionary this way comes

2011-08-25T03:12:00.006+10:00

When I announced that Maestro 4.0 would give you the revolutionary ability to connect to multiple sites at the same time, there was actually a reason for that. Because also coming in Maestro 4.0 is an entirely new way of managing and authoring your MapGuide resources.

Introducing the Local Connection Mode

When you click Connect Locally, you still have to supply a configuration file as you would a TCP/IP connection, exception this file will be provided by the Maestro installation.

And it functions and operates like any other connection

But here's the main difference. Unlike the TCP/IP connection, which is just a wrapper around the official MapGuide API, and thus requires a connection to the MapGuide Server and a cumbersome assembly signing process to properly set up, the Local Connection does not require any MapGuide Server at all!

This is because the Local Connection wraps our very own implementation of the MapGuide API, which runs entirely on the desktop allowing for fully client-side spatial data access and map rendering/stylization.

With the Local Connection mode, you can completely author up a whole bunch of Maps completely disconnected from any MapGuide Server and when you're done, use the magic of packages to instantly load this onto a given MapGuide Server without having to leave the application at all!

Because the MapGuide API uses FDO, we have the (near) full capabilities of FDO available to us, allowing my grand vision of merging FDO Toolbox together with Maestro to finally become reality. Here's some ideas that are possible with Local Connection mode:

Bulk Copying of feature source data with support for re-projecting features provided by the MgCoordinateSystem API

On a similar theme: Creating optimized datasets from Feature Sources containing Feature Joins

Supporting the Convert to SDF and Generalize Data options of Load Procedures

Fully client-side previewing of Maps, Layers and Feature Sources with the exact rendering/stylization engine

Every other conceivable feature that currently exists in FDO Toolbox, but not in Maestro

Super blazing fast localized tile-generation^

Now sadly, this groundbreaking new feature has one small caveat just like FDO Toolbox. It will be windows-only :( Because even though the MapGuide Desktop API itself was written in the most portable fashion of C++, it is the glue libraries that allow a .net application like Maestro to interop with it that are not compatible with Mono in Linux/Mac. But hey, having one revolutionary new feature is just as good as two revolutionary new features is it not?

Stay tuned for a more in-depth overview of the Desktop implementation of the MapGuide API that powers this new feature.

^ This idea is predicated on the fact that the Desktop implementation of the Tile Service APIs is nearly identical to the MapGuide Server, thus it would be theoretically possible to generate the tile cache client-side and copy the tile cache directory over to its corresponding directory in the MapGuide Server installation.

Something revolutionary this way comes

2011-08-16T21:42:00.005+10:00

Each release of Maestro until now has brought with it a series of enhancements that are mostly incremental and evolutionary in nature that improves your MapGuide authoring productivity.

Coming to the next release of Maestro (4.0) is a new feature which I can safely say will be nothing but revolutionary

That's right! Maestro 4.0 will let you connect to and work with multiple sites at the same time! Can you imagine the possibilities?

Announcing: MapGuide Maestro 3.5 final + SDK

2011-08-15T21:42:00.002+10:00

I'm happy to announce the final release of MapGuide Maestro 3.5 and SDK

New Features from 3.5 beta 2:

Layer editor now supports multiple composite styles per scale range

New informative progress dialog for map definition extent calculation

New "Copy Resource IDs to clipboard" context menu command

New Symbol Definition Validation rules

Client-side support for transforming coordinates to WGS84.PseudoMercator. It should now be possible to change your Map Definition coordinate system to WGS84.PseudoMercator, and have the extents automatically transformed to match, and immediately usable in a Fusion Application Definition with a Google/Yahoo/Bing backdrop

New in the SDK is a new sample: StandaloneWebLayoutEditor. This sample illustrates how to use the Maestro.Editors library to re-use the Maestro resource editors from outside of MapGuide Maestro.

Download
Download SDK

Announcing: MapGuide Maestro 3.5 beta 2

2011-08-06T00:30:00.007+10:00

I'm happy to announce the second beta release of MapGuide Maestro 3.5

One of the interesting new features is in-place upgrading of resources to the latest schema version. You know that pale yellow bar at the top with that upgrade button that's always disabled?

It's now enabled, and when you click it it will upgrade the edited resource to the latest schema version supported by the MapGuide Server you're connected to.

Once upgraded, the editor refreshes itself and the new editor features for that schema version become activated.

This is supported for all resource editors. Currently the conversion is one-way (always to the latest schema version. I may look at converting to a specific version in a future release.

Other new features and changes include

Enhanced Autodesk Infrastructure Map Server 2012 support

Previewing is now enabled for Watermark Definitions

Map Definition support for re-ordering layer groups

Layer Definition editor now supports inline symbol definitions for composite symbolization

A whole bunch of assorted productivity improvements (too many to detail, but you'll recognise it when you see it)

The usual assortment of bugfixes

This is the last beta release before the final 3.5 release

Download

Maestro API: 3 ways to create and work with resources

2011-08-05T20:37:00.008+10:00

As explained previously, the Maestro API allows you to work with MapGuide resources in an object-oriented manner, completely avoiding the need to work with raw XML content (although the Maestro API provides such facilities should you require them)

What I didn't fully explain was how one actually can create retrieve and work with these objects. In the Maestro API, there are 3 ways to do this.

First way: Using the ObjectFactory class

The ObjectFactory class allows you to create resource objects from scratch. This method was available in the previous version of the Maestro API, but because you were working with generated classes, there was a very high chance of NullReferenceExceptions and DBXML errors being thrown at your face because you forgot to instantiate one or more of its many child properties.

The ObjectFactory class insulates these concerns away for you. Any resource you create via this approach satisfies the minimum content model requirements of its respective XML schema.

Here's an example of creating a feature source object to a SQL Server 2008 Express database from scratch

IFeatureSource fs = (IFeatureSource)ObjectFactory.CreateFeatureSource(conn, "OSGeo.SQLServerSpatial");
fs.SetConnectionProperty("Service", "(local)\\SQLEXPRESS");
fs.SetConnectionProperty("DataStore", "MyDatabase");
fs.SetConnectionProperty("Username", "mapguide");
fs.SetConnectionProperty("Password", "maestro");

where conn is an instance of the IServerConnection interface

Second way: Using the IResourceService

The GetResource method of the IResourceService interface automatically fetches XML content for the specified resource id and returns a strongly-typed IResource object.

Here's an example of fetching a feature source object

IFeatureSource fs = (IFeatureSource)conn.ResourceService.GetResource("Library://Test/Data/SQLServer.FeatureSource");

where conn is an instance of the IServerConnection interface

Final way: Using ResourceTypeRegistry

The final way is to use the ResourceTypeRegistry class to go from raw XML content to IResource objects and vice versa.

Here's an example of creating a feature source object from an feature source XML document on disk.

string xml = File.ReadAllText("FeatureSource.xml");
IFeatureSource fs = (IFeatureSource)ResourceTypeRegistry.Deserialize(xml);
fs.CurrentConnection = conn; //Need to assign a connection if you want to use any extension methods

where conn is an instance of the IServerConnection interface

And here's one example of going the other way, from feature source object to file

IFeatureSource fs = ...;
using(Stream sr = ResourceTypeRegistry.Serialize(fs))
{
    using(FileStream fs = File.OpenWrite("FeatureSource.xml"))
    {
        Utility.CopyStream(sr, fs); //Or if you use .net 4.0 use the new CopyTo() method
    }
}

So there you have it, 3 simple ways of working with resources in the Maestro API

Debugging with the Edit As Xml command in Maestro

2011-08-05T20:17:00.006+10:00

Here'a a useful tip to assist in reporting bugs and debugging in Maestro.

At the heart of Maestro is the editors to let you edit the various types of resources that can be stored in a MapGuide Server. Now these editors are fully functional for most general cases, but should some part of a resource editor not work as advertised, here's what you can do.

Use the Edit As Xml command to view the XML form of the resource you are editing.

This command is not only convenient in that it allows you to bypass the editor and work on the actual XML content, if you know what you're trying to edit, but it also shows the xml content of the edited resource in its current state.

The resource editors in Maestro do not operate on raw XML content, instead they operate on a deserialized in-memory object form of that content. It is here that certain properties and attributes may be set incorrectly or missed due to bugs in the editor.

By invoking that command, Maestro is instructing the in-memory resource object to serialize itself back into XML, thus allowing you to see for yourself whether edits you have made in the editor have actually been applied.

This command has been very useful for me personally when implementing new resource editors or enhancing existing ones because the XML you see is exactly what gets sent back to the MapGuide Server when you hit the Save button, thus it has proven invaluable for me in debugging editor functionality and XML content model errors.

A bug reporting public service announcement

2011-07-08T21:45:00.005+10:00

Ever get this error message in Maestro?

Object Reference not set to an instance of an object

This message and its exception type of System.NullReferenceException generally means that I (or a library I'm using) screwed up somewhere in the code.

However, just generally telling me this happened does not help me or you one iota because I require additional information:

A stack trace of this exception message (so I can trace down the offending location in the code)

The steps you took to produce this error (so I can construct the possible sequence of events and data that leads up to the offending location in the code)

The data you are working with (where applicable)

Without these pieces of information, it makes it very hard for me to fix the cause of such errors.

The error handling in Maestro 3.5 now uses a more flexible dialog to display such exception information. Exceptions are now displayed in a more flexible dialog.

The message and detail components can both be copy/pasted or you can save the entire error dump to a text file and upload that as part an attachment to your trac issue, allowing for better quality bug reports.

However, what I have just explained doesn't just cover Maestro or this specific error. This is good practice for reporting bugs and issues in any application you use. Bad bug reports will most likely stay ignored because there is not enough information to work on. Developers are not psychic people, we need as much information as possible!

Providing at least the information as I've pointed out is a good start for any bug report and ensures that the developer can provide a suitable fix or workaround for you particular issue.

Announcing: MapGuide Maestro 3.5 beta 1

2011-07-06T23:44:00.003+10:00

I'm happy to announce the first beta release of MapGuide Maestro 3.5

The significant new features of this beta are some new resource editors for:

Simple and Compound Symbol Definitions
Watermark Definitions

These editors are really rough quality at the moment and I would like feedback on these editors to see how the usability can be improved. Especially the Symbol Definition stuff as that has existed in MapGuide since 2007, but until now has not had a specialized editor due to the complexity of the XML schema.

If you need a refresher on Symbol Definitions and Advanced Stylization, here's a good starting point.

Other new features and changes include

Fusion Editor has been updated to use Google Maps V3. No more API keys required
The generated Web Layout for any resource preview includes a new command to report the map extents.
A more flexible dialog for error messages
Layer Definition editor has been re-structured to use less vertical screen space.
The usual assortment of bugfixes

This beta can reside side-by-side with older versions.

Download

Book Review: OpenLayers 2.10 Beginner's Guide

2011-07-03T19:26:00.003+10:00

This post is a review of the book: OpenLayers 2.10 Beginner's Guide

Many thanks to Packt Publishing for provding me a review copy of this book allowing me to write this review.

Relevance/Shelf Life

The problem with some technological books is that the technology advances at such a rapid pace that is renders the book's content out of date or obsolete after several months.

Fortunately, this is not the case with this book because the current release OpenLayers is still 2.10 and the OpenLayers APIs have been relatively stable that the content in this book is relevant enough for future releases of OpenLayers to come. In short, don't let the version number in the book title fool you, the book does have lasting relevance should you decide to revisit the content in this book in the future.

Content

The problem with writing a beginner's guide is, what level of knowledge do you assume the reader to have (if any)? If we were to take the book title at face value, then it assumes the reader has:

At least heard of a thing called javascript
Has used a web browser other than Internet Explorer.

Fortunately the book's introductory chapter covers the fundamentals of JavaScript, and all other foundational web development concepts (AJAX, JSON, Object Oriented Programming, etc) that eases you into to meat of the book: using the OpenLayers library to make compelling web mapping applications.

It is my own personal opinion that if you are to teach a newbie about web application development, they have to know what Firebug is and how to use it to simplify and optimize their web development workflow. I have stated in the past that if it weren't for Firebug (Ok. Let's extrapolate: If it weren't for modern web browsers like Firefox and Chrome), I wouldn't be in the business of doing web development.

Fortunately the book devotes an entire chapter to the Firebug extension for Firefox, which I believe should be a mandatory chapter in any book that delves into Web application development. In this respect, this book passes my newbie web developer test with flying colors.

So then comes the meat of this book: Using the OpenLayers library itself. The content is structured in a logical fashion, starting with getting a basic map up and running and then spicing it up with many different types of layer objects that you can add to this map (a single chapter is devoted to detailing all the available layer types you can add to your map). The important concept of projections is also significantly covered.

Another important aspect of OpenLayers is using controls to improve presentation and to add interactivity to your maps, and this book throughly covers the different types of controls available and how to use CSS to customize the style and appearance of these controls.

One last important aspect of OpenLayers is Vector Layers and the book covers all the intricacies of creating, styling and presenting Vector layers. (A sample chapter from the book covers Vector Layers)

The Web 2.0 ecosystem is an open-ended one where many different libraries and web services can talk to each other. OpenLayers is no different and the book clearly demonstrates the "Open" part of OpenLayers by showcasing how to interface and interop with third party libraries and web services. The book covers creating mashups with Google, Microsoft and Yahoo mapping services, as well as consuming photos from Flickr.

All in all, the content of this book does target its intended audience and does take care to not overwhelm the reader with OpenLayers API specifics, because that is what API reference documentation is for.

Verdict

This book lives up to the title. It is a comprehensive introduction to OpenLayers and web 2.0 application development. The chapter on Firebug alone is enough to guide new users to the proper path of web development, something I am thankful for, because I do get tired of giving the same "use firebug" response to mailing list questions over and over again!

Score: 8/10

Introducing the MapGuide Instant Setup utility

2011-06-11T01:05:00.007+10:00

As someone who is getting more invovled with core mapguide development, having to build and run the installer (which may not even work properly and may pollute my registry with junk settings) just to be able to test my freshly built trunk working copy is a time-consuming process.

What would be really nice is to have some kind of tool/utility that allows me to instantly configure the freshly built source (that is prepared before building the installer) and have a functional server/webtier setup, completely bypassing the installer step.

Enter the Instant Setup utility

This utility requires building the source and preparing it. For a recap, this is:

MgDev\build.bat -a=build -w=all
MgDev\build.bat -a=install -w=all -o=C:\Staging\
Installer\build.bat -a=prepare -source=C:\Staging\

These 3 steps will set up the built binaries (and Apache/Tomcat/PHP with templated config files) under C:\Staging\. This is where the Instant Setup utility comes in.

For the Source Directory enter C:\Staging\ (or whatever directory you chose instead)

For the Batch File Output Directory enter the directory where this utility will generate batch files to start the server and web tier in interactive mode.

The MapGuide Service Name is the service name that will be used when the configured MapGuide Server is installed as a service (not used at the moment).

Then comes the detailed bits:

The port numbers where the the configured server will use
The virtual directory the configured web tier will exist under
The port number where the configured apache will use
The service name to use if apache is installed as a service (not used at the moment)
The default viewer to use for the mapviewerajax virtual directory
Whether to enable Java, and what port to use for Tomcat if this is the case.

Once you have specified all this information, hitting the Configure button will do the following.

Write your specified values into the templated Apache/Tomcat/PHP configuration files
Write 2 batch files (mgserver.bat and mgwebtier.bat) to start the MapGuide Server and Apache both in interactive mode.

Once configured, your C:\Staging\ directory is now a functional MapGuide Server/Web Tier installation, albeit only in interactive mode at the moment.

Some may have noticed that I haven't mentioned IIS. That's because this support is not implemented yet. Eventually support for that will be added. For now, this will give you a functional Apache/PHP/Tomcat/Java configuration.

The source for the instant setup utility can be found here. I hope this tool simplifies your MapGuide hacking experience, as it did for me.

Introducing the (re-vamped) Maestro API: Part 2

2011-06-06T20:27:00.002+10:00

For part 2 of this series I am going to talk about the overall design of the Maestro API.

Having used FDO for quite some time now, a lot of its API design has influenced my design of the Maestro API. Those who have used FDO may notice many parallels in the design when working with the Maestro API.

The first similarity is the heavy use of interfaces. FDO models its connections and commands via interfaces. In the Maestro API, we model the following in the same manner using interfaces:

MapGuide Server connections
MapGuide Service APIs
MapGuide Resource classes and message types

By having these types as interfaces, it allows the implementation of these interfaces to be totally different, and I will show later on in this post where having this quality is extremely beneficial.

The MapGuide Server connection is represented by the IServerConnection interface. This is the main point of entry in the Maestro API.

This contains the ResourceService and FeatureService interfaces to provide resource manipulation and feature querying capabilities. Additional MapGuide services are available via GetService method and you can interrogate the Capabilities property to determine what you can and can't do with this particular connection.

Now the reason this is an interface is because in the Maestro API, there are currently 2 implementations of this connection:

One that communicates with the mapagent via http. (Maestro.Http)
One that wraps the official MapGuide API. (Maestro.LocalNative)

Because this is an interface, the client application can use the same code regardless of implementation. As there is an implementation that wraps the official MapGuide API, you can even use MapGuide Maestro without even needing a web tier because MapGuide Maestro works against the interfaces defined in the Maestro API.

Now given that IServerConnection is an interface, how does one go about creating instances of it? Enter the ConnectionProviderRegistry

Simply call CreateConnection passing in the desired provider and the parameters needed to initialize it. The ConnectionProviderRegistry reads from a ConnectionProviders.xml file which contains all the registered connection providers. Each connection provider is an implementation of the IServerConnection interface.

So having acquired a connection, we can now interact with the services provided by MapGuide. Once again, these services are modeled as interfaces

Each service is defined in a corresponding interface. For reference, they are:

IFeatureService
IResourceService
IDrawingService
IMappingService (also contains rendering service APIs)
IFusionService
ITileService
ISiteService

Each service interface contains methods which correspond to what you see in the mapagent test page. These services are obtained via the GetService method on IServerConnection. For IResourceService and IFeatureService, these already exist as properties so you can access them directly. Once again because these are interfaces, the implementations can be wildly different:

For the http connection provider, these interfaces wrap http requests to the mapagent and automatically processes the XML responses from them.
For the local connection provider, these interfaces wrap the offical MapGuide service classes (eg. The implementation of IFeatureService wraps the methods of the MgFeatureService class, and does automatic conversion of MgByteReader values)

Finally, there is MapGuide's resource classes and message types. The MapGuide Server returns many different types of XML data. But with the Maestro API, instead of working with raw XML content and having to write a lot of boilerplate code, you get to work with strongly typed classes and interfaces, with XML serialization automatically handled for you

Now there's a lot of XML Schemas for all the various forms of XML data that MapGuide returns. Actually building the classes that represent this data by hand would've taken an eternity, so I've taken a shortcut for this particular case and used the xsd2code code generator to generate all the required classes from their XML Schemas. I used xsd2code for generating the classes instead of using the default xsd.exe tool for reasons I have already explained. The set of generated classes produced by xsd2code a much cleaner (relative to xsd.exe anyway) and gave me a very useful foundation to work with.

In the case of resource classes, using the generated classes as-is was still not good enough. Additional tweaking of this generated code was required. The reason is that each particular version of a resource was its own separate class when generated. Each particular version of a resource in its generated class form had nothing in common. Once again, interfaces come to save the day.

Now you may notice that there is only one interface for Layer Definitions, but there's been 3 additional revisions to date in the Layer Definition XML schema (ref 1, 2, 3, 4 and 5). So how were 4 separeately generated classes able to be reconciled into a single interface?

One of the fortunate things thus far, that Autodesk did when they introduced a new version of a given resource was that the schema revisions have been incremental and additive. Nothing is actually removed or altered in every schema revision thus far.

Because of this, the design of these interfaces is such that they represent the 1.0.0 version of the respective resource type each interface is modeling. Elements introduced in newer versions of the schema are exposed through a new version of the interface that extends the original.

So with this design, we have a consistent baseline interface for all resource types and we can interrogate the resource version to determine if we can cast these interfaces (or its child properties, which are also interfaces) to the newer versions to tap into the extra functionality exposed in these newer interfaces.

As is the case with the Web Layout in the above diagram. IWebLayout2 extends IWebLayout and maps to the 1.1.0 version of the Web Layout schema that introduced a new "ping server" property. However both can be accessed via the IWebLayout interface. We can check if the resource version is 1.1.0 to determine if it can be cast into the IWebLayout2 interface.

It is through this design that the Resource Editors in MapGuide Maestro are able to edit most, if not all known versions of a given resource type, and have the necessary intelligence to enable/disable certain UI elements for elements not supported by the edited resource version. This design allows Maestro to keep up to date as newer resource types or schema versions are made available, providing that these schema revisions stay true to their additive form.

This incremental quality of the XML schema revisions is also reflected in the generated code. Thus with the magic of partial classes and careful use of the C# pre-processor, getting different versioned classes to implement the same baseline interface was actually an easy task. Then it was a case of extracting the newer properties and methods introduced in newer schema versions into their own separate interface that extends the original.

The end result, is a consistent object-oriented API that is (mostly :) ) free of boilerplate code that you would normally write to deal with raw XML content, MgByteReaders and HTTP requests/responses. Any developer who has worked with the official MapGuide API would appreciate

So that's the high-level overview of the design of the Maestro API. Stay tuned for part 3, where I actually show some concrete examples of how to use this library.

MapGuide Application Development tips

2011-06-06T20:25:00.007+10:00

Sometimes on the mapguide-users mailing list, we get questions that make me scratch my head sometimes. These are questions that can answer themselves with the use and knowlege of the right tools and configuration settings.

So giving the benefit of the doubt regarding programming ability, and simply assuming the case of "not knowing what's out there", here's the tools and configuration settings that I always use when developing MapGuide applications, which should greatly assist and simplify the process of developing and debugging MapGuide applications. Experienced web developers can probably tune out because you should already know these tools :)

1. Firebug

If you haven't heard of firebug or haven't used it before, stop reading this post and download it now. DO IT!

If firebug didn't exist, I probably wouldn't be taking Web Development as seriously (hell, I probably wouldn't do web development full stop!). If you do any development on the MapGuide Platform (or web development in general), you will have to write some javascript and firebug provides top-class debugging facilities.

But it doesn't just do javascript, it also does:

CSS/DOM debugging
HTTP request tracing / performance monitoring. (you can see all the requests that Fusion/AJAX viewer is making to your MapGuide Web Tier)
Lots more!

It is the complete web development package! Of course, you should already know that (and I shouldn't even have to be writing this post!)

2. Mozilla Firefox

Besides the fact that this is needed for firebug, Firefox is the epitomy of the modern web browser, and has lots of healthy competition from Google Chrome and other WebKit-based bretheren to help keep moving the web forward ... Unlike that browser from Redmond^!

But even still, the Firefox + Firebug combination provides a solid foundation for your design ensuring that the time spent in Internet Explorer is kept to a minimum*

My web development workflow is simply:

Design and develop and test in Firefox / Firebug. This design will 99.9% work in all modern browsers.
Contort and bastardise this design (hopefully not too much) to make it work in Internet Explorer
Re-test against Firefox / Firebug to ensure no breakages.

Simply put, the Firefox + Firebug combination significantly reduces the time spent in the 2nd step of this workflow. The amount of pain and suffering (and the amount of swearing directed at Redmond) would be kept to a minimum.

3. Baretail + MapGuide log files

Believe it or not, MapGuide actually logs lots of information when its running (under default server configuration settings). If a viewer has made a request to the MapGuide Server, it is logged. If MapGuide throws an error, it is logged. If something has made the MapGuide Server fall over, chances are it is logged. Simply put, the logging facilities built into MapGuide provides you with a lot of information to work with. When things go south in your MapGuide application, the log files should almost always be the first port of call.

Baretail is a windows utility that is effectively the windows equivalent to the unix tail utility, showing you the latest entries in error.log and access.log (and any other log file) as they are written by the MapGuide Server. It is an invaluable resource to assist in debugging and problem diagnosis. Does your MapGuide application code not work? Try running it again while observing the mapguide logs under baretail. They might tell you something.

4. Set display_errors = On in php.ini

The PHP that is bundled with MapGuide uses production-level settings. This means any warnings or errors (like unhandled MapGuide exceptions) in any PHP code you may be running are silently swept under the carpet most of the time. Setting the display_errors setting to On in php.ini will reveal and display these errors. If PHP is your development environment, this should be the first thing you do on a fresh development install of MapGuide.

5. JavaScript lint

Sometimes I wish JavaScript was a compiled language. That way the theoretical javascript compiler can report to me all the syntax errors it finds in my javascript source code immediately instead of me having to wait until runtime to get a nasty surprise!

Well JavaScript will never become a compiled language, but we do have JavaScript Lint which is the closest thing we will ever get to a "compiler". Usage is simple, run the jsl.exe executable on your javascript source and watch it report any javascript syntax errors with matching line numbers!

Knowing these tools and configuration settings have made my web development life simpler, I hope this post makes your's simpler too!

^ Generally speaking, where IE gets it completely wrong is in two areas: 1) Certain parts of the DOM API and 2) Flagrant disregard or misinterpretation of certain CSS rules (most infamously, the box model bug). But it's 2011, these are known problems solved by almost every web framework out there, which you should be using already! Which is why I said that the Firefox + Firebug combination takes you 90% there.

* I think if all of us web developers charged a mandatory "IE tax" on our web development work, it would make some of these regressive organisations think twice about holding us (and the modern web) back by still mandating Internet Explorer 6 as the "standard web browser". Microsoft got the message, why won't you!? To be fair, none of the clients I have worked with in my career thus far fall under this category, but the fact that there are still such organisations out there makes baby Jesus cry! At least IE9 is a half-modern web browser, and if Microsoft is serious about its vision of application development for Windows 8, they have no choice but to make IE10 an actual functional modern web browser!