站内搜索: 请输入搜索关键词
当前页面: 在线文档首页 > JDK 5 Documentation v1.4.1, Java 2 SDK 英文文档

VirtualMachine (Java Debug Interface) - JDK 5 Documentation v1.4.1, Java 2 SDK 英文文档

Overview  Package   Class  Use  Tree  Index  Help 
Java Debug Interface
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.sun.jdi
Interface VirtualMachine

All Superinterfaces:
Mirror
All Known Subinterfaces:
PathSearchingVirtualMachine
public interface VirtualMachine
extends Mirror

A virtual machine targeted for debugging. More precisely, a 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.

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 Summary
static int TRACE_ALL
          All tracing is enabled.
static int TRACE_EVENTS
          Tracing enabled for internal event handling.
static int TRACE_NONE
          All tracing is disabled.
static int TRACE_OBJREFS
          Tracing enabled for internal management of object references.
static int TRACE_RECEIVES
          Tracing enabled for JDWP packets received from target VM.
static int TRACE_REFTYPES
          Tracing enabled for internal managment of reference types.
static int TRACE_SENDS
          Tracing enabled for JDWP packets sent to target VM.
 
Method Summary
 List allClasses()
          Returns all loaded types.
 List 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 canGetBytecodes()
          Determines if the target VM supports the retrieval of a method's bytecodes.
 boolean canGetCurrentContendedMonitor()
          Determines if the target VM supports the retrieval of the monitor for which a thread is currently waiting.
 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 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 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(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.
 BooleanValue mirrorOf(boolean value)
          Creates a BooleanValue for the given value.
 ByteValue mirrorOf(byte value)
          Creates a ByteValue for the given value.
 CharValue mirrorOf(char value)
          Creates a CharValue for the given value.
 DoubleValue mirrorOf(double value)
          Creates a DoubleValue for the given value.
 FloatValue mirrorOf(float value)
          Creates a FloatValue for the given value.
 IntegerValue mirrorOf(int value)
          Creates an IntegerValue for the given value.
 LongValue mirrorOf(long value)
          Creates a LongValue for the given value.
 ShortValue mirrorOf(short value)
          Creates a ShortValue for the given value.
 StringReference mirrorOf(String value)
          Creates a string in this virtual machine.
 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(Map 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 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.
 
Methods inherited from interface com.sun.jdi.Mirror
toString, virtualMachine
 

Field Detail

TRACE_NONE

public static final int TRACE_NONE
All tracing is disabled.

See Also:
Constant Field Values

TRACE_SENDS

public static final int TRACE_SENDS
Tracing enabled for JDWP packets sent to target VM.

See Also:
Constant Field Values

TRACE_RECEIVES

public static final int TRACE_RECEIVES
Tracing enabled for JDWP packets received from target VM.

See Also:
Constant Field Values

TRACE_EVENTS

public static final int TRACE_EVENTS
Tracing enabled for internal event handling.

See Also:
Constant Field Values

TRACE_REFTYPES

public static final int TRACE_REFTYPES
Tracing enabled for internal managment of reference types.

See Also:
Constant Field Values

TRACE_OBJREFS

public static final int TRACE_OBJREFS
Tracing enabled for internal management of object references.

See Also:
Constant Field Values

TRACE_ALL

public static final int TRACE_ALL
All tracing is enabled.

See Also:
Constant Field Values
Method Detail

classesByName

public List classesByName(String className)
Returns 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 a 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.

Parameters:
className - the class/interface name to search for
Returns:
a list of ReferenceType objects, each mirroring a type in the target VM with the given name.

allClasses

public List allClasses()
Returns all loaded types. For each loaded type in the target VM a 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.

Returns:
a list of ReferenceType objects, each mirroring a loaded type in the target VM.

redefineClasses

public void redefineClasses(Map classToBytes)
All classes given are redefined according to the definitions supplied. If any redefined methods have active stack frames, those active frames continue to run the bytecodes of the previous method. The redefined methods will be used on new invokes. If resetting these frames is desired, use ThreadReference.popFrames(StackFrame) with Method.isObsolete().

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.

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.

Parameters:
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.
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 following will throw this exception
    • changing the schema (the fields)
    • changing the hierarchy (subclasses, interfaces)
    • deleting a method
    • changing class modifiers
    • changing method modifiers
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.
Since:
1.4
See Also:
Method.isObsolete(), ThreadReference.popFrames(com.sun.jdi.StackFrame), canRedefineClasses(), canAddMethod(), canUnrestrictedlyRedefineClasses()

allThreads

public List allThreads()
Returns a list of the currently running threads. For each running thread in the target VM, a 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.

Returns:
a list of ThreadReference objects, one for each running thread in the mirrored VM.

suspend

public void suspend()
Suspends the execution of the application running in this virtual machine. All threads currently running will be suspended.

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.

resume

public void resume()
Continues the execution of the application running in this virtual machine. All threads are resumed as documented in ThreadReference.resume().

See Also:
suspend()

topLevelThreadGroups

public List topLevelThreadGroups()
Returns each thread group which does not have a parent. For each top level thread group a 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.

Returns:
a list of ThreadGroupReference objects, one for each top level thread group.

eventQueue

public EventQueue eventQueue()
Returns the event queue for this virtual machine. A virtual machine has only one EventQueue object, this method will return the same instance each time it is invoked.

Returns:
the EventQueue for this virtual machine.

eventRequestManager

public EventRequestManager eventRequestManager()
Returns the event request manager for this virtual machine. The 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.

Returns:
the EventRequestManager for this virtual machine.

mirrorOf

public BooleanValue mirrorOf(boolean value)
Creates a 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.

Parameters:
value - a boolean for which to create the value
Returns:
the BooleanValue for the given boolean.

mirrorOf

public ByteValue mirrorOf(byte value)
Creates a 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.

Parameters:
value - a byte for which to create the value
Returns:
the ByteValue for the given byte.

mirrorOf

public CharValue mirrorOf(char value)
Creates a 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.

Parameters:
value - a char for which to create the value
Returns:
the CharValue for the given char.

mirrorOf

public ShortValue mirrorOf(short value)
Creates a 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.

Parameters:
value - a short for which to create the value
Returns:
the ShortValue for the given short.

mirrorOf

public IntegerValue mirrorOf(int value)
Creates an 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.

Parameters:
value - an int for which to create the value
Returns:
the IntegerValue for the given int.

mirrorOf

public LongValue mirrorOf(long value)
Creates a 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.

Parameters:
value - a long for which to create the value
Returns:
the LongValue for the given long.

mirrorOf

public FloatValue mirrorOf(float value)
Creates a 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.

Parameters:
value - a float for which to create the value
Returns:
the FloatValue for the given float.

mirrorOf

public DoubleValue mirrorOf(double value)
Creates a 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.

Parameters:
value - a double for which to create the value
Returns:
the DoubleValue for the given double.

mirrorOf

public StringReference mirrorOf(String value)
Creates 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.

Returns:
a StringReference that mirrors the newly created string in the target VM.

process

public Process process()
Returns the Process object for this virtual machine if launched by a LaunchingConnector

Returns:
the Process object for this virtual machine, or null if it was not launched by a LaunchingConnector.

dispose

public void 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: Any current method invocations executing in the target VM are continued after the disconnection. Upon completion of any such method invocation, the invoking thread continues from the location where it was originally stopped.

Resources originating in this VirtualMachine (ObjectReferences, ReferenceTypes, etc.) will become invalid.

exit

public void 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.

canWatchFieldModification

public boolean canWatchFieldModification()
Determines if the target VM supports watchpoints for field modification.

Returns:
true if the feature is supported, false otherwise.

canWatchFieldAccess

public boolean canWatchFieldAccess()
Determines if the target VM supports watchpoints for field access.

Returns:
true if the feature is supported, false otherwise.

canGetBytecodes

public boolean canGetBytecodes()
Determines if the target VM supports the retrieval of a method's bytecodes.

Returns:
true if the feature is supported, false otherwise.

canGetSyntheticAttribute

public boolean canGetSyntheticAttribute()
Determines if the target VM supports the query of the synthetic attribute of a method or field.

Returns:
true if the feature is supported, false otherwise.

canGetOwnedMonitorInfo

public boolean canGetOwnedMonitorInfo()
Determines if the target VM supports the retrieval of the monitors owned by a thread.

Returns:
true if the feature is supported, false otherwise.

canGetCurrentContendedMonitor

public boolean canGetCurrentContendedMonitor()
Determines if the target VM supports the retrieval of the monitor for which a thread is currently waiting.

Returns:
true if the feature is supported, false otherwise.

canGetMonitorInfo

public boolean canGetMonitorInfo()
Determines if the target VM supports the retrieval of the monitor information for an object.

Returns:
true if the feature is supported, false otherwise.

canUseInstanceFilters

public boolean canUseInstanceFilters()
Determines if the target VM supports filtering events by specific instance object. For example, see BreakpointRequest.addInstanceFilter(com.sun.jdi.ObjectReference).

Returns:
true if the feature is supported, false otherwise.

canRedefineClasses

public boolean canRedefineClasses()
Determines if the target VM supports any level of class redefinition.

Returns:
true if the feature is supported, false otherwise.
Since:
1.4
See Also:
redefineClasses(java.util.Map)

canAddMethod

public boolean canAddMethod()
Determines if the target VM supports the addition of methods when performing class redefinition.

Returns:
true if the feature is supported, false otherwise.
Since:
1.4
See Also:
redefineClasses(java.util.Map)

canUnrestrictedlyRedefineClasses

public boolean canUnrestrictedlyRedefineClasses()
Determines if the target VM supports unrestricted changes when performing class redefinition.

Returns:
true if the feature is supported, false otherwise.
Since:
1.4
See Also:
redefineClasses(java.util.Map)

canPopFrames

public boolean canPopFrames()
Determines if the target VM supports popping frames of a threads stack.

Returns:
true if the feature is supported, false otherwise.
Since:
1.4
See Also:
ThreadReference.popFrames(com.sun.jdi.StackFrame)

canGetSourceDebugExtension

public boolean canGetSourceDebugExtension()
Determines if the target VM supports getting the source debug extension.

Returns:
true if the feature is supported, false otherwise.
Since:
1.4
See Also:
ReferenceType.sourceDebugExtension()

canRequestVMDeathEvent

public boolean canRequestVMDeathEvent()
Determines if the target VM supports the creation of VMDeathRequests.

Returns:
true if the feature is supported, false otherwise.
Since:
1.4
See Also:
EventRequestManager.createVMDeathRequest()

setDefaultStratum

public void setDefaultStratum(String stratum)
Set this VM's default stratum (see 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.

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

getDefaultStratum

public String 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:
setDefaultStratum(String), ReferenceType.defaultStratum()

description

public String 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 through version(), VirtualMachineManager.majorInterfaceVersion(), and VirtualMachineManager.minorInterfaceVersion()

Returns:
the description.

version

public String version()
Returns the version of the Java Runtime Environment in the target VM as reported by the property java.version. For obtaining the JDI interface version, use VirtualMachineManager.majorInterfaceVersion() and VirtualMachineManager.minorInterfaceVersion()

Returns:
the target VM version.

name

public String name()
Returns the name of the target VM as reported by the property java.vm.name.

Returns:
the target VM name.

setDebugTraceMode

public void 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.
Overview  Package   Class  Use  Tree  Index  Help 
Java Debug Interface
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD