Class TreeMerger

java.lang.Object
cloud.opencode.base.tree.operation.TreeMerger
public final class TreeMerger extends Object
Tree Merger - Merges two tree forests by matching node IDs 树合并器 - 通过匹配节点ID合并两棵树森林

Merges two tree forests (lists of root nodes) into a single forest by matching nodes based on their IDs and applying a configurable merge strategy to resolve conflicts when the same node exists in both forests.

通过匹配节点ID将两棵树森林（根节点列表）合并为一棵，当相同节点存在于两棵森林中时， 使用可配置的合并策略来解决冲突。

Features | 主要功能:

  • Merge two tree forests by ID matching - 按ID匹配合并两棵树森林
  • Configurable merge strategy (KEEP_LEFT, KEEP_RIGHT, custom) - 可配置合并策略
  • Recursive children merging - 递归合并子节点
  • Nodes only in one side are included as-is - 仅在一侧的节点原样包含
  • Max depth protection (1000) to prevent stack overflow - 最大深度保护防止栈溢出

Usage Examples | 使用示例:

// Merge keeping left nodes on conflict
// 冲突时保留左侧节点
List<MyNode> merged = TreeMerger.mergeKeepLeft(leftRoots, rightRoots);

// Merge keeping right nodes on conflict
// 冲突时保留右侧节点
List<MyNode> merged = TreeMerger.mergeKeepRight(leftRoots, rightRoots);

// Merge with custom strategy
// 使用自定义策略合并
List<MyNode> merged = TreeMerger.merge(leftRoots, rightRoots, (left, right) -> {
    left.setName(right.getName()); // take name from right
    return left;
});

Security | 安全性:

  • Thread-safe: Yes (stateless utility class) - 是（无状态工具类）
  • Null-safe: No (parameters must not be null) - 否（参数不能为null）
  • Depth-limited: Max 1000 levels to prevent stack overflow - 深度限制1000层防止栈溢出
Since:
JDK 25, opencode-base-tree V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • merge

      public static <T extends Treeable<T,ID>, ID> List<T> merge(List<T> left, List<T> right, TreeMerger.MergeStrategy<T> strategy)
      Merges two tree forests using the specified merge strategy. 使用指定的合并策略合并两棵树森林。

      Nodes present in both forests are resolved using the provided strategy. Nodes present only in one forest are included as-is. Children of resolved nodes are always recursively merged from both original sides (the strategy resolves node data only; children are merged structurally, not taken from the resolved node). Nodes with null IDs are skipped.

      同时存在于两棵森林中的节点使用提供的策略解决。仅存在于一棵森林中的节点 原样包含。已解决节点的子节点始终从两棵原始树递归合并（策略仅解决节点数据； 子节点按结构合并，不取自已解决节点）。ID为null的节点将被跳过。

      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      left - the left forest (list of root nodes) | 左侧森林（根节点列表）
      right - the right forest (list of root nodes) | 右侧森林（根节点列表）
      strategy - the merge strategy for conflict resolution | 冲突解决的合并策略
      Returns:
      the merged forest | 合并后的森林
      Throws:
      NullPointerException - if any parameter is null | 如果任何参数为null
      TreeException - if max depth (1000) is exceeded | 如果超过最大深度（1000）

    • mergeKeepLeft

      public static <T extends Treeable<T,ID>, ID> List<T> mergeKeepLeft(List<T> left, List<T> right)
      Merges two tree forests, keeping the left node on conflict. 合并两棵树森林，冲突时保留左侧节点。

      When a node with the same ID exists in both forests, the left node is kept and its children are recursively merged with the right node's children.

      当相同ID的节点存在于两棵森林中时，保留左侧节点，并递归合并其子节点与右侧节点的子节点。

      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      left - the left forest (list of root nodes) | 左侧森林（根节点列表）
      right - the right forest (list of root nodes) | 右侧森林（根节点列表）
      Returns:
      the merged forest | 合并后的森林
      Throws:
      NullPointerException - if any parameter is null | 如果任何参数为null
      TreeException - if max depth (1000) is exceeded | 如果超过最大深度（1000）

    • mergeKeepRight

      public static <T extends Treeable<T,ID>, ID> List<T> mergeKeepRight(List<T> left, List<T> right)
      Merges two tree forests, keeping the right node on conflict. 合并两棵树森林，冲突时保留右侧节点。

      When a node with the same ID exists in both forests, the right node is kept and its children are recursively merged with the left node's children.

      当相同ID的节点存在于两棵森林中时，保留右侧节点，并递归合并其子节点与左侧节点的子节点。

      Type Parameters:
      T - the node type | 节点类型
      ID - the ID type | ID类型
      Parameters:
      left - the left forest (list of root nodes) | 左侧森林（根节点列表）
      right - the right forest (list of root nodes) | 右侧森林（根节点列表）
      Returns:
      the merged forest | 合并后的森林
      Throws:
      NullPointerException - if any parameter is null | 如果任何参数为null
      TreeException - if max depth (1000) is exceeded | 如果超过最大深度（1000）