VirtualMachineManager (Java Debug Interface) - Java 2 SDK v1.4.2, Java 2 SDK 英文文档

Overview

Package

Class

Use

Tree

Index

Help

Java Debug Interface

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface VirtualMachineManager

public interface VirtualMachineManager

A manager of connections to target virtual machines. The VirtualMachineManager allows one application to debug multiple target VMs. (Note that the converse is not supported; a target VM can be debugged by only one debugger application.) This interface contains methods to manage connections to remote target VMs and to obtain the VirtualMachine mirror for available target VMs.

Connections can be made using one of several different Connector objects. Each connector encapsulates a different way of connecting the debugger with a target VM.

The VirtualMachineManager supports many different scenarios for connecting a debugger to a virtual machine. Four examples are presented in the table below. The examples use the command line syntax in Sun's classic VM. Some Connector implementations may require slightly different handling than presented below.

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 -Xrunjdwp:transport=xxx,server=y -Xdebug -Xnoagent -Djava.compiler=NONE

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 -Xrunjdwp:transport=xxx,address=yyy -Xdebug -Xnoagent -Djava.compiler=NONE 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 -Xrunjdwp: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.

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 `-Xrunjdwp:transport=xxx,server=y -Xdebug -Xnoagent -Djava.compiler=NONE` 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 `-Xrunjdwp:transport=xxx,address=yyy -Xdebug -Xnoagent -Djava.compiler=NONE` 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 `-Xrunjdwp: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.

Since:: 1.3

Method Summary

List allConnectors()
          Returns the list of all known Connector objects.

List attachingConnectors()
          Returns the list of known AttachingConnector objects.

List connectedVirtualMachines()
          Lists all target VMs which are connected to the debugger.

LaunchingConnector defaultConnector()
          Identifies the default connector.

List launchingConnectors()
          Returns the list of known LaunchingConnector objects.

List listeningConnectors()
          Returns the list of known ListeningConnector objects.

int majorInterfaceVersion()
          Returns the major version number of the JDI interface.

int minorInterfaceVersion()
          Returns the minor version number of the JDI interface.

Method Detail

defaultConnector

public LaunchingConnector defaultConnector()

Identifies the default connector. This connector should be used as the launching connector when selection of a connector with specific characteristics is unnecessary.

Returns:: the default LaunchingConnector

launchingConnectors

public List launchingConnectors()

Returns the list of known LaunchingConnector objects. Any of the returned objects can be used to launch a new target VM and immediately create a VirtualMachine mirror for it. Note that a target VM launched by a launching connector is not guaranteed to be stable until after the VMStartEvent has been received.

Returns:: a list of LaunchingConnector objects.

attachingConnectors

public List attachingConnectors()

Returns the list of known AttachingConnector objects. Any of the returned objects can be used to attach to an existing target VM and create a VirtualMachine mirror for it.

Returns:: a list of AttachingConnector objects.

listeningConnectors

public List listeningConnectors()

Returns the list of known ListeningConnector objects. Any of the returned objects can be used to listen for a connection initiated by a target VM and create a VirtualMachine mirror for it.

Returns:: a list of ListeningConnector objects.

allConnectors

public List allConnectors()

Returns the list of all known Connector objects.

Returns:: a list of Connector objects.

connectedVirtualMachines

public List connectedVirtualMachines()

Lists all target VMs which are connected to the debugger. The list includes VirtualMachine instances for any target VMs which initiated a connection and any target VMs to which this manager has initiated a connection. A target VM will remain in this list until the VM is disconnected. VMDisconnectEvent is placed in the event queue after the VM is removed from the list.

Returns:: a list of VirtualMachine objects, each mirroring a target VM.

majorInterfaceVersion

public int majorInterfaceVersion()

Returns the major version number of the JDI interface. See VirtualMachine.version() target VM version and information and VirtualMachine.description() more version information.

Returns:: the integer major version number.

minorInterfaceVersion

public int minorInterfaceVersion()

Returns the minor version number of the JDI interface. See VirtualMachine.version() target VM version and information and VirtualMachine.description() more version information.

Returns:: the integer minor version number