JSON Guide

JSON is a language independent object serialization format. A guide to JSON syntax can be found at json.org. JSON is language independent but its origins are in Javascript. In fact JSON is a subset of javascript, here's a very simple JSON object serialization...

{ "hello" : "world" }

This JSON string can be parsed in javascript likes this:

var o={ "hello" : "world" };

so that o.hello has the value "world".

JSON is often used as an over-the-wire format for AJAX applications and is widely supported in AJAX toolkits. Equally mod-json provides the infrastructure which makes JSON a viable cross-language data exchange format for inter-service messaging within NetKernel.

The mod-json library offers a set of resources that enable JSON to be used a first-class resource model in NetKernel. It provides a low-level Java object model based on the org.json library and includes NetKernel resource model infrastructure including aspects and transreptors. This guide will illustrate the features of the library with examples.

Scripting JSON

mod-json exports a Java class library containng Java classes that provide JSON support. The primary implementation is org.json.JSONObject. Here is a beanshell script which constructs a JSONObject and sets a named value. The JSONObject is wrapped in a NetKernel aspect JSONAspect which implements the interface IAspectJSON. The JSONAspect is immutable and is returned through the script context.

import org.json.*;
import org.ten60.json.representation.*;

//Create a simple JSONObject
void main()
{   jo=new JSONObject();
    jo.put("name", "value");
    System.out.println(jo.toString());
    joa=new JSONAspect(jo);
    context.createResponseFrom(joa);
}

The System.out toString() call produces the following serialized JSON text...

{ "name":"value" }

Parsing JSON

Parsing JSON to obtain a scriptable resource is straightforward. A default JSONParser transreptor is registered in mod-json. If a binary resource is requested with an IAspectJSON then it will automatically invoke this transreptor. Here's an example. Suppose we have a serialized JSON file called "test.json"

{ "name":"value", array:[1,2,3]}

The following beanshell script sources this file and obtains a JSONAspect...

import org.json.*;
import org.ten60.json.representation.*;
import java.lang.*;

json=context.sourceAspect("test.json", IAspectJSON.class);

System.out.println(json.getJSONObject().get("array").get(0));

When executed this script will print '1' in stdout.

Serializing JSON

Serializing JSON is as easy as parsing it. Simply return a JSONAspect and the default serializer will be invoked whenever any service wants a binary stream representation of the aspect. Here's an example...

import org.json.*;
import org.ten60.json.representation.*;

//Create a simple JSONObject, modify it and return JSONAspect
void main()
{   jo=new JSONObject("{ \"name\":\"value\", array:[1,2,3]}" );
    jo.put("hello", "world");
    joa=new JSONAspect(jo);
    context.createResponseFrom(joa);
}

If this script were called by something that expects a binary stream, like for example the HTTP transport, it would produce the following text serialization...

{ "name":"value", array:[1,2,3], "hello", "world"}

Using JSON to roundtrip between client and server-side javascript

Since JSON is a subset of Javascript it can be evaluated and turned into an object within Javascript very easily. This is an example server-side javascript which parses a string of JSON to create a scriptable object.

importPackage(Packages.com.ten60.netkernel.urii.aspect);
importPackage(Packages.java.lang);

//Source output of test.json as a string
res=context.sourceAspect("test.json", IAspectString);

//Evaluate the JSON serialized string to an object
var o = eval('(' + res.getString() + ')');
System.out.println(o.name);

Review the documentation of your AJAX library for the symmetrical client-side methods to construct javascript objects from JSON service calls.

Security Warning: Calling javascript's eval() on externally supplied strings is generally unsafe. Please see json.org for javascript libraries that provide safe JSON object construction without directly calling eval.

JSON to/from XML

JSON is a textual serialization format and in some ways shares similar characteristics to XML. As a convenience an accessor is provided for constructing JSON objects from XML - see JSONFromXML. JSON can also be serialized to XML with JSONToXML - but take care since depending on how you construct your JSON resource it cannot be guaranteed to serialize into well-formed XML.

Source/Javadoc

The full source code for the library is shipped with the module. Online javadoc is available here: http://1060.org/resources/modules/mod-json/javadoc/