MapGuide RFC 137 - Describe Runtime Map structure over HTTP

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	31 July 2013
Last Modified	14 Aug 2013
Author	Jackie Ng
RFC Status	adopted
Implementation Status	completed
Proposed Milestone	2.6
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1	Jackie,Zac
+0
-0
-1
no vote	Bob,Tom,Haris,Bruce,Trevor,Paul

Overview

This RFC proposes to add support for describing Runtime Maps via the mapagent

Motivation

While MapGuide RFC 134 solves the problem of client applications not being able to create runtime map instances via the mapagent, that RFC does not support being able to describe the same structure with an existing mapname/sessionid. Client-side viewer functionality such as a viewer legend require the ability to re-interrogate the layer/group structure of the runtime map to rebuild itself to incorporate any layer/group changes made by any server-side logic using the MapGuide Web API.

This RFC aims to address this shortcoming.

Proposed Solution

We'll a new DescribeRuntimeMap API to complement the existing CreateRuntimeMap in MgMappingService:

class MG_MAPGUIDE_API MgMappingService : public MgService
{
PUBLISHED_API:
    ////////////////////////////////////////////////////////////////////////////////
    /// \brief
    /// Returns an XML-based description of the runtime map
    ///
    /// <!-- Syntax in .Net, Java, and PHP -->
    /// \htmlinclude DotNetSyntaxTop.html
    /// virtual MgByteReader DescribeRuntimeMap(MgMap map, int requestedFeatures, int iconsPerScaleRange);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual MgByteReader DescribeRuntimeMap(MgMap map, int requestedFeatures, int iconsPerScaleRange);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual MgByteReader DescribeRuntimeMap(MgMap map, int requestedFeatures, int iconsPerScaleRange);
    /// \htmlinclude SyntaxBottom.html
    ///
    /// \param map (MgMap)
    /// The map to describe
    /// \param requestedFeatures (int)
    /// A bitmask representing the desired information to return in the XML response: 
    /// 1=Layer/Group structure, 2=Layer Icons, 4=Layer Feature Source Information
    /// \param iconsPerScaleRange (int)
    /// The number of legend icons per scale range to render inline in the XML response as base64 strings. 
    /// If a scale range contains a number of rules that exceeds this value, only the first and
    /// last rules of a type style in the scale range will have inline icons
    ///
    /// \remarks
    /// The bitmask values of 2 (Layer Icons) and 4 (Layer Feature Source Information) have no effect if 1 (Layer/Group structure)
    /// is not specified
    ///
    /// \return
    /// Returns an XML-based description of the runtime map
    ///
    virtual MgByteReader* DescribeRuntimeMap(MgMap* map,
                                             INT32 requestedFeatures,
                                             INT32 iconsPerScaleRange) = 0;

    ////////////////////////////////////////////////////////////////////////////////
    /// \brief
    /// Returns an XML-based description of the given runtime map
    ///
    /// <!-- Syntax in .Net, Java, and PHP -->
    /// \htmlinclude DotNetSyntaxTop.html
    /// virtual MgByteReader DescribeRuntimeMap(MgMap map, string iconFormat, int iconWidth, int iconHeight, int requestedFeatures, int iconsPerScaleRange);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual MgByteReader DescribeRuntimeMap(MgMap map, String iconFormat, int iconWidth, int iconHeight, int requestedFeatures, int iconsPerScaleRange);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual MgByteReader DescribeRuntimeMap(MgMap map, string iconFormat, int iconWidth, int iconHeight, int requestedFeatures, int iconsPerScaleRange);
    /// \htmlinclude SyntaxBottom.html
    ///
    /// \param map (MgMap)
    /// The map to describe
    /// \param iconFormat (String/string)
    /// The desired image format for icons (from MgImageFormats)
    /// \param iconWidth (int)
    /// The width of each individual inline legend icons. Has no effect if icons was not requested in the response.
    /// \param iconHeight (int)
    /// The height of each individual inline legend icons. Has no effect if icons was not requested in the response.
    /// \param requestedFeatures (int)
    /// A bitmask representing the desired information to return in the XML response: 
    /// 1=Layer/Group structure, 2=Layer Icons, 4=Layer Feature Source Information
    /// \param iconsPerScaleRange (int)
    /// The number of legend icons per scale range to render inline in the XML response as base64 strings. 
    /// If a scale range contains a number of rules that exceeds this value, only the first and
    /// last rules of a type style in the scale range will have inline icons
    ///
    /// \remarks
    /// The bitmask values of 2 (Layer Icons) and 4 (Layer Feature Source Information) have no effect if 1 (Layer/Group structure)
    /// is not specified
    ///
    /// \return
    /// Returns an XML-based description of the runtime map
    ///
    /// \exception MgInvalidArgumentException
    /// \exception MgNullArgumentException
    ///
    virtual MgByteReader* DescribeRuntimeMap(MgMap* map,
                                             CREFSTRING iconFormat,
                                             INT32 iconWidth,
                                             INT32 iconHeight,
                                             INT32 requestedFeatures,
                                             INT32 iconsPerScaleRange) = 0;
};

Functionality-wise DescribeRuntimeMap returns the same XML structure as the CreateRuntimeMap. See MapGuideRfc134 for all the sample responses.

Like CREATERUNTIMEMAP, we'll also introduce a new operation to the mapagent: DESCRIBERUNTIMEMAP

This new operation has the following parameters (in addition to the standard OPERATION, VERSION, LOCALE, SESSION, USERNAME, PASSWORD and FORMAT parameters)

Name	Description	Required
MAPNAME	The map name of the runtime map to describe the structure of	Yes
REQUESTEDFEATURES	A bitmask specifying what pieces of information to includein the DESCRIBERUNTIMEMAP response	No
ICONSPERSCALERANGE	The number of icons to render inline (as base64 images) per scale range in each layer of the map	No
ICONFORMAT	The icon image format (default: PNG)	No
ICONWIDTH	The width of each inline icon that will be rendered (default: 16)	No
ICONHEIGHT	The height of each inline icon that will be rendered (default: 16)	No

All parameters behave like its CREATERUNTIMEMAP counterpart.

All changes have been implemented in ​this sandbox. Upon adoption of this RFC, changes will be merged back into the trunk code stream.

Implications

This is a brand new API. There are no compatibility issues.

The Fusion viewer will use this API for rebuilding its Legend structure (for widgets like Buffer/Redline that add layers/groups).

Test Plan

Test the operation after a CREATERUNTIMEMAP operation (using its mapname/sessionID) and verify responses are the same.

Test that various layer/group changes in a MgMap are reflected in its XML structure when running a DescribeRuntimeMap on it.

Funding / Resources

Community