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 an MBean server.

Class Summary

Class	Description
IndentPadding	This class provides a way to do indented formatting of the output to make it easier to read for debugging.
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.
JsonObject	This class provides a way to make an list of properties to be used to create JSON objects.
JSONParser	This is a JSON parser.
JSONReflectedClass	This class wraps a class to be explicitly reflected and allows you to choose the names of the fields to be reflected, regardless of privacy as well as set up aliases for field names in the JSON output.
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).
ReflectUtil	Some reflection utility constants to be used with JSONConfig.setReflectionPrivacy(int) and JSONConfigDefaults.setReflectionPrivacy(int)

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.
JSONReflectionException	Exception for wrapping reflection exceptions.
LoopDetectionFailureException	Exception if the data structure loop detection breaks.
UndefinedCodePointException	Exception used when undefined code points are encountered in the input and the value of JSONConfig.getUndefinedCodePointPolicy() is JSONConfig.EXCEPTION.
UnmatchedSurrogateException	Exception used when unmatched surrogates are encountered in the input and the value of JSONConfig.getUnmatchedSurrogatePolicy() is JSONConfig.EXCEPTION.

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.

This package optionally supports reflection so that you don't have to use a Map at all. You can choose which types of objects to use reflection on with JSONConfig.addReflectClass(Object) or JSONConfig.addReflectClasses(Collection) or you can have it use reflection on all unrecognized objects by using JSONConfig.setReflectUnknownObjects(boolean). The privacy level of fields to show with reflection can be controlled by using JSONConfig.setPrivacyLevel(int). By default only fields which are public or which have public getters will be included, but protected, package private and private can be included by using that setting.

There is 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, array or reflected class, then their JSONAble.toJSON(JSONConfig,Writer) method will be called to add them to the output.

Maps, Iterables, Enumerations, arrays and reflected classes 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.

There is some support for arbitrary precision numbers. All Javascript numbers are internally 64-bit double precision floating point and all numbers eventually get converted to that format by default by whatever parses the JSON. If you set JSONConfig.setPreciseNumbers(boolean) to true then numbers which cannot be accurately represented by 64-bit double precision floating point will be quoted in the output. This allows those string representations of those numbers to be fed to an arbitrary precision package constructor to maintain the original precision. There are several arbitrary precision math packages available for Javascript. JSONParser creates BigInteger and BigDecimal whenever it encounters numbers that lose precision in Long or Double respectively.

This package uses Apache Commons Logging facade 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.