Changes between Version 9 and Version 10 of MapGuideRfc25

Timestamp:

08/09/07 17:14:57 (18 years ago)

Author:

jasonchen

Comment:

--

MapGuideRfc25

@@ -1 +1 @@
 = !MapGuide RFC # - JSON format responses =
 
-This page contains an change request (RFC) for the !MapGuide Open Source project.  
+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.
 
@@ -27 +27 @@
 == Motivation ==
 
-This is the most important part of the RFC.  It describes the problem domain in detail.  Focusing on this will allow reviewers to fully understand why the proposed change is being made, and potentially suggest different/better ways of accomplishing the desired results.  The more time we spend on understanding the problem, the better our solution will be.
-
 The Fusion framework uses JSON in order to keep client side code simple (it much easier to work with than XML) and JSON is a more compact format so communication over the wire is more efficient.
 
@@ -35 +33 @@
 == Proposed Solution ==
 
-An additioanl OEM component has been added to the source -- jsoncpp. Jsoncpp is a C++ implementation of the JSON specification ([http://sourceforge.net/projects/jsoncpp/]).
+The solution involves adding an extra "format" parameter on selected API invocations from the Web-tier to the Server. The "format" can be either "text/xml" or "application/json". If no parameter is specified at the Web-tier, the "format" will default to "text/xml". Due to performance considerations, two additional APIs (i.e. !DescribeSchemaAsJson and GetFDOCacheInfoAsJson) have been added to handle the special cases.
+
+----
+
+An additional OEM component has been added to the source -- jsoncpp. Jsoncpp is a C++ implementation of the JSON specification ([http://sourceforge.net/projects/jsoncpp/]).
 
 ----
@@ -89 +91 @@
 # !GetVisibleMapExtent (1) [[BR]]
 
-where the appended labeling scheme indicates the different implementation considerations: [[BR]]
-(1) Web-tier changes -- every !ToXml function is matched with an !ToJson function implementation that creates a JSON document in place. [[BR]]
-(2) Web-tier changes -- utilizes the !MgXmlJsonConvert class to convert XML documents to JSON documents. [[BR]]
-(3) Server changes -- an extra parameter "CREFSTRING format" has been added to the respective API call; the !MgXmlJsonConvert class is used if format equals to the JSON MIME type. [[BR]]
+where the appended labeling indicates the different implementation schemes:
+
+(1) Web-tier changes -- every !ToXml implementation is matched with a !ToJson implementation that composes a JSON document in place.
+
+(2) Web-tier changes -- utilizes the !MgXmlJsonConvert class to convert XML documents to JSON documents.
+
+(3) Server changes -- an extra parameter "CREFSTRING format" has been added to the respective API call; the !MgXmlJsonConvert class is used if format is equaled to the JSON MIME type.
+
 (4) Server changes -- an extra API has been added matching the respective API call (e.g. !DescribeSchemaAsXml has !DescribeSchemaAsJson as the JSON version, and GetFDOCacheInfo has GetFDOCacheInfoAsJson as its JSON specific implementation); this is because the original APIs return "STRING" and could not be efficiently adapted by the conversion process within the !MgXmlJsonConvert class implementation; and for the affected APIs, the !MgByteReader* is returned instead.
 
 == Implications ==
 
-This section allows discussion of the repercussions of the change, such as whether there will be any breakage in backwards compatibility, if documentation will need to be updated, etc.
+The major changes involve differing API signatures (i.e. some functions take an extra parameter "format"). Any API invocation made to the Server will be affected. However, API calls made to the Web-tier will behave the same if the format parameter is not specified (i.e. it defaults to the "text/xml" format). Documentation should be updated to indicate that the above APIs now take an extra parameter, "format".
 
 == Test Plan ==
 
-Tests need to be done after the upgrade:
+The following tests should be performed:
 
     * Resource Service unit tests must all pass.