Package name.martingeisse.grumpyjson

Class JsonEngine

java.lang.Object
name.martingeisse.grumpyjson.StructuralJsonEngine
name.martingeisse.grumpyjson.JsonEngine
Direct Known Subclasses:
GsonBasedJsonEngine
public abstract class JsonEngine extends StructuralJsonEngine
This class is the main entry point into the JSON conversion system.

This class should be used in two phases, configuration phase and runtime phase. The transition between the two phases is called sealing the engine. Simply put, first call configuration methods only, then seal the engine, then call runtime methods only. The behavior of this class is undefined if this sequence is not adhered to, and this class is expected to throw an exception in such a case.

A new instance of this class has standard converters for convenience. More converters can be added using StructuralJsonEngine.registerDualConverter(name.martingeisse.grumpyjson.serialize.JsonSerializer), StructuralJsonEngine.registerSerializer(name.martingeisse.grumpyjson.serialize.JsonSerializer) and StructuralJsonEngine.registerDeserializer(name.martingeisse.grumpyjson.deserialize.JsonDeserializer). If the standard converters are not desired, you can call StructuralJsonEngine.getRegistries() / StructuralJsonEngine.getSerializerRegistry() / StructuralJsonEngine.getDeserializerRegistry() and then .clear() to remove all currently registered converters. Note that you can override standard converters just by adding your own ones, since later-added converters will take precedence.

This class is abstract because it delegates handling the actual JSON syntax to a JSON library such as Gson or Jackson. Concrete implementations implement the glue code for the various JSON libraries.

  • Constructor Details

    • JsonEngine

      public JsonEngine()
      Creates a new JSON engine with standard converters registered.

  • Method Details

    • deserialize

      public abstract <T> T deserialize(String source, Class<T> clazz) throws JsonDeserializationException
      deserializes JSON from a String.
      Type Parameters:
      T - the static target type
      Parameters:
      source - the source string
      clazz - the target type to deserialize to
      Returns:
      the deserialized value
      Throws:
      JsonDeserializationException - if the JSON is malformed or does not match the target type

    • deserialize

      public abstract <T> T deserialize(String source, TypeToken<T> typeToken) throws JsonDeserializationException
      deserializes JSON from a String.
      Type Parameters:
      T - the static target type
      Parameters:
      source - the source string
      typeToken - a type token for the target type to deserialize to
      Returns:
      the deserialized value
      Throws:
      JsonDeserializationException - if the JSON is malformed or does not match the target type

    • deserialize

      public abstract Object deserialize(String source, Type type) throws JsonDeserializationException
      deserializes JSON from a String.
      Parameters:
      source - the source string
      type - the target type to deserialize to
      Returns:
      the deserialized value
      Throws:
      JsonDeserializationException - if the JSON is malformed or does not match the target type

    • deserialize

      public abstract <T> T deserialize(InputStream source, Class<T> clazz) throws JsonDeserializationException
      deserializes JSON from an InputStream. As demanded by the MIME type application/json, the input must be UTF-8 encoded.
      Type Parameters:
      T - the static target type
      Parameters:
      source - the source stream
      clazz - the target type to deserialize to
      Returns:
      the deserialized value
      Throws:
      JsonDeserializationException - if the JSON is malformed or does not match the target type

    • deserialize

      public abstract <T> T deserialize(InputStream source, TypeToken<T> typeToken) throws JsonDeserializationException
      deserializes JSON from an InputStream. As demanded by the MIME type application/json, the input must be UTF-8 encoded.
      Type Parameters:
      T - the static target type
      Parameters:
      source - the source stream
      typeToken - a type token for the target type to deserialize to
      Returns:
      the deserialized value
      Throws:
      JsonDeserializationException - if the JSON is malformed or does not match the target type

    • deserialize

      public abstract Object deserialize(InputStream source, Type type) throws JsonDeserializationException
      deserializes JSON from an InputStream. As demanded by the MIME type application/json, the input must be UTF-8 encoded.
      Parameters:
      source - the source stream
      type - the target type to deserialize to
      Returns:
      the deserialized value
      Throws:
      JsonDeserializationException - if the JSON is malformed or does not match the target type

    • deserialize

      public abstract <T> T deserialize(Reader source, Class<T> clazz) throws JsonDeserializationException
      deserializes JSON from an Reader.
      Type Parameters:
      T - the static target type
      Parameters:
      source - the source reader
      clazz - the target type to deserialize to
      Returns:
      the deserialized value
      Throws:
      JsonDeserializationException - if the JSON is malformed or does not match the target type

    • deserialize

      public abstract <T> T deserialize(Reader source, TypeToken<T> typeToken) throws JsonDeserializationException
      deserializes JSON from an Reader.
      Type Parameters:
      T - the static target type
      Parameters:
      source - the source reader
      typeToken - a type token for the target type to deserialize to
      Returns:
      the deserialized value
      Throws:
      JsonDeserializationException - if the JSON is malformed or does not match the target type

    • deserialize

      public abstract Object deserialize(Reader source, Type type) throws JsonDeserializationException
      deserializes JSON from an Reader.
      Parameters:
      source - the source reader
      type - the target type to deserialize to
      Returns:
      the deserialized value
      Throws:
      JsonDeserializationException - if the JSON is malformed or does not match the target type

    • serializeToString

      public abstract String serializeToString(Object value) throws JsonSerializationException
      Turns a value into a JSON string.
      Parameters:
      value - the value to serialize
      Returns:
      the JSON string
      Throws:
      JsonSerializationException - if the value is in an inconsistent state or a state that cannot be turned into JSON

    • writeTo

      public abstract void writeTo(Object value, OutputStream destination) throws JsonSerializationException
      Turns a value into JSON that is written to an output stream. As demanded by the MIME type application/json, the output will be UTF-8 encoded.
      Parameters:
      value - the value to convert
      destination - the stream to write to
      Throws:
      JsonSerializationException - if the value is in an inconsistent state or a state that cannot be turned into JSON

    • writeTo

      public abstract void writeTo(Object value, Writer destination) throws JsonSerializationException
      Turns a value into JSON that is written to a writer.
      Parameters:
      value - the value to convert
      destination - the writer to write to
      Throws:
      JsonSerializationException - if the value is in an inconsistent state or a state that cannot be turned into JSON