Module jdk.jdi
Package com.sun.jdi

Interface StackFrame

所有超级接口:
Locatable, Mirror
public interface StackFrame extends Mirror, Locatable
一个线程调用堆栈上一个方法调用的状态。当线程执行时，随着方法的调用和返回，堆栈帧被推送和弹出。StackFrame在目标VM中镜像了线程执行过程中某个时刻的一个堆栈帧。因此，调用堆栈简单地是一个StackFrame对象的列表。可以在任何时候通过调用ThreadReference.frames()来获取调用堆栈。

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

StackFrame的生命周期非常有限。它仅在挂起的线程中可用，并且一旦其线程恢复，它就会变得无效。

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

如果StackFrame上的任何方法以StackFrame作为参数，则可能会在目标VM耗尽内存时抛出VMOutOfMemoryException。

自1.3版本起:
1.3

  • Method Details

    • location

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

    • thread

      ThreadReference thread()
      返回运行此帧方法的线程。
      返回:
      一个反映帧线程的ThreadReference。
      抛出:
      InvalidStackFrameException - 如果此堆栈帧已失效。一旦帧的线程恢复，堆栈帧将不再有效。

    • thisObject

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

    • visibleVariables

      List<LocalVariable> visibleVariables() throws AbsentInformationException
      返回包含可以从此帧位置访问的每个LocalVariable的列表。

      可见性基于此StackFrame当前指令的代码索引。每个变量都有一个字节码索引范围，在该范围内可以访问它。如果此堆栈帧的方法与此变量的方法匹配，并且此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关联的映射
      抛出:
      IllegalArgumentException - 如果任何变量对此帧的方法无效或不可见。
      InvalidStackFrameException - 如果此堆栈帧已失效。一旦帧的线程恢复，堆栈帧将不再有效。

    • setValue

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

      对于虚拟线程，当此帧是顶层帧且线程在事件上暂停时，目标VM支持设置局部变量的值。目标VM可能在其他情况下支持设置局部变量。

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

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

    • getArgumentValues

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