Package org.eclipse.jetty.util.ajax

Class JSON

java.lang.Object

org.eclipse.jetty.util.ajax.JSON

public class JSON
extends Object

JSON parser and generator.

This class provides methods to convert POJOs to and from JSON notation.

The mapping from JSON to Java is:

   object --> Map<String, Object>
   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 toJSON(Object) method will use JSON.Generator.addJSON(Appendable) to generate the JSON.

The class JSON.Literal may be used to hold pre-generated JSON object.

The interface JSON.Convertor may be implemented to provide converters for objects that may be registered with addConvertor(Class, Convertor). These converters are looked up by class, interface and super class by getConvertor(Class).

If a JSON object has a class field, then a Java class for that name is loaded and the method convertTo(Class, Map) is used to find a JSON.Convertor for that class.

If a JSON object has a x-class field then a direct lookup for a JSON.Convertor for that class name is done (without loading the class).

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	JSON.Convertible	JSON Convertible object.
static interface	JSON.Convertor	JSON Convertor.
static interface	JSON.Generator	JSON Generator.
static class	JSON.Literal	A Literal JSON generator.
static interface	JSON.Output	JSON Output class for use by JSON.Convertible.
static class	JSON.ReaderSource	A Reader source for a JSON string.
static interface	JSON.Source	A generic source for a JSON representation.
static class	JSON.StringSource	An in-memory source for a JSON string.

Constructor Summary

Constructors

Constructor	Description
JSON()

Method Summary

Modifier and Type	Method	Description
void	addConvertor(Class<?> forClass, JSON.Convertor convertor)	Registers a JSON.Convertor for the given class.
void	addConvertorFor(String name, JSON.Convertor convertor)	Registers a JSON.Convertor for a named class.
void	append(Appendable buffer, Object object)	Appends the given object as JSON to string buffer.
void	appendArray(Appendable buffer, Object array)
void	appendArray(Appendable buffer, Collection<?> collection)
void	appendBoolean(Appendable buffer, Boolean b)
void	appendJSON(Appendable buffer, JSON.Convertible converter)
void	appendJSON(Appendable buffer, JSON.Convertor convertor, Object object)
void	appendJSON(Appendable buffer, JSON.Generator generator)
void	appendMap(Appendable buffer, Map<?,?> map)
void	appendNull(Appendable buffer)
void	appendNumber(Appendable buffer, Number number)
void	appendString(Appendable buffer, String string)
protected static void	complete(String seek, JSON.Source source)
protected JSON	contextFor(String field)	Every time a JSON object field representation {"name": value} is parsed, this method is called to (possibly) return a different JSON instance (for example configured with different converters) to parse the object field.
protected JSON	contextForArray()	Every time a JSON array representation [...] is parsed, this method is called to (possibly) return a different JSON instance (for example configured with different converters) to parse the array items.
protected Object	convertTo(Class<?> type, Map<String,Object> map)
void	escapeString(Appendable buffer, String input)	Escapes the characters of the given input string into the given buffer.
protected void	escapeUnicode(Appendable buffer, char c)	Per JSON specification, unicode characters are by default NOT escaped.
Object	fromJSON(Reader reader)	Parses the JSON from the given Reader into an object.
Object	fromJSON(String string)	Parses the given JSON string into an object.
Function<List<?>,Object>	getArrayConverter()
protected JSON.Convertor	getConvertor(Class<?> forClass)	Looks up a convertor for a class.
JSON.Convertor	getConvertorFor(String name)	Looks up a convertor for a class name.
int	getStringBufferSize()
protected Object	handleUnknown(JSON.Source source, char c)
protected Object[]	newArray(int size)	Deprecated. use setArrayConverter(Function) instead.
protected Map<String,Object>	newMap()	Factory method that creates a Map when a JSON representation of {...} is parsed.
Object	parse(JSON.Source source)	Parses the given JSON source into an object.
Object	parse(JSON.Source source, boolean stripOuterComment)	Parses the given JSON source into an object.
protected Object	parseArray(JSON.Source source)
Number	parseNumber(JSON.Source source)
protected Object	parseObject(JSON.Source source)
protected String	parseString(JSON.Source source)
JSON.Convertor	removeConvertor(Class<?> forClass)	Unregisters a JSON.Convertor for a class.
JSON.Convertor	removeConvertorFor(String name)	Unregisters a JSON.Convertor for a named class.
protected void	seekTo(char seek, JSON.Source source)
protected char	seekTo(String seek, JSON.Source source)
void	setArrayConverter(Function<List<?>,Object> arrayConverter)	Sets the function to convert JSON arrays from their default Java representation, a List<Object>, to another Java data structure such as an Object[].
void	setStringBufferSize(int stringBufferSize)
String	toJSON(Object object)	Converts any object to JSON.

Methods inherited from class java.lang.Object

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

Constructor Details

JSON

public JSON()

Method Details

getStringBufferSize

public int getStringBufferSize()

Returns:

the initial stringBuffer size to use when creating JSON strings (default 1024)

setStringBufferSize

public void setStringBufferSize(int stringBufferSize)

Parameters:

stringBufferSize - the initial stringBuffer size to use when creating JSON strings (default 1024)

escapeString

public void escapeString(Appendable buffer,
 String input)
                  throws IOException

Escapes the characters of the given input string into the given buffer.

Parameters:

buffer - the buffer to escape the string into

input - the string to escape

Throws:

IOException - if appending to the buffer fails

See Also:

• escapeUnicode(Appendable, char)

escapeUnicode

protected void escapeUnicode(Appendable buffer,
 char c)
                      throws IOException

Per JSON specification, unicode characters are by default NOT escaped.

Overriding this method allows for alternate behavior to escape those with your choice of encoding.

 protected void escapeUnicode(Appendable buffer, char c) throws IOException
 {
     // Unicode is backslash-u escaped
     buffer.append(String.format("\\u%04x", (int)c));
 }
 

Throws:

IOException

toJSON

public String toJSON(Object object)

Converts any object to JSON.

Parameters:

object - the object to convert

Returns:

the JSON string representation of the object

See Also:

• append(Appendable, Object)

append

public void append(Appendable buffer,
 Object object)

Appends the given object as JSON to string buffer.

This method tests the given object type and calls other appends methods for each object type, see for example appendMap(Appendable, Map).

Parameters:

buffer - the buffer to append to

object - the object to convert to JSON

appendNull

public void appendNull(Appendable buffer)

appendJSON

public void appendJSON(Appendable buffer,
 JSON.Convertor convertor,
 Object object)

appendJSON

public void appendJSON(Appendable buffer,
 JSON.Convertible converter)

appendJSON

public void appendJSON(Appendable buffer,
 JSON.Generator generator)

appendMap

public void appendMap(Appendable buffer,
 Map<?,?> map)

appendArray

public void appendArray(Appendable buffer,
 Collection<?> collection)

appendArray

public void appendArray(Appendable buffer,
 Object array)

appendBoolean

public void appendBoolean(Appendable buffer,
 Boolean b)

appendNumber

public void appendNumber(Appendable buffer,
 Number number)

appendString

public void appendString(Appendable buffer,
 String string)

newMap

protected Map<String,Object> newMap()

Factory method that creates a Map when a JSON representation of {...} is parsed.

Returns:

a new Map representing the JSON object

newArray

@Deprecated
protected Object[] newArray(int size)

Deprecated.

use setArrayConverter(Function) instead.

Factory method that creates an array when a JSON representation of [...] is parsed.

Parameters:

size - the size of the array

Returns:

a new array representing the JSON array

contextForArray

protected JSON contextForArray()

Every time a JSON array representation [...] is parsed, this method is called to (possibly) return a different JSON instance (for example configured with different converters) to parse the array items.

Returns:

a JSON instance to parse array items

contextFor

protected JSON contextFor(String field)

Every time a JSON object field representation {"name": value} is parsed, this method is called to (possibly) return a different JSON instance (for example configured with different converters) to parse the object field.

Parameters:

field - the field name

Returns:

a JSON instance to parse the object field

convertTo

protected Object convertTo(Class<?> type,
 Map<String,Object> map)

addConvertor

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

Registers a JSON.Convertor for the given class.

Parameters:

forClass - the class the convertor applies to

convertor - the convertor for the class

addConvertorFor

public void addConvertorFor(String name,
 JSON.Convertor convertor)

Registers a JSON.Convertor for a named class.

Parameters:

name - the name of the class the convertor applies to

convertor - the convertor for the class

removeConvertor

public JSON.Convertor removeConvertor(Class<?> forClass)

Unregisters a JSON.Convertor for a class.

Parameters:

forClass - the class the convertor applies to

Returns:

the convertor for the class

removeConvertorFor

public JSON.Convertor removeConvertorFor(String name)

Unregisters a JSON.Convertor for a named class.

Parameters:

name - the name of the class the convertor applies to

Returns:

the convertor for the class

getConvertor

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

Looks up 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 its interfaces are tried iteratively.

Parameters:

forClass - the class to look up the convertor

Returns:

a JSON.Convertor or null if none was found for the class

getConvertorFor

public JSON.Convertor getConvertorFor(String name)

Looks up a convertor for a class name.

Parameters:

name - name of the class to look up the convertor

Returns:

a JSON.Convertor or null if none were found.

getArrayConverter

public Function<List<?>,Object> getArrayConverter()

Returns:

the function to customize the Java representation of JSON arrays

See Also:

• setArrayConverter(Function)

setArrayConverter

public void setArrayConverter(Function<List<?>,Object> arrayConverter)

Sets the function to convert JSON arrays from their default Java representation, a List<Object>, to another Java data structure such as an Object[].

Parameters:

arrayConverter - the function to customize the Java representation of JSON arrays

See Also:

• getArrayConverter()

parse

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

Parses the given JSON source into an object.

Although the JSON specification does not allow comments (of any kind) this method optionally strips out outer comments of this form:

 // An outer comment line.
 /* Another outer comment, multiline.
 // Yet another comment line.
 {
     "name": "the real JSON"
 }
 */ End of outer comment, multiline.
 

Parameters:

source - the JSON source to parse

stripOuterComment - whether to strip outer comments

Returns:

the object constructed from the JSON string representation

fromJSON

public Object fromJSON(String string)

Parses the given JSON string into an object.

Parameters:

string - the JSON string to parse

Returns:

the object constructed from the JSON string representation

fromJSON

public Object fromJSON(Reader reader)

Parses the JSON from the given Reader into an object.

Parameters:

reader - the Reader to read the JSON from

Returns:

the object constructed from the JSON string representation

parse

public Object parse(JSON.Source source)

Parses the given JSON source into an object.

Although the JSON specification does not allow comments (of any kind) this method strips out initial comments of this form:

 // An initial comment line.
 /* An initial
    multiline comment */
 {
     "name": "foo"
 }
 

This method detects the object type and calls other parse methods for each object type, see for example parseArray(Source).

Parameters:

source - the JSON source to parse

Returns:

the object constructed from the JSON string representation

handleUnknown

protected Object handleUnknown(JSON.Source source,
 char c)

parseObject

protected Object parseObject(JSON.Source source)

parseArray

protected Object parseArray(JSON.Source source)

parseString

protected String parseString(JSON.Source source)

parseNumber

public Number parseNumber(JSON.Source source)

seekTo

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

seekTo

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

complete

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