模块 jdk.jdi

软件包 com.sun.jdi

Interface VirtualMachineManager

public interface VirtualMachineManager

与目标虚拟机的连接管理器。 VirtualMachineManager允许一个应用程序调试多个目标VM。 （请注意，不支持converse;目标VM只能由一个调试器应用程序调试。）此接口包含管理与远程目标VM的连接以及获取可用目标VM的VirtualMachine镜像的方法。

可以使用多个不同的Connector对象之一进行连接。 每个连接器封装了一种将调试器与目标VM连接的不同方式。

VirtualMachineManager支持许多不同的方案，用于将调试器连接到虚拟机。 下表列出了四个例子。 这些示例在Sun的实现中使用命令行语法。 一些Connector实现可能需要稍微不同的处理，如下所示。

Four scenarios for connecting a debugger to a virtual machine" Scenario Description Debugger launches target VM (simplest, most-common scenario) Debugger calls the LaunchingConnector.launch(java.util.Map) method of the default connector, obtained with defaultConnector(). The target VM is launched, and a connection between that VM and the debugger is established. A VirtualMachine mirror is returned.

Or, for more control

• Debugger selects a connector from the list returned by launchingConnectors() with desired characteristics (for example, transport type, etc.).
• Debugger calls the LaunchingConnector.launch(java.util.Map) method of the selected connector. The target VM is launched, and a connection between that VM and the debugger is established. A VirtualMachine mirror is returned.

Debugger attaches to previously-running VM

• Target VM is launched using the options -agentlib:jdwp=transport=xxx,server=y
• Target VM generates and outputs the tranport-specific address at which it will listen for a connection.
• Debugger is launched. Debugger selects a connector in the list returned by attachingConnectors() matching the transport with the name "xxx".
• Debugger presents the default connector parameters (obtained through Connector.defaultArguments()) to the end user, allowing the user to fill in the transport-specific address generated by the target VM.
• Debugger calls the AttachingConnector.attach(java.util.Map) method of the selected to attach to the target VM. A VirtualMachine mirror is returned.

Target VM attaches to previously-running debugger

• At startup, debugger selects one or more connectors from the list returned by listeningConnectors() for one or more transports.
• Debugger calls the ListeningConnector.startListening(java.util.Map) method for each selected connector. For each call, a transport-specific address string is generated and returned. The debugger makes the transport names and corresponding address strings available to the end user.
• Debugger calls ListeningConnector.accept(java.util.Map) for each selected connector to wait for a target VM to connect.
• Later, target VM is launched by end user with the options -agentlib:jdwp=transport=xxx,address=yyy where "xxx" the transport for one of the connectors selected by the the debugger and "yyy" is the address generated by ListeningConnector.accept(java.util.Map) for that transport.
• Debugger's call to ListeningConnector.accept(java.util.Map) returns a VirtualMachine mirror.

Target VM launches debugger (sometimes called "Just-In-Time" debugging)

• Target VM is launched with the options -agentlib:jdwp=launch=cmdline,onuncaught=y,transport=xxx,server=y
• Later, an uncaught exception is thrown in the target VM. The target VM generates the tranport-specific address at which it will listen for a connection.
• Target VM launches the debugger with the following items concatenated together (separated by spaces) to form the command line:
  • The launch= value
  • The transport= value
  • The generated transport-specific address at which VM is listening for debugger connection.
• Upon launch, debugger selects a connector in the list returned by attachingConnectors() matching the transport with the name "xxx".
• Debugger changes the default connector parameters (obtained through Connector.defaultArguments()) to specify the transport specific address at which the VM is listenig. Optionally, other connector arguments can be presented to the user.
• Debugger calls the AttachingConnector.attach(java.util.Map) method of the selected to attach to the target VM. A VirtualMachine mirror is returned.

连接器在启动时创建。 也就是说，它们是在第一次调用Bootstrap.virtualMachineManager()时创建的。 可以通过调用allConnectors方法从VirtualMachineManager获取在启动时创建的所有连接器的列表。

如果连接器安装在平台上，则会在启动时创建连接器。 此外，VirtualMachineManager会自动创建连接器，以封装平台上安装的任何TransportService实现。 这里描述了这两种创建连接器的机制。

如果Connector安装在对Connector类型的定义类加载器可见的jar文件中，并且该jar文件在资源目录META-INF/services包含名为Connector的提供程序配置文件，并且提供程序配置文件列出Connector实现的完全限定类名。 Connector是实现Connector接口的类。 更适当地该类实现的特定连接器类型中的一种，即AttachingConnector ， ListeningConnector ，或LaunchingConnector 。 提供程序配置文件的格式是每行一个完全限定的类名。 每个类周围的空格和制表符以及空行都将被忽略。 注释字符为'#' （ 0x23 ），并且在每一行上忽略第一个注释字符后面的所有字符。 该文件必须以UTF-8编码。

在启动时，VirtualMachineManager尝试加载并实例化（使用no-arg构造函数）提供程序配置文件中列出的每个类。 捕获并忽略加载或创建连接器时抛出的异常。 换句话说，尽管有错误，启动过程仍在继续。

除了安装在平台上的连接器之外，VirtualMachineManager还将创建连接器以封装平台上安装的任何TransportService实现。 如果TransportService安装在对于TransportService类型的定义类加载器可见的jar文件中，并且该jar文件在资源目录META-INF/services包含名为TransportService的提供程序配置文件，并且提供程序配置文件列表， TransportService在平台上安装META-INF/services 。 TransportService实现的完全限定类名。 TransportService是TransportService的具体子类。 提供程序配置文件的格式与连接器的提供程序配置文件相同，只是列出的每个类必须是实现TransportService接口的类的完全限定类名。

对于平台上安装的每个TransportService，VirtualMachineManager创建相应的AttachingConnector和ListeningConnector 。 创建这些连接器是为了封装Transport ，而后者又封装了TransportService。 Attach将根据与字符串Attach连接的传输服务的名称进行命名。 例如，如果传输服务name()方法返回telepathic则telepathic将命名为telepathicAttach 。 类似地，ListeningConnector将以字符串Listen命名，该字符串标记在传输服务的名称上。 AttachingConnector和ListeningConnector的description()方法将委托给底层传输服务的description()方法。 AttachingConnector和ListeningConnector都有两个Connector Arguments 。 一个StringArgument命名为address的连接参数指定的地址过于重视，还是要听的。 甲IntegerArgument命名timeout是该连接器的参数时附接，或接受来指定超时。 可以忽略超时连接器，具体取决于传输服务是否支持附加超时或接受超时。

如果虚拟机管理器无法创建任何连接器，则初始化虚拟机管理器将失败，即Bootstrap.virtualMachineManager()将引发错误。

从以下版本开始：

1.3

方法摘要

变量和类型	方法	描述
List<Connector>	allConnectors()	返回所有已知Connector对象的列表。
List<AttachingConnector>	attachingConnectors()	返回已知AttachingConnector对象的列表。
List<VirtualMachine>	connectedVirtualMachines()	列出连接到调试器的所有目标VM。
VirtualMachine	createVirtualMachine(Connection connection)	创建一个新的虚拟机。
VirtualMachine	createVirtualMachine(Connection connection, Process process)	为目标VM创建虚拟机镜像。
LaunchingConnector	defaultConnector()	标识默认连接器。
List<LaunchingConnector>	launchingConnectors()	返回已知LaunchingConnector对象的列表。
List<ListeningConnector>	listeningConnectors()	返回已知ListeningConnector对象的列表。
int	majorInterfaceVersion()	返回JDI接口的主要版本号。
int	minorInterfaceVersion()	返回JDI接口的次要版本号。

方法详细信息

defaultConnector

LaunchingConnector defaultConnector()

标识默认连接器。 当不需要选择具有特定特性的连接器时，该连接器应用作启动连接器。

结果

默认为LaunchingConnector

launchingConnectors

List<LaunchingConnector> launchingConnectors()

返回已知LaunchingConnector对象的列表。 任何返回的对象都可用于启动新的目标VM，并立即为其创建一个VirtualMachine镜像。 请注意，发送连接器启动的目标VM在收到VMStartEvent之后才能保证稳定。

结果

LaunchingConnector对象的列表。

attachingConnectors

List<AttachingConnector> attachingConnectors()

返回已知AttachingConnector对象的列表。 任何返回的对象都可用于附加到现有目标VM，并为其创建一个VirtualMachine镜像。

结果

AttachingConnector个对象的列表。

listeningConnectors

List<ListeningConnector> listeningConnectors()

返回已知ListeningConnector对象的列表。 任何返回的对象都可以用于监听由目标VM发起的连接，并创建一个VirtualMachine它镜。

结果

ListeningConnector对象的列表。

allConnectors

List<Connector> allConnectors()

返回所有已知Connector对象的列表。

结果

Connector对象的列表。

connectedVirtualMachines

List<VirtualMachine> connectedVirtualMachines()

列出连接到调试器的所有目标VM。 该列表包括用于启动连接的任何目标VM的VirtualMachine个实例以及此管理器已启动连接的任何目标VM。 目标VM将保留在此列表中，直到VM断开连接。 从列表中删除VM后，将VMDisconnectEvent放置在事件队列中。

结果

VirtualMachine对象的列表，每个对象镜像一个目标VM。

majorInterfaceVersion

int majorInterfaceVersion()

返回JDI接口的主要版本号。 请参阅VirtualMachine.version()目标VM版本和信息以及VirtualMachine.description()更多版本信息。

结果

整数主要版本号。

minorInterfaceVersion

int minorInterfaceVersion()

返回JDI接口的次要版本号。 请参阅VirtualMachine.version()目标VM版本和信息以及VirtualMachine.description()更多版本信息。

结果

整数次要版本号

createVirtualMachine

VirtualMachine createVirtualMachine(Connection connection,
                                    Process process)
                             throws IOException

为目标VM创建虚拟机镜像。

为已存在Connection的目标VM创建虚拟机镜像。 当Connector建立连接并成功与目标VM握手时，将创建连接。 然后，Connector可以使用此方法创建虚拟机镜像以表示目标VM的复合状态。

process参数指定taget VM的Process对象。 它可能被指定为null 。 如果目标VM由LaunchingConnector启动，则应指定process参数，否则在创建的虚拟机上调用VirtualMachine.process()将返回null 。

存在此方法，以便连接器可以在与目标VM建立连接时创建虚拟机镜像。 只有创建新Connector实现的开发人员才需要直接使用此方法。

参数

connection - 与目标VM的开放连接。

process - 如果已启动， 则为目标VM的Process对象。 null如果没有启动。

结果

表示目标VM的新虚拟机。

异常

IOException - 如果发生I / O错误

IllegalStateException - 如果连接未打开

从以下版本开始：

1.5

另请参见：

Connection.isOpen() ， VirtualMachine.process()

createVirtualMachine

VirtualMachine createVirtualMachine(Connection connection)
                             throws IOException

创建一个新的虚拟机。

此方便方法的工作方式类似于调用createVirtualMachine(Connection, Process)方法并将null指定为process参数。

存在此方法，以便连接器可以在与目标VM建立连接时创建虚拟机镜像。 只有创建新Connector实现的开发人员才需要直接使用此方法。

结果

新的虚拟机

异常

IOException - 如果发生I / O错误

IllegalStateException - 如果连接未打开

从以下版本开始：

1.5