Package org.kopitubruk.util.json

Provides utilities to convert objects into JSON and parse JSON into Java objects.

See: Description

Interface Summary

Interface	Description
JSONAble	This interface specifies a method which implementing objects will use to provide a JSON representation of themselves.
JSONConfigDefaultsMBean	MBean interface for JSONConfigDefaults to expose its methods to view and modify the defaults at run time when this library is used with a MBean server.

Class Summary

Class	Description
JSONConfig	A configuration object for JSONUtil to control various encoding options.
JSONConfigDefaults	This class provides a singleton object which is used to change static defaults used by JSONConfig and it is used as an MBean to allow JMX clients with MBean support to view and modify the defaults.
JSONParser	This is a JSON parser.
JSONUtil	This class converts certain common types of objects into JSON using the static methods JSONUtil.toJSON(Object), JSONUtil.toJSON(Object,JSONConfig), JSONUtil.toJSON(Object,Writer) and JSONUtil.toJSON(Object,JSONConfig,Writer).

Exception Summary

Exception	Description
BadPropertyNameException	Exception for handling bad Javascript property identifiers for JSONUtil.
DataStructureLoopException	Exception for handling loops in the data structures sent to various toJSON methods.
DuplicatePropertyNameException	Exception thrown when a map produces duplicate property names in the same object, which is extremely unlikely but could happen if the map has two keys which are not equal but produce the same result from their toString() method.
JSONException	Holds some redundant code/data for the other exceptions thrown by JSONUtil.
JSONParserException	Exception for problems parsing JSON.
LoopDetectionFailureException	Exception if the data structure loop detection breaks.

Package org.kopitubruk.util.json Description

Provides utilities to convert objects into JSON and parse JSON into Java objects. The JSONUtil class is an alternative to the org.json package.

Instead of creating its own maps for objects or lists for arrays, this package allows you to use any Map you like, allowing for iterations on your Map to be predictable by using a TreeMap or a LinkedHashMap which can be useful for debugging. You can also use any Iterable object or Enumeration to create a Javascript array or even use an actual array of objects or primitives. In many cases it may be possible to use existing data structures without modification.

There is also an interface provided called JSONAble which enables marking classes that can convert themselves to JSON and when those are encountered as the values in a Map, Iterable, Enumeration or array, their JSONAble#toJSON(JSONConfig,Writer) method will be called to add them to the output.

Maps, Iterables, Enumerations and arrays are traversed, allowing the creation of complex graphs of JSON data with one call. JSONAbles may also be traversed if the JSONAble object implements complex data structures within itself and uses this package to generate its own JSON.

There is loop detection which attempts to avoid infinite recursion, but there are some ways to get past the detection, particularly with toString() methods in non-JSONAble objects, or with JSONAbles which do not properly pass their JSONConfig object along so care should still be exercised in avoiding loops in data structures.

There are a number of configuration options to allow you to disable validation and loop detection, change some of the character escape behavior and even generate certain types of non-standard JSON which may work if you're using a Javascript eval() on it rather than a strict JSON parser.

ECMAScript 6 support is available by enabling it in JSONConfig. This causes ECMAScript 6 code point escapes to be recognized as well as generated when it saves characters over code unit escapes. It also allows a larger set of characters in identifiers as per the ECMAScript 6 standard.

This package uses Apache Commons Logging in a few places so it should work with whatever logging framework you're using, but most of the messages are debug level so you shouldn't see them unless you enable debug for the package/classes. They are all related to JNDI lookups or MBean access so if you're having trouble with those, you may want to enable debug for this package.

The JSONParser class parses JSON data. It converts Javascript objects into LinkedHashMaps and Javascript arrays into ArrayLists. It's a "loose" parser in that it accepts valid Javascript syntax for objects and arrays, numbers and strings so it is less strict than the JSON standard.