Module de.seggebaeing.sqlanalyzer
Package de.seggebaeing.sqlanalyzer.persistence

Class PersistenceHelper

java.lang.Object
de.seggebaeing.sqlanalyzer.persistence.PersistenceHelper
public class PersistenceHelper extends Object
File–system based JSON de.seggebaeing.sqlanalyzer.persistence utility for DTOs implementing Persistable.

Stores each object as a single .json file under a class-named directory (<basePath>/<SimpleClassName>/<id>.json). Provides CRUD-style helpers: persist, load, loadAll, and delete. Serialization uses Gson (pretty printed). A small normalization step ensures top-level String fields of Java records are non-null.

Versioning: persist(de.seggebaeing.sqlanalyzer.persistence.dto.Persistable) compares the on-disk version() with the candidate. Older or equal versions are not overwritten; newer candidates replace the file. Attempting to save an older version results in a PersistenceException.

Threading/Concurrency: This is a static, process-local helper. It is not a full concurrency control mechanism; coordinate concurrent writes at a higher level if multiple threads/processes may persist the same object.

Since:
1.0
Author:
Felix Seggebäing
Implementation Note:
JSON normalization only affects top-level String components on record types.
API Note:
Call initializeBasePath(java.nio.file.Path) exactly once before any other method. The base path is immutable afterward. Directory names are derived from clazz.getSimpleName().

  • Constructor Details

    • PersistenceHelper

      public PersistenceHelper()

  • Method Details

    • initializeBasePath

      public static void initializeBasePath(Path basePath)
      Initializes the root directory for de.seggebaeing.sqlanalyzer.persistence operations.

      Must be called exactly once before any other method of this helper is used. Subsequent calls will throw an IllegalStateException.

      Parameters:
      basePath - the directory under which all persisted objects will be stored; subdirectories are created per class name
      Throws:
      IllegalStateException - if the de.seggebaeing.sqlanalyzer.persistence base path has already been initialized

    • persist

      public static void persist(Persistable p) throws PersistenceException
      Persists a Persistable object to the file system.

      Each object is stored as a JSON file named by its id() in a directory specific to its class. If a file with the same ID already exists, the stored version() is compared against the candidate:

      • If the new version is greater, the file is overwritten.
      • If the versions are equal, nothing is changed.
      • If the existing version is greater, a PersistenceException is thrown.
      Parameters:
      p - the persistable object to save
      Throws:
      PersistenceException - if file access fails, if the existing JSON cannot be parsed as the expected type, or if a newer version already exists on disk

    • load

      public static <T extends Persistable> T load(Class<T> clazz, long id) throws PersistenceException
      Loads a persisted object by class and identifier.

      Reads the JSON file named &lt;id&gt;.json from the directory corresponding to the given class, deserializes it with Gson, and normalizes top-level string fields for record types.

      Type Parameters:
      T - the type of the object to load
      Parameters:
      clazz - the class of the object, used to resolve the directory and target type
      id - the identifier of the object (file name without extension)
      Returns:
      the deserialized object of type T
      Throws:
      PersistenceException - if the file is missing, unreadable, contains invalid JSON, or does not match the expected type

    • loadAll

      public static <T extends Persistable> Set<T> loadAll(Class<T> clazz) throws PersistenceException
      Loads all persisted objects of the given class.

      Scans the directory associated with clazz for .json files, deserializes each into an instance of T, and returns them as a set. Invalid or unreadable files are skipped with a logged warning.

      Type Parameters:
      T - the type of objects to load
      Parameters:
      clazz - the class whose persisted instances should be loaded
      Returns:
      a set of deserialized objects of type T; may be empty if no files exist
      Throws:
      PersistenceException - if the directory listing fails

    • delete

      public static void delete(Persistable p) throws PersistenceException
      Deletes the persisted file of the given object.

      Resolves the JSON file path from the object's class and id(), then attempts to delete it from disk.

      Parameters:
      p - the persistable object whose file should be removed
      Throws:
      PersistenceException - if the file does not exist or an I/O error occurs during deletion