模块 jdk.jdi
包 com.sun.jdi

接口 StackFrame

所有父级接口：
Locatable , Mirror
public interface StackFrame extends Mirror , Locatable
线程调用堆栈上一个方法调用的状态。当线程执行时，堆栈帧会随着方法的调用而从其调用堆栈中被压入和弹出，然后返回。 StackFrame 在其线程执行的某个时刻从目标 VM 镜像一个这样的帧。那么，调用堆栈只是一个 StackFrame 对象列表。通过调用ThreadReference.frames() 可以在线程挂起时随时获取调用堆栈

StackFrames 提供对方法的局部变量及其当前值的访问。

StackFrame 的生命周期非常有限。它仅对挂起的线程可用，并且一旦其线程恢复就失效。

如果目标 VM 已断开连接并且 VMDisconnectEvent 已经或可从 EventQueue 读取，则 StackFrame 上以 StackFrame 作为参数的任何方法都可能抛出 VMDisconnectedException 。

如果目标 VM 内存不足，StackFrame 上以 StackFrame 作为参数的任何方法都可能抛出 VMOutOfMemoryException 。

自从：
1.3

  • 方法详情

    • location

      Location  location()
      返回帧中当前指令的Location 。创建此框架的方法也可以通过返回的位置访问。对于堆栈中的顶部帧，此位置标识要执行的下一条指令。对于所有其他帧，此位置标识导致调用下一帧方法的指令。如果框架表示本地方法调用，则返回的位置指示类和方法，但代码索引将无效 (-1)。
      指定者：
      location 在接口 Locatable 中
      返回：
      当前指令的Location 。
      抛出：
      InvalidStackFrameException - 如果此堆栈帧已失效。一旦框架的线程恢复，堆栈框架就不再有效。

    • thread

      ThreadReference  thread()
      返回运行此框架方法的线程。
      返回：
      a ThreadReference 镜像框架的线程。
      抛出：
      InvalidStackFrameException - 如果此堆栈帧已失效。一旦框架的线程恢复，堆栈框架就不再有效。

    • thisObject

      ObjectReference  thisObject()
      返回当前帧的“this”值。 'this' 的 ObjectReference 仅适用于非本机实例方法。
      返回：
      一个 ObjectReference ，如果框架表示本机或静态方法，则为 null。
      抛出：
      InvalidStackFrameException - 如果此堆栈帧已失效。一旦框架的线程恢复，堆栈框架就不再有效。

    • visibleVariables

      List <LocalVariable > visibleVariables() throws AbsentInformationException
      返回一个列表，其中包含可以从此框架的位置访问的每个 LocalVariable 。

      可见性基于此 StackFrame 的当前指令的代码索引。每个变量都有一个字节码索引范围，可以在其中访问它。如果这个栈帧的方法匹配这个变量的方法，并且如果这个栈帧的代码索引在变量的字节码范围内，那么这个变量是可见的。

      变量的字节码范围至少与该变量的范围一样大，但在某些情况下可以继续超出范围的末尾：

      • 编译器/VM 不会立即重用变量的槽。
      • 实现编译器/VM 以报告上述项目产生的扩展范围。
      扩展范围的优点是来自最近退出范围的变量可能仍可用于检查（这对循环索引特别有用）。如果作为上述扩展的结果，当前帧位置包含在多个同名局部变量的范围内，则为返回列表选择具有最高起始范围的变量。
      返回：
      当前可见的 LocalVariable 对象列表；如果没有可见变量，列表将为空；具体来说，本地方法中的框架将始终返回一个零长度列表。
      抛出：
      AbsentInformationException - 如果此方法没有局部变量信息。
      InvalidStackFrameException - 如果此堆栈帧已失效。一旦框架的线程恢复，堆栈框架就不再有效。
      NativeMethodException - 如果当前方法是原生的。

    • visibleVariableByName

      LocalVariable  visibleVariableByName(String  name) throws AbsentInformationException
      查找与给定名称匹配且在当前帧位置可见的 LocalVariable 。有关可见性的更多信息，请参见 visibleVariables() 。
      参数：
      name - 要查找的变量名
      返回：
      匹配的 LocalVariable ，如果没有具有给定名称的可见变量，则为 null ；本机方法中的框架将始终返回 null。
      抛出：
      AbsentInformationException - 如果此方法没有局部变量信息。
      InvalidStackFrameException - 如果此堆栈帧已失效。一旦框架的线程恢复，堆栈框架就不再有效。
      NativeMethodException - 如果当前方法是原生的。

    • getValue

      Value  getValue(LocalVariable  variable)
      在此帧中获取 LocalVariable 的 Value 。根据 visibleVariables() 中描述的规则，该变量必须对该框架的方法有效并且可见。
      参数：
      variable - 要访问的 LocalVariable
      返回：
      实例字段的Value 。
      抛出：
      IllegalArgumentException - 如果变量对该框架的方法无效或不可见。
      InvalidStackFrameException - 如果此堆栈帧已失效。一旦框架的线程恢复，堆栈框架就不再有效。

    • getValues

      Map <LocalVariable ,Value > getValues(List <? extends LocalVariable > variables)
      返回此帧中多个局部变量的值。根据 visibleVariables() 中描述的规则，每个变量必须对该框架的方法有效并且可见。
      参数：
      variables - 要访问的 LocalVariable 对象的列表
      返回：
      将每个 LocalVariable 与其 Value 相关联的map
      抛出：
      IllegalArgumentException - 如果任何变量对该框架的方法无效或不可见。
      InvalidStackFrameException - 如果此堆栈帧已失效。一旦框架的线程恢复，堆栈框架就不再有效。

    • setValue

      void setValue(LocalVariable  variable, Value  value) throws InvalidTypeException , ClassNotLoadedException
      在此帧中设置 LocalVariable 的 Value 。根据 visibleVariables() 中描述的规则，该变量必须对该框架的方法有效并且可见。

      在虚拟线程的情况下，当此帧是最顶层帧并且线程在断点或单步事件处挂起时，目标 VM 支持设置局部变量的值。在其他情况下，目标 VM 可能支持设置局部变量。

      对象值必须是与变量类型兼容的赋值（这意味着必须通过封闭类的类加载器加载变量类型）。原始值必须是与变量类型兼容的赋值，或者必须可转换为变量类型而不丢失信息。有关分配兼容性的更多信息，请参阅 JLS 5.2 节。

      参数：
      variable - 包含请求值的字段
      value - 要分配的新值
      抛出：
      IllegalArgumentException - 如果字段对该对象的类无效。
      InvalidTypeException - 如果值的类型与变量的类型不匹配。
      ClassNotLoadedException - 如果尚未通过适当的类加载器加载变量类型。
      InvalidStackFrameException - 如果此堆栈帧已失效。一旦框架的线程恢复，堆栈框架就不再有效。
      OpaqueFrameException - 如果此帧位于虚拟线程的调用堆栈上并且目标 VM 不支持在此帧中设置局部变量的值。
      VMCannotBeModifiedException - 如果 VirtualMachine 是只读的。
      参见：

    • getArgumentValues

      List <Value > getArgumentValues()
      返回此帧中所有参数的值。即使不存在局部变量信息，也会返回值。
      返回：
      包含此帧的每个参数的 Value 对象的列表，按照参数声明的顺序排列。如果与此框架对应的方法没有参数，则返回一个空列表。
      抛出：
      InvalidStackFrameException - 如果此堆栈帧已失效。一旦框架的线程恢复，堆栈框架就不再有效。
      自从：
      1.6