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 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 attaches to previously-running VM |
|
Target VM attaches to previously-running debugger |
|
Target VM launches debugger (sometimes called "Just-In-Time" debugging) |
|
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.
Modifier and Type | Method | Description |
---|---|---|
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. |
VirtualMachine |
createVirtualMachine |
Creates a new virtual machine. |
VirtualMachine |
createVirtualMachine |
Create a virtual machine mirror for a target VM. |
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. |
LaunchingConnector defaultConnector()
LaunchingConnector
List<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 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.
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 openVirtualMachine 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
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/jdk.jdi/com/sun/jdi/VirtualMachineManager.html