/*******************************************************************************
 * Copyright (c) 2000, 2005 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.debug.core.model;


import org.eclipse.debug.core.DebugException;

/**
 * A stack frame represents an execution context in a suspended thread.
 * A stack frame contains variables representing visible locals and arguments at
 * the current execution location. Minimally, a stack frame supports
 * the following:
 * <ul>
 * <li>suspend/resume (convenience to resume this stack frame's thread)
 * <li>stepping
 * <li>termination (convenience to terminate this stack frame's thread or debug target)
 * </ul>
 * <p>
 * A debug model implementation may choose to re-use or discard
 * stack frames on iterative thread suspensions. Clients
 * cannot assume that stack frames are identical or equal across
 * iterative thread suspensions and must check for equality on iterative
 * suspensions if they wish to re-use the objects.
 * </p>
 * <p>
 * A debug model implementation that preserves equality
 * across iterative suspensions may display more desirable behavior in
 * some clients. For example, if stack frames are preserved
 * while stepping, a UI client would be able to update the UI incrementally,
 * rather than collapse and redraw the entire list. 
 * </p>
 * <p>
 * Clients may implement this interface.
 * </p>
 * @see IStep
 * @see ISuspendResume
 * @see ITerminate
 */
public interface IStackFrame extends IDebugElement, IStep, ISuspendResume, ITerminate {
	/**
	 * Returns the thread this stack frame is contained in.
	 * 
	 * @return thread
	 * @since 2.0
	 */
	public IThread getThread();
	/**
	 * Returns the visible variables in this stack frame. An empty
	 * collection is returned if there are no visible variables.
	 * 
	 * @return collection of visible variables
	 * @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 2.0
	 */
	public IVariable[] getVariables() throws DebugException;
	
	/**
	 * Returns whether this stack frame currently contains any visible variables.
	 * 
	 * @return whether this stack frame currently contains any visible variables
	 * @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 2.0
	 */
	public boolean hasVariables() throws DebugException;
		
	/**
	 * Returns the line number of the instruction pointer in 
	 * this stack frame that corresponds to a line in an associated source
	 * element, or <code>-1</code> if line number information
	 * is unavailable.
	 *
	 * @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>
	 */
	public int getLineNumber() throws DebugException;
	
	/**
	 * Returns the index of the first character in the associated source
	 * element that corresponds to the current location of the instruction pointer
	 * in this stack frame, or <code>-1</code> if the information is unavailable.
	 * <p>
	 * If a debug model supports expression level stepping, the start/end
	 * character ranges are used to highlight the expression within a line
	 * that is being executed.
	 * </p>
	 * @return index of the first character in the associated source
	 * element that corresponds to the current location of the instruction pointer
	 * in this stack frame, or <code>-1</code> if the 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 2.0
	 */
	public int getCharStart() throws DebugException;
	
	/**
	 * Returns the index of the last character in the associated source
	 * element that corresponds to the current location of the instruction pointer
	 * in this stack frame, or <code>-1</code> if the information is unavailable.
	 * <p>
	 * If a debug model supports expression level stepping, the start/end
	 * character ranges are used to highlight the expression within a line
	 * that is being executed.
	 * </p>
	 * @return index of the last character in the associated source
	 * element that corresponds to the current location of the instruction pointer
	 * in this stack frame, or <code>-1</code> if the 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 2.0
	 */
	public int getCharEnd() throws DebugException;	
		
	/**
	 * Returns the name of this stack frame. Name format is debug model
	 * specific, and should be specified by a debug model.
	 *
	 * @return this frame's name
	 * @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>
	 */
	public String getName() throws DebugException;
	
	/**
	 * Returns the register groups assigned to this stack frame,
	 * or an empty collection if no register groups are assigned
	 * to this stack frame.
	 * 
	 * @return the register groups assigned to this stack frame
	 *  or an empty collection if no register groups are assigned
	 *  to this stack frame
	 * @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 2.0
	 */
	public IRegisterGroup[] getRegisterGroups() throws DebugException;
	
	/**
	 * Returns whether this stack frame contains any register groups.
	 * 
	 * @return whether this stack frame contains any visible register groups
	 * @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 2.0
	 */
	public boolean hasRegisterGroups() throws DebugException;	
}