Record Class CallerInfo

java.lang.Object
java.lang.Record
cloud.opencode.base.log.CallerInfo
public record CallerInfo(String className, String methodName, String fileName, int lineNumber) extends Record
Caller Information Record - Captures Stack Frame Location 调用者信息记录 - 捕获堆栈帧位置

An immutable record that encapsulates the source location of a log call, including class name, method name, file name and line number.

一个不可变记录，封装日志调用的源位置信息， 包括类名、方法名、文件名和行号。

Features | 主要功能:

  • Captures caller location via StackWalker - 通过 StackWalker 捕获调用者位置
  • Provides short and compact string representations - 提供短格式和紧凑格式的字符串表示
  • Immutable and thread-safe - 不可变且线程安全
  • Supports frame skipping for wrapper methods - 支持跳过包装方法的帧

Usage Examples | 使用示例:

// Capture caller info
CallerInfo info = CallerInfo.capture();
System.out.println(info.toShortString());  // "MyClass.myMethod:42"

// Capture with additional frame skip
CallerInfo info = CallerInfo.capture(2);

// Use UNKNOWN for cases where caller info is unavailable
CallerInfo unknown = CallerInfo.UNKNOWN;

Security | 安全性:

  • Thread-safe: Yes (immutable record) - 线程安全: 是（不可变记录）
  • Null-safe: No (components must not be null) - 空值安全: 否（组件不能为 null）
Since:
JDK 25, opencode-base-log V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final CallerInfo
    UNKNOWN
    Unknown caller info constant, used when caller information is unavailable.

  • Constructor Summary

    Constructors
    Constructor
    Description
    CallerInfo(String className, String methodName, String fileName, int lineNumber)
    Compact constructor that validates non-null parameters.

  • Method Summary

    Modifier and Type
    Method
    Description
    static CallerInfo
    capture()
    Captures the caller location by walking the stack and skipping internal log frames.
    static CallerInfo
    capture(int skipFrames)
    Captures the caller location with additional frame skipping.
    String
    className()
    Returns the value of the className record component.
    final boolean
    equals(Object o)
    Indicates whether some other object is "equal to" this one.
    String
    fileName()
    Returns the value of the fileName record component.
    final int
    hashCode()
    Returns a hash code value for this object.
    int
    lineNumber()
    Returns the value of the lineNumber record component.
    String
    methodName()
    Returns the value of the methodName record component.
    String
    toCompactString()
    Returns a compact string representation in "SimpleClassName:line" format.
    String
    toShortString()
    Returns a short string representation in "SimpleClassName.method:line" format.
    String
    toString()
    Returns a string representation of this record class.

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • UNKNOWN

      public static final CallerInfo UNKNOWN
      Unknown caller info constant, used when caller information is unavailable. 未知调用者信息常量，当调用者信息不可用时使用。

  • Constructor Details

    • CallerInfo

      public CallerInfo(String className, String methodName, String fileName, int lineNumber)
      Compact constructor that validates non-null parameters. 紧凑构造函数，验证非空参数。
      Parameters:
      className - the fully qualified class name | 完全限定类名
      methodName - the method name | 方法名
      fileName - the source file name | 源文件名
      lineNumber - the line number | 行号

  • Method Details

    • capture

      public static CallerInfo capture()
      Captures the caller location by walking the stack and skipping internal log frames. 通过遍历堆栈并跳过内部日志帧来捕获调用者位置。
      Returns:
      the caller info, or UNKNOWN if not found | 调用者信息，如果未找到则返回 UNKNOWN

    • capture

      public static CallerInfo capture(int skipFrames)
      Captures the caller location with additional frame skipping. 捕获调用者位置，并跳过额外的帧数。

      The method automatically skips all internal frames from the cloud.opencode.base.log package, then skips the specified number of additional frames.

      该方法自动跳过 cloud.opencode.base.log 包中的所有内部帧， 然后跳过指定数量的额外帧。

      Parameters:
      skipFrames - the number of additional frames to skip | 要跳过的额外帧数
      Returns:
      the caller info, or UNKNOWN if not found | 调用者信息，如果未找到则返回 UNKNOWN
      Throws:
      IllegalArgumentException - if skipFrames is negative | 如果 skipFrames 为负数

    • toShortString

      public String toShortString()
      Returns a short string representation in "SimpleClassName.method:line" format. 返回 "简单类名.方法:行号" 格式的短字符串表示。
      Returns:
      short string representation | 短字符串表示

    • toCompactString

      public String toCompactString()
      Returns a compact string representation in "SimpleClassName:line" format. 返回 "简单类名:行号" 格式的紧凑字符串表示。
      Returns:
      compact string representation | 紧凑字符串表示

    • toString

      public String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with the compare method from their corresponding wrapper classes.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • className

      public String className()
      Returns the value of the className record component.
      Returns:
      the value of the className record component

    • methodName

      public String methodName()
      Returns the value of the methodName record component.
      Returns:
      the value of the methodName record component

    • fileName

      public String fileName()
      Returns the value of the fileName record component.
      Returns:
      the value of the fileName record component

    • lineNumber

      public int lineNumber()
      Returns the value of the lineNumber record component.
      Returns:
      the value of the lineNumber record component