模块 jdk.jdi
包 com.sun.jdi

接口 VirtualMachine

所有父级接口：
Mirror
所有已知的子接口：
PathSearchingVirtualMachine
public interface VirtualMachine extends Mirror
用于调试的虚拟机。更准确地说，一个 mirror 表示目标 VM 的复合状态。所有其他镜像都与该接口的一个实例相关联。对所有其他镜像的访问是通过此接口的实例直接或间接实现的。此接口直接支持对全局 VM 属性的访问和对 VM 执行的控制。

此接口的实例由 Connector 的实例创建。例如，AttachingConnector 附加到目标 VM 并返回其虚拟机镜像。连接器通常会通过调用 VirtualMachineManager 的 VirtualMachineManager.createVirtualMachine(Connection) createVirtualMachine(Connection) 方法来创建 VirtualMachine。

请注意，在收到 VMStartEvent 之前，不能保证由启动连接器启动的目标 VM 是稳定的。

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

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

自从：
1.3

  • 字段详细信息

    • TRACE_NONE

      static final int TRACE_NONE
      禁用所有跟踪。
      参见：

    • TRACE_SENDS

      static final int TRACE_SENDS
      为发送到目标 VM 的 JDWP 数据包启用跟踪。
      参见：

    • TRACE_RECEIVES

      static final int TRACE_RECEIVES
      为从目标 VM 接收到的 JDWP 数据包启用跟踪。
      参见：

    • TRACE_EVENTS

      static final int TRACE_EVENTS
      为内部事件处理启用跟踪。
      参见：

    • TRACE_REFTYPES

      static final int TRACE_REFTYPES
      为引用类型的内部管理启用跟踪。
      参见：

    • TRACE_OBJREFS

      static final int TRACE_OBJREFS
      为对象引用的内部管理启用跟踪。
      参见：

    • TRACE_ALL

      static final int TRACE_ALL
      启用所有跟踪。
      参见：

  • 方法详情

    • allModules

      default List <ModuleReference > allModules()
      返回所有模块。对于目标 VM 中的每个模块，ModuleReference 将被放置在返回的列表中。

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

      实现要求：
      默认实现抛出 UnsupportedOperationException 。
      返回：
      ModuleReference 对象的列表，每个对象都镜像目标 VM 中的一个模块。
      抛出：
      UnsupportedOperationException - 如果目标虚拟机不支持此操作。
      自从：
      9

    • classesByName

      List <ReferenceType > classesByName(String  className)
      返回与给定名称匹配的加载引用类型。该名称必须是完全限定的（例如，java.lang.String）。对于使用给定名称找到的每个类或接口，返回的列表将包含一个 ReferenceType 。搜索仅限于加载的类；不会尝试加载给定名称的类。

      返回的列表将包括至少加载到准备点的引用类型和未定义准备的类型（如数组）。

      参数：
      className - 要搜索的类/接口名称
      返回：
      ReferenceType 对象的列表，每个对象都使用给定名称镜像目标 VM 中的一种类型。

    • allClasses

      List <ReferenceType > allClasses()
      返回目标 VM 中的所有 加载类型。

      返回的列表包括所有引用类型，包括 hidden classes or interfaces ，至少加载到准备点和未定义准备的类型（如数组）。

      返回：
      ReferenceType 对象的列表，每个对象都镜像目标 VM 中的一个加载类型。
      参见：

    • redefineClasses

      void redefineClasses(Map <? extends ReferenceType ,byte[]> classToBytes)
      根据提供的定义重新定义所有给定的类。重新定义的类中的方法称为“等效”（对于该方法的旧版本）如果
      • 除了常量池中的索引外，它们的字节码是相同的，并且
      • 引用的常量相等。
      否则，新方法称为“非等效”。如果重新定义的方法具有活动堆栈帧，则这些活动堆栈帧将继续运行该方法的先前版本的字节码。如果此类方法的新版本不等效，则来自这些活动框架之一的方法称为“过时”，并且 Method.isObsolete() 在调用这些方法之一时将返回 true。如果需要重置这样的框架，请使用 ThreadReference.popFrames(StackFrame) 从堆栈中弹出旧的过时方法执行。重新定义方法的新调用将始终调用新版本。

      这个函数不会导致任何初始化，除非在通常的 JVM 语义下会发生初始化。换句话说，重新定义一个类不会导致其初始化程序运行。预先存在的静态变量的值将保持在调用之前的状态。然而，完全未初始化的（新的）静态变量将被赋予它们的默认值。

      如果重新定义的类有实例，那么所有这些实例都将在调用完成时具有由重新定义的类定义的字段。先前存在的字段将保留其先前的值。任何新字段都将具有默认值；没有运行实例初始化程序或构造方法。

      线程不需要暂停。

      此函数不生成任何事件。

      删除重新定义的类中的所有断点。

      并非所有目标虚拟机都支持此操作。使用 canRedefineClasses() 确定是否支持该操作。使用canAddMethod() 判断重定义是否可以添加方法。使用canUnrestrictedlyRedefineClasses() 判断重定义是否可以改变schema、删除方法、改变类层次等。

      参数：
      classToBytes - 从 ReferenceType 到字节数组的映射。字节表示新的类定义并且采用 Java 虚拟机类文件格式。
      抛出：
      UnsupportedOperationException - 如果目标虚拟机不支持此操作。
      NoClassDefFoundError - 如果字节不对应于引用类型（名称不匹配）。
      VerifyError - 如果“验证者”检测到一个类虽然格式正确，但包含内部不一致或安全问题。
      ClassFormatError - 如果字节不代表有效类。
      ClassCircularityError - 如果在初始化类时检测到循环。
      UnsupportedClassVersionError - 如果 VM 不支持以字节为单位的主要和次要版本号。
      VMCannotBeModifiedException - 如果 VirtualMachine 是只读的 - 请参阅 canBeModified() 。
      自从：
      1.4
      参见：

    • allThreads

      List <ThreadReference > allThreads()
      返回目标 VM 中的活动线程列表。尚未启动的线程或已终止的线程不包括在列表中。

      返回的列表包含目标 VM 中每个活动的 平台线程 的 ThreadReference。这包括使用 java.lang.Thread API 创建的平台线程和使用 JNI代码 附加到目标 VM 的所有本机线程。

      如果列表包含目标 VM 中实时 虚拟线程 的元素，则取决于实现。目标 VM 可能不会返回任何对虚拟线程的引用，或者它可能被配置为返回对某些或所有虚拟线程的引用。想要跟踪所有虚拟线程的工具可以启用 ThreadStartRequest 和 ThreadDeathRequest 以在虚拟线程启动和终止时获得通知。

      返回：
      目标 VM 中线程的 ThreadReference 对象列表

    • suspend

      void suspend()
      暂停在此虚拟机中运行的应用程序的执行。当前运行的所有线程都将被挂起。

      计算虚拟机和单个线程的挂起。在线程再次运行之前，它必须恢复（通过 resume() 或 ThreadReference.resume() ）与暂停次数相同的次数。

      抛出：
      VMCannotBeModifiedException - 如果虚拟机是只读的
      参见：

    • resume

      void resume()
      继续执行在此虚拟机中运行的应用程序。所有线程都按照 ThreadReference.resume() 中的记录恢复。
      抛出：
      VMCannotBeModifiedException - 如果虚拟机是只读的
      参见：

    • topLevelThreadGroups

      List <ThreadGroupReference > topLevelThreadGroups()
      返回没有父线程组的每个线程组。对于每个顶级线程组，一个 ThreadGroupReference 被放置在返回的列表中。

      此命令可用作构建现有线程组的树（或多个树）的第一步。

      返回：
      ThreadGroupReference 对象列表，每个顶级线程组一个。

    • eventQueue

      EventQueue  eventQueue()
      返回此虚拟机的事件队列。一个虚拟机只有一个EventQueue 对象，这个方法每次调用都会返回同一个实例。
      返回：
      此虚拟机的 EventQueue 。
      抛出：
      VMCannotBeModifiedException - 如果 VirtualMachine 是只读的 - 请参阅 canBeModified() 。

    • eventRequestManager

      EventRequestManager  eventRequestManager()
      返回此虚拟机的事件请求管理器。 EventRequestManager 控制用户可设置的事件，例如断点。一个虚拟机只有一个EventRequestManager 对象，这个方法每次调用都会返回同一个实例。
      返回：
      此虚拟机的 EventRequestManager 。
      抛出：
      VMCannotBeModifiedException - 如果 VirtualMachine 是只读的 - 请参阅 canBeModified() 。

    • mirrorOf

      BooleanValue  mirrorOf(boolean value)
      为给定值创建一个 BooleanValue 。该值可用于设置和比较从该虚拟机中的变量或字段检索的值。
      参数：
      value - 为其创建值的boolean
      返回：
      给定boolean的 BooleanValue 。

    • mirrorOf

      ByteValue  mirrorOf(byte value)
      为给定值创建一个 ByteValue 。该值可用于设置和比较从该虚拟机中的变量或字段检索的值。
      参数：
      value - 为其创建值的字节
      返回：
      给定字节的 ByteValue 。

    • mirrorOf

      CharValue  mirrorOf(char value)
      为给定值创建一个 CharValue 。该值可用于设置和比较从该虚拟机中的变量或字段检索的值。
      参数：
      value - 要为其创建值的字符
      返回：
      给定字符的 CharValue 。

    • mirrorOf

      ShortValue  mirrorOf(short value)
      为给定值创建一个 ShortValue 。该值可用于设置和比较从该虚拟机中的变量或字段检索的值。
      参数：
      value - 为其创建值的缩写
      返回：
      给定短的 ShortValue 。

    • mirrorOf

      IntegerValue  mirrorOf(int value)
      为给定值创建一个 IntegerValue 。该值可用于设置和比较从该虚拟机中的变量或字段检索的值。
      参数：
      value - 要为其创建值的 int
      返回：
      给定整数的 IntegerValue 。

    • mirrorOf

      LongValue  mirrorOf(long value)
      为给定值创建一个 LongValue 。该值可用于设置和比较从该虚拟机中的变量或字段检索的值。
      参数：
      value - 为其创造值的多头
      返回：
      给定多头的 LongValue 。

    • mirrorOf

      FloatValue  mirrorOf(float value)
      为给定值创建一个 FloatValue 。该值可用于设置和比较从该虚拟机中的变量或字段检索的值。
      参数：
      value - 为其创建值的浮点数
      返回：
      给定浮点数的 FloatValue 。

    • mirrorOf

      DoubleValue  mirrorOf(double value)
      为给定值创建一个 DoubleValue 。该值可用于设置和比较从该虚拟机中的变量或字段检索的值。
      参数：
      value - 为其创建值的双精度数
      返回：
      给定双精度的 DoubleValue 。

    • mirrorOf

      StringReference  mirrorOf(String  value)
      在此虚拟机中创建一个字符串。创建的字符串可用于设置和比较从该虚拟机中的变量或字段检索的字符串值。
      参数：
      value - 要创建的字符串
      返回：
      StringReference 镜像目标 VM 中新创建的字符串。
      抛出：
      VMCannotBeModifiedException - 如果 VirtualMachine 是只读的 - 请参阅 canBeModified() 。

    • mirrorOfVoid

      VoidValue  mirrorOfVoid()
      创建一个 VoidValue 。当要退出 void 方法时，可以将此值传递给 ThreadReference.forceEarlyReturn(com.sun.jdi.Value) 。
      返回：
      VoidValue 。

    • process

      Process  process()
      如果由 LaunchingConnector 启动，则返回此虚拟机的 Process 对象
      返回：
      此虚拟机的 Process 对象，如果它不是由 LaunchingConnector 启动的，则为 null。
      抛出：
      VMCannotBeModifiedException - 如果 VirtualMachine 是只读的 - 请参阅 canBeModified() 。

    • dispose

      void dispose()
      使该虚拟机镜像无效。到目标VM的通信通道关闭，目标VM准备接受来自这个调试器或另一个调试器的另一个后续连接，包括以下任务： 在目标 VM 中执行的任何当前方法调用在断开连接后继续。完成任何此类方法调用后，调用线程将从它最初停止的位置继续。

      源自此 VirtualMachine 的资源（ObjectReferences、ReferenceTypes 等）将变得无效。

    • exit

      void exit(int exitCode)
      导致镜像 VM 以给定的错误代码终止。与此 VirtualMachine 关联的所有资源都已释放。如果镜像 VM 是远程的，则与它的通信通道将被关闭。源自此 VirtualMachine 的资源（ObjectReferences、ReferenceTypes 等）将变得无效。

      在镜像 VM 中运行的线程突然终止。不会抛出线程死亡异常，也不会运行 finally 块。

      参数：
      exitCode - 目标 VM 的退出代码。在某些平台上，退出代码可能会被截断，例如，截断为低 8 位。
      抛出：
      VMCannotBeModifiedException - 如果 VirtualMachine 是只读的 - 请参阅 canBeModified() 。

    • canWatchFieldModification

      boolean canWatchFieldModification()
      确定目标 VM 是否支持用于字段修改的观察点。
      返回：
      true 如果支持该功能，false 否则。

    • canWatchFieldAccess

      boolean canWatchFieldAccess()
      确定目标 VM 是否支持现场访问观察点。
      返回：
      true 如果支持该功能，false 否则。

    • canGetBytecodes

      boolean canGetBytecodes()
      确定目标 VM 是否支持方法字节码的检索。
      返回：
      true 如果支持该功能，false 否则。

    • canGetSyntheticAttribute

      boolean canGetSyntheticAttribute()
      判断目标VM是否支持查询某个方法或字段的综合属性。
      返回：
      true 如果支持该功能，false 否则。

    • canGetOwnedMonitorInfo

      boolean canGetOwnedMonitorInfo()
      确定目标 VM 是否支持检索线程拥有的监视器。
      返回：
      true 如果支持该功能，false 否则。

    • canGetCurrentContendedMonitor

      boolean canGetCurrentContendedMonitor()
      确定目标 VM 是否支持检索线程当前正在等待的监视器。
      返回：
      true 如果支持该功能，false 否则。

    • canGetMonitorInfo

      boolean canGetMonitorInfo()
      确定目标 VM 是否支持检索对象的监视器信息。
      返回：
      true 如果支持该功能，false 否则。

    • canUseInstanceFilters

      boolean canUseInstanceFilters()
      确定目标 VM 是否支持按特定实例对象过滤事件。例如，请参阅 BreakpointRequest.addInstanceFilter(com.sun.jdi.ObjectReference) 。
      返回：
      true 如果支持该功能，false 否则。

    • canRedefineClasses

      boolean canRedefineClasses()
      确定目标 VM 是否支持任何级别的类重新定义。
      返回：
      true 如果支持该功能，false 否则。
      自从：
      1.4
      参见：

    • canAddMethod

      @Deprecated (since ="15") boolean canAddMethod()
      已弃用。
      基于 JVM TI 的 JDWP 后端永远不会将此功能设置为 true。
      确定目标 VM 是否支持在执行类重定义时添加方法。
      返回：
      true 如果支持该功能，false 否则。
      自从：
      1.4
      参见：

    • canUnrestrictedlyRedefineClasses

      @Deprecated (since ="15") boolean canUnrestrictedlyRedefineClasses()
      已弃用。
      基于 JVM TI 的 JDWP 后端永远不会将此功能设置为 true。
      确定目标 VM 在执行类重新定义时是否支持更改，否则受 redefineClasses(java.util.Map<? extends com.sun.jdi.ReferenceType, byte[]>) 限制。
      返回：
      true 如果支持该功能，false 否则。
      自从：
      1.4
      参见：

    • canPopFrames

      boolean canPopFrames()
      确定目标 VM 是否支持线程堆栈的弹出帧。
      返回：
      true 如果支持该功能，false 否则。
      自从：
      1.4
      参见：

    • canGetSourceDebugExtension

      boolean canGetSourceDebugExtension()
      确定目标 VM 是否支持获取源调试扩展。
      返回：
      true 如果支持该功能，false 否则。
      自从：
      1.4
      参见：

    • canRequestVMDeathEvent

      boolean canRequestVMDeathEvent()
      确定目标 VM 是否支持创建 VMDeathRequest s。
      返回：
      true 如果支持该功能，false 否则。
      自从：
      1.4
      参见：

    • canGetMethodReturnValues

      boolean canGetMethodReturnValues()
      确定目标 VM 是否支持在 MethodExitEvent s 中包含返回值。
      返回：
      true 如果支持该功能，false 否则。
      自从：
      1.6
      参见：

    • canGetInstanceInfo

      boolean canGetInstanceInfo()
      确定目标 VM 是否支持访问类实例、实例计数和引用对象。
      返回：
      true 如果支持该功能，false 否则。
      自从：
      1.6
      参见：

    • canUseSourceNameFilters

      boolean canUseSourceNameFilters()
      确定目标 VM 是否支持按源名称过滤类准备事件。见ClassPrepareRequest.addSourceNameFilter(java.lang.String) 。
      返回：
      true 如果支持该功能，false 否则。
      自从：
      1.6

    • canForceEarlyReturn

      boolean canForceEarlyReturn()
      确定目标 VM 是否支持强制方法提前返回。
      返回：
      true 如果支持该功能，false 否则。
      自从：
      1.6
      参见：

    • canBeModified

      boolean canBeModified()
      确定目标 VM 是否为只读 VM。如果在只读 VM 上调用会修改 VM 状态的方法，则会抛出 VMCannotBeModifiedException 。
      返回：
      true 如果支持该功能，false 否则。
      自从：
      1.5

    • canRequestMonitorEvents

      boolean canRequestMonitorEvents()
      确定目标 VM 是否支持创建 MonitorContendedEnterRequest s。 MonitorContendedEnteredRequest s。 MonitorWaitRequest s。 MonitorWaitedRequest s。
      返回：
      true 如果支持该功能，false 否则。
      自从：
      1.6
      参见：

    • canGetMonitorFrameInfo

      boolean canGetMonitorFrameInfo()
      确定目标 VM 是否支持获取哪个框架已获取监视器。
      返回：
      true 如果支持该功能，false 否则。
      自从：
      1.6
      参见：

    • canGetClassFileVersion

      boolean canGetClassFileVersion()
      确定目标 VM 是否支持读取类文件的主要版本和次要版本。
      返回：
      true 如果支持该功能，false 否则。
      自从：
      1.6
      参见：

    • canGetConstantPool

      boolean canGetConstantPool()
      判断目标VM是否支持获取类的常量池信息。
      返回：
      true 如果支持该功能，false 否则。
      自从：
      1.6
      参见：

    • canGetModuleInfo

      default boolean canGetModuleInfo()
      确定目标 VM 是否支持获取有关模块的信息。
      实现要求：
      默认实现返回 false 。
      返回：
      true 如果支持该功能，false 否则
      自从：
      9
      参见：

    • setDefaultStratum

      void setDefaultStratum(String  stratum)
      设置此 VM 的默认层（有关层的讨论，请参阅 Location ）。覆盖类文件中每个类的默认设置。

      影响位置查询（例如 Location.sourceName() ）和单步执行中使用的线边界。

      参数：
      stratum - 设置为 VM 默认值的层，或者为 null 以使用每个类的默认值。
      抛出：
      UnsupportedOperationException - 如果目标虚拟机不支持此操作。
      自从：
      1.4

    • getDefaultStratum

      String  getDefaultStratum()
      返回此 VM 的默认层。
      返回：
      null（意味着应该使用每类默认值 - ReferenceType.defaultStratum() -）除非已使用 setDefaultStratum(String) 设置默认层。
      自从：
      1.4
      参见：

    • instanceCounts

      long[] instanceCounts(List <? extends ReferenceType > refTypes)
      返回“refTypes”列表中每个 ReferenceType 的实例数。仅计算出于垃圾收集目的可访问的实例。

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

      参数：
      refTypes - 要获取其计数的 ReferenceType 对象的列表。
      返回：
      long 的数组，包含“refTypes”列表中每个元素的一个元素。数组的元素 i 包含“refTypes”列表中位置 i 处 ReferenceType 的目标 VM 中的实例数。如果“refTypes”列表为空，则返回零长度数组。如果 refTypes 中的 ReferenceType 已被垃圾回收，则其实例计数将返回零。
      抛出：
      UnsupportedOperationException - 如果目标虚拟机不支持此操作 - 请参阅 canGetInstanceInfo()
      NullPointerException - 如果“refTypes”列表为空。
      自从：
      1.6
      参见：

    • description

      String  description()
      返回有关目标 VM 和镜像它的调试器支持的文本信息。不保证此信息的特定格式。通常，此字符串包含目标 VM 和调试器接口的版本信息。可通过 version() 、VirtualMachineManager.majorInterfaceVersion() 和 VirtualMachineManager.minorInterfaceVersion() 获得有关 VM 和 JDI 版本的更精确信息
      返回：
      说明。

    • version

      String  version()
      返回属性 java.version 报告的目标 VM 中 Java 运行时环境的版本。获取JDI接口版本，使用VirtualMachineManager.majorInterfaceVersion() 和VirtualMachineManager.minorInterfaceVersion()
      返回：
      目标虚拟机版本。

    • name

      String  name()
      返回属性 java.vm.name 报告的目标 VM 的名称。
      返回：
      目标 VM 名称。

    • setDebugTraceMode

      void setDebugTraceMode(int traceFlags)
      跟踪 com.sun.jdi 实现执行的活动。所有跟踪信息都输出到 System.err。给定的跟踪标志用于将输出限制为仅包含所需的信息。给定的标志有效，相应的跟踪将继续，直到下一次调用此方法。

      输出依赖于实现，跟踪模式可能会被忽略。

      参数：
      traceFlags - 标识要启用的跟踪类型。