Package de.murmelmeister.library.configuration

Class YamlMurmel

java.lang.Object
de.murmelmeister.library.configuration.YamlMurmel
public class YamlMurmel extends Object
YamlMurmel is a utility class for reading and writing YAML configuration files. It provides methods to get and set values in a YAML structure, supporting nested keys using dot notation. The class is thread-safe, allowing concurrent read and write operations.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    YamlMurmel.Builder
    A Builder class for constructing instances of YamlMurmel with customizable options.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final ReadWriteLock
    lock
     
    private final Path
    path
     
    private final org.yaml.snakeyaml.Yaml
    yaml
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    YamlMurmel(YamlMurmel.Builder builder)
    Constructs a new instance of YamlMurmel, a utility class for managing YAML configuration files.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addComment(String key, String comment, boolean inLine)
    Adds a comment to a specific key in the YAML configuration file.
    static YamlMurmel.Builder
    builder(String fileName)
    Creates and returns a new instance of the Builder class for configuring and constructing a YamlMurmel instance.
    private org.yaml.snakeyaml.nodes.NodeTuple
    findNodeTuple(org.yaml.snakeyaml.nodes.Node root, String[] path)
    Recursively searches for a specific node tuple within a YAML structure based on a given path.
    <T> T
    getValue(String key, Class<T> type)
    Retrieves a value from the YAML configuration file for the specified dot-delimited key.
    <T> T
    getValue(String key, Class<T> type, T fallback)
    Retrieves a value from the YAML configuration file for the specified dot-delimited key.
    void
    removeKey(String key)
    Removes a specified key and its associated value from the YAML configuration file.
    private void
    setCommentBlock(org.yaml.snakeyaml.nodes.Node node, String comment)
    Sets a block comment for a given node in the YAML structure.
    private void
    setCommentInLine(org.yaml.snakeyaml.nodes.Node node, String comment)
    Sets an inline comment for a given node in the YAML structure.
    <T> void
    setValue(String key, T value)
    Sets a value in the YAML configuration file for the specified dot-delimited key.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • path

      private final Path path

    • yaml

      private final org.yaml.snakeyaml.Yaml yaml

    • lock

      private final ReadWriteLock lock

  • Constructor Details

    • YamlMurmel

      public YamlMurmel(YamlMurmel.Builder builder)
      Constructs a new instance of YamlMurmel, a utility class for managing YAML configuration files. This constructor initializes the YAML processor with the specified configuration options provided by the builder.
      Parameters:
      builder - The builder containing all configuration options for initializing the YamlMurmel instance. The `Builder` includes the file name, formatting options, and settings related to processing YAML.

  • Method Details

    • getValue

      public <T> T getValue(String key, Class<T> type)
      Retrieves a value from the YAML configuration file for the specified dot-delimited key. This method navigates the YAML structure based on the provided key and returns the corresponding value if it exists and matches the expected type.
      Type Parameters:
      T - The type of the value to be retrieved.
      Parameters:
      key - The dot-delimited key path where the value should be retrieved (e.g., "parent.child.grandchild").
      type - The expected type of the value to be retrieved.
      Returns:
      The value associated with the specified key if it exists and matches the expected type, or null if the key does not exist or is not a match.
      Throws:
      YamlMurmelException - If an error occurs while reading the YAML file.

    • getValue

      public <T> T getValue(String key, Class<T> type, T fallback)
      Retrieves a value from the YAML configuration file for the specified dot-delimited key. If the value does not exist, the provided fallback value is used, set in the configuration, and returned.
      Type Parameters:
      T - The type of the value to be retrieved.
      Parameters:
      key - The dot-delimited key path where the value should be retrieved (e.g., "parent.child.grandchild").
      type - The expected type of the value to be retrieved.
      fallback - The fallback value to return and set in the YAML file if the key does not exist.
      Returns:
      The value retrieved for the specified key, or the fallback value if the key does not exist.
      Throws:
      YamlMurmelException - If an error occurs while reading or writing the YAML file.

    • setValue

      public <T> void setValue(String key, T value)
      Sets a value in the YAML configuration file for the specified dot-delimited key. If the key path does not exist, it will be created along with any necessary parent keys. The updated configuration is saved back to the YAML file.
      Parameters:
      key - The dot-delimited key path where the value should be set (e.g., "parent.child.grandchild").
      value - The value to be set at the specified key.
      Throws:
      YamlMurmelException - If an error occurs while reading or writing the YAML file.

    • removeKey

      public void removeKey(String key)
      Removes a specified key and its associated value from the YAML configuration file. This method traverses the YAML structure using a dot-delimited key, removes the specified key, and cleans up any empty parent nodes if necessary. Updates are saved back to the YAML file.
      Parameters:
      key - The dot-delimited key path to be removed from the YAML configuration (e.g., "parent.child.grandchild").
      Throws:
      YamlMurmelException - If an error occurs while reading or writing the YAML file.

    • addComment

      public void addComment(String key, String comment, boolean inLine)
      Adds a comment to a specific key in the YAML configuration file. The comment can be added either as an inline comment or a block comment depending on the specified parameter. If the key or file does not exist, the operation is skipped. The updated YAML configuration is saved back to the file.
      Parameters:
      key - The dot-delimited key path where the comment is to be added (e.g., "parent.child.key").
      comment - The content of the comment to add.
      inLine - Specifies whether the comment should be added as an inline comment or a block comment. If true, the comment will be added inline; otherwise, it will be added as a block comment.
      Throws:
      YamlMurmelException - If an error occurs while reading or writing the YAML file.

    • setCommentInLine

      private void setCommentInLine(org.yaml.snakeyaml.nodes.Node node, String comment)
      Sets an inline comment for a given node in the YAML structure. This method appends the specified comment to the list of existing inline comments associated with the node.
      Parameters:
      node - The node for which the inline comment is to be set.
      comment - The content of the inline comment to add.

    • setCommentBlock

      private void setCommentBlock(org.yaml.snakeyaml.nodes.Node node, String comment)
      Sets a block comment for a given node in the YAML structure. This method adds the specified comment to the list of block comments associated with the node.
      Parameters:
      node - The node for which the block comment is to be set.
      comment - The content of the block comments to add.

    • findNodeTuple

      private org.yaml.snakeyaml.nodes.NodeTuple findNodeTuple(org.yaml.snakeyaml.nodes.Node root, String[] path)
      Recursively searches for a specific node tuple within a YAML structure based on a given path. This method traverses a tree of nodes, navigating through mappings and matching keys to elements provided in the path array to locate the corresponding node tuple.
      Parameters:
      root - The root node of the YAML structure to search from.
      path - An array of strings representing the hierarchical path to the desired node. Each element in the array corresponds to a key in the YAML structure.
      Returns:
      The NodeTuple corresponding to the final key in the path if it exists, or null if the key is not found in the YAML structure.

    • builder

      public static YamlMurmel.Builder builder(String fileName)
      Creates and returns a new instance of the Builder class for configuring and constructing a YamlMurmel instance.
      Parameters:
      fileName - The name of the YAML file to be managed by the YamlMurmel instance. This is a required parameter and sets the context for the YAML operations.
      Returns:
      A new Builder instance initialized with the specified file name.