Package de.iip_ecosphere.platform.support.json

Class Json

java.lang.Object
de.iip_ecosphere.platform.support.json.Json
public abstract class Json extends Object
Json interface. Requires an implementing plugin of type Json or an active JsonProviderDescriptor.
Author:
Holger Eichelberger, SSE

  • Field Details

    • prototype

      private static Json prototype

  • Constructor Details

    • Json

      public Json()

  • Method Details

    • createInstance

      public static Json createInstance()
      Creates a configurable instance.
      Returns:
      the Json instance

    • setPrototype

      public static void setPrototype(Json json)
      Manually sets the instance. Shall not be needed, but may be required in some tests.
      Parameters:
      json - the Json instance

    • createInstanceImpl

      protected abstract Json createInstanceImpl()
      Creates the actual instance.
      Returns:
      the instance

    • toJson

      public abstract String toJson(Object obj) throws IOException
      Turns an object to JSON.
      Parameters:
      obj - the object (may be null), must have getters/setters for all attributes and a no-arg constructor no-arg constructor
      Returns:
      the JSON string or an empty string in case of problems/no address
      Throws:
      IOException
      See Also:

    • fromJson

      public abstract <R> R fromJson(Object json, Class<R> cls) throws IOException
      Reads an Object from a JSON string.
      Type Parameters:
      R - the object type, must have getters/setters for all attributes and a no-arg constructor
      Parameters:
      json - the JSON value (usually a String)
      cls - the class of the type to read
      Returns:
      the object or null if reading fails
      Throws:
      IOException
      See Also:

    • listFromJson

      public abstract <R> List<R> listFromJson(Object json, Class<R> cls)
      Reads a typed List from a JSON string.
      Type Parameters:
      R - the entity type
      Parameters:
      json - the JSON value (usually a String)
      cls - the class of the entity type to read
      Returns:
      the list or null if reading fails
      See Also:

    • mapFromJson

      public abstract <K, V> Map<K,V> mapFromJson(Object json, Class<K> keyCls, Class<K> valueCls)
      Reads a typed Map from a JSON string.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      json - the JSON value (usually a String)
      keyCls - the class of the key type to read
      valueCls - the class of the value type to read
      Returns:
      the map or null if reading fails
      See Also:

    • readValue

      public abstract <T> T readValue(String src, Class<T> cls) throws IOException
      Reads a value from a string.
      Type Parameters:
      T - the result type
      Parameters:
      src - the value as string
      cls - the value type
      Throws:
      IOException - if reading fails

    • readValue

      public abstract <T> T readValue(byte[] src, Class<T> cls) throws IOException
      Reads a value from a byte array.
      Type Parameters:
      T - the result type
      Parameters:
      src - the value as byte array
      cls - the value type
      Throws:
      IOException - if reading fails

    • writeValueAsBytes

      public abstract byte[] writeValueAsBytes(Object value) throws IOException
      Writes a given values into a byte array representation.
      Parameters:
      value - the value to write
      Returns:
      the byte array representation
      Throws:
      IOException - if writing fails

    • convertValue

      public abstract <T> T convertValue(Object value, Class<T> cls) throws IllegalArgumentException
      Convenience method for doing two-step conversion from given value, into instance of given value type, by writing value into temporary buffer and reading from the buffer into specified target type.
      Parameters:
      value - the value to convert
      cls - the target type
      Throws:
      IllegalArgumentException - If conversion fails due to incompatible type; if so, root cause will contain underlying checked exception data binding functionality threw

    • toJsonDflt

      public static String toJsonDflt(Object obj) throws IOException
      Turns an object to JSON on the default instance.
      Parameters:
      obj - the object (may be null), must have getters/setters for all attributes and a no-arg constructor no-arg constructor
      Returns:
      the JSON string or an empty string in case of problems/no address
      Throws:
      IOException
      See Also:

    • fromJsonDflt

      public static <R> R fromJsonDflt(Object json, Class<R> cls) throws IOException
      Reads an Object from a JSON string on the default instance.
      Type Parameters:
      R - the object type, must have getters/setters for all attributes and a no-arg constructor
      Parameters:
      json - the JSON value (usually a String)
      cls - the class of the type to read
      Returns:
      the object or null if reading fails
      Throws:
      IOException
      See Also:

    • listFromJsonDflt

      public static <R> List<R> listFromJsonDflt(Object json, Class<R> cls)
      Reads a typed List from a JSON string.
      Type Parameters:
      R - the entity type
      Parameters:
      json - the JSON value (usually a String)
      cls - the class of the entity type to read
      Returns:
      the list or null if reading fails
      See Also:

    • mapFromJsonDflt

      public static <K, V> Map<K,V> mapFromJsonDflt(Object json, Class<K> keyCls, Class<K> valueCls)
      Reads a typed Map from a JSON string.
      Type Parameters:
      K - the key type
      V - the value type
      Parameters:
      json - the JSON value (usually a String)
      keyCls - the class of the key type to read
      valueCls - the class of the value type to read
      Returns:
      the map or null if reading fails
      See Also:

    • configureFor

      public abstract Json configureFor(Class<?> cls)
      Configures this instance for cls by considering the annotations in cls.
      Parameters:
      cls - the class
      Returns:
      this for chaining

    • handleIipDataClasses

      public abstract Json handleIipDataClasses()
      Configures this instance for IIP conventions.
      Returns:
      this for chaining

    • defineOptionals

      public abstract Json defineOptionals(Class<?> cls, String... fieldNames)
      Configures this instance for the given fieldNames as optional during deserialization.
      Parameters:
      cls - the cls the class fieldNames are member of
      fieldNames - the field names (names of Java fields)
      Returns:
      this for chaining

    • defineFields

      public abstract Json defineFields(String... fieldNames)
      Configures this instance so that Java field names map exactly to the given names.
      Parameters:
      fieldNames - the field names (names of JSON/Java fields)
      Returns:
      this for chaining

    • exceptFields

      public abstract Json exceptFields(String... fieldNames)
      Configures this instance so that it excludes the fieldNames to be excluded.
      Parameters:
      fieldNames - the field names
      Returns:
      this for chaining

    • filterAllExceptFields

      public abstract Json filterAllExceptFields(String... fieldNames)
      Configures this instance to filter to all given field names.
      Parameters:
      fieldNames - the field names that shall be excluded
      Returns:
      this for chaining

    • failOnUnknownProperties

      public abstract Json failOnUnknownProperties(boolean fail)
      Configures this instance to fail/fail not on unknown fields/properties.
      Parameters:
      fail - to fail or not to fail
      Returns:
      this for chaining

    • createEnumMapping

      public <T> Json.EnumMapping<T> createEnumMapping(Class<T> type)
      Creates a mapping specification, with no mapping, for incremental creation.
      Parameters:
      type - the type to map

    • createEnumMapping

      public abstract <T> Json.EnumMapping<T> createEnumMapping(Class<T> type, Map<String,T> mapping)
      Creates a mapping specification, with mapping.
      Parameters:
      type - the type to map
      mapping - the mapping of values

    • declareEnums

      public abstract Json declareEnums(Json.EnumMapping<?>... mappings)
      Declares enums and their mappings.
      Parameters:
      mappings - the mappings
      Returns:
      this for chaining

    • configureLazy

      public abstract Json configureLazy(Set<Object> ignore)
      Configures this instance for lazy serialization ignoring given classes and members.
      Parameters:
      ignore - , classes (also as return types) and (reflection) fields that shall be ignored
      Returns:
      this for chaining

    • createIterator

      public abstract <T> IOIterator<T> createIterator(InputStream stream, Class<T> cls) throws IOException
      Creates an iterator over the information in stream assuming a heterogeneous collection of cls.
      Type Parameters:
      T - the element type
      Parameters:
      stream - the input stream to read
      cls - the element type
      Returns:
      an iterator over the element types
      Throws:
      IOException - if accessing the stream fails

    • createObject

      public static JsonObject createObject(String string) throws IOException
      Creates a JSON object for individual access from string.
      Parameters:
      string - the string
      Returns:
      the JSON object
      Throws:
      IOException - if the object cannot be read/constructed
      See Also:

    • createObject

      public static JsonObject createObject(Reader reader) throws IOException
      Creates a JSON object for individual access from reader.
      Parameters:
      reader - the reader
      Returns:
      the JSON object
      Throws:
      IOException - if the object cannot be read/constructed

    • createObjectImpl

      protected abstract JsonObject createObjectImpl(Reader reader) throws IOException
      Creates a JSON object for individual access from reader.
      Parameters:
      reader - the reader
      Returns:
      the JSON object
      Throws:
      IOException - if the object cannot be read/constructed

    • createObjectBuilder

      public static JsonObjectBuilder createObjectBuilder()
      Creates a JSON object builder.
      Returns:
      the JSON object builder

    • createObjectBuilderImpl

      protected abstract JsonObjectBuilder createObjectBuilderImpl()
      Creates a JSON object builder.
      Returns:
      the JSON object builder

    • createArrayBuilder

      public static JsonArrayBuilder createArrayBuilder()
      Creates a JSON array builder.
      Returns:
      the JSON array builder

    • createArrayBuilderImpl

      protected abstract JsonArrayBuilder createArrayBuilderImpl()
      Creates a JSON array builder.
      Returns:
      the JSON array builder

    • parseImpl

      protected abstract JsonIterator parseImpl(String text)
      Parses text into an interatively parsable structure.
      Parameters:
      text - the JSON text to parse
      Returns:
      the iterator, may indicate invalid data

    • parseImpl

      protected abstract JsonIterator parseImpl(byte[] data)
      Parses data into an interatively parsable structure.
      Parameters:
      data - the JSON data to parse
      Returns:
      the iterator, may indicate invalid data

    • parse

      public static JsonIterator parse(String text)
      Parses text into an interatively parsable structure.
      Parameters:
      text - the JSON text to parse
      Returns:
      the iterator, may indicate invalid data

    • parse

      public static JsonIterator parse(byte[] data)
      Parses data into an interatively parsable structure.
      Parameters:
      data - the JSON data to parse
      Returns:
      the iterator, may indicate invalid data