Class CloneContext

java.lang.Object
cloud.opencode.base.deepclone.CloneContext
public final class CloneContext extends Object
Context for tracking clone state and handling circular references 用于跟踪克隆状态和处理循环引用的上下文

Each clone operation should use a fresh CloneContext to track already-cloned objects and prevent infinite loops from circular references.

每次克隆操作应使用新的CloneContext来跟踪已克隆的对象，防止循环引用导致的无限循环。

Features | 主要功能:

  • Circular reference detection via IdentityHashMap - 通过IdentityHashMap检测循环引用
  • Clone depth tracking - 克隆深度跟踪
  • Clone path tracking for debugging - 用于调试的克隆路径跟踪
  • Statistics collection - 统计信息收集

Usage Examples | 使用示例:

CloneContext context = CloneContext.create();

// Check if object already cloned
if (context.isCloned(original)) {
    return context.getCloned(original);
}

// Register cloned object
context.registerCloned(original, cloned);

Security | 安全性:

  • Thread-safe: No (use separate context per thread) - 线程安全: 否（每线程使用单独上下文）
Since:
JDK 25, opencode-base-deepclone V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    CloneContext.CloneStatistics
    Clone statistics record 克隆统计信息记录

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addWarning(String warning)
    Adds a warning message (used in LENIENT mode) 添加警告消息（用于宽松模式）
    static CloneContext
    create()
    Creates a new CloneContext 创建新的CloneContext
    static CloneContext
    create(int maxDepth)
    Creates a new CloneContext with a max depth 创建指定最大深度的CloneContext
    static CloneContext
    create(int maxDepth, ClonePolicy policy)
    Creates a new CloneContext with max depth and policy 创建指定最大深度和策略的CloneContext
    int
    decrementDepth()
    Decrements the depth and returns the new value 减少深度并返回新值
    <T> T
    getCloned(Object original)
    Gets the cloned copy of an object 获取对象的克隆副本
    Map<Object,Object>
    getClonedObjects()
    Gets the map of cloned objects 获取已克隆对象的映射
    int
    getDepth()
    Gets the current clone depth 获取当前克隆深度
    int
    getMaxDepth()
    Gets the maximum allowed depth 获取允许的最大深度
    List<String>
    getPath()
    Gets the current clone path 获取当前克隆路径
    String
    getPathString()
    Gets the current path as a string 获取当前路径字符串
    ClonePolicy
    getPolicy()
    Gets the clone policy 获取克隆策略
    CloneContext.CloneStatistics
    getStatistics()
    Gets clone statistics 获取克隆统计信息
    List<String>
    getWarnings()
    Gets all warning messages 获取所有警告消息
    int
    incrementDepth()
    Increments the depth and returns the new value 增加深度并返回新值
    void
    incrementSkipped()
    Increments the skipped objects count 增加跳过对象计数
    boolean
    isCloned(Object original)
    Checks if an object has already been cloned 检查对象是否已被克隆
    boolean
    isLenient()
    Checks if the policy is lenient 检查策略是否为宽松模式
    boolean
    isMaxDepthExceeded()
    Checks if max depth has been exceeded 检查是否超过最大深度
    boolean
    isStrict()
    Checks if the policy is strict 检查策略是否为严格模式
    void
    popPath()
    Pops an element from the path 从路径弹出元素
    void
    pushPath(String element)
    Pushes an element onto the path 将元素压入路径
    void
    registerCloned(Object original, Object cloned)
    Registers a cloned object mapping 注册克隆对象映射

    Methods inherited from class Object

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

  • Method Details

    • create

      public static CloneContext create()
      Creates a new CloneContext 创建新的CloneContext
      Returns:
      the new context | 新的上下文

    • create

      public static CloneContext create(int maxDepth)
      Creates a new CloneContext with a max depth 创建指定最大深度的CloneContext
      Parameters:
      maxDepth - the maximum depth | 最大深度
      Returns:
      the new context | 新的上下文

    • create

      public static CloneContext create(int maxDepth, ClonePolicy policy)
      Creates a new CloneContext with max depth and policy 创建指定最大深度和策略的CloneContext
      Parameters:
      maxDepth - the maximum depth | 最大深度
      policy - the clone policy | 克隆策略
      Returns:
      the new context | 新的上下文

    • getClonedObjects

      public Map<Object,Object> getClonedObjects()
      Gets the map of cloned objects 获取已克隆对象的映射
      Returns:
      the original-to-clone mapping | 原始对象到克隆对象的映射

    • isCloned

      public boolean isCloned(Object original)
      Checks if an object has already been cloned 检查对象是否已被克隆
      Parameters:
      original - the original object | 原始对象
      Returns:
      true if already cloned | 如果已克隆返回true

    • getCloned

      public <T> T getCloned(Object original)
      Gets the cloned copy of an object 获取对象的克隆副本
      Type Parameters:
      T - the object type | 对象类型
      Parameters:
      original - the original object | 原始对象
      Returns:
      the cloned copy, or null if not cloned | 克隆副本，如果未克隆则为null

    • registerCloned

      public void registerCloned(Object original, Object cloned)
      Registers a cloned object mapping 注册克隆对象映射
      Parameters:
      original - the original object | 原始对象
      cloned - the cloned object | 克隆对象

    • incrementSkipped

      public void incrementSkipped()
      Increments the skipped objects count 增加跳过对象计数

    • getDepth

      public int getDepth()
      Gets the current clone depth 获取当前克隆深度
      Returns:
      the current depth | 当前深度

    • getMaxDepth

      public int getMaxDepth()
      Gets the maximum allowed depth 获取允许的最大深度
      Returns:
      the max depth | 最大深度

    • incrementDepth

      public int incrementDepth()
      Increments the depth and returns the new value 增加深度并返回新值
      Returns:
      the new depth | 新深度

    • decrementDepth

      public int decrementDepth()
      Decrements the depth and returns the new value 减少深度并返回新值
      Returns:
      the new depth | 新深度

    • isMaxDepthExceeded

      public boolean isMaxDepthExceeded()
      Checks if max depth has been exceeded 检查是否超过最大深度
      Returns:
      true if max depth exceeded | 如果超过最大深度返回true

    • getPath

      public List<String> getPath()
      Gets the current clone path 获取当前克隆路径
      Returns:
      the path as a list | 路径列表

    • getPathString

      public String getPathString()
      Gets the current path as a string 获取当前路径字符串
      Returns:
      the path string | 路径字符串

    • pushPath

      public void pushPath(String element)
      Pushes an element onto the path 将元素压入路径
      Parameters:
      element - the path element | 路径元素

    • popPath

      public void popPath()
      Pops an element from the path 从路径弹出元素

    • getPolicy

      public ClonePolicy getPolicy()
      Gets the clone policy 获取克隆策略
      Returns:
      the policy | 策略

    • isLenient

      public boolean isLenient()
      Checks if the policy is lenient 检查策略是否为宽松模式
      Returns:
      true if lenient | 如果是宽松模式返回true

    • isStrict

      public boolean isStrict()
      Checks if the policy is strict 检查策略是否为严格模式
      Returns:
      true if strict | 如果是严格模式返回true

    • addWarning

      public void addWarning(String warning)
      Adds a warning message (used in LENIENT mode) 添加警告消息（用于宽松模式）
      Parameters:
      warning - the warning message | 警告消息

    • getWarnings

      public List<String> getWarnings()
      Gets all warning messages 获取所有警告消息
      Returns:
      unmodifiable list of warnings | 不可修改的警告列表

    • getStatistics

      public CloneContext.CloneStatistics getStatistics()
      Gets clone statistics 获取克隆统计信息
      Returns:
      the statistics | 统计信息