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
26package com.sun.jdi;
27
28import java.util.List;
29import 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 */
61public 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}
240