Class JsonUtilities

public final class JsonUtilities

Counterpart to XmlUtilities for working with JSON resources using the Jakarta JSON Binding (JSON-B) and Jakarta JSON Processing (JSON-P) APIs.

The class provides two layers of access:

  • A binding layer ([URL)][#read(Class,], [Path)][#read(Class,], [Path)][#save(Object,]) that maps JSON documents to plain Java objects via JSON-B, mirroring the API offered by XmlUtilities for JAXB.
  • A tree-model layer (readTree(URL), readTree(Path), [Path)][#saveTree(JsonValue,]) that exposes the underlying JsonStructure for cases where direct DOM-style access is preferable to data binding.

Both layers cache their factories and Jsonb instances per configuration so repeated use does not pay the cost of recreating them.

  • Method Summary

    Modifier and Type
    Method
    Description
    static jakarta.json.bind.Jsonb
    getJsonb(boolean pretty)
    Returns a cached Jsonb instance configured with the requested formatting.
    static <T> T
    read(Class<T> cls, Reader reader)
    Reads a JSON document from the given reader and binds it to an instance of the requested class.
    static <T> T
    read(Class<T> cls, URL path)
    Reads a JSON document from the given URL and binds it to an instance of the requested class.
    static <T> T
    read(Class<T> cls, Path filePath)
    Reads a JSON document from the given path and binds it to an instance of the requested class.
    static jakarta.json.JsonStructure
    readTree(Reader reader)
    Reads the JSON document from the given reader into a JsonStructure.
    static jakarta.json.JsonStructure
    readTree(URL path)
    Reads the JSON document referenced by the given URL into a JsonStructure (object or array).
    static jakarta.json.JsonStructure
    readTree(Path filePath)
    Reads the JSON document at the given path into a JsonStructure (object or array).
    static void
    save(Object object, Writer writer, boolean pretty)
    Binds the given object to JSON and writes it to the supplied writer.
    static Path
    save(Object object, Path filePath)
    Binds the given object to JSON and writes it to the specified path (pretty-printed).
    static Path
    save(Object object, Path path, String extension)
    Binds the given object to JSON and writes it to the specified path, ensuring the path ends with the supplied extension (e.g. "json" or ".json").
    static Path
    saveTree(jakarta.json.JsonValue value, Path filePath)
    Convenience overload that pretty-prints by default.
    static Path
    saveTree(jakarta.json.JsonValue value, Path filePath, boolean pretty)
    Writes a JsonValue tree to the specified path.
    static String
    writeTreeToString(jakarta.json.JsonValue value, boolean pretty)
    Serializes the given JSON value to a string.

    Methods inherited from class Object

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

  • Method Details

    • getJsonb

      public static jakarta.json.bind.Jsonb getJsonb(boolean pretty)
      Returns a cached Jsonb instance configured with the requested formatting.
      Parameters:
      pretty - Whether the returned instance produces pretty-printed output.
      Returns:
      A shared, thread-safe Jsonb instance.

    • read

      public static <T> T read(Class<T> cls, URL path)
      Reads a JSON document from the given URL and binds it to an instance of the requested class.
      Type Parameters:
      T - The bound type.
      Parameters:
      cls - The target class.
      path - The URL of the JSON document.
      Returns:
      The bound instance, or null if the document cannot be read.

    • read

      public static <T> T read(Class<T> cls, Path filePath)
      Reads a JSON document from the given path and binds it to an instance of the requested class.
      Type Parameters:
      T - The bound type.
      Parameters:
      cls - The target class.
      filePath - The path to the JSON document.
      Returns:
      The bound instance, or null if the document cannot be read.

    • read

      public static <T> T read(Class<T> cls, Reader reader)
      Reads a JSON document from the given reader and binds it to an instance of the requested class.
      Type Parameters:
      T - The bound type.
      Parameters:
      cls - The target class.
      reader - The reader providing the JSON content.
      Returns:
      The bound instance.

    • readTree

      public static jakarta.json.JsonStructure readTree(URL path)
      Reads the JSON document referenced by the given URL into a JsonStructure (object or array). Useful when the document does not follow a fixed schema.
      Parameters:
      path - The URL of the JSON document.
      Returns:
      The parsed structure, or null if the document cannot be read.

    • readTree

      public static jakarta.json.JsonStructure readTree(Path filePath)
      Reads the JSON document at the given path into a JsonStructure (object or array).
      Parameters:
      filePath - The path to the JSON document.
      Returns:
      The parsed structure, or null if the document cannot be read.

    • readTree

      public static jakarta.json.JsonStructure readTree(Reader reader)
      Reads the JSON document from the given reader into a JsonStructure.
      Parameters:
      reader - The reader providing the JSON content.
      Returns:
      The parsed structure.

    • save

      public static Path save(Object object, Path filePath)
      Binds the given object to JSON and writes it to the specified path (pretty-printed).
      Parameters:
      object - The object to serialize.
      filePath - The destination path.
      Returns:
      The destination path, or null if the path is null or writing fails.

    • save

      public static Path save(Object object, Path path, String extension)
      Binds the given object to JSON and writes it to the specified path, ensuring the path ends with the supplied extension (e.g. "json" or ".json").
      Parameters:
      object - The object to serialize.
      path - The destination path.
      extension - The file extension (with or without a leading dot).
      Returns:
      The actual destination path used.

    • save

      public static void save(Object object, Writer writer, boolean pretty)
      Binds the given object to JSON and writes it to the supplied writer.
      Parameters:
      object - The object to serialize.
      writer - The writer to write the JSON to.
      pretty - Whether to pretty-print the output.

    • saveTree

      public static Path saveTree(jakarta.json.JsonValue value, Path filePath, boolean pretty)
      Writes a JsonValue tree to the specified path.
      Parameters:
      value - The JSON value to write.
      filePath - The destination path.
      pretty - Whether to pretty-print the output.
      Returns:
      The destination path, or null if writing fails.

    • saveTree

      public static Path saveTree(jakarta.json.JsonValue value, Path filePath)
      Convenience overload that pretty-prints by default.
      Parameters:
      value - The JSON value to write.
      filePath - The destination path.
      Returns:
      The destination path.

    • writeTreeToString

      public static String writeTreeToString(jakarta.json.JsonValue value, boolean pretty)
      Serializes the given JSON value to a string.
      Parameters:
      value - The JSON value to serialize.
      pretty - Whether to pretty-print the output.
      Returns:
      The serialized JSON string.