1 /*
2 * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package com.sun.jdi;
27
28 import java.util.List;
29 import java.util.Map;
30
31 /**
32 * The state of one method invocation on a thread's call stack.
33 * As a thread executes, stack frames are pushed and popped from
34 * its call stack as methods are invoked and then return. A StackFrame
35 * mirrors one such frame from a target VM at some point in its
36 * thread's execution. The call stack is, then, simply a List of
37 * StackFrame objects. The call stack can be obtained any time a thread
38 * is suspended through a call to {@link ThreadReference#frames}
39 * <p>
40 * StackFrames provide access to a method's local variables and their
41 * current values.
42 * <p>
43 * The lifetime of a StackFrame is very limited. It is available only
44 * for suspended threads and becomes invalid once its thread is resumed.
45 * <p>
46 * Any method on <code>StackFrame</code> which
47 * takes <code>StackFrame</code> as an parameter may throw
48 * {@link com.sun.jdi.VMDisconnectedException} if the target VM is
49 * disconnected and the {@link com.sun.jdi.event.VMDisconnectEvent} has been or is
50 * available to be read from the {@link com.sun.jdi.event.EventQueue}.
51 * <p>
52 * Any method on <code>StackFrame</code> which
53 * takes <code>StackFrame</code> as an parameter may throw
54 * {@link com.sun.jdi.VMOutOfMemoryException} if the target VM has run out of memory.
55 *
56 * @author Robert Field
57 * @author Gordon Hirsch
58 * @author James McIlree
59 * @since 1.3
60 */
61 public interface StackFrame extends Mirror, Locatable {
62
63 /**
64 * Returns the {@link Location} of the current instruction in the frame.
65 * The method for which this frame was created can also be accessed
66 * through the returned location.
67 * For the top frame in the stack, this location identifies the
68 * next instruction to be executed. For all other frames, this
69 * location identifies the instruction that caused the next frame's
70 * method to be invoked.
71 * If the frame represents a native method invocation, the returned
72 * location indicates the class and method, but the code index will
73 * not be valid (-1).
74 *
75 * @return the {@link Location} of the current instruction.
76 * @throws InvalidStackFrameException if this stack frame has become
77 * invalid. Once the frame's thread is resumed, the stack frame is
78 * no longer valid.
79 */
80 Location location();
81
82 /**
83 * Returns the thread under which this frame's method is running.
84 *
85 * @return a {@link ThreadReference} which mirrors the frame's thread.
86 * @throws InvalidStackFrameException if this stack frame has become
87 * invalid. Once the frame's thread is resumed, the stack frame is
88 * no longer valid.
89 */
90 ThreadReference thread();
91
92 /**
93 * Returns the value of 'this' for the current frame.
94 * The {@link ObjectReference} for 'this' is only available for
95 * non-native instance methods.
96 *
97 * @return an {@link ObjectReference}, or null if the frame represents
98 * a native or static method.
99 * @throws InvalidStackFrameException if this stack frame has become
100 * invalid. Once the frame's thread is resumed, the stack frame is
101 * no longer valid.
102 */
103 ObjectReference thisObject();
104
105 /**
106 * Returns a list containing each {@link LocalVariable}
107 * that can be accessed from this frame's location.
108 * <p>
109 * Visibility is based on the code index of the current instruction of
110 * this StackFrame. Each variable has a range of byte code indices in which
111 * it is accessible.
112 * If this stack frame's method
113 * matches this variable's method and if the code index of this
114 * StackFrame is within the variable's byte code range, the variable is
115 * visible.
116 * <p>
117 * A variable's byte code range is at least as large as the scope of
118 * that variable, but can continue beyond the end of the scope under
119 * certain circumstances:
120 * <ul>
121 * <li>the compiler/VM does not immediately reuse the variable's slot.
122 * <li>the compiler/VM is implemented to report the extended range that
123 * would result from the item above.
124 * </ul>
125 * The advantage of an extended range is that variables from recently
126 * exited scopes may remain available for examination (this is especially
127 * useful for loop indices). If, as a result of the extensions above,
128 * the current frame location is contained within the range
129 * of multiple local variables of the same name, the variable with the
130 * highest-starting range is chosen for the returned list.
131 *
132 * @return the list of {@link LocalVariable} objects currently visible;
133 * the list will be empty if there are no visible variables;
134 * specifically, frames in native methods will always return a
135 * zero-length list.
136 * @throws AbsentInformationException if there is no local variable
137 * information for this method.
138 * @throws InvalidStackFrameException if this stack frame has become
139 * invalid. Once the frame's thread is resumed, the stack frame is
140 * no longer valid.
141 * @throws NativeMethodException if the current method is native.
142 */
143 List<LocalVariable> visibleVariables() throws AbsentInformationException;
144
145 /**
146 * Finds a {@link LocalVariable} that matches the given name and is
147 * visible at the current frame location.
148 * See {@link #visibleVariables} for more information on visibility.
149 *
150 * @param name the variable name to find
151 * @return the matching {@link LocalVariable}, or null if there is no
152 * visible variable with the given name; frames in native methods
153 * will always return null.
154 * @throws AbsentInformationException if there is no local variable
155 * information for this method.
156 * @throws InvalidStackFrameException if this stack frame has become
157 * invalid. Once the frame's thread is resumed, the stack frame is
158 * no longer valid.
159 * @throws NativeMethodException if the current method is native.
160 */
161 LocalVariable visibleVariableByName(String name) throws AbsentInformationException;
162
163 /**
164 * Gets the {@link Value} of a {@link LocalVariable} in this frame.
165 * The variable must be valid for this frame's method and visible
166 * according to the rules described in {@link #visibleVariables}.
167 *
168 * @param variable the {@link LocalVariable} to be accessed
169 * @return the {@link Value} of the instance field.
170 * @throws java.lang.IllegalArgumentException if the variable is
171 * either invalid for this frame's method or not visible.
172 * @throws InvalidStackFrameException if this stack frame has become
173 * invalid. Once the frame's thread is resumed, the stack frame is
174 * no longer valid.
175 */
176 Value getValue(LocalVariable variable);
177
178 /**
179 * Returns the values of multiple local variables in this frame.
180 * Each variable must be valid for this frame's method and visible
181 * according to the rules described in {@link #visibleVariables}.
182 *
183 * @param variables a list of {@link LocalVariable} objects to be accessed
184 * @return a map associating each {@link LocalVariable} with
185 * its {@link Value}
186 * @throws java.lang.IllegalArgumentException if any variable is
187 * either invalid for this frame's method or not visible.
188 * @throws InvalidStackFrameException if this stack frame has become
189 * invalid. Once the frame's thread is resumed, the stack frame is
190 * no longer valid.
191 */
192 Map<LocalVariable,Value> getValues(List<? extends LocalVariable> variables);
193
194 /**
195 * Sets the {@link Value} of a {@link LocalVariable} in this frame.
196 * The variable must be valid for this frame's method and visible
197 * according to the rules described in {@link #visibleVariables}.
198 * <p>
199 * Object values must be assignment compatible with the variable type
200 * (This implies that the variable type must be loaded through the
201 * enclosing class's class loader). Primitive values must be
202 * either assignment compatible with the variable type or must be
203 * convertible to the variable type without loss of information.
204 * See JLS section 5.2 for more information on assignment
205 * compatibility.
206 *
207 * @param variable the field containing the requested value
208 * @param value the new value to assign
209 * @throws java.lang.IllegalArgumentException if the field is not valid for
210 * this object's class.
211 * @throws InvalidTypeException if the value's type does not match
212 * the variable's type.
213 * @throws ClassNotLoadedException if the variable type has not yet been loaded
214 * through the appropriate class loader.
215 * @throws InvalidStackFrameException if this stack frame has become
216 * invalid. Once the frame's thread is resumed, the stack frame is
217 * no longer valid.
218 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
219 */
220 void setValue(LocalVariable variable, Value value)
221 throws InvalidTypeException, ClassNotLoadedException;
222
223 /**
224 * Returns the values of all arguments in this frame. Values are
225 * returned even if no local variable information is present.
226 *
227 * @return a list containing a {@link Value} object for each argument
228 * to this frame, in the order in which the arguments were
229 * declared. If the method corresponding to this frame has
230 * no arguments, an empty list is returned.
231 *
232 * @throws InvalidStackFrameException if this stack frame has become
233 * invalid. Once the frame's thread is resumed, the stack frame is
234 * no longer valid.
235 * @since 1.6
236 */
237 List<Value> getArgumentValues();
238
239 }