Interface VirtualMachine
- All Superinterfaces:
- Mirror
- All Known Subinterfaces:
- PathSearchingVirtualMachine
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.
- Since:
- 1.3
- 
Field SummaryFieldsModifier and TypeFieldDescriptionstatic final intAll tracing is enabled.static final intTracing enabled for internal event handling.static final intAll tracing is disabled.static final intTracing enabled for internal management of object references.static final intTracing enabled for JDWP packets received from target VM.static final intTracing enabled for internal management of reference types.static final intTracing enabled for JDWP packets sent to target VM.
- 
Method SummaryModifier and TypeMethodDescriptionReturns all loaded types in the target VM.default List<ModuleReference> Returns all modules.Returns a list of the live threads in the target VM.booleanDeprecated.A JVM TI based JDWP back-end will never set this capability to true.booleanDetermines if the target VM is a read-only VM.booleanDetermines if the target VM supports the forcing of a method to return early.booleanDetermines if the target VM supports the retrieval of a method's bytecodes.booleanDetermines if the target VM supports reading class file major and minor versions.booleanDetermines if the target VM supports getting constant pool information of a class.booleanDetermines if the target VM supports the retrieval of the monitor for which a thread is currently waiting.booleanDetermines if the target VM supports the accessing of class instances, instance counts, and referring objects.booleanDetermines if the target VM supports the inclusion of return values inMethodExitEvents.default booleanDetermines if the target VM supports getting information about modules.booleanDetermines if the target VM supports getting which frame has acquired a monitor.booleanDetermines if the target VM supports the retrieval of the monitor information for an object.booleanDetermines if the target VM supports the retrieval of the monitors owned by a thread.booleanDetermines if the target VM supports getting the source debug extension.booleanDetermines if the target VM supports the query of the synthetic attribute of a method or field.booleanDetermines if the target VM supports popping frames of a threads stack.booleanDetermines if the target VM supports any level of class redefinition.booleanDetermines if the target VM supports the creation ofMonitorContendedEnterRequests.booleanDetermines if the target VM supports the creation ofVMDeathRequests.booleanDeprecated.A JVM TI based JDWP back-end will never set this capability to true.booleanDetermines if the target VM supports filtering events by specific instance object.booleanDetermines if the target VM supports the filtering of class prepare events by source name.booleanDetermines if the target VM supports watchpoints for field access.booleanDetermines if the target VM supports watchpoints for field modification.classesByName(String className) Returns the loaded reference types that match a given name.Returns text information on the target VM and the debugger support that mirrors it.voiddispose()Invalidates this virtual machine mirror.Returns the event queue for this virtual machine.Returns the event request manager for this virtual machine.voidexit(int exitCode) Causes the mirrored VM to terminate with the given error code.Return this VM's default stratum.long[]instanceCounts(List<? extends ReferenceType> refTypes) Returns the number of instances of each ReferenceType in the 'refTypes' list.mirrorOf(boolean value) Creates aBooleanValuefor the given value.mirrorOf(byte value) Creates aByteValuefor the given value.mirrorOf(char value) Creates aCharValuefor the given value.mirrorOf(double value) Creates aDoubleValuefor the given value.mirrorOf(float value) Creates aFloatValuefor the given value.mirrorOf(int value) Creates anIntegerValuefor the given value.mirrorOf(long value) Creates aLongValuefor the given value.mirrorOf(short value) Creates aShortValuefor the given value.Creates a string in this virtual machine.Creates aVoidValue.name()Returns the name of the target VM as reported by the propertyjava.vm.name.process()Returns theProcessobject for this virtual machine if launched by aLaunchingConnectorvoidredefineClasses(Map<? extends ReferenceType, byte[]> classToBytes) All classes given are redefined according to the definitions supplied.voidresume()Continues the execution of the application running in this virtual machine.voidsetDebugTraceMode(int traceFlags) Traces the activities performed by the com.sun.jdi implementation.voidsetDefaultStratum(String stratum) Set this VM's default stratum (seeLocationfor a discussion of strata).voidsuspend()Suspends the execution of the application running in this virtual machine.Returns each thread group which does not have a parent.version()Returns the version of the Java Runtime Environment in the target VM as reported by the propertyjava.version.Methods declared in interface com.sun.jdi.MirrortoString, virtualMachine
- 
Field Details- 
TRACE_NONEstatic final int TRACE_NONEAll tracing is disabled.- See Also:
 
- 
TRACE_SENDSstatic final int TRACE_SENDSTracing enabled for JDWP packets sent to target VM.- See Also:
 
- 
TRACE_RECEIVESstatic final int TRACE_RECEIVESTracing enabled for JDWP packets received from target VM.- See Also:
 
- 
TRACE_EVENTSstatic final int TRACE_EVENTSTracing enabled for internal event handling.- See Also:
 
- 
TRACE_REFTYPESstatic final int TRACE_REFTYPESTracing enabled for internal management of reference types.- See Also:
 
- 
TRACE_OBJREFSstatic final int TRACE_OBJREFSTracing enabled for internal management of object references.- See Also:
 
- 
TRACE_ALLstatic final int TRACE_ALLAll tracing is enabled.- See Also:
 
 
- 
- 
Method Details- 
allModulesReturns all modules. For each module in the target VM aModuleReferencewill be placed in the returned list.Not all target virtual machines support this operation. Use canGetModuleInfo()to determine if the operation is supported.- Implementation Requirements:
- The default implementation throws UnsupportedOperationException.
- Returns:
- a list of ModuleReferenceobjects, each mirroring a module in the target VM.
- Throws:
- UnsupportedOperationException- if the target virtual machine does not support this operation.
- Since:
- 9
 
- 
classesByNameReturns the loaded reference types that match a given name. The name must be fully qualified (for example, java.lang.String). The returned list will contain aReferenceTypefor 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. - Parameters:
- className- the class/interface name to search for
- Returns:
- a list of ReferenceTypeobjects, each mirroring a type in the target VM with the given name.
 
- 
allClassesList<ReferenceType> allClasses()Returns all loaded types in the target VM.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.- Returns:
- a list of ReferenceTypeobjects, each mirroring a loaded type in the target VM.
- See Also:
 
- 
redefineClassesAll classes given are redefined according to the definitions supplied. A method in a redefined class is called 'equivalent' (to the old version of the method) if- their bytecodes are the same except for indices into the constant pool, and
- the referenced constants are equal.
 Method.isObsolete()will return true when called on one of these methods. If resetting such a frame is desired, useThreadReference.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. UsecanAddMethod()to determine if the redefinition can add methods. UsecanUnrestrictedlyRedefineClasses()to determine if the redefinition can change the schema, delete methods, change the class hierarchy, etc.- Parameters:
- classToBytes- A map from- ReferenceTypeto array of byte. The bytes represent the new class definition and are in Java Virtual Machine class file format.
- Throws:
- UnsupportedOperationException- if the target virtual machine does not support this operation.- If canRedefineClasses()is false any call of this method will throw this exception.
- If canAddMethod()is false attempting to add a method will throw this exception.
- If canUnrestrictedlyRedefineClasses()is false attempting any of the unsupported class file changes described in JVM TI RedefineClasses will throw this exception.
 
- If 
- 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().
- Since:
- 1.4
- See Also:
 
- 
allThreadsList<ThreadReference> allThreads()Returns a list of the live threads in the target VM. Threads that have not yet started or threads that have terminated are not included in the list.The returned list contains a ThreadReferencefor each live platform thread in the target VM. This includes platform threads created with thejava.lang.ThreadAPI 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 ThreadStartRequestandThreadDeathRequestto get notifications when virtual threads start and terminate.- Returns:
- a list of ThreadReferenceobjects for the threads in the target VM
 
- 
suspendvoid suspend()Suspends the execution of the application running in this virtual machine. All threads currently running will be suspended.Suspends of both the virtual machine and individual threads are counted. Before a thread will run again, it must be resumed (through resume()orThreadReference.resume()) the same number of times it has been suspended.- Throws:
- VMCannotBeModifiedException- if the VirtualMachine is read-only
- See Also:
 
- 
resumevoid resume()Continues the execution of the application running in this virtual machine. All threads are resumed as documented inThreadReference.resume().- Throws:
- VMCannotBeModifiedException- if the VirtualMachine is read-only
- See Also:
 
- 
topLevelThreadGroupsList<ThreadGroupReference> topLevelThreadGroups()Returns each thread group which does not have a parent. For each top level thread group aThreadGroupReferenceis 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. - Returns:
- a list of ThreadGroupReferenceobjects, one for each top level thread group.
 
- 
eventQueueEventQueue eventQueue()Returns the event queue for this virtual machine. A virtual machine has only oneEventQueueobject, this method will return the same instance each time it is invoked.- Returns:
- the EventQueuefor this virtual machine.
- Throws:
- VMCannotBeModifiedException- if the VirtualMachine is read-only - see- canBeModified().
 
- 
eventRequestManagerEventRequestManager eventRequestManager()Returns the event request manager for this virtual machine. TheEventRequestManagercontrols user settable events such as breakpoints. A virtual machine has only oneEventRequestManagerobject, this method will return the same instance each time it is invoked.- Returns:
- the EventRequestManagerfor this virtual machine.
- Throws:
- VMCannotBeModifiedException- if the VirtualMachine is read-only - see- canBeModified().
 
- 
mirrorOfCreates aBooleanValuefor 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.- Parameters:
- value- a boolean for which to create the value
- Returns:
- the BooleanValuefor the given boolean.
 
- 
mirrorOf
- 
mirrorOf
- 
mirrorOfCreates aShortValuefor 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.- Parameters:
- value- a short for which to create the value
- Returns:
- the ShortValuefor the given short.
 
- 
mirrorOfCreates anIntegerValuefor 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.- Parameters:
- value- an int for which to create the value
- Returns:
- the IntegerValuefor the given int.
 
- 
mirrorOf
- 
mirrorOfCreates aFloatValuefor 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.- Parameters:
- value- a float for which to create the value
- Returns:
- the FloatValuefor the given float.
 
- 
mirrorOfCreates aDoubleValuefor 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.- Parameters:
- value- a double for which to create the value
- Returns:
- the DoubleValuefor the given double.
 
- 
mirrorOfCreates a string in this virtual machine. The created string can be used for setting and comparing against a string value retrieved from a variable or field in this virtual machine.- Parameters:
- value- the string to be created
- Returns:
- a StringReferencethat mirrors the newly created string in the target VM.
- Throws:
- VMCannotBeModifiedException- if the VirtualMachine is read-only - see- canBeModified().
 
- 
mirrorOfVoidVoidValue mirrorOfVoid()Creates aVoidValue. This value can be passed toThreadReference.forceEarlyReturn(com.sun.jdi.Value)when a void method is to be exited.- Returns:
- the VoidValue.
 
- 
processProcess process()Returns theProcessobject for this virtual machine if launched by aLaunchingConnector- Returns:
- the Processobject for this virtual machine, or null if it was not launched by aLaunchingConnector.
- Throws:
- VMCannotBeModifiedException- if the VirtualMachine is read-only - see- canBeModified().
 
- 
disposevoid dispose()Invalidates this virtual machine mirror. The communication channel to the target VM is closed, and the target VM prepares to accept another subsequent connection from this debugger or another debugger, including the following tasks:- All event requests are cancelled.
- All threads suspended by suspend()or byThreadReference.suspend()are resumed as many times as necessary for them to run.
- Garbage collection is re-enabled in all cases where it was
 disabled through ObjectReference.disableCollection().
 Resources originating in this VirtualMachine (ObjectReferences, ReferenceTypes, etc.) will become invalid. 
- 
exitvoid exit(int exitCode) Causes the mirrored VM to terminate with the given error code. All resources associated with this VirtualMachine are freed. If the mirrored VM is remote, the communication channel to it will be closed. Resources originating in this VirtualMachine (ObjectReferences, ReferenceTypes, etc.) will become invalid.Threads running in the mirrored VM are abruptly terminated. A thread death exception is not thrown and finally blocks are not run. - Parameters:
- 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.
- Throws:
- VMCannotBeModifiedException- if the VirtualMachine is read-only - see- canBeModified().
 
- 
canWatchFieldModificationboolean canWatchFieldModification()Determines if the target VM supports watchpoints for field modification.- Returns:
- trueif the feature is supported,- falseotherwise.
 
- 
canWatchFieldAccessboolean canWatchFieldAccess()Determines if the target VM supports watchpoints for field access.- Returns:
- trueif the feature is supported,- falseotherwise.
 
- 
canGetBytecodesboolean canGetBytecodes()Determines if the target VM supports the retrieval of a method's bytecodes.- Returns:
- trueif the feature is supported,- falseotherwise.
 
- 
canGetSyntheticAttributeboolean canGetSyntheticAttribute()Determines if the target VM supports the query of the synthetic attribute of a method or field.- Returns:
- trueif the feature is supported,- falseotherwise.
 
- 
canGetOwnedMonitorInfoboolean canGetOwnedMonitorInfo()Determines if the target VM supports the retrieval of the monitors owned by a thread.- Returns:
- trueif the feature is supported,- falseotherwise.
 
- 
canGetCurrentContendedMonitorboolean canGetCurrentContendedMonitor()Determines if the target VM supports the retrieval of the monitor for which a thread is currently waiting.- Returns:
- trueif the feature is supported,- falseotherwise.
 
- 
canGetMonitorInfoboolean canGetMonitorInfo()Determines if the target VM supports the retrieval of the monitor information for an object.- Returns:
- trueif the feature is supported,- falseotherwise.
 
- 
canUseInstanceFiltersboolean canUseInstanceFilters()Determines if the target VM supports filtering events by specific instance object. For example, seeBreakpointRequest.addInstanceFilter(com.sun.jdi.ObjectReference).- Returns:
- trueif the feature is supported,- falseotherwise.
 
- 
canRedefineClassesboolean canRedefineClasses()Determines if the target VM supports any level of class redefinition.- Returns:
- trueif the feature is supported,- falseotherwise.
- Since:
- 1.4
- See Also:
 
- 
canAddMethodDeprecated.A JVM TI based JDWP back-end will never set this capability to true.Determines if the target VM supports the addition of methods when performing class redefinition.- Returns:
- trueif the feature is supported,- falseotherwise.
- Since:
- 1.4
- See Also:
 
- 
canUnrestrictedlyRedefineClassesDeprecated.A JVM TI based JDWP back-end will never set this capability to true.Determines if the target VM supports changes when performing class redefinition that are otherwise restricted byredefineClasses(java.util.Map<? extends com.sun.jdi.ReferenceType, byte[]>).- Returns:
- trueif the feature is supported,- falseotherwise.
- Since:
- 1.4
- See Also:
 
- 
canPopFramesboolean canPopFrames()Determines if the target VM supports popping frames of a threads stack.- Returns:
- trueif the feature is supported,- falseotherwise.
- Since:
- 1.4
- See Also:
 
- 
canGetSourceDebugExtensionboolean canGetSourceDebugExtension()Determines if the target VM supports getting the source debug extension.- Returns:
- trueif the feature is supported,- falseotherwise.
- Since:
- 1.4
- See Also:
 
- 
canRequestVMDeathEventboolean canRequestVMDeathEvent()Determines if the target VM supports the creation ofVMDeathRequests.- Returns:
- trueif the feature is supported,- falseotherwise.
- Since:
- 1.4
- See Also:
 
- 
canGetMethodReturnValuesboolean canGetMethodReturnValues()Determines if the target VM supports the inclusion of return values inMethodExitEvents.- Returns:
- trueif the feature is supported,- falseotherwise.
- Since:
- 1.6
- See Also:
 
- 
canGetInstanceInfoboolean canGetInstanceInfo()Determines if the target VM supports the accessing of class instances, instance counts, and referring objects.- Returns:
- trueif the feature is supported,- falseotherwise.
- Since:
- 1.6
- See Also:
 
- 
canUseSourceNameFiltersboolean canUseSourceNameFilters()Determines if the target VM supports the filtering of class prepare events by source name.- Returns:
- trueif the feature is supported,- falseotherwise.
- Since:
- 1.6
- See Also:
 
- 
canForceEarlyReturnboolean canForceEarlyReturn()Determines if the target VM supports the forcing of a method to return early.- Returns:
- trueif the feature is supported,- falseotherwise.
- Since:
- 1.6
- See Also:
 
- 
canBeModifiedboolean canBeModified()Determines if the target VM is a read-only VM. If a method which would modify the state of the VM is called on a read-only VM, thenVMCannotBeModifiedExceptionis thrown.- Returns:
- trueif the feature is supported,- falseotherwise.
- Since:
- 1.5
 
- 
canRequestMonitorEventsboolean canRequestMonitorEvents()Determines if the target VM supports the creation ofMonitorContendedEnterRequests.MonitorContendedEnteredRequests.MonitorWaitRequests.MonitorWaitedRequests.- Returns:
- trueif the feature is supported,- falseotherwise.
- Since:
- 1.6
- See Also:
 
- 
canGetMonitorFrameInfoboolean canGetMonitorFrameInfo()Determines if the target VM supports getting which frame has acquired a monitor.- Returns:
- trueif the feature is supported,- falseotherwise.
- Since:
- 1.6
- See Also:
 
- 
canGetClassFileVersionboolean canGetClassFileVersion()Determines if the target VM supports reading class file major and minor versions.- Returns:
- trueif the feature is supported,- falseotherwise.
- Since:
- 1.6
- See Also:
 
- 
canGetConstantPoolboolean canGetConstantPool()Determines if the target VM supports getting constant pool information of a class.- Returns:
- trueif the feature is supported,- falseotherwise.
- Since:
- 1.6
- See Also:
 
- 
canGetModuleInfodefault boolean canGetModuleInfo()Determines if the target VM supports getting information about modules.- Implementation Requirements:
- The default implementation returns false.
- Returns:
- trueif the feature is supported,- falseotherwise
- Since:
- 9
- See Also:
 
- 
setDefaultStratumSet this VM's default stratum (seeLocationfor 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.- Parameters:
- stratum- the stratum to set as VM default, or null to use per-class defaults.
- Throws:
- UnsupportedOperationException- if the target virtual machine does not support this operation.
- Since:
- 1.4
 
- 
getDefaultStratumString getDefaultStratum()Return this VM's default stratum.- Returns:
- null(meaning that the per-class default -- ReferenceType.defaultStratum()- should be used) unless the default stratum has been set with- setDefaultStratum(String).
- Since:
- 1.4
- See Also:
 
- 
instanceCountsReturns the number of instances of each ReferenceType in the 'refTypes' list. Only instances that are reachable for the purposes of garbage collection are counted.Not all target virtual machines support this operation. Use canGetInstanceInfo()to determine if the operation is supported.- Parameters:
- refTypes- the list of- ReferenceTypeobjects for which counts are to be obtained.
- Returns:
- an array of longcontaining 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.
- Throws:
- UnsupportedOperationException- if the target virtual machine does not support this operation - see- canGetInstanceInfo()
- NullPointerException- if the 'refTypes' list is null.
- Since:
- 1.6
- See Also:
 
- 
descriptionString description()Returns text information on the target VM and the debugger support that mirrors it. No specific format for this information is guaranteed. Typically, this string contains version information for the target VM and debugger interfaces. More precise information on VM and JDI versions is available throughversion(),VirtualMachineManager.majorInterfaceVersion(), andVirtualMachineManager.minorInterfaceVersion()- Returns:
- the description.
 
- 
versionString version()Returns the version of the Java Runtime Environment in the target VM as reported by the propertyjava.version. For obtaining the JDI interface version, useVirtualMachineManager.majorInterfaceVersion()andVirtualMachineManager.minorInterfaceVersion()- Returns:
- the target VM version.
 
- 
nameString name()Returns the name of the target VM as reported by the propertyjava.vm.name.- Returns:
- the target VM name.
 
- 
setDebugTraceModevoid setDebugTraceMode(int traceFlags) Traces the activities performed by the com.sun.jdi implementation. All trace information is output to System.err. The given trace flags are used to limit the output to only the information desired. The given flags are in effect and the corresponding trace will continue until the next call to this method.Output is implementation dependent and trace mode may be ignored. - Parameters:
- traceFlags- identifies which kinds of tracing to enable.
 
 
-