MapGuide RFC 21 - Expose functionality for manipulating Runtime map, using Xml format

This page contains a change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	May 7, 2007
Last Modified	Bruce Dechant Timestamp
Author	Kenneth, GEOGRAF A/S
RFC Status	draft
Implementation Status	pending
Proposed Milestone	2.0
Assigned PSC guide(s)
Voting History
+1
+0
-0
-1

Overview

This RFC exposes some existing functionality as well as some new functionality for manipulating the runtime map.

Motivation

The map definition is Xml based, and easy to manipulate. The runtime map is in binary format, and tightly tied to the inner workings of the MapGuide server. It should be expected that the current format will change over time, thus breaking compatibility with external binary reader/writer applications.

When using the current MapGuide API, the code for creating and maintaining the runtime map is found in code shared by the server and the API. This means that an application must be adapted to fit a specific version of the MapGuide server. Or at least have the correct version of the codebase (eg. dll's).

Proposed Solution

There already exists code in the server to create a runtime map from a map defintion. There should be three more functions in the MgMap class:

void MgMap::UpdateRuntimeMap(MgResourceService* resourceService, MgResourceIdentifier* mapDefinition, MgResourceIdentifier* mapName);
void MgMap::UpdateMapDefinition(MgResourceService* resourceService, MgResourceIdentifier* mapDefinition, MgResourceIdentifier* mapName);
void MgMap::CreateRuntimeMap(MgResourceService* resourceService, MgResourceIdentifier* mapDefinition, MgResourceIdentifier* mapName);

The third function would be equvalent to the current MgMap::!Create, but taking a full resource identifier, rather than just the name of the map.

The UpdateMapDefinition should just overwrite the mapDefinition with the current runtimemap. The UpdateRuntimeMap should try to sync the runtime map, by settings map properties. This will allow the current change-list scheme to work.

These three functions should be exposed in the HttpHandler.

Considerations

This is prone to a race condition, as the client must get a copy of the runtime map, update it, and write it back. There is currently a generation scheme, at least with the Ajax viewer. This can be used to catch such problems.

There may be an unwanted overhead, as the mapDefinition must be written to the server, resulting in the following scenario:

Call UpdateMapDefinition
Download MapDefinition
Modify map on client
Upload MapDefintion
Call UpdateRuntimeMap

In some cases it might be more efficient to use these three variants:

void MgMap::UpdateRuntimeMap(MgResourceService* resourceService, MgByteReader* mapDefinitionAsXml, MgResourceIdentifier* mapName);
MgByteReader* MgMap::MapDefinitionFromRuntimeMap(MgResourceService* resourceService, MgResourceIdentifier* mapName);
void MgMap::CreateMap(MgResourceService* resourceService, MgByteReader* mapDefinitionAsXml, MgResourceIdentifier* mapName);

Which could reduce the number of service calls from 4 to 2:

Call MapDefinitionFromRuntimeMap
Modify map on client
Call UpdateRuntimeMap

Implications

This RFC is strictly an API enhancement. If the update to the runtime map, is done as a "diff" on the current map (as opposed to overwrite), there should be no compatibility problems. Any errors in this code, will effect only applications using this extension. Worst case would be a corrupted runtime map.

Test Plan

Write a small test application that calls the functions through the HttpHandler. Should be very easy to test.

Funding/Resources

Community contributed enhancement.