= !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 [wiki:MapGuideRfcs 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.