Mirror
PathSearchingVirtualMachine
public interface VirtualMachine extends Mirror
mirror
representing the composite state of the target VM. All other mirrors are associated with an instance of this interface. Access to all other mirrors is achieved directly or indirectly through an instance of this interface. Access to global VM properties and control of VM execution are supported directly by this interface. Instances of this interface are created by instances of Connector
. For example, an AttachingConnector
attaches to a target VM and returns its virtual machine mirror. A Connector will typically create a VirtualMachine by invoking the VirtualMachineManager's VirtualMachineManager.createVirtualMachine(Connection)
createVirtualMachine(Connection) method.
Note that a target VM launched by a launching connector is not guaranteed to be stable until after the VMStartEvent
has been received.
Any method on VirtualMachine
which takes VirtualMachine
as an parameter may throw VMDisconnectedException
if the target VM is disconnected and the VMDisconnectEvent
has been or is available to be read from the EventQueue
.
Any method on VirtualMachine
which takes VirtualMachine
as an parameter may throw VMOutOfMemoryException
if the target VM has run out of memory.
Modifier and Type | Field | Description |
---|---|---|
static final int |
TRACE_ALL |
All tracing is enabled. |
static final int |
TRACE_EVENTS |
Tracing enabled for internal event handling. |
static final int |
TRACE_NONE |
All tracing is disabled. |
static final int |
TRACE_OBJREFS |
Tracing enabled for internal management of object references. |
static final int |
TRACE_RECEIVES |
Tracing enabled for JDWP packets received from target VM. |
static final int |
TRACE_REFTYPES |
Tracing enabled for internal management of reference types. |
static final int |
TRACE_SENDS |
Tracing enabled for JDWP packets sent to target VM. |
Modifier and Type | Method | Description |
---|---|---|
List |
allClasses() |
Returns all loaded types in the target VM. |
default List |
allModules() |
Returns all modules. |
List |
allThreads() |
Returns a list of the live threads in the target VM. |
boolean |
canAddMethod() |
Deprecated. A JVM TI based JDWP back-end will never set this capability to true. |
boolean |
canBeModified() |
Determines if the target VM is a read-only VM. |
boolean |
canForceEarlyReturn() |
Determines if the target VM supports the forcing of a method to return early. |
boolean |
canGetBytecodes() |
Determines if the target VM supports the retrieval of a method's bytecodes. |
boolean |
canGetClassFileVersion() |
Determines if the target VM supports reading class file major and minor versions. |
boolean |
canGetConstantPool() |
Determines if the target VM supports getting constant pool information of a class. |
boolean |
canGetCurrentContendedMonitor() |
Determines if the target VM supports the retrieval of the monitor for which a thread is currently waiting. |
boolean |
canGetInstanceInfo() |
Determines if the target VM supports the accessing of class instances, instance counts, and referring objects. |
boolean |
canGetMethodReturnValues() |
Determines if the target VM supports the inclusion of return values in MethodExitEvent s. |
default boolean |
canGetModuleInfo() |
Determines if the target VM supports getting information about modules. |
boolean |
canGetMonitorFrameInfo() |
Determines if the target VM supports getting which frame has acquired a monitor. |
boolean |
canGetMonitorInfo() |
Determines if the target VM supports the retrieval of the monitor information for an object. |
boolean |
canGetOwnedMonitorInfo() |
Determines if the target VM supports the retrieval of the monitors owned by a thread. |
boolean |
canGetSourceDebugExtension() |
Determines if the target VM supports getting the source debug extension. |
boolean |
canGetSyntheticAttribute() |
Determines if the target VM supports the query of the synthetic attribute of a method or field. |
boolean |
canPopFrames() |
Determines if the target VM supports popping frames of a threads stack. |
boolean |
canRedefineClasses() |
Determines if the target VM supports any level of class redefinition. |
boolean |
canRequestMonitorEvents() |
Determines if the target VM supports the creation of MonitorContendedEnterRequest s. |
boolean |
canRequestVMDeathEvent() |
Determines if the target VM supports the creation of VMDeathRequest s. |
boolean |
canUnrestrictedlyRedefineClasses() |
Deprecated. A JVM TI based JDWP back-end will never set this capability to true. |
boolean |
canUseInstanceFilters() |
Determines if the target VM supports filtering events by specific instance object. |
boolean |
canUseSourceNameFilters() |
Determines if the target VM supports the filtering of class prepare events by source name. |
boolean |
canWatchFieldAccess() |
Determines if the target VM supports watchpoints for field access. |
boolean |
canWatchFieldModification() |
Determines if the target VM supports watchpoints for field modification. |
List |
classesByName |
Returns the loaded reference types that match a given name. |
String |
description() |
Returns text information on the target VM and the debugger support that mirrors it. |
void |
dispose() |
Invalidates this virtual machine mirror. |
EventQueue |
eventQueue() |
Returns the event queue for this virtual machine. |
EventRequestManager |
eventRequestManager() |
Returns the event request manager for this virtual machine. |
void |
exit |
Causes the mirrored VM to terminate with the given error code. |
String |
getDefaultStratum() |
Return this VM's default stratum. |
long[] |
instanceCounts |
Returns the number of instances of each ReferenceType in the 'refTypes' list. |
BooleanValue |
mirrorOf |
Creates a BooleanValue for the given value. |
ByteValue |
mirrorOf |
Creates a ByteValue for the given value. |
CharValue |
mirrorOf |
Creates a CharValue for the given value. |
DoubleValue |
mirrorOf |
Creates a DoubleValue for the given value. |
FloatValue |
mirrorOf |
Creates a FloatValue for the given value. |
IntegerValue |
mirrorOf |
Creates an IntegerValue for the given value. |
LongValue |
mirrorOf |
Creates a LongValue for the given value. |
ShortValue |
mirrorOf |
Creates a ShortValue for the given value. |
StringReference |
mirrorOf |
Creates a string in this virtual machine. |
VoidValue |
mirrorOfVoid() |
Creates a VoidValue . |
String |
name() |
Returns the name of the target VM as reported by the property java.vm.name . |
Process |
process() |
Returns the Process object for this virtual machine if launched by a LaunchingConnector
|
void |
redefineClasses |
All classes given are redefined according to the definitions supplied. |
void |
resume() |
Continues the execution of the application running in this virtual machine. |
void |
setDebugTraceMode |
Traces the activities performed by the com.sun.jdi implementation. |
void |
setDefaultStratum |
Set this VM's default stratum (see Location for a discussion of strata). |
void |
suspend() |
Suspends the execution of the application running in this virtual machine. |
List |
topLevelThreadGroups() |
Returns each thread group which does not have a parent. |
String |
version() |
Returns the version of the Java Runtime Environment in the target VM as reported by the property java.version . |
toString, virtualMachine
static final int TRACE_NONE
static final int TRACE_SENDS
static final int TRACE_RECEIVES
static final int TRACE_EVENTS
static final int TRACE_REFTYPES
static final int TRACE_OBJREFS
static final int TRACE_ALL
default List<ModuleReference> allModules()
ModuleReference
will be placed in the returned list. Not all target virtual machines support this operation. Use canGetModuleInfo()
to determine if the operation is supported.
UnsupportedOperationException
.ModuleReference
objects, each mirroring a module in the target VM.UnsupportedOperationException
- if the target virtual machine does not support this operation.List<ReferenceType> classesByName(String className)
ReferenceType
for each class or interface found with the given name. The search is confined to loaded classes only; no attempt is made to load a class of the given name. The returned list will include reference types loaded at least to the point of preparation and types (like array) for which preparation is not defined.
className
- the class/interface name to search forReferenceType
objects, each mirroring a type in the target VM with the given name.List<ReferenceType> allClasses()
The returned list includes all reference types, including hidden classes or interfaces
, loaded at least to the point of preparation and types (like array) for which preparation is not defined.
ReferenceType
objects, each mirroring a loaded type in the target VM.void redefineClasses(Map<? extends ReferenceType,byte[]> classToBytes)
Method.isObsolete()
will return true when called on one of these methods. If resetting such a frame is desired, use ThreadReference.popFrames(StackFrame)
to pop the old obsolete method execution from the stack. New invocations of redefined methods will always invoke the new versions. This function does not cause any initialization except that which would occur under the customary JVM semantics. In other words, redefining a class does not cause its initializers to be run. The values of preexisting static variables will remain as they were prior to the call. However, completely uninitialized (new) static variables will be assigned their default value.
If a redefined class has instances then all those instances will have the fields defined by the redefined class at the completion of the call. Preexisting fields will retain their previous values. Any new fields will have their default values; no instance initializers or constructors are run.
Threads need not be suspended.
No events are generated by this function.
All breakpoints in the redefined classes are deleted.
Not all target virtual machines support this operation. Use canRedefineClasses()
to determine if the operation is supported. Use canAddMethod()
to determine if the redefinition can add methods. Use canUnrestrictedlyRedefineClasses()
to determine if the redefinition can change the schema, delete methods, change the class hierarchy, etc.
classToBytes
- A map from ReferenceType
to array of byte. The bytes represent the new class definition and are in Java Virtual Machine class file format.UnsupportedOperationException
- if the target virtual machine does not support this operation. canRedefineClasses()
is false any call of this method will throw this exception. canAddMethod()
is false attempting to add a method will throw this exception. canUnrestrictedlyRedefineClasses()
is false attempting any of the unsupported class file changes described in JVM TI RedefineClasses will throw this exception. NoClassDefFoundError
- if the bytes don't correspond to the reference type (the names don't match).VerifyError
- if a "verifier" detects that a class, though well formed, contains an internal inconsistency or security problem.ClassFormatError
- if the bytes do not represent a valid class.ClassCircularityError
- if a circularity has been detected while initializing a class.UnsupportedClassVersionError
- if the major and minor version numbers in bytes are not supported by the VM.VMCannotBeModifiedException
- if the VirtualMachine is read-only - see canBeModified()
.List<ThreadReference> allThreads()
The returned list contains a ThreadReference
for each live platform thread in the target VM. This includes platform threads created with the java.lang.Thread
API and all native threads attached to the target VM with JNI code.
It is implementation dependent if the list contains elements for live virtual threads in the target VM. The target VM may not return any references to virtual threads, or it may be configured to return a reference to some or all virtual threads. Tools that want to track all virtual threads may enable ThreadStartRequest
and ThreadDeathRequest
to get notifications when virtual threads start and terminate.
ThreadReference
objects for the threads in the target VMvoid suspend()
Suspends of both the virtual machine and individual threads are counted. Before a thread will run again, it must be resumed (through resume()
or ThreadReference.resume()
) the same number of times it has been suspended.
VMCannotBeModifiedException
- if the VirtualMachine is read-onlyvoid resume()
ThreadReference.resume()
.VMCannotBeModifiedException
- if the VirtualMachine is read-onlyList<ThreadGroupReference> topLevelThreadGroups()
ThreadGroupReference
is placed in the returned list. This command may be used as the first step in building a tree (or trees) of the existing thread groups.
ThreadGroupReference
objects, one for each top level thread group.EventQueue eventQueue()
EventQueue
object, this method will return the same instance each time it is invoked.EventQueue
for this virtual machine.VMCannotBeModifiedException
- if the VirtualMachine is read-only - see canBeModified()
.EventRequestManager eventRequestManager()
EventRequestManager
controls user settable events such as breakpoints. A virtual machine has only one EventRequestManager
object, this method will return the same instance each time it is invoked.EventRequestManager
for this virtual machine.VMCannotBeModifiedException
- if the VirtualMachine is read-only - see canBeModified()
.BooleanValue mirrorOf(boolean value)
BooleanValue
for the given value. This value can be used for setting and comparing against a value retrieved from a variable or field in this virtual machine.value
- a boolean for which to create the valueBooleanValue
for the given boolean.ByteValue mirrorOf(byte value)
ByteValue
for the given value. This value can be used for setting and comparing against a value retrieved from a variable or field in this virtual machine.value
- a byte for which to create the valueByteValue
for the given byte.CharValue mirrorOf(char value)
CharValue
for the given value. This value can be used for setting and comparing against a value retrieved from a variable or field in this virtual machine.value
- a char for which to create the valueCharValue
for the given char.ShortValue mirrorOf(short value)
ShortValue
for the given value. This value can be used for setting and comparing against a value retrieved from a variable or field in this virtual machine.value
- a short for which to create the valueShortValue
for the given short.IntegerValue mirrorOf(int value)
IntegerValue
for the given value. This value can be used for setting and comparing against a value retrieved from a variable or field in this virtual machine.value
- an int for which to create the valueIntegerValue
for the given int.LongValue mirrorOf(long value)
LongValue
for the given value. This value can be used for setting and comparing against a value retrieved from a variable or field in this virtual machine.value
- a long for which to create the valueLongValue
for the given long.FloatValue mirrorOf(float value)
FloatValue
for the given value. This value can be used for setting and comparing against a value retrieved from a variable or field in this virtual machine.value
- a float for which to create the valueFloatValue
for the given float.DoubleValue mirrorOf(double value)
DoubleValue
for the given value. This value can be used for setting and comparing against a value retrieved from a variable or field in this virtual machine.value
- a double for which to create the valueDoubleValue
for the given double.StringReference mirrorOf(String value)
value
- the string to be createdStringReference
that mirrors the newly created string in the target VM.VMCannotBeModifiedException
- if the VirtualMachine is read-only -see canBeModified()
.VoidValue mirrorOfVoid()
VoidValue
. This value can be passed to ThreadReference.forceEarlyReturn(com.sun.jdi.Value)
when a void method is to be exited.VoidValue
.Process process()
Process
object for this virtual machine if launched by a LaunchingConnector
Process
object for this virtual machine, or null if it was not launched by a LaunchingConnector
.VMCannotBeModifiedException
- if the VirtualMachine is read-only -see canBeModified()
.void dispose()
suspend()
or by ThreadReference.suspend()
are resumed as many times as necessary for them to run. ObjectReference.disableCollection()
. Resources originating in this VirtualMachine (ObjectReferences, ReferenceTypes, etc.) will become invalid.
void exit(int exitCode)
Threads running in the mirrored VM are abruptly terminated. A thread death exception is not thrown and finally blocks are not run.
exitCode
- the exit code for the target VM. On some platforms, the exit code might be truncated, for example, to the lower order 8 bits.VMCannotBeModifiedException
- if the VirtualMachine is read-only - see canBeModified()
.boolean canWatchFieldModification()
true
if the feature is supported, false
otherwise.boolean canWatchFieldAccess()
true
if the feature is supported, false
otherwise.boolean canGetBytecodes()
true
if the feature is supported, false
otherwise.boolean canGetSyntheticAttribute()
true
if the feature is supported, false
otherwise.boolean canGetOwnedMonitorInfo()
true
if the feature is supported, false
otherwise.boolean canGetCurrentContendedMonitor()
true
if the feature is supported, false
otherwise.boolean canGetMonitorInfo()
true
if the feature is supported, false
otherwise.boolean canUseInstanceFilters()
BreakpointRequest.addInstanceFilter(com.sun.jdi.ObjectReference)
.true
if the feature is supported, false
otherwise.boolean canRedefineClasses()
true
if the feature is supported, false
otherwise.@Deprecated(since="15") boolean canAddMethod()
true
if the feature is supported, false
otherwise.@Deprecated(since="15") boolean canUnrestrictedlyRedefineClasses()
redefineClasses(java.util.Map<? extends com.sun.jdi.ReferenceType, byte[]>)
.true
if the feature is supported, false
otherwise.boolean canPopFrames()
true
if the feature is supported, false
otherwise.boolean canGetSourceDebugExtension()
true
if the feature is supported, false
otherwise.boolean canRequestVMDeathEvent()
VMDeathRequest
s.true
if the feature is supported, false
otherwise.boolean canGetMethodReturnValues()
MethodExitEvent
s.true
if the feature is supported, false
otherwise.boolean canGetInstanceInfo()
true
if the feature is supported, false
otherwise.boolean canUseSourceNameFilters()
ClassPrepareRequest.addSourceNameFilter(java.lang.String)
.true
if the feature is supported, false
otherwise.boolean canForceEarlyReturn()
true
if the feature is supported, false
otherwise.boolean canBeModified()
VMCannotBeModifiedException
is thrown.true
if the feature is supported, false
otherwise.boolean canRequestMonitorEvents()
MonitorContendedEnterRequest
s. MonitorContendedEnteredRequest
s. MonitorWaitRequest
s. MonitorWaitedRequest
s.true
if the feature is supported, false
otherwise.boolean canGetMonitorFrameInfo()
true
if the feature is supported, false
otherwise.boolean canGetClassFileVersion()
true
if the feature is supported, false
otherwise.boolean canGetConstantPool()
true
if the feature is supported, false
otherwise.default boolean canGetModuleInfo()
false
.true
if the feature is supported, false
otherwisevoid setDefaultStratum(String stratum)
Location
for a discussion of strata). Overrides the per-class default set in the class file. Affects location queries (such as, Location.sourceName()
) and the line boundaries used in single stepping.
stratum
- the stratum to set as VM default, or null to use per-class defaults.UnsupportedOperationException
- if the target virtual machine does not support this operation.String getDefaultStratum()
null
(meaning that the per-class default - ReferenceType.defaultStratum()
- should be used) unless the default stratum has been set with setDefaultStratum(String)
.long[] instanceCounts(List<? extends ReferenceType> refTypes)
Not all target virtual machines support this operation. Use canGetInstanceInfo()
to determine if the operation is supported.
refTypes
- the list of ReferenceType
objects for which counts are to be obtained.long
containing one element for each element in the 'refTypes' list. Element i of the array contains the number of instances in the target VM of the ReferenceType at position i in the 'refTypes' list. If the 'refTypes' list is empty, a zero-length array is returned. If a ReferenceType in refTypes has been garbage collected, zero is returned for its instance count.UnsupportedOperationException
- if the target virtual machine does not support this operation - see canGetInstanceInfo()
NullPointerException
- if the 'refTypes' list is null.String description()
version()
, VirtualMachineManager.majorInterfaceVersion()
, and VirtualMachineManager.minorInterfaceVersion()
String version()
java.version
. For obtaining the JDI interface version, use VirtualMachineManager.majorInterfaceVersion()
and VirtualMachineManager.minorInterfaceVersion()
String name()
java.vm.name
.void setDebugTraceMode(int traceFlags)
Output is implementation dependent and trace mode may be ignored.
traceFlags
- identifies which kinds of tracing to enable.
© 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/VirtualMachine.html