-
public interface StackFrame extends Mirror, Locatable
The state of one method invocation on a thread's call stack. As a thread executes, stack frames are pushed and popped from its call stack as methods are invoked and then return. A StackFrame mirrors one such frame from a target VM at some point in its thread's execution. The call stack is, then, simply a List of StackFrame objects. The call stack can be obtained any time a thread is suspended through a call toThreadReference.frames()
StackFrames provide access to a method's local variables and their current values.
The lifetime of a StackFrame is very limited. It is available only for suspended threads and becomes invalid once its thread is resumed.
Any method on
StackFrame
which takesStackFrame
as an parameter may throwVMDisconnectedException
if the target VM is disconnected and theVMDisconnectEvent
has been or is available to be read from theEventQueue
.Any method on
StackFrame
which takesStackFrame
as an parameter may throwVMOutOfMemoryException
if the target VM has run out of memory.- Since:
- 1.3
-
-
Method Summary
Modifier and Type Method Description List<Value>
getArgumentValues()
Returns the values of all arguments in this frame.Value
getValue(LocalVariable variable)
Gets theValue
of aLocalVariable
in this frame.Map<LocalVariable,Value>
getValues(List<? extends LocalVariable> variables)
Returns the values of multiple local variables in this frame.Location
location()
Returns theLocation
of the current instruction in the frame.void
setValue(LocalVariable variable, Value value)
Sets theValue
of aLocalVariable
in this frame.ObjectReference
thisObject()
Returns the value of 'this' for the current frame.ThreadReference
thread()
Returns the thread under which this frame's method is running.LocalVariable
visibleVariableByName(String name)
Finds aLocalVariable
that matches the given name and is visible at the current frame location.List<LocalVariable>
visibleVariables()
Returns a list containing eachLocalVariable
that can be accessed from this frame's location.-
Methods declared in interface com.sun.jdi.Mirror
toString, virtualMachine
-
-
-
-
Method Detail
-
location
Location location()
Returns theLocation
of the current instruction in the frame. The method for which this frame was created can also be accessed through the returned location. For the top frame in the stack, this location identifies the next instruction to be executed. For all other frames, this location identifies the instruction that caused the next frame's method to be invoked. If the frame represents a native method invocation, the returned location indicates the class and method, but the code index will not be valid (-1).- Specified by:
location
in interfaceLocatable
- Returns:
- the
Location
of the current instruction. - Throws:
InvalidStackFrameException
- if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.
-
thread
ThreadReference thread()
Returns the thread under which this frame's method is running.- Returns:
- a
ThreadReference
which mirrors the frame's thread. - Throws:
InvalidStackFrameException
- if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.
-
thisObject
ObjectReference thisObject()
Returns the value of 'this' for the current frame. TheObjectReference
for 'this' is only available for non-native instance methods.- Returns:
- an
ObjectReference
, or null if the frame represents a native or static method. - Throws:
InvalidStackFrameException
- if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.
-
visibleVariables
List<LocalVariable> visibleVariables() throws AbsentInformationException
Returns a list containing eachLocalVariable
that can be accessed from this frame's location.Visibility is based on the code index of the current instruction of this StackFrame. Each variable has a range of byte code indices in which it is accessible. If this stack frame's method matches this variable's method and if the code index of this StackFrame is within the variable's byte code range, the variable is visible.
A variable's byte code range is at least as large as the scope of that variable, but can continue beyond the end of the scope under certain circumstances:
- the compiler/VM does not immediately reuse the variable's slot.
- the compiler/VM is implemented to report the extended range that would result from the item above.
- Returns:
- the list of
LocalVariable
objects currently visible; the list will be empty if there are no visible variables; specifically, frames in native methods will always return a zero-length list. - Throws:
AbsentInformationException
- if there is no local variable information for this method.InvalidStackFrameException
- if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.NativeMethodException
- if the current method is native.
-
visibleVariableByName
LocalVariable visibleVariableByName(String name) throws AbsentInformationException
Finds aLocalVariable
that matches the given name and is visible at the current frame location. SeevisibleVariables()
for more information on visibility.- Parameters:
name
- the variable name to find- Returns:
- the matching
LocalVariable
, or null if there is no visible variable with the given name; frames in native methods will always return null. - Throws:
AbsentInformationException
- if there is no local variable information for this method.InvalidStackFrameException
- if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.NativeMethodException
- if the current method is native.
-
getValue
Value getValue(LocalVariable variable)
Gets theValue
of aLocalVariable
in this frame. The variable must be valid for this frame's method and visible according to the rules described invisibleVariables()
.- Parameters:
variable
- theLocalVariable
to be accessed- Returns:
- the
Value
of the instance field. - Throws:
IllegalArgumentException
- if the variable is either invalid for this frame's method or not visible.InvalidStackFrameException
- if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.
-
getValues
Map<LocalVariable,Value> getValues(List<? extends LocalVariable> variables)
Returns the values of multiple local variables in this frame. Each variable must be valid for this frame's method and visible according to the rules described invisibleVariables()
.- Parameters:
variables
- a list ofLocalVariable
objects to be accessed- Returns:
- a map associating each
LocalVariable
with itsValue
- Throws:
IllegalArgumentException
- if any variable is either invalid for this frame's method or not visible.InvalidStackFrameException
- if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.
-
setValue
void setValue(LocalVariable variable, Value value) throws InvalidTypeException, ClassNotLoadedException
Sets theValue
of aLocalVariable
in this frame. The variable must be valid for this frame's method and visible according to the rules described invisibleVariables()
.Object values must be assignment compatible with the variable type (This implies that the variable type must be loaded through the enclosing class's class loader). Primitive values must be either assignment compatible with the variable type or must be convertible to the variable type without loss of information. See JLS section 5.2 for more information on assignment compatibility.
- Parameters:
variable
- the field containing the requested valuevalue
- the new value to assign- Throws:
IllegalArgumentException
- if the field is not valid for this object's class.InvalidTypeException
- if the value's type does not match the variable's type.ClassNotLoadedException
- if the variable type has not yet been loaded through the appropriate class loader.InvalidStackFrameException
- if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.VMCannotBeModifiedException
- if the VirtualMachine is read-only - seeVirtualMachine.canBeModified()
.
-
getArgumentValues
List<Value> getArgumentValues()
Returns the values of all arguments in this frame. Values are returned even if no local variable information is present.- Returns:
- a list containing a
Value
object for each argument to this frame, in the order in which the arguments were declared. If the method corresponding to this frame has no arguments, an empty list is returned. - Throws:
InvalidStackFrameException
- if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.- Since:
- 1.6
-
-