M5 Core Enhancements

The following updates are planned for the Project Zero core in M5.

Deferred Initialization

Persisting Global Context Zones

JSON API updates

Replacement of decodeAsURL(String) with decode(URL)

The Json API method decodeAsURL that takes a String argument will be replaced with decode that takes a URL argument. The API now consistently uses decode and encode to parse JSON data into an object and vice versa. To decode from a URL, you could do the following.

URL url = new URL("file:// ....);
try {
    Object json = Json.decode(url);
} catch ( ...)

Replace JSON parser implementation with ANTLR based JSON parser

The ANTLR based parser is much more performant and provides better diagnostic messages in case of errors in the JSON data. We will now have a single common JSON parser for both configuration processing and parsing application data.

Ability to decode JSON data into custom objects directly

The JSON parser will be augmented to give control back to the callers when it needs to create a JSON object or array from the data.

/**
 * An implementation of this callback interface can be provided to the decode function of the 
 * {@link Json} utility to allow the caller to create its own representation of a JSON object 
 * or array. If this callback interface is not used, the JSON parser will create a new instance 
 * of a Map or List to represent a JSON object and an array respectively.
 */
public interface JsonParserCallback {
   
   /**
    * This method is invoked by the JSON parser when it encounters a JSON object in the stream. 
    * The implementer of this interface is expected to maintain an internal representation of the 
    * JSON object through the @link(JsonObjectCallback) interface.
    * @return JsonObjectCallback
    */
   public JsonObjectCallback createJsonObject();
   
   /**
    * This method is invoked by the JSON parser when it encounters a JSON array in the stream. The 
    * implementer of this interface is expected to maintain an internal representation of the JSON 
    * array through the @link(JsonArrayCallback) interface.
    * @return JsonArrayCallback
    */
   public JsonArrayCallback  createJsonArray();

}

In case of JSON object, it then calls back when it needs to add an attribute.

/**
 * This interface is invoked by the JSON parser in the course of processing an JSON object from
 * a stream. This allows the implementer of this interface to update its internal representation 
 * of the JSON object as the JSON object is parsed. It also provides the the JSON parser with 
 * the representation of the JSON object to return.
 *
 */
public interface JsonObjectCallback {

   /**
    * This method is invoked by the JSON parser when it encounters a member (key/value pair) 
    * in the JSON object. The implementer of this method is expected to store the member 
    * in its representation of the JSON object.
    * 
    * @param key The name of the key or field to set in the object.
    * @param value The value of the key or field to set in the object.
    */
   void put(String key, Object value);
   
   /**
    * This method is invoked by the JSON parser needs to retrieve the JSON object representation 
    * so that it can return the representation to the caller.
    * @return the Object representation of the JSON array.
    */
   Object getObject();

}

Similarly the parser calls back when an new element has to be added to an array.

/**
 * This interface is invoked by the JSON parser while processing a  JSON array from 
 * a stream. This allows the implementer of this interface to update its internal 
 * representation of the JSON array as the JSON array is parsed. It also provides 
 * the JSON  * parser with the representation of the JSON array to return.
 *
 */
public interface JsonArrayCallback {
   
   /**
    * This method is called when the JSON parser encounters an element in a JSON array. 
    * The implementer of this interface adds the element to its representation of the JSON array.
    * @param value The value of the JSON array element encountered.
    */
   void add(Object value);
   
   /**
    * This method is invoked when the JSON parser needs to retrieve the JSON array 
    * representation so that it can return the representation to the caller.
    * @return the Object representation of the JSON array.
    */
   Object getObject();

}

Ability to specify JSON string filters

It will be possible to register implementation of string filters for JSON in the global context at /config/json/stringFilters. The following is a registration of string filter in zero.config file

/config/json/stringFilters += ["com.acme.JsonSecurityFilter"]

The string filters should implement the following interface.

/**
 * Callback interface invoked by the JSON parser when it encounters a JSON string in the stream that it 
 * is parsing. This interface can be registered via the Global Context to allow for special filtering 
 * of content that may be embedded in the JSON string.
 *
 */
public interface JsonStringFilter {
   
   /**
    * This method is invoked by the JSON parser when it encounters a JSON string in the stream. 
    * This can be used by special handlers that need to filter the JSON encoded string for 
    * inappropriate content. 
    * @param value
    * @return String
    */
   public String filterString(String value);
}

-- madhu - 14 Mar 2008