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. The default instances, e.g., for toJsonDflt(Object) does not necessarily consider annotations. For annotations, please create a configured instance, e.g., via createInstance(Class) or createInstance4All().
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, no annotations are considered by default.
      Returns:
      the Json instance

    • createInstance4All

      public static Json createInstance4All()
      Creates a configurable instance, all annotations are considered by default.
      Returns:
      the Json instance

    • createInstance

      public static Json createInstance(Class<?> cls)
      Creates a pre-configured configurable instance by applying configureFor(Class) so that usual annotations are considered.
      Parameters:
      cls - the class to configure for
      Returns:
      the Json instance

    • createInstance

      public static Json createInstance(Class<?>... cls)
      Creates a pre-configured configurable instance by applying configureFor(Class) so that usual annotations are considered.
      Parameters:
      cls - the classes to configure for
      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(boolean considerAnnotations)
      Creates the actual instance.
      Parameters:
      considerAnnotations - whether annotations shall be considered automatically
      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 - in case of serious issues
      See Also:

    • toJsonQuiet

      public String toJsonQuiet(Object obj)
      Turns an object to JSON without throwing exceptions.
      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

    • 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<V> 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

    • readValueDflt

      public static <T> T readValueDflt(String src, Class<T> cls) throws IOException
      Reads a value from a string using the default instance.
      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

    • readValueDflt

      public static <T> T readValueDflt(byte[] src, Class<T> cls) throws IOException
      Reads a value from a byte array using the default instance.
      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

    • writeValueAsString

      public abstract String writeValueAsString(Object value) throws IOException
      Writes a given values into a string representation.
      Parameters:
      value - the value to write
      Returns:
      the string 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<V> 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:

    • writeValueAsBytesDflt

      public static byte[] writeValueAsBytesDflt(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

    • writeValueAsStringDflt

      public static String writeValueAsStringDflt(Object value) throws IOException
      Writes a given values into a string representation.
      Parameters:
      value - the value to write
      Returns:
      the string representation
      Throws:
      IOException - if writing fails

    • 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

    • configureExceptFieldsFilter

      public abstract Json configureExceptFieldsFilter(String filterId, String... fieldNames)
      Enables a filter for the given id (as declared by Filter) that excepts the given fields. Combination of annotation and configured filter in case that excepts cannot be setup directly on classes or the class object is not available/accessible for some reason. Similar to filterAllExceptFields(String...), which is applied to all classes to be serialized.
      Parameters:
      filterId - the filter id
      fieldNames - the fields to except
      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.
      Type Parameters:
      T - the (enum) type
      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.
      Type Parameters:
      T - the (enum) type
      Parameters:
      type - the type to map
      mapping - the mapping of values

    • createEnumValueMapping

      public <T extends Enum<T>> Json.EnumMapping<T> createEnumValueMapping(Class<T> type)
      Creates a mapping specification based on createEnumValueMap(Class).
      Type Parameters:
      T - the enum type
      Parameters:
      type - the enum to map

    • declareEnums

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

    • createEnumValueMap

      public static <T extends Enum<T>> Map<String,T> createEnumValueMap(Class<? extends T> enm)
      Creates a default value mapping for the given enum.
      Type Parameters:
      T - the enum type
      Parameters:
      enm - the enum to map/take values from
      Returns:
      the name-value map for enum

    • 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(byte[] data) throws IOException
      Creates a JSON object for individual access from the byte array data.
      Parameters:
      data - the byte array
      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

    • createGeneratorImpl

      protected abstract JsonGenerator createGeneratorImpl(Writer writer) throws IOException
      Creates a generator instance for writer.
      Parameters:
      writer - the writer
      Returns:
      the generator
      Throws:
      IOException - if the generator cannot be created

    • createGenerator

      public static JsonGenerator createGenerator(Writer writer) throws IOException
      Creates a generator instance for writer.
      Parameters:
      writer - the writer
      Returns:
      the generator
      Throws:
      IOException - if the generator cannot be created