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[]).

JSON facade also provides methods for (de)serialization with inband type information, see stringifyObject(Writer, Object) and parseObject(Reader). This is an extension to JSON protocol that include class property before the actual object JSON stream.

A JSON stream with inbad type information may look like below. Please note class property from JSON start.

  {"class":"js.net.Event","id":1234 ... }
 

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.
<T> T	parseObject(Reader reader) Deserialize JSON encoded object with inband type information.
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.
void	stringifyObject(Writer writer, Object value) Serialize object instance with inband type information.

Method Detail

stringify

void stringify(Writer writer,
               Object value)
        throws 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:

IOException - if IO write operation fails.

parse

<T> T parse(Reader reader,
            Type type)
     throws 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:

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 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:

IOException - if IO read operation fails.

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

stringifyObject

void stringifyObject(Writer writer,
                     Object value)
              throws IOException

Serialize object instance with inband type information. An object serialized with this method must be parsed by parseObject(Reader) companion method. After serialization completes writer is flushed but left unclosed.

Implementation note: this method uses a proprietary extension to JSON protocol.

Parameters:

writer - characters stream writer,

value - object instance to serialize.

Throws:

IOException - if write operation fails.

parseObject

<T> T parseObject(Reader reader)
           throws IOException,
                  JsonException,
                  ClassCastException

Deserialize JSON encoded object with inband type information. This method expect a stream generated by stringifyObject(Writer, Object) companion method. After parsing completion used reader remains opened.

Implementation note: this method uses a proprietary extension to JSON protocol.

Type Parameters:

T - object type.

Parameters:

reader - characters stream reader.

Returns:

initialized instance auto-cast to expected parameterized type T.

Throws:

IOException - if read operation fails.

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

ClassCastException - if inband type cannot be cast to expected parameterized type T.

stringify

String stringify(Object value)

Handy method for value object serialization to JSON formatted string.

Parameters:

value - primitive or aggregate value.

Returns:

value JSON string representation.

parse

<T> T parse(String value,
            Type type)
     throws 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,

type - desired value type.

Returns:

newly created instance.

Throws:

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