# 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 implementation. Some `Connector` implementations may require slightly different handling than presented below.

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 transport-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 transport-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.

Connectors are created at start-up time. That is, they are created the first time that `Bootstrap.virtualMachineManager()` is invoked. The list of all Connectors created at start-up time can be obtained from the VirtualMachineManager by invoking the `allConnectors` method.

Connectors are created at start-up time if they are installed on the platform. In addition, Connectors are created automatically by the VirtualMachineManager to encapsulate any `TransportService` implementations that are installed on the platform. These two mechanisms for creating Connectors are described here.

A Connector is installed on the platform if it is installed in a jar file that is visible to the defining class loader of the `Connector` type, and that jar file contains a provider configuration file named `Connector` in the resource directory `META-INF/services`, and the provider configuration file lists the full-qualified class name of the Connector implementation. A Connector is a class that implements the `Connector` interface. More appropriately the class implements one of the specific Connector types, namely `AttachingConnector`, `ListeningConnector`, or `LaunchingConnector`. The format of the provider configuration file is one fully-qualified class name per line. Space and tab characters surrounding each class, as well as blank lines are ignored. The comment character is `'#'` (`0x23`), and on each line all characters following the first comment character are ignored. The file must be encoded in UTF-8.

At start-up time the VirtualMachineManager attempts to load and instantiate (using the no-arg constructor) each class listed in the provider configuration file. Exceptions thrown when loading or creating the Connector are caught and ignored. In other words, the start-up process continues despite of errors.

In addition to Connectors installed on the platform the VirtualMachineManager will also create Connectors to encapsulate any `TransportService` implementations that are installed on the platform. A TransportService is installed on the platform if it installed in a jar file that is visible to the defining class loader for the `TransportService` type, and that jar file contains a provider configuration file named `TransportService` in the resource directory `META-INF/services`, and the provider configuration file lists the full-qualified class name of the TransportService implementation. A TransportService is a concrete sub-class of `TransportService`. The format of the provider configuration file is the same as the provider configuration file for Connectors except that each class listed must be the fully-qualified class name of a class that implements the TransportService interface.

For each TransportService installed on the platform, the VirtualMachineManager creates a corresponding `AttachingConnector` and `ListeningConnector`. These Connectors are created to encapsulate a `Transport` that in turn encapsulates the TransportService. The AttachingConnector will be named based on the name of the transport service concatenated with the string `Attach`. For example, if the transport service `name()` method returns `telepathic` then the AttachingConnector will be named `telepathicAttach`. Similarly the ListeningConnector will be named with the string `Listen` tagged onto the name of the transport service. The `description()` method of both the AttachingConnector, and the ListeningConnector, will delegate to the `description()` method of the underlying transport service. Both the AttachingConnector and the ListeningConnector will have two Connector `Arguments`. A `StringArgument` named `address` is the connector argument to specify the address to attach too, or to listen on. A `IntegerArgument` named `timeout` is the connector argument to specify the timeout when attaching, or accepting. The timeout connector may be ignored depending on if the transport service supports an attach timeout or accept timeout.

Initialization of the virtual machine manager will fail, that is `Bootstrap.virtualMachineManager()` will throw an error if the virtual machine manager is unable to create any connectors.

Since:
  1.3

## Method Summary

Modifier and Type
Method
Description
`List<Connector>`
`allConnectors()`
Returns the list of all known `Connector` objects.
`List<AttachingConnector>`
`attachingConnectors()`
Returns the list of known `AttachingConnector` objects.
`List<VirtualMachine>`
`connectedVirtualMachines()`
Lists all target VMs which are connected to the debugger.
`VirtualMachine`
`createVirtualMachine(Connection connection)`
Creates a new virtual machine.
`VirtualMachine`
`createVirtualMachine(Connection connection, Process process)`
Create a virtual machine mirror for a target VM.
`LaunchingConnector`
`defaultConnector()`
Identifies the default connector.
`List<LaunchingConnector>`
`launchingConnectors()`
Returns the list of known `LaunchingConnector` objects.
`List<ListeningConnector>`
`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 Details

### defaultConnector

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

List<LaunchingConnector> 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

List<AttachingConnector> 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

List<ListeningConnector> 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

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

Returns:
  a list of `Connector` objects.

### connectedVirtualMachines

List<VirtualMachine> 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

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

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

### createVirtualMachine

VirtualMachine createVirtualMachine(Connection connection, Process process) throws IOException
Create a virtual machine mirror for a target VM.

Creates a virtual machine mirror for a target VM for which a `Connection` already exists. A Connection is created when a `Connector` establishes a connection and successfully handshakes with a target VM. A Connector can then use this method to create a virtual machine mirror to represent the composite state of the target VM.

The `process` argument specifies the `Process` object for the target VM. It may be specified as `null`. If the target VM is launched by a `LaunchingConnector` the `process` argument should be specified, otherwise calling `VirtualMachine.process()` on the created virtual machine will return `null`.

This method exists so that Connectors may create a virtual machine mirror when a connection is established to a target VM. Only developers creating new Connector implementations should need to make direct use of this method.

Parameters:
  `connection` - The open connection to the target VM.
  `process` - If launched, the `Process` object for the target VM. `null` if not launched.
Returns:
  new virtual machine representing the target VM.
Throws:
  `IOException` - if an I/O error occurs
  `IllegalStateException` - if the connection is not open
Since:
  1.5
See Also:
  - `Connection.isOpen()`
  - `VirtualMachine.process()`

### createVirtualMachine

VirtualMachine createVirtualMachine(Connection connection) throws IOException
Creates a new virtual machine.

This convenience method works as if by invoking `createVirtualMachine(Connection, Process)` method and specifying `null` as the `process` argument.

This method exists so that Connectors may create a virtual machine mirror when a connection is established to a target VM. Only developers creating new Connector implementations should need to make direct use of this method.

Returns:
  the new virtual machine
Throws:
  `IOException` - if an I/O error occurs
  `IllegalStateException` - if the connection is not open
Since:
  1.5