@Exported 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 and Description | 
|---|---|
| static int | TRACE_ALLAll tracing is enabled. | 
| static int | TRACE_EVENTSTracing enabled for internal event handling. | 
| static int | TRACE_NONEAll tracing is disabled. | 
| static int | TRACE_OBJREFSTracing enabled for internal management of object references. | 
| static int | TRACE_RECEIVESTracing enabled for JDWP packets received from target VM. | 
| static int | TRACE_REFTYPESTracing enabled for internal managment of reference types. | 
| static int | TRACE_SENDSTracing enabled for JDWP packets sent to target VM. | 
| Modifier and Type | Method and Description | 
|---|---|
| List<ReferenceType> | allClasses()Returns all loaded types. | 
| List<ThreadReference> | allThreads()Returns a list of the currently running threads. | 
| boolean | canAddMethod()Determines if the target VM supports the addition
 of methods when performing class redefinition. | 
| 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
  MethodExitEvents. | 
| 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
  MonitorContendedEnterRequests. | 
| boolean | canRequestVMDeathEvent()Determines if the target VM supports the creation of
  VMDeathRequests. | 
| boolean | canUnrestrictedlyRedefineClasses()Determines if the target VM supports unrestricted
 changes when performing class redefinition. | 
| 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<ReferenceType> | classesByName(String className)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(int exitCode)Causes the mirrored VM to terminate with the given error code. | 
| String | getDefaultStratum()Return this VM's default stratum. | 
| long[] | instanceCounts(List<? extends ReferenceType> refTypes)Returns the number of instances of each ReferenceType in the 'refTypes'
 list. | 
| BooleanValue | mirrorOf(boolean value)Creates a  BooleanValuefor the given value. | 
| ByteValue | mirrorOf(byte value)Creates a  ByteValuefor the given value. | 
| CharValue | mirrorOf(char value)Creates a  CharValuefor the given value. | 
| DoubleValue | mirrorOf(double value)Creates a  DoubleValuefor the given value. | 
| FloatValue | mirrorOf(float value)Creates a  FloatValuefor the given value. | 
| IntegerValue | mirrorOf(int value)Creates an  IntegerValuefor the given value. | 
| LongValue | mirrorOf(long value)Creates a  LongValuefor the given value. | 
| ShortValue | mirrorOf(short value)Creates a  ShortValuefor the given value. | 
| StringReference | mirrorOf(String value)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  Processobject for this
 virtual machine if launched
 by aLaunchingConnector | 
| void | redefineClasses(Map<? extends ReferenceType,byte[]> classToBytes)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(int traceFlags)Traces the activities performed by the com.sun.jdi implementation. | 
| void | setDefaultStratum(String stratum)Set this VM's default stratum (see  Locationfor a
 discussion of strata). | 
| void | suspend()Suspends the execution of the application running in this
 virtual machine. | 
| List<ThreadGroupReference> | 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, virtualMachinestatic 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
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()
ReferenceType will be placed in the returned list.
 The list will include ReferenceTypes which mirror classes,
 interfaces, and array types.
 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.
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 following 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().Method.isObsolete(), 
ThreadReference.popFrames(com.sun.jdi.StackFrame), 
canRedefineClasses(), 
canAddMethod(), 
canUnrestrictedlyRedefineClasses()List<ThreadReference> allThreads()
ThreadReference
 that mirrors it is placed in the list.
 The returned list contains threads created through
 java.lang.Thread, all native threads attached to
 the target VM through JNI, and system threads created
 by the target VM. Thread objects that have
 not yet been started
 (see Thread.start())
 and thread objects that have
 completed their execution are not included in the returned list.ThreadReference objects, one for each
 running thread in the mirrored VM.void suspend()
 Unlike Thread.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-only - see canBeModified().void resume()
ThreadReference.resume().VMCannotBeModifiedException - if the VirtualMachine is read-only - see canBeModified().suspend()List<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 LaunchingConnectorProcess 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.redefineClasses(java.util.Map<? extends com.sun.jdi.ReferenceType, byte[]>)boolean canAddMethod()
true if the feature is supported,
 false otherwise.redefineClasses(java.util.Map<? extends com.sun.jdi.ReferenceType, byte[]>)boolean canUnrestrictedlyRedefineClasses()
true if the feature is supported,
 false otherwise.redefineClasses(java.util.Map<? extends com.sun.jdi.ReferenceType, byte[]>)boolean canPopFrames()
true if the feature is supported,
 false otherwise.ThreadReference.popFrames(com.sun.jdi.StackFrame)boolean canGetSourceDebugExtension()
true if the feature is supported,
 false otherwise.ReferenceType.sourceDebugExtension()boolean canRequestVMDeathEvent()
VMDeathRequests.true if the feature is supported,
 false otherwise.EventRequestManager.createVMDeathRequest()boolean canGetMethodReturnValues()
MethodExitEvents.true if the feature is supported,
 false otherwise.EventRequestManager.createMethodExitRequest()boolean canGetInstanceInfo()
true if the feature is supported,
 false otherwise.instanceCounts(java.util.List<? extends com.sun.jdi.ReferenceType>), 
ReferenceType.instances(long), 
ObjectReference.referringObjects(long)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.ThreadReference.forceEarlyReturn(Value)boolean canBeModified()
VMCannotBeModifiedException is thrown.true if the feature is supported,
 false otherwise.boolean canRequestMonitorEvents()
MonitorContendedEnterRequests.
 MonitorContendedEnteredRequests.
 MonitorWaitRequests.
 MonitorWaitedRequests.true if the feature is supported,
 false otherwise.EventRequestManager.createMonitorContendedEnterRequest(), 
EventRequestManager.createMonitorContendedEnteredRequest(), 
EventRequestManager.createMonitorWaitRequest(), 
EventRequestManager.createMonitorWaitedRequest()boolean canGetMonitorFrameInfo()
true if the feature is supported,
 false otherwise.ThreadReference.ownedMonitorsAndFrames()boolean canGetClassFileVersion()
true if the feature is supported,
 false otherwise.ReferenceType.majorVersion(), 
ReferenceType.minorVersion()boolean canGetConstantPool()
true if the feature is supported,
 false otherwise.ReferenceType.constantPoolCount(), 
ReferenceType.constantPool()void 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).setDefaultStratum(String), 
ReferenceType.defaultStratum()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.ReferenceType.instances(long), 
ObjectReference.referringObjects(long)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.
 Copyright © 1999, 2025, Oracle and/or its affiliates.  All rights reserved.