com.holonplatform.json

## Interface Json

- All Known Subinterfaces:
    GsonJson, JacksonJson
  All Known Implementing Classes:
    DefaultGsonJson, DefaultJacksonJson

      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

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    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 `JsonProvider`s 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 `JsonProvider`s 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 `JsonProvider`s 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 `PropertyBox`s (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 `PropertyBox`s (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 `PropertyBox`s (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 `PropertyBox`s (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 `JsonProvider`s 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 `JsonProvider`s 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 `JsonProvider`s and using the one with higher priority.
      Parameters:
        `classLoader` - ClassLoader to use
      Returns:
        The `Json` implementation, if available

Copyright © 2019 The Holon Platform. All rights reserved.