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 @jdk.Exported 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 */ location()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 */ thread()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 */ thisObject()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 */ visibleVariables()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 */ visibleVariableByName(String name)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 */ getValue(LocalVariable variable)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 */ getValues(List<? extends LocalVariable> variables)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 */ setValue(LocalVariable variable, Value value)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 */ getArgumentValues()238 List<Value> getArgumentValues(); 239 240 } 241