Module jdk.jdi
Package com.sun.jdi

Interface VirtualMachine

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

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

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

如果目标虚拟机断开连接并且VMDisconnectEvent已被接收或可从EventQueue中读取，则在VirtualMachine上采用VirtualMachine作为参数的任何方法可能会抛出VMDisconnectedException。

如果目标虚拟机已耗尽内存，则在VirtualMachine上采用VirtualMachine作为参数的任何方法可能会抛出VMOutOfMemoryException。

自版本:
1.3

  • Field Details

    • TRACE_NONE

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

    • TRACE_SENDS

      static final int TRACE_SENDS
      向目标虚拟机发送的JDWP数据包的跟踪已启用。
      参见:

    • TRACE_RECEIVES

      static final int TRACE_RECEIVES
      从目标虚拟机接收的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
      所有跟踪已启用。
      参见:

  • Method Details

    • allModules

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

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

      实现要求:
      默认实现会抛出 UnsupportedOperationException。
      返回:
      一个 ModuleReference 对象列表，每个对象反映目标虚拟机中的一个模块。
      抛出:
      UnsupportedOperationException - 如果目标虚拟机不支持此操作。
      自版本:
      9

    • classesByName

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

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

      参数:
      className - 要搜索的类/接口名称
      返回:
      一个 ReferenceType 对象列表，每个对象反映目标虚拟机中具有给定名称的类型。

    • allClasses

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

      返回的列表包括所有引用类型，包括 隐藏类或接口，至少加载到准备阶段的类型（如数组），以及准备未定义的类型。

      返回:
      一个 ReferenceType 对象列表，每个对象反映目标虚拟机中已加载的类型。
      参见:

    • redefineClasses

      void redefineClasses(Map<? extends ReferenceType,byte[]> classToBytes)
      所有给定的类都根据提供的定义重新定义。如果重新定义类中的方法被称为“等效”（与方法的旧版本相同），则：
      • 它们的字节码相同，除了常量池中的索引，以及
      • 引用的常量是相等的。
      否则，新方法被称为“非等效”。如果重新定义的方法具有活动栈帧，则这些活动帧将继续运行先前版本方法的字节码。如果新版本的方法是非等效的，则其中一个活动帧中的方法被称为“过时”，当在这些方法之一上调用 Method.isObsolete() 时将返回 true。如果希望重置这样的帧，请使用 ThreadReference.popFrames(StackFrame) 弹出栈中旧的过时方法执行。重新定义方法的新调用将始终调用新版本。

      此函数不会引起任何初始化，除非按照通常的 JVM 语义发生初始化。换句话说，重新定义类不会导致其初始化器运行。现有静态变量的值将保持调用之前的值。但是，完全未初始化（新的）静态变量将被分配其默认值。

      如果重新定义的类具有实例，则所有这些实例将在调用完成时具有重新定义类定义的字段。现有字段将保留其先前的值。任何新字段将具有其默认值；不会运行任何实例初始化程序或构造函数。

      线程无需暂停。

      此函数不会生成任何事件。

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

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

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

    • allThreads

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

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

      列表是否包含目标虚拟机中的活动 虚拟线程 取决于实现。目标虚拟机可能不返回对虚拟线程的任何引用，或者可能配置为返回对某些或所有虚拟线程的引用。希望跟踪所有虚拟线程的工具可以启用 ThreadStartRequest 和 ThreadDeathRequest，以在虚拟线程启动和终止时收到通知。

      返回:
      一个 ThreadReference 对象列表，表示目标虚拟机中的线程

    • suspend

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

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

      抛出:
      VMCannotBeModifiedException - 如果 VirtualMachine 是只读的
      参见:

    • resume

      void resume()
      继续运行在此虚拟机中的应用程序。所有线程都将如 ThreadReference.resume() 中所述恢复。
      抛出:
      VMCannotBeModifiedException - 如果 VirtualMachine 是只读的
      参见:

    • 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 - 要创建值的布尔值
      返回:
      给定布尔值的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 - 要创建值的整型
      返回:
      给定整型的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 - 要创建的字符串
      返回:
      反映目标VM中新创建的字符串的StringReference。
      抛出:
      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()
      确定目标虚拟机是否支持检索线程当前正在等待的监视器。
      返回值:
      如果支持该功能，则返回true，否则返回false。

    • canGetMonitorInfo

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

    • canUseInstanceFilters

      boolean canUseInstanceFilters()
      确定目标虚拟机是否支持通过特定实例对象筛选事件。例如，参见BreakpointRequest.addInstanceFilter(com.sun.jdi.ObjectReference)。
      返回值:
      如果支持该功能，则返回true，否则返回false。

    • canRedefineClasses

      boolean canRedefineClasses()
      确定目标虚拟机是否支持任何级别的类重定义。
      返回值:
      如果支持该功能，则返回true，否则返回false。
      自版本:
      1.4
      参见:

    • canAddMethod

      @Deprecated(since="15") boolean canAddMethod()
      Deprecated.
      A JVM TI based JDWP back-end will never set this capability to true.
      确定目标虚拟机是否支持在执行类重定义时添加方法。
      返回值:
      如果支持该功能，则返回true，否则返回false。
      自版本:
      1.4
      参见:

    • canUnrestrictedlyRedefineClasses

      @Deprecated(since="15") boolean canUnrestrictedlyRedefineClasses()
      Deprecated.
      A JVM TI based JDWP back-end will never set this capability to true.
      确定目标虚拟机是否支持在执行类重定义时支持的更改，否则受到redefineClasses(java.util.Map<? extends com.sun.jdi.ReferenceType, byte[]>)限制。
      返回值:
      如果支持该功能，则返回true，否则返回false。
      自版本:
      1.4
      参见:

    • canPopFrames

      boolean canPopFrames()
      确定目标虚拟机是否支持弹出线程堆栈的帧。
      返回值:
      如果支持该功能，则返回true，否则返回false。
      自版本:
      1.4
      参见:

    • canGetSourceDebugExtension

      boolean canGetSourceDebugExtension()
      确定目标虚拟机是否支持获取源调试扩展。
      返回值:
      如果支持该功能，则返回true，否则返回false。
      自版本:
      1.4
      参见:

    • canRequestVMDeathEvent

      boolean canRequestVMDeathEvent()
      确定目标虚拟机是否支持创建VMDeathRequest。
      返回值:
      如果支持该功能，则返回true，否则返回false。
      自版本:
      1.4
      参见:

    • canGetMethodReturnValues

      boolean canGetMethodReturnValues()
      确定目标虚拟机是否支持在MethodExitEvent中包含返回值。
      返回值:
      如果支持该功能，则返回true，否则返回false。
      自版本:
      1.6
      参见:

    • canGetInstanceInfo

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

    • canUseSourceNameFilters

      boolean canUseSourceNameFilters()
      确定目标虚拟机是否支持通过源名称筛选类准备事件。参见ClassPrepareRequest.addSourceNameFilter(java.lang.String)。
      返回值:
      如果支持该功能，则返回true，否则返回false。
      自版本:
      1.6

    • canForceEarlyReturn

      boolean canForceEarlyReturn()
      确定目标虚拟机是否支持强制方法提前返回。
      返回值:
      如果支持该功能，则返回true，否则返回false。
      自版本:
      1.6
      参见:

    • canBeModified

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

    • canRequestMonitorEvents

      boolean canRequestMonitorEvents()
      确定目标虚拟机是否支持创建MonitorContendedEnterRequest、MonitorContendedEnteredRequest、MonitorWaitRequest、MonitorWaitedRequest。
      返回值:
      如果支持该功能，则返回true，否则返回false。
      自版本:
      1.6
      参见:

    • canGetMonitorFrameInfo

      boolean canGetMonitorFrameInfo()
      确定目标虚拟机是否支持获取已获取监视器的帧。
      返回值:
      如果支持该功能，则返回true，否则返回false。
      自版本:
      1.6
      参见:

    • canGetClassFileVersion

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

    • canGetConstantPool

      boolean canGetConstantPool()
      确定目标虚拟机是否支持获取类的常量池信息。
      返回值:
      如果支持该功能，则返回true，否则返回false。
      自版本:
      1.6
      参见:

    • canGetModuleInfo

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

    • setDefaultStratum

      void setDefaultStratum(String stratum)
      设置此虚拟机的默认stratum（参见Location讨论strata）。覆盖类文件中设置的每类默认值。

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

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

    • getDefaultStratum

      String getDefaultStratum()
      返回此虚拟机的默认stratum。
      返回:
      null（表示应使用每个类的默认值 - ReferenceType.defaultStratum() - 除非已使用 setDefaultStratum(String) 设置了默认层）。
      自版本:
      1.4
      参见:

    • instanceCounts

      long[] instanceCounts(List<? extends ReferenceType> refTypes)
      返回'refTypes'列表中每个ReferenceType实例的数量。仅计算可达以进行垃圾回收的实例。

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

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

    • description

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

    • version

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

    • name

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

    • setDebugTraceMode

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

      输出是实现相关的，跟踪模式可能会被忽略。

      参数:
      traceFlags - 标识要启用哪种跟踪。