Class TreeBuilder

java.lang.Object
cloud.opencode.base.tree.TreeBuilder
public final class TreeBuilder extends Object
Tree Builder 树构建器

Utility for building trees from flat lists.

从扁平列表构建树的工具。

Features | 主要功能:

  • Build tree from flat list with ID extractors - 通过ID提取器从扁平列表构建树
  • Build from nested map structure - 从嵌套Map结构构建
  • Flatten tree to list with optional depth info - 将树展平为列表（可带深度信息）
  • Depth limit protection against stack overflow - 深度限制防止栈溢出

Usage Examples | 使用示例:

// Build tree from flat list - 从扁平列表构建树
List<TreeNode<Item>> roots = TreeBuilder.build(items, Item::getId, Item::getParentId);

// Build single root tree - 构建单根树
TreeNode<Item> root = TreeBuilder.buildSingle(items, Item::getId, Item::getParentId);

// Flatten tree - 展平树
List<Item> flat = TreeBuilder.flatten(root);

Security | 安全性:

  • Thread-safe: Yes (stateless utility class) - 线程安全: 是（无状态工具类）
  • Null-safe: Partial (null parent IDs treated as roots) - 空值安全: 部分（null父ID视为根节点）

Performance | 性能特性:

  • Time complexity: O(n) - build/flatten traverse all nodes once - 时间复杂度: O(n) - build/flatten 均单次遍历全部节点
  • Space complexity: O(n) - node map and result list proportional to input size - 空间复杂度: O(n) - 节点映射和结果列表与输入规模成正比
Since:
JDK 25, opencode-base-tree V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • build

      public static <T,ID> List<TreeNode<T>> build(Collection<T> items, Function<T,ID> idExtractor, Function<T,ID> parentIdExtractor)
      Build tree from flat list 从扁平列表构建树
      Type Parameters:
      T - the item type | 项类型
      ID - the ID type | ID类型
      Parameters:
      items - the flat list | 扁平列表
      idExtractor - the ID extractor | ID提取器
      parentIdExtractor - the parent ID extractor | 父ID提取器
      Returns:
      the root nodes | 根节点列表

    • buildSingle

      public static <T,ID> TreeNode<T> buildSingle(Collection<T> items, Function<T,ID> idExtractor, Function<T,ID> parentIdExtractor)
      Build single rooted tree 构建单根树
      Type Parameters:
      T - the item type | 项类型
      ID - the ID type | ID类型
      Parameters:
      items - the flat list | 扁平列表
      idExtractor - the ID extractor | ID提取器
      parentIdExtractor - the parent ID extractor | 父ID提取器
      Returns:
      the root node or null | 根节点或null

    • buildFromMap

      public static TreeNode<Map<String,Object>> buildFromMap(Map<String,Object> data, String childrenKey)
      Build from nested map structure 从嵌套映射结构构建
      Parameters:
      data - the root data | 根数据
      childrenKey - the children key | 子节点键
      Returns:
      the root node | 根节点
      Throws:
      TreeException - if max depth is exceeded | 如果超过最大深度

    • buildFromMap

      public static TreeNode<Map<String,Object>> buildFromMap(Map<String,Object> data, String childrenKey, int maxDepth)
      Build from nested map structure with depth limit 从嵌套映射结构构建（带深度限制）
      Parameters:
      data - the root data | 根数据
      childrenKey - the children key | 子节点键
      maxDepth - the maximum tree depth | 最大树深度
      Returns:
      the root node | 根节点
      Throws:
      TreeException - if max depth is exceeded | 如果超过最大深度

    • flatten

      public static <T> List<T> flatten(TreeNode<T> root)
      Flatten tree to list 将树展平为列表
      Type Parameters:
      T - the data type | 数据类型
      Parameters:
      root - the root node | 根节点
      Returns:
      the flattened list | 展平后的列表

    • flattenWithDepth

      public static <T> List<TreeBuilder.NodeWithDepth<T>> flattenWithDepth(TreeNode<T> root)
      Flatten tree to list with depth info 将树展平为带深度信息的列表
      Type Parameters:
      T - the data type | 数据类型
      Parameters:
      root - the root node | 根节点
      Returns:
      list of node-depth pairs | 节点-深度对列表