1 /*
2 * Copyright (c) 1998, 2005, 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 @jdk.Supported
62 public interface StackFrame extends Mirror, Locatable {
63
64 /**
65 * Returns the {@link Location} of the current instruction in the frame.
66 * The method for which this frame was created can also be accessed
67 * through the returned location.
68 * For the top frame in the stack, this location identifies the
69 * next instruction to be executed. For all other frames, this
70 * location identifies the instruction that caused the next frame's
71 * method to be invoked.
72 * If the frame represents a native method invocation, the returned
73 * location indicates the class and method, but the code index will
74 * not be valid (-1).
75 *
76 * @return the {@link Location} of the current instruction.
77 * @throws InvalidStackFrameException if this stack frame has become
78 * invalid. Once the frame's thread is resumed, the stack frame is
79 * no longer valid.
80 */
81 Location location();
82
83 /**
84 * Returns the thread under which this frame's method is running.
85 *
86 * @return a {@link ThreadReference} which mirrors the frame's thread.
87 * @throws InvalidStackFrameException if this stack frame has become
88 * invalid. Once the frame's thread is resumed, the stack frame is
89 * no longer valid.
90 */
91 ThreadReference thread();
92
93 /**
94 * Returns the value of 'this' for the current frame.
95 * The {@link ObjectReference} for 'this' is only available for
96 * non-native instance methods.
97 *
98 * @return an {@link ObjectReference}, or null if the frame represents
99 * a native or static method.
100 * @throws InvalidStackFrameException if this stack frame has become
101 * invalid. Once the frame's thread is resumed, the stack frame is
102 * no longer valid.
103 */
104 ObjectReference thisObject();
105
106 /**
107 * Returns a list containing each {@link LocalVariable}
108 * that can be accessed from this frame's location.
109 * <p>
110 * Visibility is based on the code index of the current instruction of
111 * this StackFrame. Each variable has a range of byte code indices in which
112 * it is accessible.
113 * If this stack frame's method
114 * matches this variable's method and if the code index of this
115 * StackFrame is within the variable's byte code range, the variable is
116 * visible.
117 * <p>
118 * A variable's byte code range is at least as large as the scope of
119 * that variable, but can continue beyond the end of the scope under
120 * certain circumstances:
121 * <ul>
122 * <li>the compiler/VM does not immediately reuse the variable's slot.
123 * <li>the compiler/VM is implemented to report the extended range that
124 * would result from the item above.
125 * </ul>
126 * The advantage of an extended range is that variables from recently
127 * exited scopes may remain available for examination (this is especially
128 * useful for loop indices). If, as a result of the extensions above,
129 * the current frame location is contained within the range
130 * of multiple local variables of the same name, the variable with the
131 * highest-starting range is chosen for the returned list.
132 *
133 * @return the list of {@link LocalVariable} objects currently visible;
134 * the list will be empty if there are no visible variables;
135 * specifically, frames in native methods will always return a
136 * zero-length list.
137 * @throws AbsentInformationException if there is no local variable
138 * information for this method.
139 * @throws InvalidStackFrameException if this stack frame has become
140 * invalid. Once the frame's thread is resumed, the stack frame is
141 * no longer valid.
142 * @throws NativeMethodException if the current method is native.
143 */
144 List<LocalVariable> visibleVariables() throws AbsentInformationException;
145
146 /**
147 * Finds a {@link LocalVariable} that matches the given name and is
148 * visible at the current frame location.
149 * See {@link #visibleVariables} for more information on visibility.
150 *
151 * @param name the variable name to find
152 * @return the matching {@link LocalVariable}, or null if there is no
153 * visible variable with the given name; frames in native methods
154 * will always return null.
155 * @throws AbsentInformationException if there is no local variable
156 * information for this method.
157 * @throws InvalidStackFrameException if this stack frame has become
158 * invalid. Once the frame's thread is resumed, the stack frame is
159 * no longer valid.
160 * @throws NativeMethodException if the current method is native.
161 */
162 LocalVariable visibleVariableByName(String name) throws AbsentInformationException;
163
164 /**
165 * Gets the {@link Value} of a {@link LocalVariable} in this frame.
166 * The variable must be valid for this frame's method and visible
167 * according to the rules described in {@link #visibleVariables}.
168 *
169 * @param variable the {@link LocalVariable} to be accessed
170 * @return the {@link Value} of the instance field.
171 * @throws java.lang.IllegalArgumentException if the variable is
172 * either invalid for this frame's method or not visible.
173 * @throws InvalidStackFrameException if this stack frame has become
174 * invalid. Once the frame's thread is resumed, the stack frame is
175 * no longer valid.
176 */
177 Value getValue(LocalVariable variable);
178
179 /**
180 * Returns the values of multiple local variables in this frame.
181 * Each variable must be valid for this frame's method and visible
182 * according to the rules described in {@link #visibleVariables}.
183 *
184 * @param variables a list of {@link LocalVariable} objects to be accessed
185 * @return a map associating each {@link LocalVariable} with
186 * its {@link Value}
187 * @throws java.lang.IllegalArgumentException if any variable is
188 * either invalid for this frame's method or not visible.
189 * @throws InvalidStackFrameException if this stack frame has become
190 * invalid. Once the frame's thread is resumed, the stack frame is
191 * no longer valid.
192 */
193 Map<LocalVariable,Value> getValues(List<? extends LocalVariable> variables);
194
195 /**
196 * Sets the {@link Value} of a {@link LocalVariable} in this frame.
197 * The variable must be valid for this frame's method and visible
198 * according to the rules described in {@link #visibleVariables}.
199 * <p>
200 * Object values must be assignment compatible with the variable type
201 * (This implies that the variable type must be loaded through the
202 * enclosing class's class loader). Primitive values must be
203 * either assignment compatible with the variable type or must be
204 * convertible to the variable type without loss of information.
205 * See JLS section 5.2 for more information on assignment
206 * compatibility.
207 *
208 * @param variable the field containing the requested value
209 * @param value the new value to assign
210 * @throws java.lang.IllegalArgumentException if the field is not valid for
211 * this object's class.
212 * @throws InvalidTypeException if the value's type does not match
213 * the variable's type.
214 * @throws ClassNotLoadedException if the variable type has not yet been loaded
215 * through the appropriate class loader.
216 * @throws InvalidStackFrameException if this stack frame has become
217 * invalid. Once the frame's thread is resumed, the stack frame is
218 * no longer valid.
219 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}.
220 */
221 void setValue(LocalVariable variable, Value value)
222 throws InvalidTypeException, ClassNotLoadedException;
223
224 /**
225 * Returns the values of all arguments in this frame. Values are
226 * returned even if no local variable information is present.
227 *
228 * @return a list containing a {@link Value} object for each argument
229 * to this frame, in the order in which the arguments were
230 * declared. If the method corresponding to this frame has
231 * no arguments, an empty list is returned.
232 *
233 * @throws InvalidStackFrameException if this stack frame has become
234 * invalid. Once the frame's thread is resumed, the stack frame is
235 * no longer valid.
236 * @since 1.6
237 */
238 List<Value> getArgumentValues();
239
240 }