Class OpenTree

java.lang.Object
cloud.opencode.base.tree.OpenTree
public final class OpenTree extends Object
Open Tree 开放树

Main facade for tree operations.

树操作的主要门面。

Features | 主要功能:

  • Build trees from flat lists - 从扁平列表构建树
  • Multiple traversal strategies (pre-order, post-order, BFS) - 多种遍历策略（前序、后序、广度优先）
  • Search and filter operations - 搜索和过滤操作
  • Tree statistics (depth, size, leaves) - 树统计（深度、大小、叶子节点）
  • Virtual tree with lazy loading - 支持懒加载的虚拟化树
  • Serialization to JSON, XML, Map - 序列化为JSON、XML、Map
  • Tree merging with conflict resolution - 树合并与冲突解决
  • Comprehensive tree statistics - 全面的树统计
  • Lowest common ancestor (LCA) - 最近公共祖先
  • Subtree extraction and siblings - 子树提取和兄弟节点

Usage Examples | 使用示例:

// Build tree from flat list - 从扁平列表构建树
List<MyNode> tree = OpenTree.buildTree(flatList);

// Find node by ID - 通过ID查找节点
MyNode node = OpenTree.find(tree, nodeId);

// Serialize to JSON - 序列化为JSON
String json = OpenTree.toJson(tree);

Security | 安全性:

  • Thread-safe: Yes (stateless utility class) - 线程安全: 是（无状态工具类）
  • Null-safe: Partial (null checks on input lists) - 空值安全: 部分（对输入列表有空值检查）
Since:
JDK 25, opencode-base-tree V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • node

      public static <T> TreeNode<T> node(T data)

    • build

      public static <T,ID> List<TreeNode<T>> build(Collection<T> items, Function<T,ID> idExtractor, Function<T,ID> parentIdExtractor)

    • buildSingle

      public static <T,ID> TreeNode<T> buildSingle(Collection<T> items, Function<T,ID> idExtractor, Function<T,ID> parentIdExtractor)

    • fromMap

      public static TreeNode<Map<String,Object>> fromMap(Map<String,Object> data, String childrenKey)

    • flatten

      public static <T> List<T> flatten(TreeNode<T> root)

    • flattenWithDepth

      public static <T> List<TreeBuilder.NodeWithDepth<T>> flattenWithDepth(TreeNode<T> root)

    • print

      public static <T> String print(TreeNode<T> root)

    • printToConsole

      public static <T> void printToConsole(TreeNode<T> root)

    • buildTree

      public static <T extends Treeable<T,ID>, ID> List<T> buildTree(List<T> nodes)
      Build tree from flat list (default root detection) 从扁平列表构建树（默认根节点检测）
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      nodes - the flat list | 扁平列表
      Returns:
      the root nodes | 根节点列表

    • buildTree

      public static <T extends Treeable<T,ID>, ID> List<T> buildTree(List<T> nodes, ID rootId)
      Build tree from flat list with specified root ID 从扁平列表构建树（指定根节点ID）
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      nodes - the flat list | 扁平列表
      rootId - the root ID | 根节点ID
      Returns:
      the root nodes | 根节点列表

    • buildTreeSorted

      public static <T extends Treeable<T,ID>, ID> List<T> buildTreeSorted(List<T> nodes, ID rootId, Comparator<T> comparator)
      Build sorted tree 构建排序树
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      nodes - the flat list | 扁平列表
      rootId - the root ID | 根节点ID
      comparator - the comparator | 比较器
      Returns:
      the sorted root nodes | 排序后的根节点列表

    • buildTreeFromMaps

      public static List<DefaultTreeNode<Object>> buildTreeFromMaps(List<Map<String,Object>> maps, String idKey, String parentIdKey, String nameKey)
      Build tree from maps 从Map列表构建树
      Parameters:
      maps - the map list | Map列表
      idKey - the ID key | ID键
      parentIdKey - the parent ID key | 父ID键
      nameKey - the name key | 名称键
      Returns:
      the root nodes | 根节点列表

    • traversePreOrder

      public static <T extends Treeable<T,?>> void traversePreOrder(List<T> roots, Consumer<T> visitor)
      Pre-order traversal 前序遍历
      Type Parameters:
      T - the node type | 节点类型
      Parameters:
      roots - the root nodes | 根节点列表
      visitor - the visitor | 访问者

    • traversePostOrder

      public static <T extends Treeable<T,?>> void traversePostOrder(List<T> roots, Consumer<T> visitor)
      Post-order traversal 后序遍历
      Type Parameters:
      T - the node type | 节点类型
      Parameters:
      roots - the root nodes | 根节点列表
      visitor - the visitor | 访问者

    • traverseBreadthFirst

      public static <T extends Treeable<T,?>> void traverseBreadthFirst(List<T> roots, Consumer<T> visitor)
      Breadth-first (level order) traversal 广度优先（层序）遍历
      Type Parameters:
      T - the node type | 节点类型
      Parameters:
      roots - the root nodes | 根节点列表
      visitor - the visitor | 访问者

    • traverseWithDepth

      public static <T extends Treeable<T,?>> void traverseWithDepth(List<T> roots, BiConsumer<T,Integer> visitor)
      Traverse with depth information 带深度信息的遍历
      Type Parameters:
      T - the node type | 节点类型
      Parameters:
      roots - the root nodes | 根节点列表
      visitor - the visitor | 访问者

    • find

      public static <T extends Treeable<T,ID>, ID> T find(List<T> roots, ID id)
      Find node by ID 按ID查找节点
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      roots - the root nodes | 根节点列表
      id - the ID to find | 要查找的ID
      Returns:
      the found node or null | 找到的节点或null

    • findAll

      public static <T extends Treeable<T,?>> List<T> findAll(List<T> roots, Predicate<T> predicate)
      Find all nodes matching predicate 查找所有满足条件的节点
      Type Parameters:
      T - the node type | 节点类型
      Parameters:
      roots - the root nodes | 根节点列表
      predicate - the predicate | 谓词
      Returns:
      the matching nodes | 匹配的节点列表

    • getPath

      public static <T extends Treeable<T,ID>, ID> List<T> getPath(List<T> roots, ID id)
      Get path from root to specified node 获取从根到指定节点的路径
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      roots - the root nodes | 根节点列表
      id - the target node ID | 目标节点ID
      Returns:
      the path from root to node | 从根到节点的路径

    • getLeaves

      public static <T extends Treeable<T,?>> List<T> getLeaves(List<T> roots)
      Get all leaf nodes 获取所有叶子节点
      Type Parameters:
      T - the node type | 节点类型
      Parameters:
      roots - the root nodes | 根节点列表
      Returns:
      the leaf nodes | 叶子节点列表

    • filter

      public static <T extends Treeable<T,ID>, ID> List<T> filter(List<T> roots, Predicate<T> predicate)
      Filter tree (keep matching nodes and their ancestors) 过滤树（保留匹配节点及其祖先）
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      roots - the root nodes | 根节点列表
      predicate - the predicate | 谓词
      Returns:
      the filtered root nodes | 过滤后的根节点列表

    • flattenTree

      public static <T extends Treeable<T,?>> List<T> flattenTree(List<T> roots)
      Flatten tree to list 将树扁平化为列表
      Type Parameters:
      T - the node type | 节点类型
      Parameters:
      roots - the root nodes | 根节点列表
      Returns:
      the flattened list | 扁平化后的列表

    • depth

      public static <T extends Treeable<T,?>> int depth(List<T> roots)
      Calculate tree depth 计算树深度
      Type Parameters:
      T - the node type | 节点类型
      Parameters:
      roots - the root nodes | 根节点列表
      Returns:
      the maximum depth | 最大深度

    • size

      public static <T extends Treeable<T,?>> int size(List<T> roots)
      Calculate total node count 计算节点总数
      Type Parameters:
      T - the node type | 节点类型
      Parameters:
      roots - the root nodes | 根节点列表
      Returns:
      the total count | 总数

    • sortTree

      @Deprecated(since="1.0.3", forRemoval=true) public static <T extends Treeable<T,?>> void sortTree(List<T> nodes, Comparator<T> comparator)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Use sort(List, Comparator) instead, which uses iterative depth-safe TreeSorter
      Sort tree recursively 递归排序树
      Type Parameters:
      T - the node type | 节点类型
      Parameters:
      nodes - the nodes to sort | 要排序的节点
      comparator - the comparator | 比较器

    • virtualTree

      public static <T,ID> VirtualTree<T,ID> virtualTree(ID id, T data, LazyChildLoader<VirtualTree<T,ID>, ID> childLoader)
      Create a virtual tree root with lazy loading 创建支持懒加载的虚拟树根节点
      Type Parameters:
      T - the data type | 数据类型
      ID - the ID type | ID类型
      Parameters:
      id - the root ID | 根节点ID
      data - the root data | 根节点数据
      childLoader - the lazy child loader | 懒加载器
      Returns:
      the virtual tree root | 虚拟树根节点

    • virtualTreeBuilder

      public static <T,ID> VirtualTree.Builder<T,ID> virtualTreeBuilder()
      Create a virtual tree builder 创建虚拟树构建器
      Type Parameters:
      T - the data type | 数据类型
      ID - the ID type | ID类型
      Returns:
      the builder | 构建器

    • preloadVirtualTree

      public static <T,ID> void preloadVirtualTree(VirtualTree<T,ID> root, int depth)
      Preload virtual tree to specified depth 预加载虚拟树到指定深度
      Type Parameters:
      T - the data type | 数据类型
      ID - the ID type | ID类型
      Parameters:
      root - the virtual tree root | 虚拟树根节点
      depth - the depth to preload | 预加载深度

    • toJson

      public static <T extends Treeable<T,ID>, ID> String toJson(List<T> roots)
      Serialize tree to JSON 将树序列化为JSON
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      roots - the root nodes | 根节点列表
      Returns:
      the JSON string | JSON字符串

    • toJson

      public static <T extends Treeable<T,ID>, ID> String toJson(List<T> roots, Function<T, Map<String,Object>> fieldExtractor)
      Serialize tree to JSON with custom field extractor 使用自定义字段提取器将树序列化为JSON
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      roots - the root nodes | 根节点列表
      fieldExtractor - the field extractor | 字段提取器
      Returns:
      the JSON string | JSON字符串

    • toXml

      public static <T extends Treeable<T,ID>, ID> String toXml(List<T> roots)
      Serialize tree to XML 将树序列化为XML
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      roots - the root nodes | 根节点列表
      Returns:
      the XML string | XML字符串

    • toXml

      public static <T extends Treeable<T,ID>, ID> String toXml(List<T> roots, Function<T, Map<String,Object>> fieldExtractor)
      Serialize tree to XML with custom field extractor 使用自定义字段提取器将树序列化为XML
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      roots - the root nodes | 根节点列表
      fieldExtractor - the field extractor | 字段提取器
      Returns:
      the XML string | XML字符串

    • toMaps

      public static <T extends Treeable<T,ID>, ID> List<Map<String,Object>> toMaps(List<T> roots)
      Convert tree to list of maps 将树转换为Map列表
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      roots - the root nodes | 根节点列表
      Returns:
      the map list | Map列表

    • toFlatMaps

      public static <T extends Treeable<T,ID>, ID> List<Map<String,Object>> toFlatMaps(List<T> roots)
      Convert tree to flat list of maps (without hierarchy) 将树扁平化为Map列表（无层级）
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      roots - the root nodes | 根节点列表
      Returns:
      the flat map list | 扁平Map列表

    • treeNodeToJson

      public static <T> String treeNodeToJson(TreeNode<T> root, Function<T, Map<String,Object>> dataSerializer)
      Serialize TreeNode to JSON 将TreeNode序列化为JSON
      Type Parameters:
      T - the data type | 数据类型
      Parameters:
      root - the root node | 根节点
      dataSerializer - function to serialize data | 数据序列化函数
      Returns:
      the JSON string | JSON字符串

    • treeNodeToXml

      public static <T> String treeNodeToXml(TreeNode<T> root, Function<T, Map<String,Object>> dataSerializer)
      Serialize TreeNode to XML 将TreeNode序列化为XML
      Type Parameters:
      T - the data type | 数据类型
      Parameters:
      root - the root node | 根节点
      dataSerializer - function to serialize data | 数据序列化函数
      Returns:
      the XML string | XML字符串

    • mergeKeepLeft

      public static <T extends Treeable<T,ID>, ID> List<T> mergeKeepLeft(List<T> left, List<T> right)
      Merge two tree forests, keeping left node on conflict 合并两个树森林，冲突时保留左侧节点
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      left - the left forest | 左侧森林
      right - the right forest | 右侧森林
      Returns:
      the merged forest | 合并后的森林
      Since:
      V1.0.3

    • mergeKeepRight

      public static <T extends Treeable<T,ID>, ID> List<T> mergeKeepRight(List<T> left, List<T> right)
      Merge two tree forests, keeping right node on conflict 合并两个树森林，冲突时保留右侧节点
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      left - the left forest | 左侧森林
      right - the right forest | 右侧森林
      Returns:
      the merged forest | 合并后的森林
      Since:
      V1.0.3

    • merge

      public static <T extends Treeable<T,ID>, ID> List<T> merge(List<T> left, List<T> right, TreeMerger.MergeStrategy<T> strategy)
      Merge two tree forests with custom conflict resolution 使用自定义冲突解决合并两个树森林
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      left - the left forest | 左侧森林
      right - the right forest | 右侧森林
      strategy - conflict resolution function | 冲突解决函数
      Returns:
      the merged forest | 合并后的森林
      Since:
      V1.0.3

    • sort

      public static <T extends Treeable<T,ID>, ID> void sort(List<T> roots, Comparator<T> comparator)
      Sort tree recursively using TreeSorter 使用 TreeSorter 递归排序树
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      roots - the root nodes | 根节点列表
      comparator - the comparator | 比较器
      Since:
      V1.0.3

    • sortBy

      public static <T extends Treeable<T,ID>, ID, U extends Comparable<? super U>> void sortBy(List<T> roots, Function<T,U> keyExtractor)
      Sort tree recursively by extracted key 按提取的键递归排序树
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      U - the comparable key type | 可比较键类型
      Parameters:
      roots - the root nodes | 根节点列表
      keyExtractor - the key extractor | 键提取器
      Since:
      V1.0.3

    • isSorted

      public static <T extends Treeable<T,ID>, ID> boolean isSorted(List<T> roots, Comparator<T> comparator)
      Check if tree is sorted at all levels 检查树在所有层级是否已排序
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      roots - the root nodes | 根节点列表
      comparator - the comparator | 比较器
      Returns:
      true if sorted | 如果已排序返回true
      Since:
      V1.0.3

    • statistics

      public static <T extends Treeable<T,ID>, ID> TreeStatistics statistics(List<T> roots)
      Collect comprehensive tree statistics in a single BFS pass 通过单次 BFS 收集全面的树统计
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      roots - the root nodes | 根节点列表
      Returns:
      the statistics | 统计信息
      Since:
      V1.0.3

    • findLCA

      public static <T extends Treeable<T,ID>, ID> Optional<T> findLCA(List<T> roots, ID id1, ID id2)
      Find lowest common ancestor of two nodes by ID 通过ID查找两个节点的最近公共祖先
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      roots - the root nodes | 根节点列表
      id1 - the first node ID | 第一个节点ID
      id2 - the second node ID | 第二个节点ID
      Returns:
      the LCA if both nodes exist | 如果两个节点都存在返回最近公共祖先
      Since:
      V1.0.3

    • extractSubtree

      public static <T extends Treeable<T,ID>, ID> Optional<T> extractSubtree(List<T> roots, ID id)
      Extract the subtree rooted at the node with the given ID 提取以给定ID节点为根的子树
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      roots - the root nodes | 根节点列表
      id - the target node ID | 目标节点ID
      Returns:
      the subtree or empty if not found | 子树，未找到返回空
      Since:
      V1.0.3

    • getSiblings

      public static <T extends Treeable<T,ID>, ID> List<T> getSiblings(List<T> roots, ID id)
      Get sibling nodes of the node with the given ID 获取给定ID节点的兄弟节点
      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      roots - the root nodes | 根节点列表
      id - the target node ID | 目标节点ID
      Returns:
      the sibling nodes | 兄弟节点列表
      Since:
      V1.0.3