net.arnx.jsonic
Class JSON

java.lang.Object
  net.arnx.jsonic.JSON

Direct Known Subclasses:

WebServiceServlet.JSON

public class JSON
extends Object

The JSONIC JSON class provides JSON encoding and decoding as defined by RFC 4627.

The following example illustrates how to encode and decode. The code:

 // encodes a object into a json string.
 String s = JSON.encode(o);
 
 // decodes a json string into a object.
 Object o = JSON.decode(s);
 
 // decodes a json string into a typed object.
 Foo foo = JSON.decode(s, Foo.class);
 

Advanced topic:

 // formats a object into a json string with indents for debug.
 JSON json = new JSON();
 json.setPrettyPrint(true);
 String pretty = json.format(o);
 
 //uses Reader/InputStream
 Bar bar = JSON.decode(new FileInputStream("bar.json"), Bar.class);
 Bar bar = JSON.decode(new FileReader("bar.json"), Bar.class);
 

Summary of encoding rules for java type into json type

java type	json type
java.util.Map	object
java.lang.Object (public property or field)
java.lang.Object[]	array
java.util.Collection
boolean[], short[], int[], long[], float[], double[]
java.lang.CharSequence	string
char[]
java.lang.Character
char
java.util.TimeZone
java.util.regex.Pattern
java.lang.reflect.Type
java.lang.reflect.Member
java.net.URI
java.net.URL
byte[]	string (base64)
java.util.Locale	string (language-country)
java.lang.Number	number
byte, short, int, long, float, double
java.util.Date	number (milliseconds since 1970)
java.util.Calendar
java.lang.Boolean	true/false
boolean
null	null

Summary of decoding rules for json type into java type

json type	java type
object	java.util.LinkedHashMap
array	java.util.ArrayList
string	java.lang.String
number	java.math.BigDecimal
true/false	java.lang.Boolean
null	null

Version:

1.2.10

Author:

Hidekatsu Izuno

See Also:

RFC 4627, the Apache License, Version 2.0

Nested Class Summary

class	JSON.Context
static class	JSON.Mode JSON processing mode

Field Summary

static Class<? extends JSON>

prototype Setup your custom class for using static method.

Constructor Summary

JSON()

JSON(int maxDepth)

JSON(JSON.Mode mode)

Method Summary

Object	convert(Object value, Type type)
protected <T> T	create(JSON.Context context, Class<? extends T> c)
static <T> T	decode(InputStream in) Decodes a json stream into a object.
static <T> T	decode(InputStream in, Class<? extends T> cls) Decodes a json stream into a object.
static <T> T	decode(InputStream in, Type type) Decodes a json stream into a object.
static <T> T	decode(Reader reader) Decodes a json stream into a object.
static <T> T	decode(Reader reader, Class<? extends T> cls) Decodes a json stream into a object.
static <T> T	decode(Reader reader, Type type) Decodes a json stream into a object.
static <T> T	decode(String source) Decodes a json string into a object.
static <T> T	decode(String source, Class<? extends T> cls) Decodes a json string into a typed object.
static <T> T	decode(String source, Type type) Decodes a json string into a typed object.
static String	encode(Object source) Encodes a object into a json string.
static void	encode(Object source, Appendable appendable) Encodes a object into a json string.
static void	encode(Object source, Appendable appendable, boolean prettyPrint) Encodes a object into a json string.
static String	encode(Object source, boolean prettyPrint) Encodes a object into a json string.
static void	encode(Object source, OutputStream out) Encodes a object into a json string.
static void	encode(Object source, OutputStream out, boolean prettyPrint) Encodes a object into a json string.
static String	escapeScript(Object source) Escapes a object into JavaScript format.
static void	escapeScript(Object source, Appendable appendable) Escapes a object into JavaScript format.
static void	escapeScript(Object source, OutputStream out) Escapes a object into JavaScript format.
String	format(Object source) Format a object into a json string.
Appendable	format(Object source, Appendable ap) Format a object into a json string.
OutputStream	format(Object source, OutputStream out) Format a object into a json string.
int	getMaxDepth() Gets maximum depth for the nest depth.
JSON.Mode	getMode() Gets JSON interpreter mode.
protected boolean	ignore(JSON.Context context, Class<?> target, Member member) Ignore this property.
protected String	normalize(String name)
<T> T	parse(CharSequence cs)
<T> T	parse(CharSequence s, Class<? extends T> cls)
<T> T	parse(CharSequence s, Type type)
<T> T	parse(InputStream in)
<T> T	parse(InputStream in, Class<? extends T> cls)
<T> T	parse(InputStream in, Type type)
<T> T	parse(Reader reader)
<T> T	parse(Reader reader, Class<? extends T> cls)
<T> T	parse(Reader reader, Type type)
protected <T> T	postparse(JSON.Context context, Object value, Class<? extends T> cls, Type type) Converts Map, List, Number, String, Boolean or null to other Java Objects after parsing.
protected Object	preformat(JSON.Context context, Object value) Converts Any Java Object to JSON recognizable Java object before format.
void	setContext(Object value) Sets context for inner class.
void	setDateFormat(String format) Sets default Date format.
void	setEnumStyle(NamingStyle style) Sets default Case style for Enum.
void	setLocale(Locale locale) Sets locale for formatting, converting and selecting message.
void	setMaxDepth(int value) Sets maximum depth for the nest depth.
void	setMode(JSON.Mode mode) Sets JSON interpreter mode.
void	setNumberFormat(String format) Sets default Number format.
void	setPrettyPrint(boolean value) Output json string is to human-readable format.
void	setPropertyStyle(NamingStyle style) Sets default Case style for the property name of JSON object.
void	setSuppressNull(boolean value) If this property is true, the member of null value in JSON object is ignored.
void	setTimeZone(TimeZone timeZone) Sets timeZone for formatting and converting.
static void	validate(CharSequence cs) Validates a json text
static void	validate(InputStream in) Validates a json stream
static void	validate(Reader reader) Validates a json stream

Methods inherited from class java.lang.Object

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

Field Detail

prototype

public static volatile Class<? extends JSON> prototype

Setup your custom class for using static method. default: net.arnx.jsonic.JSON

Constructor Detail

JSON

public JSON()

JSON

public JSON(int maxDepth)

JSON

public JSON(JSON.Mode mode)

Method Detail

encode

public static String encode(Object source)
                     throws JSONException

Encodes a object into a json string.

Parameters:

source - a object to encode.

Returns:

a json string

Throws:

JSONException - if error occurred when formating.

encode

public static String encode(Object source,
                            boolean prettyPrint)
                     throws JSONException

Encodes a object into a json string.

Parameters:

source - a object to encode.

prettyPrint - output a json string with indent, space or break.

Returns:

a json string

Throws:

JSONException - if error occurred when formating.

encode

public static void encode(Object source,
                          OutputStream out)
                   throws IOException,
                          JSONException

Encodes a object into a json string.

Parameters:

source - a object to encode.

out - a destination to output a json string.

Throws:

IOException - if I/O Error occurred.

JSONException - if error occurred when formating.

encode

public static void encode(Object source,
                          OutputStream out,
                          boolean prettyPrint)
                   throws IOException,
                          JSONException

Encodes a object into a json string.

Parameters:

source - a object to encode.

out - a destination to output a json string.

prettyPrint - output a json string with indent, space or break.

Throws:

IOException - if I/O Error occurred.

JSONException - if error occurred when formating.

encode

public static void encode(Object source,
                          Appendable appendable)
                   throws IOException,
                          JSONException

Encodes a object into a json string.

Parameters:

source - a object to encode.

appendable - a destination to output a json string.

Throws:

IOException - if I/O Error occurred.

JSONException - if error occurred when formating.

encode

public static void encode(Object source,
                          Appendable appendable,
                          boolean prettyPrint)
                   throws IOException,
                          JSONException

Encodes a object into a json string.

Parameters:

source - a object to encode.

appendable - a destination to output a json string.

prettyPrint - output a json string with indent, space or break.

Throws:

IOException - if I/O Error occurred.

JSONException - if error occurred when formating.

escapeScript

public static String escapeScript(Object source)
                           throws JSONException

Escapes a object into JavaScript format.

Parameters:

source - a object to encode.

Returns:

a escaped object

Throws:

JSONException - if error occurred when formating.

escapeScript

public static void escapeScript(Object source,
                                OutputStream out)
                         throws IOException,
                                JSONException

Escapes a object into JavaScript format.

Parameters:

source - a object to encode.

out - a destination to output a json string.

Throws:

IOException - if I/O Error occurred.

JSONException - if error occurred when formating.

escapeScript

public static void escapeScript(Object source,
                                Appendable appendable)
                         throws IOException,
                                JSONException

Escapes a object into JavaScript format.

Parameters:

source - a object to encode.

appendable - a destination to output a json string.

Throws:

IOException - if I/O Error occurred.

JSONException - if error occurred when formating.

decode

public static <T> T decode(String source)
                throws JSONException

Decodes a json string into a object.

Parameters:

source - a json string to decode

Returns:

a decoded object

Throws:

JSONException - if error occurred when parsing.

decode

public static <T> T decode(String source,
                           Class<? extends T> cls)
                throws JSONException

Decodes a json string into a typed object.

Parameters:

source - a json string to decode

cls - class for converting

Returns:

a decoded object

Throws:

JSONException - if error occurred when parsing.

decode

public static <T> T decode(String source,
                           Type type)
                throws JSONException

Decodes a json string into a typed object.

Parameters:

source - a json string to decode

type - type for converting

Returns:

a decoded object

Throws:

JSONException - if error occurred when parsing.

decode

public static <T> T decode(InputStream in)
                throws IOException,
                       JSONException

Decodes a json stream into a object. (character encoding should be Unicode)

Parameters:

in - a json stream to decode

Returns:

a decoded object

Throws:

IOException - if I/O error occurred.

JSONException - if error occurred when parsing.

decode

public static <T> T decode(InputStream in,
                           Class<? extends T> cls)
                throws IOException,
                       JSONException

Decodes a json stream into a object. (character encoding should be Unicode)

Parameters:

in - a json stream to decode

cls - class for converting

Returns:

a decoded object

Throws:

IOException - if I/O error occurred.

JSONException - if error occurred when parsing.

decode

public static <T> T decode(InputStream in,
                           Type type)
                throws IOException,
                       JSONException

Decodes a json stream into a object. (character encoding should be Unicode)

Parameters:

in - a json stream to decode

type - type for converting

Returns:

a decoded object

Throws:

IOException - if I/O error occurred.

JSONException - if error occurred when parsing.

decode

public static <T> T decode(Reader reader)
                throws IOException,
                       JSONException

Decodes a json stream into a object.

Parameters:

reader - a json stream to decode

Returns:

a decoded object

Throws:

IOException - if I/O error occurred.

JSONException - if error occurred when parsing.

decode

public static <T> T decode(Reader reader,
                           Class<? extends T> cls)
                throws IOException,
                       JSONException

Decodes a json stream into a object.

Parameters:

reader - a json stream to decode

cls - class for converting

Returns:

a decoded object

Throws:

IOException - if I/O error occurred.

JSONException - if error occurred when parsing.

decode

public static <T> T decode(Reader reader,
                           Type type)
                throws IOException,
                       JSONException

Decodes a json stream into a object.

Parameters:

reader - a json stream to decode

type - type for converting

Returns:

a decoded object

Throws:

IOException - if I/O error occurred.

JSONException - if error occurred when parsing.

validate

public static void validate(CharSequence cs)
                     throws JSONException

Validates a json text

Parameters:

cs - source a json string to decode

Throws:

JSONException - if error occurred when parsing.

validate

public static void validate(InputStream in)
                     throws IOException,
                            JSONException

Validates a json stream

Parameters:

in - source a json string to decode

Throws:

IOException - if I/O error occurred.

JSONException - if error occurred when parsing.

validate

public static void validate(Reader reader)
                     throws IOException,
                            JSONException

Validates a json stream

Parameters:

reader - source a json string to decode

Throws:

IOException - if I/O error occurred.

JSONException - if error occurred when parsing.

setContext

public void setContext(Object value)

Sets context for inner class.

Parameters:

value - context object

setLocale

public void setLocale(Locale locale)

Sets locale for formatting, converting and selecting message.

Parameters:

locale - locale for formatting, converting and selecting message

setTimeZone

public void setTimeZone(TimeZone timeZone)

Sets timeZone for formatting and converting.

Parameters:

timeZone - timeZone for formatting and converting.

setPrettyPrint

public void setPrettyPrint(boolean value)

Output json string is to human-readable format.

Parameters:

value - true to format human-readable, false to shorten.

setMaxDepth

public void setMaxDepth(int value)

Sets maximum depth for the nest depth. default value is 32.

Parameters:

value - maximum depth for the nest depth.

getMaxDepth

public int getMaxDepth()

Gets maximum depth for the nest depth.

Returns:

a maximum depth

setSuppressNull

public void setSuppressNull(boolean value)

If this property is true, the member of null value in JSON object is ignored. default value is false.

Parameters:

value - true to ignore the member of null value in JSON object.

setMode

public void setMode(JSON.Mode mode)

Sets JSON interpreter mode.

Parameters:

mode - JSON interpreter mode

getMode

public JSON.Mode getMode()

Gets JSON interpreter mode.

Returns:

JSON interpreter mode

setDateFormat

public void setDateFormat(String format)

Sets default Date format. When format is null, Date is formated to JSON number.

Parameters:

format - default Date format

setNumberFormat

public void setNumberFormat(String format)

Sets default Number format. When format is null, Number is formated to JSON number.

Parameters:

format - default Number format

setPropertyStyle

public void setPropertyStyle(NamingStyle style)

Sets default Case style for the property name of JSON object.

Parameters:

style - default Case style for keys of JSON object.

setEnumStyle

public void setEnumStyle(NamingStyle style)

Sets default Case style for Enum.

Parameters:

style - default Case style for Enum.

format

public String format(Object source)

Format a object into a json string.

Parameters:

source - a object to encode.

Returns:

a json string

format

public OutputStream format(Object source,
                           OutputStream out)
                    throws IOException

Format a object into a json string.

Parameters:

source - a object to encode.

out - a destination to output a json string.

Returns:

a reference to 'out' object in parameters

Throws:

IOException

format

public Appendable format(Object source,
                         Appendable ap)
                  throws IOException

Format a object into a json string.

Parameters:

source - a object to encode.

ap - a destination. example: StringBuilder, Writer, ...

Returns:

a json string

Throws:

IOException

preformat

protected Object preformat(JSON.Context context,
                           Object value)
                    throws Exception

Converts Any Java Object to JSON recognizable Java object before format.

Parameters:

context - current context.

value - source a object to format.

Returns:

null or the instance of Map, Iterator(or Array, Enumerator), Number, CharSequence or Boolean.

Throws:

Exception - if conversion failed.

parse

public <T> T parse(CharSequence cs)
        throws JSONException

Throws:

JSONException

parse

public <T> T parse(CharSequence s,
                   Class<? extends T> cls)
        throws JSONException

Throws:

JSONException

parse

public <T> T parse(CharSequence s,
                   Type type)
        throws JSONException

Throws:

JSONException

parse

public <T> T parse(InputStream in)
        throws IOException,
               JSONException

Throws:

IOException

JSONException

parse

public <T> T parse(InputStream in,
                   Class<? extends T> cls)
        throws IOException,
               JSONException

Throws:

IOException

JSONException

parse

public <T> T parse(InputStream in,
                   Type type)
        throws IOException,
               JSONException

Throws:

IOException

JSONException

parse

public <T> T parse(Reader reader)
        throws IOException,
               JSONException

Throws:

IOException

JSONException

parse

public <T> T parse(Reader reader,
                   Class<? extends T> cls)
        throws IOException,
               JSONException

Throws:

IOException

JSONException

parse

public <T> T parse(Reader reader,
                   Type type)
        throws IOException,
               JSONException

Throws:

IOException

JSONException

convert

public Object convert(Object value,
                      Type type)
               throws JSONException

Throws:

JSONException

postparse

protected <T> T postparse(JSON.Context context,
                          Object value,
                          Class<? extends T> cls,
                          Type type)
               throws Exception

Converts Map, List, Number, String, Boolean or null to other Java Objects after parsing.

Parameters:

context - current context.

value - null or the instance of Map, List, Number, String or Boolean.

cls - class for converting

type - generics type for converting. type equals to c if not generics.

Returns:

a converted object

Throws:

Exception - if conversion failed.

normalize

protected String normalize(String name)

ignore

protected boolean ignore(JSON.Context context,
                         Class<?> target,
                         Member member)

Ignore this property. A default behavior is to ignore transient or declaring method in java.lang.Object. You can override this method if you have to change default behavior.

Parameters:

context - current context

target - target class

member - target member

Returns:

true if this member must be ignored.

create

protected <T> T create(JSON.Context context,
                       Class<? extends T> c)
            throws Exception

Throws:

Exception