= !MapGuide RFC 11 - Stateless Http GETTILEIMAGE request =

This page contains an 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||5 January 2007||
||Last Modified||jasonbirch [[Timestamp]]||
||Author||Trevor Wekel||
||RFC Status||adopted||
||Implementation Status||completed||
||Proposed Milestone||1.2||
||Assigned PSC guide(s)||Bruce Dechant||
||'''Voting History'''||January 18, 2007||
||+1||Andy, Bob, Bruce, Haris, Jason, Paul, Tom||
||+0||||
||-0||||
||-1||||
 
== Overview ==

GETTILEIMAGE relies on the session repository to do its work.  To improve tiled map performance and to facilitate external caching mechanisms like Squid, a new version of the operation should be introduced which does not require an MgMap object in the session repository.

== Motivation ==

The session repository is a key component in MapGuide Server performance.  Any reduction in load on this key component will improve overall system performance.  The GETTILEIMAGE request only operates on the base map layers for a particular map.  This means all of the dynamic layers (buffers, redlines, etc) added to a specific user's MgMap object in the session repository will not be involved in tile creation.

As far as the tiles are concerned, only the base map layers in the original map definition are of interest.  This information will be the same for all users of the map so there is no real benefit to using a unique session repository held MgMap instance for each user.

The current GETTILEIMAGE Http op needs the session id to gain access to the session held MgMap object.  This makes external cache implementations like Squid virtually impossible to use since the user's current scale is contained in the MgMap and not in the URL.

== Proposed Solution ==

Implement version 2 of GETTILEIMAGE as follows:


 OPERATION=GETTILEIMAGE


 VERSION=2.0.0


 MAPDEFINITION=Library://NavteqNorthAmerica/Maps/nacolorTiled.MapDefinition


 BASEMAPLAYERGROUPNAME=Base Layer Group


 TILECOL=9079


 TILEROW=7440


 SCALEINDEX=1


Most of the parameters are self explanatory.  The SCALEINDEX parameter is the scale index for the tile set of interest.  Tile set 0 corresponds to the most detailed scale defined in the MapDefinition.


Authentication information can be provided by any of the following but the first two methods should be preferred usage:


 HTTP Basic Auth header information


 USERNAME and PASSWORD request parameters


 SESSION request parameter


Implement a new GetTile method for MgTileService.  All of the parameters are identical so there will be minimal processing required by the Web Extensions to implement the HTTP operation.  This method can also be used to programmatically pregenerate tile caches.


class MgTileService


{


    virtual MgByteReader* GetTile(


        MgResourceIdentifier* mapDefinition,


        CREFSTRING baseMapLayerGroupName,


        INT32 tileColumn,


        INT32 tileRow,


        INT32 scaleIndex) = 0;


}

On the Server side, a cache of serialized MgMap objects will be maintained to respond to the new API.  These objects will be deserialized and used when a tile has to be rendered.  For previously cached tiles, the GetTile arguments are sufficient to construct a fully qualified file name so the MgMap object will not be used.  This will reduce the load on the session repository and speed up tile serving for cached tiles.

Two new serverconfig.ini parameters will be added to the TileService section:


[TileServiceProperties]


TiledMapCacheSize = 10


RenderOnly = 0

A very simple cache management scheme will be introduced.  When the TiledMapCacheSize is exceeded, all of the serialized MgMap objects will be dumped from the cache and rebuilt as requested.  If a site has a large number of tiled maps, the TiledMapCacheSize should be set large enough to handle "typical" concurrency loads.  An entry will be written to the Server logs when the cache size is exceeded to aid with tuning the cache size parameter.

If a map's tile cache is cleared or it's MapDefinition changed, the corresponding MgMap serialized form will be removed from the cache.

The RenderOnly parameter determines whether rendered tiles are written to disk.  If set to "1", tiles will not be written to the MapGuide disk cache.  This can be set to facilitate use of external HTTP caches like Squid.

== Implications ==

The existing version 1.0.0 GETTILEIMAGE request will remain in existence.  It should be deprecated in a future release.  To make use of the new request, all of the Ajax viewers will be updated.  This could break backward compatibility for users who have performed significant script customizations.  They will be required to merge the changes into their existing scripts.  The following viewer files will require a few lines of change:


ajaxmappane.templ


mapframe.php


mapframe.aspx


mapframe.jsp

The new MgTileService::GetTile method will need to be documented.  Since the documentation is autogenerated from the header files, there should be minimal documetation impact.

== Test Plan ==

Visual testing with updated Ajax viewers will be performed.

Multi-threaded load tests for both tile generation and tile rendering will be executed.

== Funding/Resources ==

Autodesk