Overview | Package | Class | Use | Tree | Index | Help
| Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | 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.

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.
  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 `ListeningConnector` 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 it is discarded through `VirtualMachine.dispose()` or until it `VMDeathEvent` is received, whichever happens first.
  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

Overview | Package | Class | Use | Tree | Index | Help
| Java Debug Interface
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD