Class RawYamlLoader

java.lang.Object
net.blockhost.commons.config.migration.RawYamlLoader
public final class RawYamlLoader extends Object

Utility class for loading and saving raw YAML files as Map structures.

This class provides low-level YAML operations using SnakeYAML, allowing direct manipulation of YAML data without mapping to Java objects. This is essential for the migration system, which needs to transform YAML structures before they can be loaded into typed configuration classes.

Features

  • Safe loading: Uses SafeConstructor to prevent arbitrary code execution
  • Order preservation: Uses LinkedHashMap to maintain key insertion order
  • Pretty output: Configures block style formatting with proper indentation
  • Flexible input: Supports loading from Path, InputStream, Reader, or String

Usage

// Load YAML from file
Path configPath = Path.of("config.yml");
Map<String, Object> data = RawYamlLoader.load(configPath);

// Modify the data
data.put("version", 2);
data.put("newField", "newValue");

// Save back to file
RawYamlLoader.save(configPath, data);

Thread Safety

Each method creates a new Yaml instance, making this class thread-safe. However, the returned Map objects are not thread-safe and should be synchronized externally if accessed from multiple threads.

See Also:

  • Method Details

    • load

      public static Map<String,Object> load(Path path)

      Loads YAML content from a file path.

      If the file does not exist, returns an empty LinkedHashMap.

      Parameters:
      path - the path to the YAML file
      Returns:
      a mutable map containing the YAML data, or empty map if file doesn't exist
      Throws:
      MigrationException - if the file cannot be read or parsed
      NullPointerException - if path is null

    • load

      public static Map<String,Object> load(InputStream inputStream)

      Loads YAML content from an input stream.

      The caller is responsible for closing the input stream.

      Parameters:
      inputStream - the input stream containing YAML content
      Returns:
      a mutable map containing the YAML data
      Throws:
      MigrationException - if the content cannot be parsed
      NullPointerException - if inputStream is null

    • load

      public static Map<String,Object> load(Reader reader)

      Loads YAML content from a reader.

      The caller is responsible for closing the reader.

      Parameters:
      reader - the reader containing YAML content
      Returns:
      a mutable map containing the YAML data
      Throws:
      MigrationException - if the content cannot be parsed
      NullPointerException - if reader is null

    • loadFromString

      public static Map<String,Object> loadFromString(String content)
      Loads YAML content from a string.
      Parameters:
      content - the YAML content as a string
      Returns:
      a mutable map containing the YAML data
      Throws:
      MigrationException - if the content cannot be parsed
      NullPointerException - if content is null

    • save

      public static void save(Path path, Map<String,Object> data)

      Saves YAML data to a file path atomically.

      Creates parent directories if they don't exist. Overwrites any existing file using an atomic write-to-temp-then-rename strategy to prevent corruption.

      Parameters:
      path - the path to save the YAML file
      data - the data to save
      Throws:
      MigrationException - if the file cannot be written
      NullPointerException - if path or data is null

    • save

      public static void save(OutputStream outputStream, Map<String,Object> data)

      Saves YAML data to an output stream.

      The caller is responsible for closing the output stream.

      Parameters:
      outputStream - the output stream to write to
      data - the data to save
      Throws:
      MigrationException - if the data cannot be serialized
      NullPointerException - if outputStream or data is null

    • save

      public static void save(Writer writer, Map<String,Object> data)

      Saves YAML data to a writer.

      The caller is responsible for closing the writer.

      Parameters:
      writer - the writer to write to
      data - the data to save
      Throws:
      MigrationException - if the data cannot be serialized
      NullPointerException - if writer or data is null

    • saveToString

      public static String saveToString(Map<String,Object> data)
      Converts YAML data to a string.
      Parameters:
      data - the data to convert
      Returns:
      the YAML content as a string
      Throws:
      MigrationException - if the data cannot be serialized
      NullPointerException - if data is null

    • readVersion

      public static int readVersion(Path path)

      Reads the version field from a YAML file.

      This is a convenience method for quickly checking the version of a configuration file without loading the entire content.

      Parameters:
      path - the path to the YAML file
      Returns:
      the version number, or 0 if the file doesn't exist or has no version field
      Throws:
      MigrationException - if the file cannot be read or the version is not a valid integer
      NullPointerException - if path is null

    • extractVersion

      public static int extractVersion(Map<String,Object> data)
      Extracts the version field from YAML data.
      Parameters:
      data - the YAML data map
      Returns:
      the version number, or 0 if no version field exists
      Throws:
      MigrationException - if the version field is not a valid integer
      NullPointerException - if data is null