fix(file): ensure directory creation and preserve generic types

src/main/java/net/theevilreaper/aves/file/FileHandler.java

@@ -9,13 +9,13 @@
 import java.util.Optional;
 
 /**
- * The class represents the base logic to load or save json files.
+ * Interface representing the base logic to load or save JSON files.
  *
  * @author theEvilReaper
  * @version 1.0.0
  * @since 1.0.0
- * * @deprecated This interface is deprecated since version 1.9.0 and will be removed in a future release. Use {@link ModernFileHandler} instead.
- **/
+ * @deprecated Deprecated since version 1.9.0 and will be removed in a future release. Use {@link ModernFileHandler} instead.
+ */
 @Deprecated(since = "1.9.0", forRemoval = true)
 public interface FileHandler {
 
@@ -29,6 +29,16 @@ public interface FileHandler {
      */
     Charset UTF_8 = StandardCharsets.UTF_8;
 
+    /**
+     * Prepares a target file path for saving by validating it is not a directory and ensuring parent directories exist.
+     *
+     * @param path target path
+     * @return true if the file does not exist yet, false otherwise
+     */
+    default boolean prepareSavePath(Path path) {
+        return FileHandlerUtil.prepareSavePath(path, LOGGER);
+    }
+
     /**
      * Saves a given object into a file.
      *

src/main/java/net/theevilreaper/aves/file/FileHandlerUtil.java

@@ -0,0 +1,41 @@
+package net.theevilreaper.aves.file;
+
+import net.minestom.server.utils.validate.Check;
+import org.slf4j.Logger;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+/**
+ * Internal utility class for file handling operations.
+ *
+ * @author theEvilReaper
+ * @version 1.0.0
+ * @since 1.14.0
+ */
+final class FileHandlerUtil {
+
+    private FileHandlerUtil() {
+    }
+
+    /**
+     * Prepares a target file path for saving by validating it is not a directory and ensuring parent directories exist.
+     *
+     * @param path   target path
+     * @param logger logger instance to log warnings
+     * @return true if the file does not exist yet, false otherwise
+     */
+    static boolean prepareSavePath(Path path, Logger logger) {
+        Check.argCondition(Files.isDirectory(path), "Unable to save a directory. Please check the used path");
+        boolean isNewFile = !Files.exists(path);
+        try {
+            if (path.getParent() != null) {
+                Files.createDirectories(path.getParent());
+            }
+        } catch (IOException exception) {
+            logger.warn("Unable to create directories for path: {}", path, exception);
+        }
+        return isNewFile;
+    }
+}

src/main/java/net/theevilreaper/aves/file/GsonFileHandler.java

@@ -10,45 +10,49 @@
 import java.util.Optional;
 
 /**
- * The class represents the implementation of the {@link FileHandler} for the {@link com.google.gson.Gson} library.
+ * Implementation of the {@link FileHandler} using the {@link Gson} library for JSON serialization and deserialization.
+ *
  * @author theEvilReaper
  * @version 1.0.0
  * @since 1.1.0
- * @deprecated This class is deprecated since version 1.9.0 and will be removed in a future release. Use {@link ModernGsonFileHandler} instead.
- **/
+ * @deprecated Deprecated since version 1.9.0 and will be removed in a future release. Use {@link ModernGsonFileHandler} instead.
+ */
 @Deprecated(since = "1.9.0", forRemoval = true)
 public final class GsonFileHandler implements FileHandler {
 
     private final Gson gson;
 
     /**
-     * Creates a new instance from the file handler.
+     * Creates a new instance of the file handler with a default {@link Gson} instance.
      */
     public GsonFileHandler() {
         this.gson = new Gson();
     }
 
     /**
-     * Creates a new instance from the file handler.
-     * @param gson the gson instance to deserialize or serialize data
+     * Creates a new instance of the file handler.
+     *
+     * @param gson the {@link Gson} instance to deserialize or serialize data
      */
     public GsonFileHandler(Gson gson) {
         this.gson = gson;
     }
 
     /**
-     * Saves a given object into a file.
-     * @param path The path where the file is located
-     * @param object The object to save
-     * @param <T> A generic type for the object value
+     * Saves a given object into a file at the specified path.
+     * Automatically creates parent directories if they do not exist.
+     *
+     * @param path   path where the file is located
+     * @param object object to save
+     * @param <T>    generic type for the object value
      */
     @Override
     public <T> void save(Path path, T object) {
-        Check.argCondition(Files.isDirectory(path), "Unable to save a directory. Please check the used path");
+        boolean isNewFile = prepareSavePath(path);
+
         try (var outputStream = Files.newBufferedWriter(path, UTF_8)) {
-            if (!Files.exists(path)) {
-                var file = Files.createFile(path).getFileName();
-                LOGGER.info("Created new file: {}", file);
+            if (isNewFile) {
+                LOGGER.info("Created new file: {}", path.getFileName());
             }
             gson.toJson(object, TypeToken.get(object.getClass()).getType(), outputStream);
         } catch (IOException exception) {
@@ -57,11 +61,12 @@
     }
 
     /**
-     * Load a given file and parse to the give class.
-     * @param path is the where the file is located
-     * @param clazz is the generic class object
-     * @param <T> is generic type for the object value
-     * @return a {@link Optional} with the object instance
+     * Loads a given file and deserializes its JSON content to the target class.
+     *
+     * @param path  path where the file is located
+     * @param clazz generic class object
+     * @param <T>   generic type for the object value
+     * @return an {@link Optional} containing the deserialized object, or empty if the file does not exist
      */
     @Override
     public <T> Optional<T> load(Path path, Class<T> clazz) {

src/main/java/net/theevilreaper/aves/file/ModernFileHandler.java

@@ -10,35 +10,45 @@
 import java.util.Optional;
 
 /**
- * The class represents the base logic to load or save JSON files.
+ * Interface representing the base logic to load or save JSON files.
  *
  * @author theEvilReaper
- * @version 1.0.0
+ * @version 1.1.0
  * @since 1.9.0
- **/
+ */
 public interface ModernFileHandler {
 
     Logger LOGGER = LoggerFactory.getLogger(ModernFileHandler.class);
 
     Charset UTF_8 = StandardCharsets.UTF_8;
 
     /**
-     * Saves a given object into a file.
+     * Prepares a target file path for saving by validating it is not a directory and ensuring parent directories exist.
      *
-     * @param path      The path where the file is located
-     * @param object    The object to save
-     * @param typeToken the type token to serialize the object
-     * @param <T>       A generic type for the object value
+     * @param path target path
+     * @return true if the file does not exist yet, false otherwise
+     */
+    default boolean prepareSavePath(Path path) {
+        return FileHandlerUtil.prepareSavePath(path, LOGGER);
+    }
+
+    /**
+     * Saves a given object into a file at the specified path.
+     *
+     * @param path      path where the file is located
+     * @param object    object to save
+     * @param typeToken type token to serialize the object
+     * @param <T>       generic type for the object value
      */
     <T> void save(Path path, T object, TypeToken<T> typeToken);
 
     /**
-     * Load a given file and parse to the give class.
+     * Loads a given file and deserializes its content to the target type.
      *
-     * @param path      is the where the file is located
-     * @param typeToken the type token to deserialize the object
-     * @param <T>       is generic type for the object value
-     * @return a {@link Optional} with the object instance
+     * @param path      path where the file is located
+     * @param typeToken type token to deserialize the object
+     * @param <T>       generic type for the object value
+     * @return an {@link Optional} containing the deserialized object, or empty if the file does not exist
      */
     <T> Optional<T> load(Path path, TypeToken<T> typeToken);
 }

src/main/java/net/theevilreaper/aves/file/ModernGsonFileHandler.java

@@ -10,56 +10,63 @@
 import java.util.Optional;
 
 /**
- * The class represents the implementation of the {@link ModernFileHandler} for the {@link com.google.gson.Gson} library.
+ * Implementation of the {@link ModernFileHandler} using the {@link Gson} library for JSON serialization and deserialization.
+ *
  * @author TheMeinerLP
- * @version 1.0.0
+ * @author theEvilReaper
+ * @version 1.1.0
  * @since 1.9.0
  */
 public class ModernGsonFileHandler implements ModernFileHandler {
 
     private final Gson gson;
 
     /**
-     * Creates a new instance from the file handler.
+     * Creates a new instance of the file handler with a default {@link Gson} instance.
      */
     public ModernGsonFileHandler() {
         this.gson = new Gson();
     }
 
     /**
-     * Creates a new instance from the file handler.
-     * @param gson the gson instance to deserialize or serialize data
+     * Creates a new instance of the file handler.
+     *
+     * @param gson the {@link Gson} instance to deserialize or serialize data
      */
     public ModernGsonFileHandler(Gson gson) {
         this.gson = gson;
     }
 
     /**
-     * Saves a given object into a file.
-     * @param path The path where the file is located
-     * @param object The object to save
-     * @param <T> A generic type for the object value
+     * Saves a given object into a file at the specified path.
+     * Automatically creates parent directories if they do not exist.
+     *
+     * @param path      path where the file is located
+     * @param object    object to save
+     * @param typeToken type token to serialize the object
+     * @param <T>       generic type for the object value
      */
     @Override
     public <T> void save(Path path, T object, TypeToken<T> typeToken) {
-        Check.argCondition(Files.isDirectory(path), "Unable to save a directory. Please check the used path");
+        boolean isNewFile = prepareSavePath(path);
+
         try (var outputStream = Files.newBufferedWriter(path, UTF_8)) {
-            if (!Files.exists(path)) {
-                var file = Files.createFile(path).getFileName();
-                LOGGER.info("Created new file: {}", file);
+            if (isNewFile) {
+                LOGGER.info("Created new file: {}", path.getFileName());
             }
-            gson.toJson(object, typeToken.getRawType(), outputStream);
+            gson.toJson(object, typeToken.getType(), outputStream);
         } catch (IOException exception) {
             LOGGER.warn("Unable to save file", exception);
         }
     }
 
     /**
-     * Load a given file and parse to the give class.
-     * @param path is the where the file is located
-     * @param typeToken the type token to deserialize the object
-     * @param <T> is generic type for the object value
-     * @return a {@link Optional} with the object instance
+     * Loads a given file and deserializes its JSON content to the target type.
+     *
+     * @param path      path where the file is located
+     * @param typeToken type token to deserialize the object
+     * @param <T>       generic type for the object value
+     * @return an {@link Optional} containing the deserialized object, or empty if the file does not exist
      */
     @Override
     public <T> Optional<T> load(Path path, TypeToken<T> typeToken) {
@@ -69,7 +76,7 @@ public <T> Optional<T> load(Path path, TypeToken<T> typeToken) {
         }
 
         try (var reader = Files.newBufferedReader(path, UTF_8)) {
-            return Optional.ofNullable(gson.fromJson(reader, typeToken));
+            return Optional.ofNullable(gson.fromJson(reader, typeToken.getType()));
         } catch (IOException exception) {
             LOGGER.warn("Unable to load file", exception);
         }