JSON Parser and Generator.

This class provides some static methods to convert POJOs to and from JSON notation. The mapping from JSON to java is:

  object ==> Map
  array  ==> Object[]
  number ==> Double or Long
  string ==> String
  null   ==> null
  bool   ==> Boolean

The java to JSON mapping is:

  String --> string
  Number --> number
  Map    --> object
  List   --> array
  Array  --> array
  null   --> null
  Boolean--> boolean
  Object --> string (dubious!)

The interface JSON.Convertible may be implemented by classes that wish to externalize and initialize specific fields to and from JSON objects. Only directed acyclic graphs of objects are supported.

The interface JSON.Generator may be implemented by classes that know how to render themselves as JSON and the toString(Object) method will use JSON.Generator#addJSON(StringBuffer) to generate the JSON. The class JSON.Literal may be used to hold pre-gnerated JSON object.

The interface Convertor may be implemented to provide static convertors for objects that may be registered with registerConvertor(Class, org.mortbay.util.ajax.JSON.Convertor). These convertors are looked up by class, interface and super class by getConvertor(Class).

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static interface	JSON.Convertible JSON Convertible object.
public static interface	JSON.Convertor Static JSON Convertor.
public static interface	JSON.Generator JSON Generator.
public static class	JSON.Literal A Literal JSON generator A utility instance of `JSON.Generator` that holds a pre-generated string on JSON text.
public static interface	JSON.Output JSON Output class for use by `Convertible`.
public static class	JSON.ReaderSource
public static interface	JSON.Source
public static class	JSON.StringSource

Field Summary

Modifier and Type	Field and Description
private static JSON	__default
private Map<K, V>	_convertors
private int	_stringBufferSize

Constructor Summary

Access	Constructor and Description
public	JSON()

Method Summary

Modifier and Type	Method and Description
public void	addConvertor(Class<T> The class or interface that the convertor applies to forClass, JSON.Convertor the convertor convertor) Register a `Convertor` for a class or interface.
public void	append(StringBuffer buffer, Object object) Append object as JSON to string buffer.
public void	appendArray(StringBuffer buffer, Collection<E> collection)
public void	appendArray(StringBuffer buffer, Object array)
public void	appendBoolean(StringBuffer buffer, Boolean b)
public void	appendJSON(final StringBuffer buffer, final JSON.Convertor convertor, final Object object)
public void	appendJSON(final StringBuffer buffer, JSON.Convertible converter)
public void	appendJSON(StringBuffer buffer, JSON.Generator generator)
public void	appendMap(StringBuffer buffer, Map<K, V> object)
public void	appendNull(StringBuffer buffer)
public void	appendNumber(StringBuffer buffer, Number number)
public void	appendString(StringBuffer buffer, String string)
protected static void	complete(String seek, JSON.Source source)
protected JSON	contextFor(String field)
protected JSON	contextForArray()
protected Object	convertTo(Class<T> type, Map<K, V> map)
public Object	Returns: The object fromJSON(String The json to convert json) Convert JSON to Object
protected JSON.Convertor	Returns: a `Convertor` or null if none were found. getConvertor(Class<T> The class forClass) Lookup a convertor for a class.
public static JSON	getDefault()
public int	Returns: the initial stringBuffer size to use when creating JSON strings (default 256) getStringBufferSize()
protected Object[]	newArray(int size)
protected Map<K, V>	newMap()
public static Object	Returns: A Map, Object array or primitive array parsed from the JSON. parse(String String containing JSON object or array. s)
public static Object	Returns: A Map, Object array or primitive array parsed from the JSON. parse(String String containing JSON object or array. s, boolean If true, an outer comment around the JSON is ignored. stripOuterComment)
public static Object	Returns: A Map, Object array or primitive array parsed from the JSON. parse(Reader Reader containing JSON object or array. in)
public static Object	Returns: A Map, Object array or primitive array parsed from the JSON. parse(Reader Stream containing JSON object or array. in, boolean If true, an outer comment around the JSON is ignored. stripOuterComment)
public static Object	Returns: A Map, Object array or primitive array parsed from the JSON. parse(InputStream Reader containing JSON object or array. in) Deprecated use `parse(Reader)`
public static Object	Returns: A Map, Object array or primitive array parsed from the JSON. parse(InputStream Stream containing JSON object or array. in, boolean If true, an outer comment around the JSON is ignored. stripOuterComment) Deprecated use `parse(Reader, boolean)`
public Object	parse(JSON.Source source, boolean stripOuterComment)
public Object	parse(JSON.Source source)
private Object	parseArray(JSON.Source source)
public Number	parseNumber(JSON.Source source)
protected Object	parseObject(JSON.Source source)
private String	parseString(JSON.Source source)
public static void	registerConvertor(Class<T> The class or interface that the convertor applies to forClass, JSON.Convertor the convertor convertor) Register a `Convertor` for a class or interface.
protected void	seekTo(char seek, JSON.Source source)
protected char	seekTo(String seek, JSON.Source source)
public static void	setDefault(JSON json)
public void	setStringBufferSize(int the initial stringBuffer size to use when creating JSON strings (default 256) stringBufferSize)
public String	Returns: The JSON String toJSON(Object The object to convert object) Convert Object to JSON
public static String	toString(Object object)
public static String	toString(Map<K, V> object)
public static String	toString(Object[] array)
protected String	toString(char[] buffer, int offset, int length)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

__default	back to summary
private static JSON __default

_convertors	back to summary
private Map<K, V> _convertors

_stringBufferSize	back to summary
private int _stringBufferSize

Constructor Detail

JSON	back to summary
public JSON()

Method Detail

addConvertor back to summary

addConvertor	back to summary
public void addConvertor(Class<T> forClass, JSON.Convertor convertor) Register a `Convertor` for a class or interface. Parameters forClass:Class<T> The class or interface that the convertor applies to convertor:JSON.Convertor the convertor

public void addConvertor(Class<T> forClass, JSON.Convertor convertor)

Parameters

forClass:Class<T>: The class or interface that the convertor applies to
convertor:JSON.Convertor: the convertor

append	back to summary
public void append(StringBuffer buffer, Object object) Append object as JSON to string buffer.

appendArray	back to summary
public void appendArray(StringBuffer buffer, Collection<E> collection)

appendArray	back to summary
public void appendArray(StringBuffer buffer, Object array)

appendBoolean	back to summary
public void appendBoolean(StringBuffer buffer, Boolean b)

appendJSON	back to summary
public void appendJSON(final StringBuffer buffer, final JSON.Convertor convertor, final Object object)

appendJSON	back to summary
public void appendJSON(final StringBuffer buffer, JSON.Convertible converter)

appendJSON	back to summary
public void appendJSON(StringBuffer buffer, JSON.Generator generator)

appendMap	back to summary
public void appendMap(StringBuffer buffer, Map<K, V> object)

appendNull	back to summary
public void appendNull(StringBuffer buffer)

appendNumber	back to summary
public void appendNumber(StringBuffer buffer, Number number)

appendString	back to summary
public void appendString(StringBuffer buffer, String string)

complete	back to summary
protected static void complete(String seek, JSON.Source source)

contextFor	back to summary
protected JSON contextFor(String field)

contextForArray	back to summary
protected JSON contextForArray()

convertTo	back to summary
protected Object convertTo(Class<T> type, Map<K, V> map)

fromJSON	back to summary
public Object fromJSON(String json) Convert JSON to Object Parameters json:String The json to convert Returns:Object The object

fromJSON

back to summary

public Object fromJSON(String json)

Convert JSON to Object

Parameters

json:String: The json to convert

Returns:Object

The object

getConvertor back to summary

getConvertor	back to summary
protected JSON.Convertor getConvertor(Class<T> forClass) Lookup a convertor for a class. If no match is found for the class, then the interfaces for the class are tried. If still no match is found, then the super class and it's interfaces are tried recursively. Parameters forClass:Class<T> The class Returns:JSON.Convertor a `Convertor` or null if none were found.

protected JSON.Convertor getConvertor(Class<T> forClass)

Lookup a convertor for a class.

If no match is found for the class, then the interfaces for the class are tried. If still no match is found, then the super class and it's interfaces are tried recursively.

Parameters

forClass:Class<T>: The class

Returns:JSON.Convertor

a Convertor or null if none were found.

getDefault	back to summary
public static JSON getDefault()

getStringBufferSize	back to summary
public int getStringBufferSize() Returns:int the initial stringBuffer size to use when creating JSON strings (default 256)

newArray	back to summary
protected Object[] newArray(int size)

newMap	back to summary
protected Map<K, V> newMap()

parse	back to summary
public static Object parse(String s) Parameters s:String String containing JSON object or array. Returns:Object A Map, Object array or primitive array parsed from the JSON.

parse	back to summary
public static Object parse(String s, boolean stripOuterComment) Parameters s:String String containing JSON object or array. stripOuterComment:boolean If true, an outer comment around the JSON is ignored. Returns:Object A Map, Object array or primitive array parsed from the JSON.

parse	back to summary
public static Object parse(Reader in) throws IOException Parameters in:Reader Reader containing JSON object or array. Returns:Object A Map, Object array or primitive array parsed from the JSON.

parse	back to summary
public static Object parse(Reader in, boolean stripOuterComment) throws IOException Parameters in:Reader Stream containing JSON object or array. stripOuterComment:boolean If true, an outer comment around the JSON is ignored. Returns:Object A Map, Object array or primitive array parsed from the JSON.

parse	back to summary
public static Object parse(InputStream in) throws IOException Deprecated use `parse(Reader)` Parameters in:InputStream Reader containing JSON object or array. Returns:Object A Map, Object array or primitive array parsed from the JSON.

parse	back to summary
public static Object parse(InputStream in, boolean stripOuterComment) throws IOException Deprecated use `parse(Reader, boolean)` Parameters in:InputStream Stream containing JSON object or array. stripOuterComment:boolean If true, an outer comment around the JSON is ignored. Returns:Object A Map, Object array or primitive array parsed from the JSON.

parse	back to summary
public Object parse(JSON.Source source, boolean stripOuterComment)

parse	back to summary
public Object parse(JSON.Source source)

parseArray	back to summary
private Object parseArray(JSON.Source source)

parseNumber	back to summary
public Number parseNumber(JSON.Source source)

parseObject	back to summary
protected Object parseObject(JSON.Source source)

parseString	back to summary
private String parseString(JSON.Source source)

registerConvertor back to summary

registerConvertor	back to summary
public static void registerConvertor(Class<T> forClass, JSON.Convertor convertor) Register a `Convertor` for a class or interface. Parameters forClass:Class<T> The class or interface that the convertor applies to convertor:JSON.Convertor the convertor

public static void registerConvertor(Class<T> forClass, JSON.Convertor convertor)

Parameters

forClass:Class<T>: The class or interface that the convertor applies to
convertor:JSON.Convertor: the convertor

seekTo	back to summary
protected void seekTo(char seek, JSON.Source source)

seekTo	back to summary
protected char seekTo(String seek, JSON.Source source)

setDefault	back to summary
public static void setDefault(JSON json)

setStringBufferSize	back to summary
public void setStringBufferSize(int stringBufferSize) Parameters stringBufferSize:int the initial stringBuffer size to use when creating JSON strings (default 256)

toJSON	back to summary
public String toJSON(Object object) Convert Object to JSON Parameters object:Object The object to convert Returns:String The JSON String

toJSON

back to summary

public String toJSON(Object object)

Convert Object to JSON

Parameters

object:Object: The object to convert

Returns:String

The JSON String

toString	back to summary
public static String toString(Object object)

toString	back to summary
public static String toString(Map<K, V> object)

toString	back to summary
public static String toString(Object[] array)

toString	back to summary
protected String toString(char[] buffer, int offset, int length)

org.mortbay.util.ajax back to summary

public Interface JSON.Convertible

JSON Convertible object. Object can implement this interface in a similar way to the Externalizable interface is used to allow classes to provide their own serialization mechanism.

A JSON.Convertible object may be written to a JSONObject or initialized from a Map of field names to values.

If the JSON is to be convertible back to an Object, then the method Output#addClass(Class) must be called from within toJSON()

Method Summary

Modifier and Type	Method and Description
public void	fromJSON(Map<K, V> object)
public void	toJSON(JSON.Output out)

Method Detail

fromJSON	back to summary
public void fromJSON(Map<K, V> object)

toJSON	back to summary
public void toJSON(JSON.Output out)

org.mortbay.util.ajax back to summary

public Interface JSON.Convertor

Known Direct Implementers: org.mortbay.util.ajax.JSONDateConvertor, org.mortbay.util.ajax.JSONEnumConvertor, org.mortbay.util.ajax.JSONObjectConvertor

Static JSON Convertor.

may be implemented to provide static convertors for objects that may be registered with {@link JSON#registerConvertor(Class, org.mortbay.util.ajax.JSON.Convertor). These convertors are looked up by class, interface and super class by JSON#getConvertor(Class). Convertors should be used when the classes to be converted cannot implement Convertible or Generator.

Method Summary

Modifier and Type	Method and Description
public Object	fromJSON(Map<K, V> object)
public void	toJSON(Object obj, JSON.Output out)

Method Detail

fromJSON	back to summary
public Object fromJSON(Map<K, V> object)

toJSON	back to summary
public void toJSON(Object obj, JSON.Output out)

org.mortbay.util.ajax back to summary

public Interface JSON.Generator

Known Direct Implementers: org.mortbay.util.ajax.JSON.Literal

JSON Generator. A class that can add it's JSON representation directly to a StringBuffer. This is useful for object instances that are frequently converted and wish to avoid multiple Conversions

Method Summary

Modifier and Type	Method and Description
public void	addJSON(StringBuffer buffer)

Method Detail

addJSON	back to summary
public void addJSON(StringBuffer buffer)

org.mortbay.util.ajax back to summary

public Class JSON.Literal

Class Inheritance

extends Object
implements Generator

java.lang.Object
org.mortbay.util.ajax.JSON.Literal

All Implemented Interfaces

org.mortbay.util.ajax.JSON.Generator

A Literal JSON generator A utility instance of JSON.Generator that holds a pre-generated string on JSON text.

Field Summary

Modifier and Type	Field and Description
private String	_json

Constructor Summary

Access	Constructor and Description
public	Literal(String A literal JSON string. json) Construct a literal JSON instance for use by `JSON#toString(Object)`.

Method Summary

Modifier and Type	Method and Description
public void	addJSON(StringBuffer buffer) Implements org.mortbay.util.ajax.JSON.Generator.addJSON.
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

_json	back to summary
private String _json

Constructor Detail

Literal back to summary

public Literal(String json)

Construct a literal JSON instance for use by JSON#toString(Object). If Log#isDebugEnabled() is true, the JSON will be parsed to check validity

Parameters

json:String: A literal JSON string.

Method Detail

addJSON	back to summary
public void addJSON(StringBuffer buffer) Implements org.mortbay.util.ajax.JSON.Generator.addJSON.

toString

back to summary

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String: a string representation of the object.

org.mortbay.util.ajax back to summary

public Interface JSON.Output

JSON Output class for use by Convertible.

Method Summary

Modifier and Type	Method and Description
public void	add(Object obj)
public void	add(String name, Object value)
public void	add(String name, double value)
public void	add(String name, long value)
public void	add(String name, boolean value)
public void	addClass(Class<T> c)

Method Detail

add	back to summary
public void add(Object obj)

add	back to summary
public void add(String name, Object value)

add	back to summary
public void add(String name, double value)

add	back to summary
public void add(String name, long value)

add	back to summary
public void add(String name, boolean value)

addClass	back to summary
public void addClass(Class<T> c)

org.mortbay.util.ajax back to summary

public Class JSON.ReaderSource

Class Inheritance

extends Object
implements Source

java.lang.Object
org.mortbay.util.ajax.JSON.ReaderSource

All Implemented Interfaces

org.mortbay.util.ajax.JSON.Source

Field Summary

Modifier and Type	Field and Description
private int	_next
private Reader	_reader
private char[]	scratch

Constructor Summary

Access	Constructor and Description
public	ReaderSource(Reader r)

Method Summary

Modifier and Type	Method and Description
private void	getNext()
public boolean	hasNext() Implements org.mortbay.util.ajax.JSON.Source.hasNext.
public char	next() Implements org.mortbay.util.ajax.JSON.Source.next.
public char	peek() Implements org.mortbay.util.ajax.JSON.Source.peek.
public char[]	scratchBuffer() Implements org.mortbay.util.ajax.JSON.Source.scratchBuffer.
public void	setReader(Reader reader)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

_next	back to summary
private int _next

_reader	back to summary
private Reader _reader

scratch	back to summary
private char[] scratch

Constructor Detail

ReaderSource	back to summary
public ReaderSource(Reader r)

Method Detail

getNext	back to summary
private void getNext()

hasNext	back to summary
public boolean hasNext() Implements org.mortbay.util.ajax.JSON.Source.hasNext.

next	back to summary
public char next() Implements org.mortbay.util.ajax.JSON.Source.next.

peek	back to summary
public char peek() Implements org.mortbay.util.ajax.JSON.Source.peek.

scratchBuffer	back to summary
public char[] scratchBuffer() Implements org.mortbay.util.ajax.JSON.Source.scratchBuffer.

setReader	back to summary
public void setReader(Reader reader)

org.mortbay.util.ajax back to summary

public Interface JSON.Source

Known Direct Implementers: org.mortbay.util.ajax.JSON.StringSource, org.mortbay.util.ajax.JSON.ReaderSource

Method Summary

Modifier and Type	Method and Description
public boolean	hasNext()
public char	next()
public char	peek()
public char[]	scratchBuffer()

Method Detail

hasNext	back to summary
public boolean hasNext()

next	back to summary
public char next()

peek	back to summary
public char peek()

scratchBuffer	back to summary
public char[] scratchBuffer()

org.mortbay.util.ajax back to summary

public Class JSON.StringSource

Class Inheritance

extends Object
implements Source

java.lang.Object
org.mortbay.util.ajax.JSON.StringSource

All Implemented Interfaces

org.mortbay.util.ajax.JSON.Source

Field Summary

Modifier and Type	Field and Description
private int	index
private char[]	scratch
private final String	string

Constructor Summary

Access	Constructor and Description
public	StringSource(String s)

Method Summary

Modifier and Type	Method and Description
public boolean	hasNext() Implements org.mortbay.util.ajax.JSON.Source.hasNext.
public char	next() Implements org.mortbay.util.ajax.JSON.Source.next.
public char	peek() Implements org.mortbay.util.ajax.JSON.Source.peek.
public char[]	scratchBuffer() Implements org.mortbay.util.ajax.JSON.Source.scratchBuffer.
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

index	back to summary
private int index

scratch	back to summary
private char[] scratch

string	back to summary
private final String string

Constructor Detail

StringSource	back to summary
public StringSource(String s)

Method Detail

hasNext	back to summary
public boolean hasNext() Implements org.mortbay.util.ajax.JSON.Source.hasNext.

next	back to summary
public char next() Implements org.mortbay.util.ajax.JSON.Source.next.

peek	back to summary
public char peek() Implements org.mortbay.util.ajax.JSON.Source.peek.

scratchBuffer	back to summary
public char[] scratchBuffer() Implements org.mortbay.util.ajax.JSON.Source.scratchBuffer.

toString

back to summary

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String: a string representation of the object.