/* * Copyright (c) 1998, 2005, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package com.sun.jdi; import java.util.List; import java.util.Map; /** * 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 {@link ThreadReference#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 * {@link com.sun.jdi.VMDisconnectedException} if the target VM is * disconnected and the {@link com.sun.jdi.event.VMDisconnectEvent} has been or is * available to be read from the {@link com.sun.jdi.event.EventQueue}. *

* Any method on StackFrame which * takes StackFrame as an parameter may throw * {@link com.sun.jdi.VMOutOfMemoryException} if the target VM has run out of memory. * * @author Robert Field * @author Gordon Hirsch * @author James McIlree * @since 1.3 */ public interface StackFrame extends Mirror, Locatable { /** * Returns the {@link 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). * * @return the {@link 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. */ Location location(); /** * Returns the thread under which this frame's method is running. * * @return a {@link ThreadReference} which mirrors the frame's thread. * @throws InvalidStackFrameException if this stack frame has become * invalid. Once the frame's thread is resumed, the stack frame is * no longer valid. */ ThreadReference thread(); /** * Returns the value of 'this' for the current frame. * The {@link ObjectReference} for 'this' is only available for * non-native instance methods. * * @return an {@link 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. */ ObjectReference thisObject(); /** * Returns a list containing each {@link 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 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. * * @return the list of {@link 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. * @throws InvalidStackFrameException if this stack frame has become * invalid. Once the frame's thread is resumed, the stack frame is * no longer valid. * @throws NativeMethodException if the current method is native. */ List visibleVariables() throws AbsentInformationException; /** * Finds a {@link LocalVariable} that matches the given name and is * visible at the current frame location. * See {@link #visibleVariables} for more information on visibility. * * @param name the variable name to find * @return the matching {@link 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. * @throws InvalidStackFrameException if this stack frame has become * invalid. Once the frame's thread is resumed, the stack frame is * no longer valid. * @throws NativeMethodException if the current method is native. */ LocalVariable visibleVariableByName(String name) throws AbsentInformationException; /** * Gets the {@link Value} of a {@link LocalVariable} in this frame. * The variable must be valid for this frame's method and visible * according to the rules described in {@link #visibleVariables}. * * @param variable the {@link LocalVariable} to be accessed * @return the {@link Value} of the instance field. * @throws java.lang.IllegalArgumentException if the variable is * either invalid for this frame's method or not visible. * @throws InvalidStackFrameException if this stack frame has become * invalid. Once the frame's thread is resumed, the stack frame is * no longer valid. */ Value getValue(LocalVariable variable); /** * 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 {@link #visibleVariables}. * * @param variables a list of {@link LocalVariable} objects to be accessed * @return a map associating each {@link LocalVariable} with * its {@link Value} * @throws java.lang.IllegalArgumentException if any variable is * either invalid for this frame's method or not visible. * @throws InvalidStackFrameException if this stack frame has become * invalid. Once the frame's thread is resumed, the stack frame is * no longer valid. */ Map getValues(List variables); /** * Sets the {@link Value} of a {@link LocalVariable} in this frame. * The variable must be valid for this frame's method and visible * according to the rules described in {@link #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. * * @param variable the field containing the requested value * @param value the new value to assign * @throws java.lang.IllegalArgumentException if the field is not valid for * this object's class. * @throws InvalidTypeException if the value's type does not match * the variable's type. * @throws ClassNotLoadedException if the variable type has not yet been loaded * through the appropriate class loader. * @throws InvalidStackFrameException if this stack frame has become * invalid. Once the frame's thread is resumed, the stack frame is * no longer valid. * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. */ void setValue(LocalVariable variable, Value value) throws InvalidTypeException, ClassNotLoadedException; /** * Returns the values of all arguments in this frame. Values are * returned even if no local variable information is present. * * @return a list containing a {@link 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. * @since 1.6 */ List getArgumentValues(); }