= !MapGuide RFC # - JSON format responses =

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||July 3, 2007||
||Last Modified||Jason Chen [[Timestamp]]||
||Author||Jason Chen||
||RFC Status||draft||
||Implementation Status||Completed||
||Proposed Milestone||1.3||
||Assigned PSC guide(s)||(when determined)||
||'''Voting History'''||July 3, 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 ==

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 ==

The solution involves adding an extra "format" parameter to the 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/]).

----

Two additional classes have been added to assist the JSON implementation in !MapGuide:

1) The !MgJsonDoc Class [[BR]]
- !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 a JSON document for the corresponding XML content, {{{<Node>Text</Node>}}}, one would call !BeginObject("Node"), !SetValue("Text"), and !EndObject() subsequently.

2) The !MgXmlJsonConvert Class [[BR]]
- !MgXmlJsonConvert converts an XML document into a JSON formatted document.

----

The following Web-tier to Server APIs are affected:

Coordinate System

# !EnumerateCategories (1) [[BR]]
# !EnumerateCoordinateSystems (1) [[BR]]

Resource

# !EnumerateResourceReferences (3) [[BR]]
# !EnumerateResources (3) [[BR]]
# !GetResourceContent (3) [[BR]]
# !GetResourceHeader (3) [[BR]]
# !EnumerateResourceData (3) [[BR]]
# !GetResourceData (3) [[BR]]
# !EnumerateUnmanagedData (3) [[BR]]

Feature

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

Rendering

# !GetVisibleMapExtent (1) [[BR]]

where the appended labeling indicates the different implementation schemes:

(1) Web-tier changes -- !ToJson functions are introduced to compose the JSON document in place; that is, most of the !ToXml implementation is matched with a !ToJson implementation.

(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 calls; the !MgXmlJsonConvert class is used if format is equaled to the JSON MIME type (i.e. "application/json").

(4) Server changes -- extra APIs have been added to handle JSON requests (e.g. !DescribeSchemaAsXml has !DescribeSchemaAsJson as the JSON version, and GetFDOCacheInfo has GetFDOCacheInfoAsJson as its JSON implementation). This is because the original APIs return "STRING" and could not be efficiently adapted by the conversion process within the !MgXmlJsonConvert class implementation. For the affected APIs, the !MgByteReader* is returned instead.

== Implications ==

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 ==

The following tests should be performed:

    * Resource Service unit tests
    * Feature Service unit tests
    * Affected APIs on the HTML test pages.

== Funding/Resources ==

Supplied by Autodesk.