MapGuide RFC # - JSON format responses

This page contains an 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	August 8, 2007
Last Modified	Jason Chen Timestamp
Author	Jason Chen
RFC Status	proposed (draft, proposed, frozen for vote, adopted, retracted, or rejected)
Implementation Status	under development
Proposed Milestone	1.3
Assigned PSC guide(s)	(when determined)
Voting History	August 8, 2007
+1	Tom, Chris, Bruce, Trevor, Jason
+0
-0
-1

Overview

JSON (​http://www.json.org) will be used to provide a lightweight data-interchange format between the web tier and any clients for requests that can currently return XML responses.

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.

Currently Fusion uses a web tier PHP script to convert the XML responses to JSON, but this is inefficient so we will move the generation of JSON into the server. This should further speed up the generation of the JSON, and where required we can eliminate the intermediate XML form.

Proposed Solution

This is a more detailed description of the actual changes desired. The contents of this section will vary based on the target of the RFC, be it a technical change, website change, or process change. For example, for a technical change, items such as files, XML schema changes, and API chances would be identified. For a process change, the new process would be laid out in detail. For a website change, the files affected would be listed.

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/).

Two additional classes have been added to assist the JSON implementation in MapGuide: 1) The MgJsonDoc Class

• MgJsonDoc is a wrapper over the jsoncpp implementation. MgJsonDoc provides many easy-to-use interfaces, such as Begin* and End*, for creating JSON documents from an XML perspective. For example, to create as JSON document for the corresponding XML content---<Node>Text</Node>---, one would call BeginObject("Node"), SetValue("Text"), and EndObject() subsequently.

2) The MgXmlJsonConvert Class

• MgXmlJsonConvert converts an XML document into a JSON formatted document.

The following Web-tier to Server APIs are affected:

Coordinate System

# EnumerateCategories (1) # EnumerateCoordinateSystems (1)

Resource

# EnumerateResourceReferences (3) # EnumerateResources (3) # GetResourceContent (3) # GetResourceHeader (3) # EnumerateResourceData (3) # GetResourceData (3) # EnumerateUnmanagedData (3)

Feature

# GetFeatureProviders (3) # GetCapabilities (3) # GetConnectPropertyValues (1) # DescribeSchema (4) # SelectFeatures (2) # SelectAggregates (1) # GetSpatialContexts (1) # GetLongTransactions (1) # EnumerateDataStores (3) # GetSchemaMapping (3) # GetSchemas (1) # GetClasses (1) # GetClassDefinition (2) # GetIdentityProperties (1) # ExecuteSqlQuery (1) # GetFdoCacheInfo (4)

Rendering

# GetVisibleMapExtent (1)

where the appended labeling scheme indicates the different implementation considerations: (1) Web-tier changes -- every ToXml function is matched with an ToJson function implementation that creates 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 equals 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 its counter part, 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.

Test Plan

Tests need to be done after the upgrade:

• Resource Service unit tests must all pass.
• Feature Service unit tests must all pass.
• API test pages should be checked against the affected APIs.

Funding/Resources

Supplied by Autodesk.