js.json

Interface Json

public interface Json

Facade for JSON parser and serializer. This facade supplies methods to stringify(Writer, Object) and parse(Reader, Type) values to and from JSON character streams. There are also convenient methods for values to JSON strings conversion, see stringify(Object) and parse(String, Type).

Parsing of not homogeneous arrays is supported but caller should supplies the type of every array item, see parse(Reader, Type[]).

Version:

final

Author:

Iulian Rotaru

Method Summary

Modifier and Type	Method and Description
<T> T	parse(Reader reader, Type type) Deserialize value of expected type.
Object[]	parse(Reader reader, Type[] types) Deserialize array of mixed types.
<T> T	parse(String value, Type type) Parse JSON encoded value and return instance of requested type.
String	stringify(Object value) Handy method for value object serialization to JSON formatted string.
void	stringify(Writer writer, Object value) Serialize value to JSON character stream and left it unclosed.

Method Detail

stringify

void stringify(Writer writer,
               Object value)
        throws IllegalArgumentException,
               IOException

Serialize value to JSON character stream and left it unclosed. Both primitive and aggregated values are allowed. If value is not primitive all fields are scanned reflectively, less static, transient and synthetic. If a field is aggregated on its turn traverse its fields too. This allows for not restricted fields graph. Note that there is no guarantee regarding fields order inside parent object.

If value argument is null serialize JSON null keyword.

After serialization completes writer is flushed but left unclosed.

Parameters:

writer - character stream to write value on,

value - value to serialize, null accepted.

Throws:

IllegalArgumentException - if writer argument is null.

IOException - if IO write operation fails.

parse

<T> T parse(Reader reader,
            Type type)
     throws IllegalArgumentException,
            IOException,
            JsonException,
            ClassCastException

Deserialize value of expected type. After parsing completion used reader remains opened.

This method uses auto cast in order to simplify user code but is caller responsibility to ensure requested type is cast compatible with type of variable to assign to.

This JSON parser method is relaxed and follows a best effort approach. If a named property from JSON stream does not have the same name field into target object, parser just warn on log and ignore. Also, fields from target object with no values into JSON stream are set to null.

Type Parameters:

T - type to auto cast on return, cast compatible with type argument.

Parameters:

reader - character stream to read from,

type - expected type.

Returns:

instance of expected type initialized from JSON character stream.

Throws:

IllegalArgumentException - if reader or type argument is null.

IOException - if read operation fails.

JsonException - if parsing process fails perhaps due to syntax violation on input.

ClassCastException - if given type cannot cast to expected type variable T.

parse

Object[] parse(Reader reader,
               Type[] types)
        throws IllegalArgumentException,
               IOException,
               JsonException

Deserialize array of mixed types. This method is able to parse not homogeneous arrays; if in need for homogeneous array one could use parse(Reader, Type) with type set to desired array class. Every object from JSON stream array must have the type defined by types parameter. It is caller responsibility to ensure that JSON stream array types number and order match requested types. Return empty object array if types is empty.

This method uses the same best effort approach as parse(Reader, Type). Note that after parsing completion used reader remains opened.

Parameters:

reader - character stream to read from,

types - expected types, empty array accepted.

Returns:

newly created and initialized array, possible empty.

Throws:

IllegalArgumentException - if reader or types argument is null.

IOException - if IO read operation fails.

JsonException - if parsing process fails perhaps due to syntax violation on input.

stringify

String stringify(Object value)

Handy method for value object serialization to JSON formatted string.

Parameters:

value - primitive or aggregate value, null accepted.

Returns:

value JSON string representation.

parse

<T> T parse(String value,
            Type type)
     throws IllegalArgumentException,
            JsonException

Parse JSON encoded value and return instance of requested type. This method creates an instance of type and initialize its fields from JSON string. It uses auto cast in order to simplify user code but is caller responsibility to ensure requested type is cast compatible with type of variable to assign to.

This method uses the same best effort approach as parse(Reader, Type).

Type Parameters:

T - type to auto cast on return, cast compatible with type argument.

Parameters:

value - JSON encode value, null accepted,

type - desired value type.

Returns:

newly created instance or null if value argument is null.

Throws:

IllegalArgumentException - if type argument is null.

JsonException - if given string value is not valid JSON format.