org.kopitubruk.util.json

Class JSONUtil

java.lang.Object

org.kopitubruk.util.json.JSONUtil

public class JSONUtil
extends Object

This class converts certain common types of objects into JSON using the static methods toJSON(Object), toJSON(Object,JSONConfig), toJSON(Object,Writer) and toJSON(Object,JSONConfig,Writer). Collections are traversed and encoded, allowing complex data graphs to be encoded in one call. It's more flexible than the org.json library and in many cases may allow the use of existing data structures directly without modification which should reduce both memory and CPU usage.

There are a number of configuration options available by passing a JSONConfig object to the toJSON methods. In most cases, the defaults are adequate so you don't need to pass a JSONConfig object if you don't want to. You can also change the defaults for some of the options so that you don't have to pass the object even if you want non-default behavior. Keep in mind that doing that affects all new JSONConfig objects that are created after that in the same class loader.

This implementation validates property names by default using the specification from ECMAScript and ECMA JSON standards. The validation can be disabled for faster performance. See JSONConfig. Leaving it on during development and testing is probably advisable.

There is some effort to detect loops in the data structure that would cause infinite recursion and throw an exception. This detection is not perfect and there are some ways to fool it, so try to be careful and not make loops in your data structures.

Top level objects which can be sent to the toJSON methods:

Maps

In most cases, this will be what you will send to the toJSON method. The Map becomes a Javascript object with the property names being the result of the key's toString() method and the values being property values. The key's toString() must produce valid Javascript identifiers and the values can be almost anything. Note that this is different than the org.json library which requires the keys to actually be Strings.

ResourceBundle

Converted to a Javascript object with the keys being the property names and the values being from ResourceBundle.getObject(String).

Iterables, Enumerations and arrays

These are encoded as Javascript arrays. These can also be top level if you want an array as your top level structure. Note that Collection is a sub-interface of Iterable, so all collections are covered by this.

JSONAbles

These are objects that know how to convert themselves to JSON. This just calls their JSONAble.toJSON(JSONConfig,Writer) method. It is possible to use these as top level objects or as values inside other objects but it's kind of redundant to use them as top level.

Other objects which can commonly be values in Maps, Iterables, Enumerations and arrays.

Numbers

Anything that implements the Number interface, which is all of the wrapper objects for primitive numbers and BigInteger and BigDecimal. They normally have their toString() methods called. Primitive versions of these are also allowed in arrays and will be converted to their wrapper objects. These get whatever their object's toString() method gives. It is possible to set number formats for any number type in the JSONConfig. If those are set then they will be used instead of toString().

Any other object

Any other object just gets its toString() method called and it's surrounded by quotes with escapes used as needed according to the ECMA JSON standard and escape options from JSONConfig. Usually this will just be for String objects, but anything that has a toString() that gives you what you want will work.

Boolean's

Encoded as boolean literals.

null

Encoded as the Javascript literal null.

Author:

Bill Davidson

See Also:

JSONAble, JSONConfig, JSONConfigDefaults

Method Summary

Modifier and Type	Method and Description
static void	checkValidJavascriptPropertyName(String propertyName) Checks if the input string represents a valid Javascript property name.
static void	checkValidJavascriptPropertyName(String propertyName, JSONConfig cfg) Checks if the input string represents a valid Javascript property name.
static Set<String>	getJavascriptReservedWords() Get the list of reserved words.
static boolean	isReservedWord(String name) Check if the given string is a reserved word.
static String	toJSON(Object obj) Convert an object to JSON and return it as a String.
static String	toJSON(Object obj, JSONConfig cfg) Convert an object to JSON and return it as a String.
static void	toJSON(Object obj, JSONConfig cfg, Writer json) Convert an object to JSON and write it to the given Writer.
static void	toJSON(Object obj, Writer json) Convert an object to JSON and write it to the given Writer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

toJSON

public static String toJSON(Object obj)

Convert an object to JSON and return it as a String. All options will use defaults.

Parameters:

obj - An object to be converted to JSON.

Returns:

A JSON string representation of the object.

toJSON

public static String toJSON(Object obj,
                            JSONConfig cfg)

Convert an object to JSON and return it as a String.

Parameters:

obj - An object to be converted to JSON.

cfg - A configuration object to use.

Returns:

A JSON string representation of the object.

toJSON

public static void toJSON(Object obj,
                          Writer json)
                   throws IOException

Convert an object to JSON and write it to the given Writer. All options will be default. Using a Writer may be preferable in servlets, particularly if the data is large because it can use a lot less memory than a StringBuffer by sending the data to the browser via a BufferedWriter on the output stream as it is being generated. The downside of that is that you could have an error after data begins being sent, which could result in corrupted partial data being sent to the caller.

Parameters:

obj - An object to be converted to JSON.

json - Something to write the JSON data to.

Throws:

IOException - If there is an error on output.

toJSON

public static void toJSON(Object obj,
                          JSONConfig cfg,
                          Writer json)
                   throws IOException

Convert an object to JSON and write it to the given Writer. Using a Writer may be preferable in servlets, particularly if the data is large because it can use a lot less memory than a StringBuffer by sending the data to the browser via a BufferedWriter on the output stream as it is being generated. The downside of that is that you could have an error after data begins being sent, which could result in corrupted partial data being sent to the caller.

Parameters:

obj - An object to be converted to JSON.

cfg - A configuration object to use to set various options. If null then defaults will be used.

json - Something to write the JSON data to.

Throws:

IOException - If there is an error on output.

getJavascriptReservedWords

public static Set<String> getJavascriptReservedWords()

Get the list of reserved words.

Returns:

the set of reserved words.

isReservedWord

public static boolean isReservedWord(String name)

Check if the given string is a reserved word.

Parameters:

name - The name to check.

Returns:

true if the name is a reserved word.

checkValidJavascriptPropertyName

public static void checkValidJavascriptPropertyName(String propertyName,
                                                    JSONConfig cfg)
                                             throws BadPropertyNameException

Checks if the input string represents a valid Javascript property name.

Parameters:

propertyName - A Javascript property name to check.

cfg - A JSONConfig to use for locale.

Throws:

BadPropertyNameException - If the propertyName is not a valid Javascript property name.

checkValidJavascriptPropertyName

public static void checkValidJavascriptPropertyName(String propertyName)
                                             throws BadPropertyNameException

Checks if the input string represents a valid Javascript property name.

Parameters:

propertyName - A Javascript property name to check.

Throws:

BadPropertyNameException - If the propertyName is not a valid Javascript property name.