com.holonplatform.json

Interface Json

All Known Subinterfaces:

GsonJson, JacksonJson

public interface Json

A simple API to serialize and deserialize Objects to and from JSON.

Any object supported by the concrete JSON parser implementation can be serialized and deserialized.

A set of methods are specifically provided to deal with collections in a simple way, serializing and deserializing to and from a JSON array. See for example toJsonArray(Class, Collection) or fromJsonArray(JsonReader, Class).

The JsonWriter interface is used to provide the JSON serialization result, allowing to obtain the JSON data in a number of ways, for example as a String, as a byte array or writing it into a provided writer.

At the opposite, the JsonReader interface is used to represent the JSON data source which has to be deserialized into a Java object, and provides a number of static builder methods to obtain the JSON data from different sources, for example a String, an array of bytes or an InputStream.

This API makes available a specific set of convenience methods to directly support the Holon platform PropertyBox data class. A PropertyBox is serialized as a generic JSON object, using the property names as the object attribute names. Any VirtualProperty is ignored by default. In the deserialization phase, it is necessary to provide the Property set to use to create a PropertyBox instance form a JSON object. For this reason, methods like fromJson(JsonReader, Iterable) allow to provide a Property set for PropertyBox deserialization.

The JsonProvider interface can be used to provide a Json API implementation using the default Java service extension feature. The default Json API implementation can be obtained using tge get() or require() methods. See JsonProvider JavaDocs and methods documentation for further information.

The Holon platform JSON module provides two standard implementations of this API by default: one based on the Jackson library and one based on the Gson library. See the Holon platform documentation for details.

Since:

5.1.0

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Json.JsonException Base Json exception class.
static class	Json.JsonReadException Exception thrown for JSON deserialization errors.
static class	Json.JsonWriteException Exception thrown for JSON serialization errors.

Field Summary

Fields

Modifier and Type	Field and Description
static String	CONTEXT_KEY Default Context resource reference

Method Summary

Modifier and Type	Method and Description
<T> T	fromJson(JsonReader reader, Class<T> type) Deserializes the specified JSON source into an object of the specified type.
<P extends com.holonplatform.core.property.Property> com.holonplatform.core.property.PropertyBox	fromJson(JsonReader reader, Iterable<P> propertySet) Deserializes the specified JSON data source into a PropertyBox, using given propertySet as PropertyBox property set.
default com.holonplatform.core.property.PropertyBox	fromJson(JsonReader reader, com.holonplatform.core.property.Property... propertySet) Deserializes the specified JSON data source into a PropertyBox, using given propertySet as PropertyBox property set.
default <T> T	fromJson(String json, Class<T> type) Deserializes the specified JSON string into an object of the specified type.
default <P extends com.holonplatform.core.property.Property> com.holonplatform.core.property.PropertyBox	fromJson(String json, Iterable<P> propertySet) Deserializes the specified JSON string into a PropertyBox, using given propertySet as PropertyBox property set.
default com.holonplatform.core.property.PropertyBox	fromJson(String json, com.holonplatform.core.property.Property... propertySet) Deserializes the specified JSON string into a PropertyBox, using given propertySet as PropertyBox property set.
<T> List<T>	fromJsonArray(JsonReader reader, Class<T> type) Deserializes the specified JSON array data source into a List of objects of the specified type.
<P extends com.holonplatform.core.property.Property> List<com.holonplatform.core.property.PropertyBox>	fromJsonArray(JsonReader reader, Iterable<P> propertySet) Deserializes the specified JSON array data source into a list of PropertyBox, using given propertySet as PropertyBox property set.
default List<com.holonplatform.core.property.PropertyBox>	fromJsonArray(JsonReader reader, com.holonplatform.core.property.Property... propertySet) Deserializes the specified JSON array data source into a list of PropertyBox, using given propertySet as PropertyBox property set.
default <T> List<T>	fromJsonArray(String json, Class<T> type) Deserializes the specified JSON array string into a List of objects of the specified type.
default <P extends com.holonplatform.core.property.Property> List<com.holonplatform.core.property.PropertyBox>	fromJsonArray(String json, Iterable<P> propertySet) Deserializes the specified JSON array string into a list of PropertyBox, using given propertySet as PropertyBox property set.
default List<com.holonplatform.core.property.PropertyBox>	fromJsonArray(String json, com.holonplatform.core.property.Property... propertySet) Deserializes the specified JSON array string into a list of PropertyBox, using given propertySet as PropertyBox property set.
static Optional<Json>	get() Try to obtain a Json implementation, either from Context, if available using CONTEXT_KEY, or relying on registered JsonProviders and using the one with higher priority.
static Optional<Json>	get(ClassLoader classLoader) Try to obtain a Json implementation using given Classloader, either from Context, if available using CONTEXT_KEY, or relying on registered JsonProviders and using the one with higher priority.
static Json	require() Requires a Json implementation, either from Context, if available using CONTEXT_KEY, or relying on registered JsonProviders and using the one with higher priority.
JsonWriter	toJson(Object value) Serialize given value to JSON.
<T> JsonWriter	toJsonArray(Class<T> type, Collection<T> values) Serialize given collection of values as a JSON array.
default <T> JsonWriter	toJsonArray(Class<T> type, T... values) Serialize given array of values as a JSON array.
default <T> String	toJsonArrayString(Class<T> type, Collection<T> values) Serialize given collection of values as a JSON array string.
default <T> String	toJsonArrayString(Class<T> type, T... values) Serialize given array of values as a JSON array string.
default String	toJsonString(Object value) Serialize given value to a JSON string.

Field Detail

CONTEXT_KEY

static final String CONTEXT_KEY

Default Context resource reference

Method Detail

toJson

JsonWriter toJson(Object value)

Serialize given value to JSON.

Parameters:

value - Value to serialize

Returns:

a JsonWriter from which to obtain the serialized JSON data.

toJsonString

default String toJsonString(Object value)

Serialize given value to a JSON string.

Parameters:

value - Value to serialize

Returns:

the JSON representation of the value as a String, null if given value was null

Throws:

Json.JsonWriteException - If a JSON serialization error occured

toJsonArray

<T> JsonWriter toJsonArray(Class<T> type,
                           Collection<T> values)

Serialize given collection of values as a JSON array.

Type Parameters:

T - Values type

Parameters:

type - Value type

values - Values collection

Returns:

a JsonWriter from which to obtain the serialized JSON data.

toJsonArray

default <T> JsonWriter toJsonArray(Class<T> type,
                                   T... values)

Serialize given array of values as a JSON array.

Type Parameters:

T - Values type

Parameters:

type - Value type

values - Values to serialize

Returns:

a JsonWriter from which to obtain the serialized JSON data.

toJsonArrayString

default <T> String toJsonArrayString(Class<T> type,
                                     Collection<T> values)

Serialize given collection of values as a JSON array string.

Type Parameters:

T - Values type

Parameters:

type - Value type

values - Values to serialize

Returns:

the JSON array as a String

Throws:

Json.JsonWriteException - If a JSON serialization error occured

toJsonArrayString

default <T> String toJsonArrayString(Class<T> type,
                                     T... values)

Serialize given array of values as a JSON array string.

Type Parameters:

T - Values type

Parameters:

type - Value type

values - Values to serialize

Returns:

the JSON array as a String

Throws:

Json.JsonWriteException - If a JSON serialization error occured

fromJson

<T> T fromJson(JsonReader reader,
               Class<T> type)

Deserializes the specified JSON source into an object of the specified type.

Type Parameters:

T - desired object type

Parameters:

reader - JSON data source (not null)

type - the type of the desired object (not null)

Returns:

the deserialized object instance

Throws:

Json.JsonReadException - If a JSON deserialization error occured

fromJson

default <T> T fromJson(String json,
                       Class<T> type)

Deserializes the specified JSON string into an object of the specified type.

Type Parameters:

T - desired object type

Parameters:

json - JSON string

type - the type of the desired object (not null)

Returns:

the deserialized object instance

Throws:

Json.JsonReadException - If a JSON deserialization error occured

fromJsonArray

<T> List<T> fromJsonArray(JsonReader reader,
                          Class<T> type)

Deserializes the specified JSON array data source into a List of objects of the specified type.

Type Parameters:

T - desired object type

Parameters:

reader - JSON data source (not null)

type - the type of the desired objects (not null)

Returns:

the deserialized objects list

Throws:

Json.JsonReadException - If a JSON deserialization error occured

fromJsonArray

default <T> List<T> fromJsonArray(String json,
                                  Class<T> type)

Deserializes the specified JSON array string into a List of objects of the specified type.

Type Parameters:

T - desired object type

Parameters:

json - JSON array string

type - the type of the desired objects (not null)

Returns:

the deserialized objects list

Throws:

Json.JsonReadException - If a JSON deserialization error occured

fromJson

<P extends com.holonplatform.core.property.Property> com.holonplatform.core.property.PropertyBox fromJson(JsonReader reader,
                                                                                                          Iterable<P> propertySet)

Deserializes the specified JSON data source into a PropertyBox, using given propertySet as PropertyBox property set.

Type Parameters:

P - Actual property type

Parameters:

reader - JSON data source (not null)

propertySet - Property set to use to build the deserialized PropertyBox (not null)

Returns:

the deserialized PropertyBox

Throws:

Json.JsonReadException - If a JSON deserialization error occured

fromJson

default com.holonplatform.core.property.PropertyBox fromJson(JsonReader reader,
                                                             com.holonplatform.core.property.Property... propertySet)

Deserializes the specified JSON data source into a PropertyBox, using given propertySet as PropertyBox property set.

Parameters:

reader - JSON data source (not null)

propertySet - Property set to use to build the deserialized PropertyBox (not null)

Returns:

the deserialized PropertyBox

Throws:

Json.JsonReadException - If a JSON deserialization error occured

fromJson

default <P extends com.holonplatform.core.property.Property> com.holonplatform.core.property.PropertyBox fromJson(String json,
                                                                                                                  Iterable<P> propertySet)

Deserializes the specified JSON string into a PropertyBox, using given propertySet as PropertyBox property set.

Type Parameters:

P - Actual property type

Parameters:

json - JSON string

propertySet - Property set to use to build the deserialized PropertyBox (not null)

Returns:

the deserialized PropertyBox

Throws:

Json.JsonReadException - If a JSON deserialization error occured

fromJson

default com.holonplatform.core.property.PropertyBox fromJson(String json,
                                                             com.holonplatform.core.property.Property... propertySet)

Deserializes the specified JSON string into a PropertyBox, using given propertySet as PropertyBox property set.

Parameters:

json - JSON string

propertySet - Property set to use to build the deserialized PropertyBox (not null)

Returns:

the deserialized PropertyBox

Throws:

Json.JsonReadException - If a JSON deserialization error occured

fromJsonArray

<P extends com.holonplatform.core.property.Property> List<com.holonplatform.core.property.PropertyBox> fromJsonArray(JsonReader reader,
                                                                                                                     Iterable<P> propertySet)

Deserializes the specified JSON array data source into a list of PropertyBox, using given propertySet as PropertyBox property set.

Type Parameters:

P - Actual property type

Parameters:

reader - JSON data source (not null)

propertySet - Property set to use to build the deserialized PropertyBoxs (not null)

Returns:

the deserialized List of PropertyBox

Throws:

Json.JsonReadException - If a JSON deserialization error occured

fromJsonArray

default List<com.holonplatform.core.property.PropertyBox> fromJsonArray(JsonReader reader,
                                                                        com.holonplatform.core.property.Property... propertySet)

Deserializes the specified JSON array data source into a list of PropertyBox, using given propertySet as PropertyBox property set.

Parameters:

reader - JSON data source (not null)

propertySet - Property set to use to build the deserialized PropertyBoxs (not null)

Returns:

the deserialized List of PropertyBox

Throws:

Json.JsonReadException - If a JSON deserialization error occured

fromJsonArray

default <P extends com.holonplatform.core.property.Property> List<com.holonplatform.core.property.PropertyBox> fromJsonArray(String json,
                                                                                                                             Iterable<P> propertySet)

Deserializes the specified JSON array string into a list of PropertyBox, using given propertySet as PropertyBox property set.

Type Parameters:

P - Actual property type

Parameters:

json - JSON string

propertySet - Property set to use to build the deserialized PropertyBoxs (not null)

Returns:

the deserialized List of PropertyBox

Throws:

Json.JsonReadException - If a JSON deserialization error occured

fromJsonArray

default List<com.holonplatform.core.property.PropertyBox> fromJsonArray(String json,
                                                                        com.holonplatform.core.property.Property... propertySet)

Deserializes the specified JSON array string into a list of PropertyBox, using given propertySet as PropertyBox property set.

Parameters:

json - JSON string

propertySet - Property set to use to build the deserialized PropertyBoxs (not null)

Returns:

the deserialized List of PropertyBox

Throws:

Json.JsonReadException - If a JSON deserialization error occured

require

static Json require()

Requires a Json implementation, either from Context, if available using CONTEXT_KEY, or relying on registered JsonProviders and using the one with higher priority.

If not available using get(), an IllegalStateException is thrown.

Returns:

The Json implementation

Throws:

IllegalStateException - If a Json implementation is not available

get

static Optional<Json> get()

Try to obtain a Json implementation, either from Context, if available using CONTEXT_KEY, or relying on registered JsonProviders and using the one with higher priority.

Returns:

The Json implementation, if available

get

static Optional<Json> get(ClassLoader classLoader)

Try to obtain a Json implementation using given Classloader, either from Context, if available using CONTEXT_KEY, or relying on registered JsonProviders and using the one with higher priority.

Parameters:

classLoader - ClassLoader to use

Returns:

The Json implementation, if available