Changes between Initial Version and Version 1 of MapGuideRfc137

Timestamp:

07/30/13 07:54:06 (11 years ago)

Author:

jng

Comment:

--

MapGuideRfc137

@@ +1 @@
+
+= !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 [wiki:MapGuideRfcs RFCs] page.
+
+
+== Status ==
+
+||RFC Template Version||(1.0)||
+||Submission Date||31 July 2013||
+||Last Modified||31 July 2013||
+||Author||Jackie Ng||
+||RFC Status||draft||
+||Implementation Status||pending||
+||Proposed Milestone||2.6||
+||Assigned PSC guide(s)||(when determined)||
+||'''Voting History'''||(vote date)||
+||+1||||
+||+0||||
+||-0||||
+||-1||||
+||no vote||||
+
+== Overview ==
+
+This RFC proposes to add support for describing Runtime Maps via the mapagent
+
+== Motivation ==
+
+While [wiki:MapGuideRfc134 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 [wiki: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.
+
+== 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