/*
 * %W% %E%
 *
 * Copyright (c) 2006, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

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}
 * <p>
 * StackFrames provide access to a method's local variables and their
 * current values.
 * <p>
 * The lifetime of a StackFrame is very limited. It is available only
 * for suspended threads and becomes invalid once its thread is resumed.
 * <p>
 * Any method on <code>StackFrame</code> which
 * takes <code>StackFrame</code> 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}.
 * <p>
 * Any method on <code>StackFrame</code> which
 * takes <code>StackFrame</code> 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.
     * <p>
     * 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.
     * <p>
     * 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:
     * <ul>
     * <li>the compiler/VM does not immediately reuse the variable's slot.
     * <li>the compiler/VM is implemented to report the extended range that
     * would result from the item above.
     * </ul>
     * 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<LocalVariable> 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<LocalVariable,Value> getValues(List<? extends LocalVariable> 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}.
     * <p>
     * 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<Value> getArgumentValues();

}