public interface

StackFrame

implements Locatable Mirror
com.sun.jdi.StackFrame
Known Indirect Subclasses

Class Overview

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 to 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 takes StackFrame 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 StackFrame which takes StackFrame as an parameter may throw VMOutOfMemoryException if the target VM has run out of memory.

Summary

Public Methods
abstract List<Value> getArgumentValues()
Returns the values of all arguments in this frame.
abstract Value getValue(LocalVariable variable)
Gets the Value of a LocalVariable in this frame.
abstract Map<LocalVariable, Value> getValues(List<? extends LocalVariable> variables)
Returns the values of multiple local variables in this frame.
abstract Location location()
Returns the Location of the current instruction in the frame.
abstract void setValue(LocalVariable variable, Value value)
Sets the Value of a LocalVariable in this frame.
abstract ObjectReference thisObject()
Returns the value of 'this' for the current frame.
abstract ThreadReference thread()
Returns the thread under which this frame's method is running.
abstract LocalVariable visibleVariableByName(String name)
Finds a LocalVariable that matches the given name and is visible at the current frame location.
abstract List<LocalVariable> visibleVariables()
Returns a list containing each LocalVariable that can be accessed from this frame's location.
[Expand]
Inherited Methods
From interface com.sun.jdi.Locatable
From interface com.sun.jdi.Mirror

Public Methods

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

public abstract Value getValue (LocalVariable variable)

Gets the Value of a LocalVariable in this frame. The variable must be valid for this frame's method and visible according to the rules described in visibleVariables().

Parameters
variable the LocalVariable 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.

public abstract 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 in visibleVariables().

Parameters
variables a list of LocalVariable objects to be accessed
Returns
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.

public abstract Location location ()

Returns the Location 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).

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.

public abstract void setValue (LocalVariable variable, Value value)

Sets the Value of a LocalVariable in this frame. The variable must be valid for this frame's method and visible according to the rules described in visibleVariables().

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 value
value 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 - see canBeModified().

public abstract ObjectReference thisObject ()

Returns the value of 'this' for the current frame. The ObjectReference 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.

public abstract ThreadReference thread ()

Returns the thread under which this frame's method is running.

Returns
Throws
InvalidStackFrameException if this stack frame has become invalid. Once the frame's thread is resumed, the stack frame is no longer valid.

public abstract LocalVariable visibleVariableByName (String name)

Finds a LocalVariable that matches the given name and is visible at the current frame location. See visibleVariables() 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.

public abstract List<LocalVariable> visibleVariables ()

Returns a list containing each LocalVariable 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.
The advantage of an extended range is that variables from recently exited scopes may remain available for examination (this is especially useful for loop indices). If, as a result of the extensions above, the current frame location is contained within the range of multiple local variables of the same name, the variable with the highest-starting range is chosen for the returned list.

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.