/*******************************************************************************
 * Copyright (c) 2000, 2011 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jdt.debug.core;

import java.util.List;

import org.eclipse.debug.core.DebugException;
import org.eclipse.debug.core.model.IDropToFrame;
import org.eclipse.debug.core.model.IFilteredStep;
import org.eclipse.debug.core.model.IStackFrame;

/**
 * A stack frame in a thread on a Java virtual machine.
 * <p>
 * Since 3.1, <code>IJavaStackFrame</code> also implements
 * {@link org.eclipse.debug.core.model.IDropToFrame}.
 * </p>
 * 
 * @see org.eclipse.debug.core.model.IStackFrame
 * @noimplement This interface is not intended to be implemented by clients.
 * @noextend This interface is not intended to be extended by clients.
 */
@SuppressWarnings("deprecation")
public interface IJavaStackFrame extends IStackFrame, IJavaModifiers,
		IFilteredStep, IDropToFrame {

	/**
	 * Status code indicating a stack frame is invalid. A stack frame becomes
	 * invalid when the thread containing the stack frame resumes. A stack frame
	 * may or may not be valid if the thread subsequently suspends, depending on
	 * the location where the thread suspends.
	 * 
	 * @since 3.1
	 */
	public static final int ERR_INVALID_STACK_FRAME = 130;

	/**
	 * Returns whether this stack frame currently supports the drop to frame
	 * operation. Note that not all VMs support the operation.
	 * 
	 * @return whether this stack frame currently supports drop to frame
	 * @deprecated since 3.1, IJavaStackFrame extends
	 *             org.eclipse.debug.core.IDropToFrame which defines
	 *             canDropToFrame(). Use this method instead.
	 */
	@Deprecated
	boolean supportsDropToFrame();

	/**
	 * Returns whether the method associated with this stack frame is a
	 * constructor.
	 * 
	 * @return whether this stack frame is associated with a constructor
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 */
	public boolean isConstructor() throws DebugException;

	/**
	 * Returns whether the method associated with this stack frame has been
	 * declared as native.
	 * 
	 * @return whether this stack frame has been declared as native
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 */
	public boolean isNative() throws DebugException;

	/**
	 * Returns whether the method associated with this stack frame is a static
	 * initializer.
	 * 
	 * @return whether this stack frame is a static initializer
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 */
	public boolean isStaticInitializer() throws DebugException;

	/**
	 * Returns whether the method associated with this stack frame has been
	 * declared as synchronized.
	 * 
	 * @return whether this stack frame has been declared as synchronized
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 */
	public boolean isSynchronized() throws DebugException;

	/**
	 * Returns whether the method associated with this stack frame is running
	 * code in the VM that is out of synch with the code in the workspace.
	 * 
	 * @return whether this stack frame is out of synch with the workspace.
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 * @since 2.0
	 */
	public boolean isOutOfSynch() throws DebugException;

	/**
	 * Returns whether the method associated with this stack frame is obsolete,
	 * that is, it is running old byte codes that have been replaced in the VM.
	 * This can occur when a hot code replace succeeds but the VM is unable to
	 * pop a call to an affected method from the call stack.
	 * 
	 * @return whether this stack frame's method is obsolete
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 * @since 2.0
	 */
	public boolean isObsolete() throws DebugException;

	/**
	 * Returns the fully qualified name of the type that declares the method
	 * associated with this stack frame.
	 * 
	 * @return declaring type name
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 */
	public String getDeclaringTypeName() throws DebugException;

	/**
	 * Returns the fully qualified name of the type that is the receiving object
	 * associated with this stack frame
	 * 
	 * @return receiving type name
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 */
	public String getReceivingTypeName() throws DebugException;

	/**
	 * Returns the JNI signature for the method this stack frame is associated
	 * with.
	 * 
	 * @return signature
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 */
	public String getSignature() throws DebugException;

	/**
	 * Returns a list of fully qualified type names of the arguments for the
	 * method associated with this stack frame.
	 * 
	 * @return argument type names, or an empty list if this method has no
	 *         arguments
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 */
	public List<String> getArgumentTypeNames() throws DebugException;

	/**
	 * Returns the name of the method associated with this stack frame
	 * 
	 * @return method name
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 */
	public String getMethodName() throws DebugException;

	/**
	 * Returns the local, static, or "this" variable with the given name, or
	 * <code>null</code> if unable to resolve a variable with the name.
	 * 
	 * @param variableName
	 *            the name of the variable to search for
	 * @return a variable, or <code>null</code> if none
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 */
	public IJavaVariable findVariable(String variableName)
			throws DebugException;

	/**
	 * Returns the line number of the instruction pointer in this stack frame
	 * that corresponds to the line in the associated source element in the
	 * specified stratum, or <code>-1</code> if line number information is
	 * unavailable.
	 * 
	 * @param stratum
	 *            the stratum to use.
	 * @return line number of instruction pointer in this stack frame, or
	 *         <code>-1</code> if line number information is unavailable
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the debug target. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                </ul>
	 * 
	 * @since 3.0
	 */
	public int getLineNumber(String stratum) throws DebugException;

	/**
	 * Returns the source name debug attribute associated with the declaring
	 * type of this stack frame, or <code>null</code> if the source name debug
	 * attribute not present.
	 * 
	 * @return source name debug attribute, or <code>null</code>
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 */
	public String getSourceName() throws DebugException;

	/**
	 * Returns the source name debug attribute associated with the declaring
	 * type of this stack frame in the specified stratum, or <code>null</code>
	 * if the source name debug attribute not present.
	 * 
	 * @param stratum
	 *            the stratum to use.
	 * @return source name debug attribute, or <code>null</code>
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 * 
	 * @since 3.0
	 */
	public String getSourceName(String stratum) throws DebugException;

	/**
	 * Returns the source path debug attribute associated with this stack frame
	 * in the specified stratum, or <code>null</code> if the source path is not
	 * known.
	 * 
	 * @param stratum
	 *            the stratum to use.
	 * @return source path debug attribute, or <code>null</code>
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 * @since 3.0
	 */
	public String getSourcePath(String stratum) throws DebugException;

	/**
	 * Returns the source path debug attribute associated with this stack frame,
	 * or <code>null</code> if the source path is not known.
	 * 
	 * @return source path debug attribute, or <code>null</code>
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 * @since 3.0
	 */
	public String getSourcePath() throws DebugException;

	/**
	 * Returns a collection of local variables that are visible at the current
	 * point of execution in this stack frame. The list includes arguments.
	 * 
	 * @return collection of locals and arguments
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 * @since 2.0
	 */
	public IJavaVariable[] getLocalVariables() throws DebugException;

	/**
	 * Returns a reference to the receiver of the method associated with this
	 * stack frame, or <code>null</code> if this stack frame represents a static
	 * method.
	 * 
	 * @return 'this' object, or <code>null</code>
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 */
	public IJavaObject getThis() throws DebugException;

	/**
	 * Returns the class in which this stack frame's method is declared.
	 * 
	 * @return the class in which this stack frame's method is declared
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 * @since 2.0
	 * @deprecated Use <code>getReferenceType()</code> instead, as a method is
	 *             not restricted to occur in a class. An interface may contain
	 *             a synthetic class initializer methods. Since 3.1, this method
	 *             throws a <code>DebugException</code> when a stack frame's
	 *             method is contained in an interface.
	 */
	@Deprecated
	public IJavaClassType getDeclaringType() throws DebugException;

	/**
	 * Returns the type in which this stack frame's method is declared.
	 * 
	 * @return the type in which this stack frame's method is declared
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 * @since 3.1
	 */
	public IJavaReferenceType getReferenceType() throws DebugException;

	/**
	 * Returns whether local variable information was available when local
	 * variables were retrieved from the target for this frame. Returns
	 * <code>true</code> if locals have never been retrieved. This data is
	 * available after the fact, since variable retrieval is expensive.
	 * 
	 * @return whether local variable information was available when variables
	 *         were retrieved from the target. Returns <code>true</code> if
	 *         locals have never been retrieved
	 * 
	 * @since 2.0
	 */
	public boolean wereLocalsAvailable();

	/**
	 * Returns whether the method associated with this stack frame accepts a
	 * variable number of arguments.
	 * 
	 * @return <code>true</code> if the method associated with this stack frame
	 *         accepts a variable number of arguments, <code>false</code>
	 *         otherwise.
	 * @exception DebugException
	 *                if this method fails. Reasons include:
	 *                <ul>
	 *                <li>Failure communicating with the VM. The
	 *                DebugException's status code contains the underlying
	 *                exception responsible for the failure.</li>
	 *                <li>This stack frame is no longer valid. That is, the
	 *                thread containing this stack frame has since been resumed.
	 *                </li>
	 *                </ul>
	 * @since 3.1
	 */
	public boolean isVarArgs() throws DebugException;

	/**
	 * Returns whether this frame currently supports a force return operation.
	 * That is, can this method force a return before it reaches a return
	 * statement. Not all VMs support this feature.
	 * <p>
	 * Force return is only available when a thread is suspended.
	 * </p>
	 * 
	 * @return whether force return can be performed currently
	 * @since 3.3
	 */
	public boolean canForceReturn();

	/**
	 * Steps out of this frame's method returning the given value. No further
	 * instructions in the method are executed but locks acquired by entering
	 * synchronized blocks are released. The following conditions must be
	 * satisfied:
	 * <ul>
	 * <li>This frame must be suspended in a non-native method.</li>
	 * <li>The return value must be assignment compatible with this frame's
	 * method's return type. Use a void value when a method return type is void
	 * (see <code>IJavaDebugTarget.voidValue()</code>).</li>
	 * </ul>
	 * 
	 * @param value
	 *            return value that must be assignment compatible with this
	 *            frame's method's return value
	 * @throws DebugException
	 *             if the operation fails
	 * @since 3.3
	 */
	public void forceReturn(IJavaValue value) throws DebugException;
}