模块 jdk.jdi
包 com.sun.jdi

接口 ObjectReference

所有父级接口：
Mirror , Value
所有已知的子接口：
ArrayReference , ClassLoaderReference , ClassObjectReference , ModuleReference , StringReference , ThreadGroupReference , ThreadReference
public interface ObjectReference extends Value
当前存在于目标 VM 中的对象。 ObjectReference 仅镜像对象本身，并不特定于当前分配给它的任何 Field 或 LocalVariable 。 ObjectReference 可以有 0 个或多个来自字段和/或变量的引用。

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

如果目标 VM 内存不足，ObjectReference 上直接或间接将 ObjectReference 作为参数的任何方法都可能抛出 VMOutOfMemoryException 。

如果镜像对象已被垃圾回收，ObjectReference 上的任何方法或直接或间接将 ObjectReference 作为参数的任何方法都可能抛出 ObjectCollectedException 。

自从：
1.3

  • 字段详细信息

    • INVOKE_SINGLE_THREADED

      static final int INVOKE_SINGLE_THREADED
      仅恢复调用线程执行方法调用
      参见：

    • INVOKE_NONVIRTUAL

      static final int INVOKE_NONVIRTUAL
      执行非虚拟方法调用
      参见：

  • 方法详情

    • referenceType

      ReferenceType  referenceType()
      获取反映此对象类型的 ReferenceType 。该类型可以是当前持有它的任何字段或变量的声明类型的子类或实现者。例如，紧跟在以下语句之后。

      Object obj = new String("Hello, world!");

      obj 的 ReferenceType 将镜像 java.lang.String 而不是 java.lang.Object。

      对象的类型永远不会改变，因此此方法将在镜像对象的整个生命周期内始终返回相同的 ReferenceType。

      返回的 ReferenceType 将是 ClassType 或 ArrayType 而绝不会是 InterfaceType 。

      返回：
      该对象的 ReferenceType 。

    • getValue

      Value  getValue(Field  sig)
      获取此对象中给定实例或静态字段的值。该字段必须对此 ObjectReference 有效；也就是说，它必须来自镜像对象的类或该类的超类。
      参数：
      sig - 包含请求值的字段
      返回：
      实例字段的Value 。
      抛出：
      IllegalArgumentException - 如果字段对该对象的类无效。

    • getValues

      Map <Field ,Value > getValues(List <? extends Field > fields)
      获取此对象中多个实例和/或静态字段的值。字段必须对此 ObjectReference 有效；也就是说，它们必须来自镜像对象的类或该类的超类。
      参数：
      fields - 包含请求值的 Field 对象列表。
      返回：
      请求的 Field 对象及其 Value 的映射。
      抛出：
      IllegalArgumentException - 如果任何字段对此对象的类无效。

    • setValue

      void setValue(Field  field, Value  value) throws InvalidTypeException , ClassNotLoadedException
      设置此对象中给定实例或静态字段的值。 Field 必须对此 ObjectReference 有效；也就是说，它必须来自镜像对象的类或该类的超类。该字段不能是最终的。

      对象值必须是与字段类型兼容的赋值（这意味着必须通过封闭类的类加载器加载字段类型）。原始值必须是与字段类型兼容的分配，或者必须可转换为字段类型而不会丢失信息。见第 5.2 节Java 语言规范有关分配兼容性的更多信息。

      参数：
      field - 包含请求值的字段
      value - 要分配的新值
      抛出：
      IllegalArgumentException - 如果该字段对此对象的类无效或该字段是最终的。
      InvalidTypeException - 如果值的类型与字段的类型不匹配。
      ClassNotLoadedException - 如果“值”不为空，并且尚未通过适当的类加载器加载字段类型。
      VMCannotBeModifiedException - 如果 VirtualMachine 是只读的 - 请参阅 VirtualMachine.canBeModified() 。

    • invokeMethod

      Value  invokeMethod(ThreadReference  thread, Method  method, List <? extends Value > arguments, int options) throws InvalidTypeException , ClassNotLoadedException , IncompatibleThreadStateException , InvocationException
      在目标 VM 中的此对象上调用指定的 Method 。可以在此对象的类、此对象的类的超类或此对象实现的接口中定义指定的方法。该方法可以是静态方法或实例方法，但不能是静态初始化程序或构造函数。使用 ClassType.newInstance(com.sun.jdi.ThreadReference, com.sun.jdi.Method, java.util.List<? extends com.sun.jdi.Value>, int) 创建一个新对象并运行其构造函数。

      方法调用将发生在指定的线程中。仅当指定线程已被该线程中发生的事件挂起时，方法调用才会发生。当目标 VM 已通过 VirtualMachine.suspend() 挂起或指定线程通过 ThreadReference.suspend() 挂起时，不支持方法调用。

      使用指定参数列表中的参数调用指定的方法。方法调用是同步的；直到调用的方法在目标 VM 中返回，此方法才会返回。如果调用的方法抛出异常，此方法将抛出一个 InvocationException ，其中包含抛出的异常对象的镜像。

      对象参数必须是与参数类型兼容的赋值（这意味着参数类型必须通过封闭类的类加载器加载）。原始参数必须是与参数类型兼容的赋值，或者必须可转换为参数类型而不丢失信息。如果被调用的方法接受可变数量的参数，那么最后一个参数类型是某个组件类型的数组。匹配位置的参数可以省略，也可以为null，相同组件类型的数组，或者组件类型的参数后跟任意数量的其他相同类型的参数。如果省略参数，则传递组件类型的 0 长度数组。组件类型可以是原始类型。不支持自动装箱。见第 5.2 节Java 语言规范有关分配兼容性的更多信息。

      默认情况下，该方法是使用动态查找调用的，如第 15.12.4.4 节所述Java 语言规范特别是，将发生基于此 ObjectReference 镜像的对象的运行时类型的覆盖。可以通过在 options 参数中指定 INVOKE_NONVIRTUAL 位标志来更改此行为。如果设置了此标志，则调用指定的方法，无论它是否被此对象的运行时类型覆盖。在这种情况下，该方法必须在类或接口中有一个实现。此选项对于执行方法调用很有用，例如在 Java 编程语言中使用 super 关键字完成的调用。

      默认情况下，如果目标 VM 中的所有线程之前被事件或 VirtualMachine.suspend() 或 ThreadReference.suspend() 暂停，则在调用该方法时恢复。这样做是为了防止在任何线程拥有调用方法所需的监视器时发生死锁。但是请注意，此隐式恢复的行为与 ThreadReference.resume() 完全相同，因此如果线程的挂起计数大于 1，它将在调用期间保持挂起状态，因此仍可能发生死锁。默认情况下，当调用完成时，目标 VM 中的所有线程都被挂起，无论它们在调用之前的状态如何。调用期间可能会发生断点或其他事件。这会导致如上所述的死锁。如果从客户端的事件处理程序线程调用 invokeMethod，它也可能导致死锁。在这种情况下，该线程将等待 invokeMethod 完成并且不会读取为新事件传入的 EventSet。如果这个新的 EventSet 是 SUSPEND_ALL，那么就会发生死锁，因为没有人会恢复 EventSet。为避免这种情况，应在执行 invokeMethod 之前禁用所有 EventRequest，或者不应从客户端的事件处理程序线程执行 invokeMethod。

      通过在 options 参数中指定 INVOKE_SINGLE_THREADED 位标志，可以防止调用期间其他线程的恢复；但是，没有针对上述死锁的保护措施或从死锁中恢复的方法，因此应非常谨慎地使用此选项。只有指定的线程将被恢复（如上面所有线程所述）。单线程调用完成后，调用线程将再次挂起。请注意，在单线程调用期间启动的任何线程都不会在调用完成时挂起。

      如果目标 VM 在调用期间断开连接（例如，通过 VirtualMachine.dispose() ），方法调用将继续。

      参数：
      thread - 要在其中调用的线程。
      method - 要调用的 Method 。
      arguments - 绑定到调用方法的 Value 参数列表。列表中的值按照它们在方法签名中出现的顺序分配给参数。
      options - 整数位标志选项。
      返回：
      被调用方法返回值的 Value 镜像。
      抛出：
      IllegalArgumentException - 如果该方法不是该对象类的成员，如果参数列表的大小与该方法声明的参数数量不匹配，如果该方法是构造函数或静态初始化器，或者如果指定了 INVOKE_NONVIRTUAL 并且方法是抽象的。
      ClassNotLoadedException - 如果任何参数类型尚未通过适当的类加载器加载。
      IncompatibleThreadStateException - 如果指定的线程没有被事件挂起。
      InvocationException - 如果方法调用导致目标 VM 出现异常。
      InvalidTypeException - 如果参数不满足此要求——对象参数必须是与参数类型兼容的赋值。这意味着必须通过封闭类的类加载器加载参数类型。原始参数必须是与参数类型兼容的赋值，或者必须可转换为参数类型而不丢失信息。有关分配兼容性的更多信息，请参阅 JLS 5.2 节。
      VMCannotBeModifiedException - 如果 VirtualMachine 是只读的 - 请参阅 VirtualMachine.canBeModified() 。

    • disableCollection

      void disableCollection()
      防止对此对象进行垃圾收集。默认情况下，JDI 返回的所有 ObjectReference 值都可以在目标 VM 运行时随时收集。调用此方法可确保不会收集该对象。 enableCollection() 可用于允许再次收集。

      对该方法的调用被计算在内。每次调用此方法都需要在重新启用垃圾回收之前相应调用 enableCollection() 。

      请注意，当目标 VM 被挂起时，不会发生垃圾回收，因为所有线程都被挂起。挂起期间对变量、字段和数组的典型检查是安全的，无需显式禁用垃圾收集。

      应谨慎使用此方法，因为它会改变目标 VM 中的垃圾收集模式，因此可能导致调试器下的应用程序行为与其未调试的行为不同。

      抛出：
      VMCannotBeModifiedException - 如果 VirtualMachine 是只读的 - 请参阅 VirtualMachine.canBeModified() 。

    • enableCollection

      void enableCollection()
      允许对此对象进行垃圾回收。默认情况下，JDI 返回的所有 ObjectReference 值都可以在目标 VM 运行时随时收集。仅当先前使用 disableCollection() 禁用垃圾回收时才需要调用此方法。
      抛出：
      VMCannotBeModifiedException - 如果 VirtualMachine 是只读的 - 请参阅 VirtualMachine.canBeModified() 。

    • isCollected

      boolean isCollected()
      确定此对象是否已在目标 VM 中被垃圾回收。
      返回：
      true 如果此 ObjectReference 已被收集； false否则。
      抛出：
      VMCannotBeModifiedException - 如果 VirtualMachine 是只读的 - 请参阅 VirtualMachine.canBeModified() 。

    • uniqueID

      long uniqueID()
      返回此 ObjectReference 的唯一标识符。它保证在来自同一 VM 的所有尚未处置的 ObjectReferences 中是唯一的。只要此 ObjectReference 尚未被处置，该保证就适用。
      返回：
      一个长的唯一 ID

    • waitingThreads

      List <ThreadReference > waitingThreads() throws IncompatibleThreadStateException
      为当前等待此对象监视器的每个线程返回一个包含 ThreadReference 的列表。有关线程何时被视为等待监视器的信息，请参阅 ThreadReference.currentContendedMonitor() 。

      并非所有目标 VM 都支持此操作。请参阅 VirtualMachine#canGetMonitorInfo 以确定是否支持该操作。

      返回：
      ThreadReference 对象列表。如果没有线程在等待监视器，则该列表的长度为零。
      抛出：
      UnsupportedOperationException - 如果目标 VM 不支持此操作。
      IncompatibleThreadStateException - 如果任何等待线程未在目标 VM 中挂起

    • owningThread

      ThreadReference  owningThread() throws IncompatibleThreadStateException
      返回当前拥有此对象监视器的线程的 ThreadReference （如果有）。有关所有权的定义，请参阅 ThreadReference.ownedMonitors() 。

      并非所有目标 VM 都支持此操作。请参阅 VirtualMachine#canGetMonitorInfo 以确定是否支持该操作。

      返回：
      当前拥有监视器的 ThreadReference ，如果无人拥有则为 null。
      抛出：
      UnsupportedOperationException - 如果目标 VM 不支持此操作。
      IncompatibleThreadStateException - 如果拥有线程未在目标 VM 中挂起

    • entryCount

      int entryCount() throws IncompatibleThreadStateException
      返回当前所属线程进入此对象监视器的次数。有关所有权的定义，请参阅 ThreadReference.ownedMonitors() 。

      并非所有目标 VM 都支持此操作。请参阅 VirtualMachine#canGetMonitorInfo 以确定是否支持该操作。

      返回：
      条目数的整数计数。
      抛出：
      UnsupportedOperationException - 如果目标 VM 不支持此操作。
      IncompatibleThreadStateException - 如果拥有线程未在目标 VM 中挂起
      参见：

    • referringObjects

      List <ObjectReference > referringObjects(long maxReferrers)
      返回直接引用此对象的对象。仅返回可用于垃圾收集目的的对象。请注意，还可以通过其他方式引用对象，例如从堆栈帧中的局部变量或从 JNI 全局引用。此方法不返回此类非对象引用。

      并非所有目标虚拟机都支持此操作。使用 VirtualMachine.canGetInstanceInfo() 确定是否支持该操作。

      参数：
      maxReferrers - 要返回的引用对象的最大数量。必须是非负数。如果为零，则返回所有引用对象。
      返回：
      ObjectReference 对象列表的 a。如果没有引用该对象的对象，则返回一个零长度列表。
      抛出：
      UnsupportedOperationException - 如果目标虚拟机不支持此操作 - 请参阅 canGetInstanceInfo()
      IllegalArgumentException - 如果 maxReferrers 小于零。
      自从：
      1.6
      参见：

    • equals

      boolean equals(Object  obj)
      比较指定的 Object 与此 ObjectReference 是否相等。
      重写：
      equals 在类 Object 中
      参数：
      obj - 要比较的参考对象。
      返回：
      如果 Object 是 ObjectReference，如果 ObjectReferences 属于同一个 VM，并且如果在该 VM 中的镜像对象上应用“==”运算符计算结果为 true，则为 true。
      参见：

    • hashCode

      int hashCode()
      返回此 ObjectReference 的哈希码值。
      重写：
      hashCode 在类 Object 中
      返回：
      整数哈希码
      参见：