Class JsonUtils

java.lang.Object
io.fluxzero.common.serialization.JsonUtils
public class JsonUtils extends Object
Utility class for JSON serialization, deserialization, and file-based JSON resource loading.

JsonUtils wraps around Jackson's JsonMapper to provide enhanced handling of JSON processing. It supports dynamic type handling, tree merging, custom file loading with `@extends` inheritance, and robust conversion between types and structures.

Key Features

  • Configurable JsonMapper for serialization (writer) and deserialization (reader)
  • Convenience methods for reading from resource files, merging JSON trees, and converting between types
  • Support for deserializing JSON using a @class field containing fully qualified class or simple class name
  • Support for extending JSON files using a @extends field
  • Handles file and URI-based input

Example Usage

MyClass object = JsonUtils.fromFile("config.json", MyClass.class);
String json = JsonUtils.asJson(object);

Type Resolution via @class

When deserializing JSON using generic methods like fromFile(String) or fromJson(String) that don't specify a target type, a @class attribute is required in the JSON to indicate the target Java type. This type can be either:
  • A fully qualified class name (e.g. com.myapp.model.DepositMoney)
  • A short or partially qualified name (e.g. DepositMoney or myapp.DepositMoney)
When a short or partial name is used, it must be registered using @RegisterType so that it can be resolved via the TypeRegistry.

The Fluxzero Runtime uses this resolution mechanism internally to support extensibility and polymorphic message deserialization.

File Inheritance via @extends

JSON files can extend other JSON files using the @extends attribute. This allows the reuse of base configurations or data structures with overridden values in the extending file.

Example: 

// deposit-to-userA.json
{
  "@class": "DepositMoney",
  "amount": 23,
  "recipient": "userA"
}

// deposit-to-userB.json
{
  "@extends": "deposit-to-userA.json",
  "recipient": "userB"
}
When deposit-to-userB.json is loaded, it will inherit all fields from deposit-to-userA.json and override the recipient field with "userB".

The inheritance is recursive and is applied before deserialization.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static com.fasterxml.jackson.databind.json.JsonMapper
    reader
    Preconfigured JsonMapper for reading/deserializing objects from JSON, including type handling.
    static com.fasterxml.jackson.databind.json.JsonMapper
    writer
    Preconfigured JsonMapper for writing/serializing objects to JSON.

  • Constructor Summary

    Constructors
    Constructor
    Description
    JsonUtils()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static byte[]
    asBytes(Object object)
    Converts an object to a JSON byte array.
    static String
    asJson(Object object)
    Converts an object to a JSON string.
    static String
    asPrettyJson(Object object)
    Converts an object to a formatted JSON string.
    static <T> T
    convertValue(Object fromValue, com.fasterxml.jackson.core.type.TypeReference<T> typeRef)
    Converts an object to an object of the given type.
    static <T> T
    convertValue(Object fromValue, Class<? extends T> toValueType)
    Converts an object to an object of the given class.
    static <T> T
    convertValue(Object fromValue, Type toValueType)
    Converts an object to an object of the given type which may be a ParameterizedType or Class.
    static <T> T
    convertValue(Object fromValue, Function<com.fasterxml.jackson.databind.type.TypeFactory, com.fasterxml.jackson.databind.JavaType> typeFunction)
    Converts an object to an object of the given type.
    static com.fasterxml.jackson.databind.json.JsonMapper.Builder
    defaultWriterBuilder()
    Creates a preconfigured builder for a JsonMapper for writing/serializing objects to JSON.
    static void
    disableJsonIgnore(com.fasterxml.jackson.databind.ObjectMapper mapper)
    Disables any Jackson @JsonIgnore behavior on the specified ObjectMapper.
    static <T> T
    fromFile(Class<?> referencePoint, String fileName)
    Loads and deserializes a JSON file located relative to the reference point into an object.
    static <T> T
    fromFile(Class<?> referencePoint, String fileName, com.fasterxml.jackson.databind.JavaType javaType)
    Loads and deserializes a JSON file located relative to the reference point into an object of the provided type.
    static <T> T
    fromFile(Class<?> referencePoint, String fileName, Class<T> type)
    Loads and deserializes a JSON file located relative to the reference point into an object of the provided type.
    static <T> T
    fromFile(Class<?> referencePoint, String fileName, Function<com.fasterxml.jackson.databind.type.TypeFactory, com.fasterxml.jackson.databind.JavaType> typeFunction)
    Loads and deserializes a JSON file located relative to the referencePoint into an object of the type specified by the provided type function.
    static Object
    fromFile(String fileName)
    Loads and deserializes a JSON file located relative to the calling class.
    static List<?>
    fromFile(String... fileNames)
    Loads and deserializes JSON files located relative to the calling class.
    static <T> T
    fromFile(String fileName, com.fasterxml.jackson.databind.JavaType javaType)
    Loads and deserializes a JSON file located relative to the calling class to an object of the specified type.
    static <T> T
    fromFile(String fileName, Class<T> type)
    Loads and deserializes a JSON file located relative to the calling class to an object of the specified type.
    static <T> T
    fromFile(String fileName, Function<com.fasterxml.jackson.databind.type.TypeFactory, com.fasterxml.jackson.databind.JavaType> typeFunction)
    Loads and deserializes a JSON file located relative to the calling class into an object of the type specified by the provided type function.
    static <T> T
    fromFileAs(String fileName)
    Loads and deserializes a JSON file located relative to the calling class and casts it to type T.
    static Object
    fromFileWith(String fileName, Map<String,Object> replaceValues)
    Loads and deserializes a JSON file located relative to the calling class, applies property replacements, and returns the resulting object.
    static <T> T
    fromJson(byte[] json)
    Deserializes a JSON byte array and casts the result to type T.
    static <T> T
    fromJson(byte[] json, com.fasterxml.jackson.databind.JavaType type)
    Deserializes a JSON byte array into an instance of the specified type.
    static <T> T
    fromJson(byte[] json, Class<T> type)
    Deserializes a JSON byte array into an instance of the specified class type.
    static <T> T
    fromJson(byte[] json, Type type)
    Converts a JSON string to an object of the given type, which may be a ParameterizedType or Class.
    static <T> T
    fromJson(byte[] json, Function<com.fasterxml.jackson.databind.type.TypeFactory, com.fasterxml.jackson.databind.JavaType> typeFunction)
    Deserializes a JSON byte array into an object of the type specified by the provided type function.
    static <T> T
    fromJson(String json)
     
    static <T> T
    fromJson(String json, com.fasterxml.jackson.databind.JavaType type)
    Converts a JSON string to an object of the given type.
    static <T> T
    fromJson(String json, Class<T> type)
    Converts a JSON string to an object of the given class type.
    static <T> T
    fromJson(String json, Type type)
    Converts a JSON string to an object of the given type, which may be a ParameterizedType or Class.
    static <T> T
    fromJson(String json, Function<com.fasterxml.jackson.databind.type.TypeFactory, com.fasterxml.jackson.databind.JavaType> typeFunction)
    Deserializes a JSON string into an object of the type specified by the provided type function.
    protected static String
    getContent(Class<?> referencePoint, String fileName)
     
    protected static String
    getContent(URI fileUri)
     
    static <T> T
    merge(T base, Object update)
    Merges a base object with a patch/update object, omitting null fields.
    static com.fasterxml.jackson.databind.node.ObjectNode
    newObjectNode(Object... keyValues)
    Constructs a new ObjectNode from alternating key-value arguments.
    static com.fasterxml.jackson.databind.JsonNode
    readTree(byte[] jsonContent)
    Reads a JSON structure as a JsonNode tree from a JSON byte array.
    static com.fasterxml.jackson.databind.JsonNode
    readTree(InputStream jsonContent)
    Reads a JSON structure as a JsonNode tree from a JSON input stream.
    static com.fasterxml.jackson.databind.JsonNode
    readTree(String jsonContent)
    Reads a JSON structure as a JsonNode tree from a JSON string.
    static com.fasterxml.jackson.databind.type.TypeFactory
    typeFactory()
    Provides access to the TypeFactory instance used by the writer.
    static <T extends com.fasterxml.jackson.databind.JsonNode>
    T
    valueToTree(Object object)
    Converts an object to a JsonNode of type T.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • writer

      public static com.fasterxml.jackson.databind.json.JsonMapper writer
      Preconfigured JsonMapper for writing/serializing objects to JSON. By default, it is created using defaultWriterBuilder().

      In advanced scenarios, users may replace this field with a custom JsonMapper. However, this is generally discouraged unless strictly necessary.

    • reader

      public static com.fasterxml.jackson.databind.json.JsonMapper reader
      Preconfigured JsonMapper for reading/deserializing objects from JSON, including type handling.

      In advanced scenarios, users may replace this field with a custom JsonMapper. However, this is generally discouraged unless strictly necessary.

      A better approach for customizing Jackson behavior is to provide your own modules via the Jackson Module SPI (ServiceLoader mechanism), which avoids overriding global configuration and ensures compatibility.

  • Constructor Details

    • JsonUtils

      public JsonUtils()

  • Method Details

    • defaultWriterBuilder

      public static com.fasterxml.jackson.databind.json.JsonMapper.Builder defaultWriterBuilder()
      Creates a preconfigured builder for a JsonMapper for writing/serializing objects to JSON.

      A better approach for customizing Jackson behavior is to provide your own modules via the Jackson Module SPI (ServiceLoader mechanism), which avoids overriding global configuration and ensures compatibility.

      Warning: This mapper is also used by the default serializer in Fluxzero applications, JacksonSerializer. Misconfiguration may result in inconsistencies in search indexing or data loss.

    • fromFile

      public static Object fromFile(String fileName)
      Loads and deserializes a JSON file located relative to the calling class. Automatically supports @extends inheritance for configuration reuse.

    • fromFile

      public static List<?> fromFile(String... fileNames)
      Loads and deserializes JSON files located relative to the calling class. Automatically supports @extends inheritance for configuration reuse.

    • fromFile

      public static <T> T fromFile(Class<?> referencePoint, String fileName)
      Loads and deserializes a JSON file located relative to the reference point into an object. Automatically supports @extends inheritance for configuration reuse.

    • getContent

      protected static String getContent(Class<?> referencePoint, String fileName)

    • getContent

      protected static String getContent(URI fileUri)

    • fromFile

      public static <T> T fromFile(String fileName, Class<T> type)
      Loads and deserializes a JSON file located relative to the calling class to an object of the specified type. Automatically supports @extends inheritance for configuration reuse.

    • fromFile

      public static <T> T fromFile(String fileName, com.fasterxml.jackson.databind.JavaType javaType)
      Loads and deserializes a JSON file located relative to the calling class to an object of the specified type. Automatically supports @extends inheritance for configuration reuse.

    • fromFile

      public static <T> T fromFile(String fileName, Function<com.fasterxml.jackson.databind.type.TypeFactory, com.fasterxml.jackson.databind.JavaType> typeFunction)
      Loads and deserializes a JSON file located relative to the calling class into an object of the type specified by the provided type function. Automatically supports @extends inheritance for configuration reuse.

    • fromFile

      public static <T> T fromFile(Class<?> referencePoint, String fileName, Class<T> type)
      Loads and deserializes a JSON file located relative to the reference point into an object of the provided type. Automatically supports @extends inheritance for configuration reuse.

    • fromFile

      public static <T> T fromFile(Class<?> referencePoint, String fileName, com.fasterxml.jackson.databind.JavaType javaType)
      Loads and deserializes a JSON file located relative to the reference point into an object of the provided type. Automatically supports @extends inheritance for configuration reuse.

    • fromFile

      public static <T> T fromFile(Class<?> referencePoint, String fileName, Function<com.fasterxml.jackson.databind.type.TypeFactory, com.fasterxml.jackson.databind.JavaType> typeFunction)
      Loads and deserializes a JSON file located relative to the referencePoint into an object of the type specified by the provided type function. Automatically supports @extends inheritance for configuration reuse.

    • fromFileAs

      public static <T> T fromFileAs(String fileName)
      Loads and deserializes a JSON file located relative to the calling class and casts it to type T. Automatically supports @extends inheritance for configuration reuse.

    • fromFileWith

      public static Object fromFileWith(String fileName, Map<String,Object> replaceValues)
      Loads and deserializes a JSON file located relative to the calling class, applies property replacements, and returns the resulting object. The method supports updating specific properties of the deserialized object using the provided replacement values.

    • fromJson

      public static <T> T fromJson(String json)

    • fromJson

      public static <T> T fromJson(String json, Class<T> type)
      Converts a JSON string to an object of the given class type.

    • fromJson

      public static <T> T fromJson(String json, Type type)
      Converts a JSON string to an object of the given type, which may be a ParameterizedType or Class.

    • fromJson

      public static <T> T fromJson(String json, com.fasterxml.jackson.databind.JavaType type)
      Converts a JSON string to an object of the given type.

    • fromJson

      public static <T> T fromJson(String json, Function<com.fasterxml.jackson.databind.type.TypeFactory, com.fasterxml.jackson.databind.JavaType> typeFunction)
      Deserializes a JSON string into an object of the type specified by the provided type function.

    • fromJson

      public static <T> T fromJson(byte[] json, Class<T> type)
      Deserializes a JSON byte array into an instance of the specified class type.

    • fromJson

      public static <T> T fromJson(byte[] json)
      Deserializes a JSON byte array and casts the result to type T.

    • fromJson

      public static <T> T fromJson(byte[] json, Type type)
      Converts a JSON string to an object of the given type, which may be a ParameterizedType or Class.

    • fromJson

      public static <T> T fromJson(byte[] json, com.fasterxml.jackson.databind.JavaType type)
      Deserializes a JSON byte array into an instance of the specified type.

    • fromJson

      public static <T> T fromJson(byte[] json, Function<com.fasterxml.jackson.databind.type.TypeFactory, com.fasterxml.jackson.databind.JavaType> typeFunction)
      Deserializes a JSON byte array into an object of the type specified by the provided type function.

    • asJson

      public static String asJson(Object object)
      Converts an object to a JSON string.

    • asPrettyJson

      public static String asPrettyJson(Object object)
      Converts an object to a formatted JSON string.

    • asBytes

      public static byte[] asBytes(Object object)
      Converts an object to a JSON byte array.

    • convertValue

      public static <T> T convertValue(Object fromValue, Class<? extends T> toValueType)
      Converts an object to an object of the given class.

    • convertValue

      public static <T> T convertValue(Object fromValue, Type toValueType)
      Converts an object to an object of the given type which may be a ParameterizedType or Class.

    • convertValue

      public static <T> T convertValue(Object fromValue, com.fasterxml.jackson.core.type.TypeReference<T> typeRef)
      Converts an object to an object of the given type.

    • convertValue

      public static <T> T convertValue(Object fromValue, Function<com.fasterxml.jackson.databind.type.TypeFactory, com.fasterxml.jackson.databind.JavaType> typeFunction)
      Converts an object to an object of the given type.

    • readTree

      public static com.fasterxml.jackson.databind.JsonNode readTree(byte[] jsonContent)
      Reads a JSON structure as a JsonNode tree from a JSON byte array.

    • readTree

      public static com.fasterxml.jackson.databind.JsonNode readTree(String jsonContent)
      Reads a JSON structure as a JsonNode tree from a JSON string.

    • readTree

      public static com.fasterxml.jackson.databind.JsonNode readTree(InputStream jsonContent)
      Reads a JSON structure as a JsonNode tree from a JSON input stream.

    • valueToTree

      public static <T extends com.fasterxml.jackson.databind.JsonNode> T valueToTree(Object object)
      Converts an object to a JsonNode of type T.

    • newObjectNode

      public static com.fasterxml.jackson.databind.node.ObjectNode newObjectNode(Object... keyValues)
      Constructs a new ObjectNode from alternating key-value arguments.

    • merge

      public static <T> T merge(T base, Object update)
      Merges a base object with a patch/update object, omitting null fields. Returns a new object of the same type with updated fields.

    • typeFactory

      public static com.fasterxml.jackson.databind.type.TypeFactory typeFactory()
      Provides access to the TypeFactory instance used by the writer.

    • disableJsonIgnore

      public static void disableJsonIgnore(com.fasterxml.jackson.databind.ObjectMapper mapper)
      Disables any Jackson @JsonIgnore behavior on the specified ObjectMapper.