IStackFrame


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    * 
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.debug.core.model;
12  
13  
14  import org.eclipse.debug.core.DebugException;
15  
16  /**
17   * A stack frame represents an execution context in a suspended thread.
18   * A stack frame contains variables representing visible locals and arguments at
19   * the current execution location. Minimally, a stack frame supports
20   * the following:
21   * <ul>
22   * <li>suspend/resume (convenience to resume this stack frame's thread)
23   * <li>stepping
24   * <li>termination (convenience to terminate this stack frame's thread or debug target)
25   * </ul>
26   * <p>
27   * A debug model implementation may choose to re-use or discard
28   * stack frames on iterative thread suspensions. Clients
29   * cannot assume that stack frames are identical or equal across
30   * iterative thread suspensions and must check for equality on iterative
31   * suspensions if they wish to re-use the objects.
32   * </p>
33   * <p>
34   * A debug model implementation that preserves equality
35   * across iterative suspensions may display more desirable behavior in
36   * some clients. For example, if stack frames are preserved
37   * while stepping, a UI client would be able to update the UI incrementally,
38   * rather than collapse and redraw the entire list. 
39   * </p>
40   * <p>
41   * Clients may implement this interface.
42   * </p>
43   * @see IStep
44   * @see ISuspendResume
45   * @see ITerminate
46   */
47  public interface IStackFrame extends IDebugElement, IStep, ISuspendResume, ITerminate {
48      /**
49       * Returns the thread this stack frame is contained in.
50       * 
51       * @return thread
52       * @since 2.0
53       */
54      public IThread getThread();
55      /**
56       * Returns the visible variables in this stack frame. An empty
57       * collection is returned if there are no visible variables.
58       * 
59       * @return collection of visible variables
60       * @exception DebugException if this method fails.  Reasons include:
61       * <ul><li>Failure communicating with the debug target.  The DebugException's
62       * status code contains the underlying exception responsible for
63       * the failure.</li>
64       * </ul>
65       * @since 2.0
66       */
67      public IVariable[] getVariables() throws DebugException;
68      
69      /**
70       * Returns whether this stack frame currently contains any visible variables.
71       * 
72       * @return whether this stack frame currently contains any visible variables
73       * @exception DebugException if this method fails.  Reasons include:
74       * <ul><li>Failure communicating with the debug target.  The DebugException's
75       * status code contains the underlying exception responsible for
76       * the failure.</li>
77       * </ul>
78       * @since 2.0
79       */
80      public boolean hasVariables() throws DebugException;
81          
82      /**
83       * Returns the line number of the instruction pointer in 
84       * this stack frame that corresponds to a line in an associated source
85       * element, or <code>-1</code> if line number information
86       * is unavailable.
87       *
88       * @return line number of instruction pointer in this stack frame, or 
89       * <code>-1</code> if line number information is unavailable
90       * @exception DebugException if this method fails.  Reasons include:
91       * <ul><li>Failure communicating with the debug target.  The DebugException's
92       * status code contains the underlying exception responsible for
93       * the failure.</li>
94       * </ul>
95       */
96      public int getLineNumber() throws DebugException;
97      
98      /**
99       * Returns the index of the first character in the associated source
100      * element that corresponds to the current location of the instruction pointer
101      * in this stack frame, or <code>-1</code> if the information is unavailable.
102      * <p>
103      * If a debug model supports expression level stepping, the start/end
104      * character ranges are used to highlight the expression within a line
105      * that is being executed.
106      * </p>
107      * @return index of the first character in the associated source
108      * element that corresponds to the current location of the instruction pointer
109      * in this stack frame, or <code>-1</code> if the information is unavailable
110      * @exception DebugException if this method fails.  Reasons include:
111      * <ul><li>Failure communicating with the debug target.  The DebugException's
112      * status code contains the underlying exception responsible for
113      * the failure.</li>
114      * </ul>
115      * @since 2.0
116      */
117     public int getCharStart() throws DebugException;
118     
119     /**
120      * Returns the index of the last character in the associated source
121      * element that corresponds to the current location of the instruction pointer
122      * in this stack frame, or <code>-1</code> if the information is unavailable.
123      * <p>
124      * If a debug model supports expression level stepping, the start/end
125      * character ranges are used to highlight the expression within a line
126      * that is being executed.
127      * </p>
128      * @return index of the last character in the associated source
129      * element that corresponds to the current location of the instruction pointer
130      * in this stack frame, or <code>-1</code> if the information is unavailable
131      * @exception DebugException if this method fails.  Reasons include:
132      * <ul><li>Failure communicating with the debug target.  The DebugException's
133      * status code contains the underlying exception responsible for
134      * the failure.</li>
135      * </ul>
136      * @since 2.0
137      */
138     public int getCharEnd() throws DebugException;  
139         
140     /**
141      * Returns the name of this stack frame. Name format is debug model
142      * specific, and should be specified by a debug model.
143      *
144      * @return this frame's name
145      * @exception DebugException if this method fails.  Reasons include:
146      * <ul><li>Failure communicating with the debug target.  The DebugException's
147      * status code contains the underlying exception responsible for
148      * the failure.</li>
149      * </ul>
150      */
151     public String   getName() throws DebugException;
152     
153     /**
154      * Returns the register groups assigned to this stack frame,
155      * or an empty collection if no register groups are assigned
156      * to this stack frame.
157      * 
158      * @return the register groups assigned to this stack frame
159      *  or an empty collection if no register groups are assigned
160      *  to this stack frame
161      * @exception DebugException if this method fails.  Reasons include:
162      * <ul><li>Failure communicating with the debug target.  The DebugException's
163      * status code contains the underlying exception responsible for
164      * the failure.</li>
165      * </ul>
166      * @since 2.0
167      */
168     public IRegisterGroup[] getRegisterGroups() throws DebugException;
169     
170     /**
171      * Returns whether this stack frame contains any register groups.
172      * 
173      * @return whether this stack frame contains any visible register groups
174      * @exception DebugException if this method fails.  Reasons include:
175      * <ul><li>Failure communicating with the debug target.  The DebugException's
176      * status code contains the underlying exception responsible for
177      * the failure.</li>
178      * </ul>
179      * @since 2.0
180      */
181     public boolean hasRegisterGroups() throws DebugException;   
182 }
183
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags