Class YmlFlattener

java.lang.Object
cloud.opencode.base.yml.transform.YmlFlattener
public final class YmlFlattener extends Object
YAML Flattener - Flattens and unflattens nested YAML structures YAML 扁平化工具 - 扁平化和还原嵌套 YAML 结构

This utility class converts between nested YAML map structures and flat dot-notation key-value maps, and vice versa.

此工具类在嵌套 YAML 映射结构与扁平点号键值映射之间进行转换。

Features | 主要功能:

  • Flatten nested maps to dot-notation: {a:{b:1}} to {"a.b": 1} - 扁平化嵌套映射为点号表示
  • Unflatten dot-notation back to nested maps - 还原点号表示为嵌套映射
  • Array support: {items:[a,b]} to {"items[0]": "a", "items[1]": "b"} - 数组支持
  • Custom separator support - 自定义分隔符支持
  • Null values preserved - 保留空值
  • Empty maps/lists become leaf values - 空映射/列表作为叶子值

Usage Examples | 使用示例:

// Flatten
Map<String, Object> nested = Map.of("server", Map.of("port", 8080));
Map<String, Object> flat = YmlFlattener.flatten(nested);
// {"server.port": 8080}

// Unflatten
Map<String, Object> restored = YmlFlattener.unflatten(flat);
// {server: {port: 8080}}

// Custom separator
Map<String, Object> slashFlat = YmlFlattener.flatten(nested, "/");
// {"server/port": 8080}

Security | 安全性:

  • Thread-safe: Yes (stateless utility class) - 线程安全: 是（无状态工具类）
  • Depth-limited: Yes (max 50 levels) - 深度限制: 是（最多 50 层）
Since:
JDK 25, opencode-base-yml V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • flatten

      public static Map<String,Object> flatten(Map<String,Object> data)
      Flattens a nested map to dot-notation using the default separator. 使用默认分隔符将嵌套映射扁平化为点号表示。
      Parameters:
      data - the nested map (may be null, treated as empty) | 嵌套映射（可为 null，视为空）
      Returns:
      unmodifiable flat map | 不可修改的扁平映射
      Throws:
      OpenYmlException - if nesting depth exceeds limit | 当嵌套深度超过限制时

    • flatten

      public static Map<String,Object> flatten(Map<String,Object> data, String separator)
      Flattens a nested map to flat notation using the specified separator. 使用指定分隔符将嵌套映射扁平化。
      Parameters:
      data - the nested map (may be null, treated as empty) | 嵌套映射（可为 null，视为空）
      separator - the path separator | 路径分隔符
      Returns:
      unmodifiable flat map | 不可修改的扁平映射
      Throws:
      NullPointerException - if separator is null | 当分隔符为 null 时
      OpenYmlException - if nesting depth exceeds limit | 当嵌套深度超过限制时

    • unflatten

      public static Map<String,Object> unflatten(Map<String,Object> flat)
      Unflattens a flat dot-notation map back to nested structure using the default separator. 使用默认分隔符将扁平点号映射还原为嵌套结构。
      Parameters:
      flat - the flat map (may be null, treated as empty) | 扁平映射（可为 null，视为空）
      Returns:
      unmodifiable nested map | 不可修改的嵌套映射

    • unflatten

      public static Map<String,Object> unflatten(Map<String,Object> flat, String separator)
      Unflattens a flat map back to nested structure using the specified separator. 使用指定分隔符将扁平映射还原为嵌套结构。
      Parameters:
      flat - the flat map (may be null, treated as empty) | 扁平映射（可为 null，视为空）
      separator - the path separator | 路径分隔符
      Returns:
      unmodifiable nested map | 不可修改的嵌套映射
      Throws:
      NullPointerException - if separator is null | 当分隔符为 null 时