@Exported
public interface VirtualMachineManager
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.
 
| Scenario | Description | 
|---|---|
| Debugger launches target VM (simplest, most-common scenario) | Debugger calls the LaunchingConnector.launch(java.util.Map)method of the default connector, obtained withdefaultConnector(). The
 target VM is launched, and a connection between that VM and the
 debugger is established. AVirtualMachinemirror is returned.Or, for more control 
 | 
| Debugger attaches to previously-running VM | 
 | 
| Target VM attaches to previously-running debugger | listeningConnectors()for one or more
 transports.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.ListeningConnector.accept(java.util.Map)for each selected connector to wait for
 a target VM to connect.-agentlib:jdwp=transport=xxx,address=yyywhere "xxx" the transport for one of the connectors selected by the
 the debugger and "yyy"
 is the address generated byListeningConnector.accept(java.util.Map)for that
 transport.ListeningConnector.accept(java.util.Map)returns
 aVirtualMachinemirror. | 
| Target VM launches debugger (sometimes called "Just-In-Time" debugging) | -agentlib:jdwp=launch=cmdline,onuncaught=y,transport=xxx,server=y
 attachingConnectors()matching the transport with
 the name "xxx".Connector.defaultArguments()) to specify
 the transport specific address at which the VM is listenig. Optionally,
 other connector arguments can be presented to the user.AttachingConnector.attach(java.util.Map)method
 of the selected to attach to the target VM. AVirtualMachinemirror 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
 com.sun.jdi.connect.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
 com.sun.jdi.connect.spi.TransportService in the resource
 directory META-INF/services, and the provider
 configuration file lists the 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. Similiarly 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.
| Modifier and Type | Method and Description | 
|---|---|
| List<Connector> | allConnectors()Returns the list of all known  Connectorobjects. | 
| List<AttachingConnector> | attachingConnectors()Returns the list of known  AttachingConnectorobjects. | 
| 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  LaunchingConnectorobjects. | 
| List<ListeningConnector> | listeningConnectors()Returns the list of known  ListeningConnectorobjects. | 
| int | majorInterfaceVersion()Returns the major version number of the JDI interface. | 
| int | minorInterfaceVersion()Returns the minor version number of the JDI interface. | 
LaunchingConnector defaultConnector()
LaunchingConnectorList<LaunchingConnector> launchingConnectors()
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.LaunchingConnector objects.List<AttachingConnector> attachingConnectors()
AttachingConnector objects.
 Any of the returned objects can be used to attach to an existing target
 VM and create a VirtualMachine mirror for it.AttachingConnector objects.List<ListeningConnector> listeningConnectors()
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.ListeningConnector objects.List<Connector> allConnectors()
Connector objects.Connector objects.List<VirtualMachine> connectedVirtualMachines()
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.VirtualMachine objects, each mirroring
 a target VM.int majorInterfaceVersion()
VirtualMachine.version() target VM version and
 information and
 VirtualMachine.description() more version information.int minorInterfaceVersion()
VirtualMachine.version() target VM version and
 information and
 VirtualMachine.description() more version information.VirtualMachine createVirtualMachine(Connection connection, Process process) throws IOException
 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 taget 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.
connection - The open connection to the target VM.process - If launched, the Process object for
         the target VM. null if not launched.IOException - if an I/O error occursIllegalStateException - if the connection is not openConnection.isOpen(), 
VirtualMachine.process()VirtualMachine createVirtualMachine(Connection connection) throws IOException
 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.
IOException - if an I/O error occursIllegalStateException - if the connection is not open
 Copyright © 1999, 2025, Oracle and/or its affiliates.  All rights reserved.