IJavaStackFrame


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 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.jdt.debug.core;
12  
13  
14  import java.util.List  ;
15  
16  import org.eclipse.debug.core.DebugException;
17  import org.eclipse.debug.core.model.IDropToFrame;
18  import org.eclipse.debug.core.model.IFilteredStep;
19  import org.eclipse.debug.core.model.IStackFrame;
20  
21  /**
22   * A stack frame in a thread on a Java virtual machine.
23   * <p>
24   * Clients are not intended to implement this interface.
25   * </p>
26   * <p>
27   * Since 3.1, <code>IJavaStackFrame</code> also implements
28   * {@link org.eclipse.debug.core.model.IDropToFrame}.
29   * </p>
30   * @see org.eclipse.debug.core.model.IStackFrame
31   */
32  
33  public interface IJavaStackFrame extends IStackFrame, IJavaModifiers, IFilteredStep, IDropToFrame {
34  
35      /**
36       * Status code indicating a stack frame is invalid. A stack frame becomes invalid
37       * when the thread containing the stack frame resumes. A stack frame may or may
38       * not be valid if the thread subsequently suspends, depending on the location
39       * where the thread suspends. 
40       * 
41       * @since 3.1
42       */
43      public static final int ERR_INVALID_STACK_FRAME = 130;
44      
45      /**
46       * Returns whether this stack frame currently supports the drop
47       * to frame operation. Note that not all VMs support the operation.
48       *
49       * @return whether this stack frame currently supports drop to frame
50       * @deprecated since 3.1, IJavaStackFrame extends org.eclipse.debug.core.IDropToFrame
51       *  which defines canDropToFrame(). Use this method instead.
52       */
53      boolean supportsDropToFrame();
54      /**
55       * Returns whether the method associated with this stack frame
56       * is a constructor.
57       * 
58       * @return whether this stack frame is associated with a constructor
59       * @exception DebugException if this method fails.  Reasons include:
60       * <ul>
61       * <li>Failure communicating with the VM.  The DebugException's
62       * status code contains the underlying exception responsible for
63       * the failure.</li>
64       * <li>This stack frame is no longer valid. That is, the thread
65       *   containing this stack frame has since been resumed.</li>
66       * </ul>
67       */
68      public boolean isConstructor() throws DebugException;
69          
70      /**
71       * Returns whether the method associated with this stack frame
72       * has been declared as native.
73       * 
74       * @return whether this stack frame has been declared as native
75       * @exception DebugException if this method fails.  Reasons include:
76       * <ul>
77       * <li>Failure communicating with the VM.  The DebugException's
78       * status code contains the underlying exception responsible for
79       * the failure.</li>
80       * <li>This stack frame is no longer valid. That is, the thread
81       *   containing this stack frame has since been resumed.</li>
82       * </ul>
83       */
84      public boolean isNative() throws DebugException;
85      /**
86       * Returns whether the method associated with this stack frame
87       * is a static initializer.
88       * 
89       * @return whether this stack frame is a static initializer
90       * @exception DebugException if this method fails. Reasons include:<ul>
91       * <ul>
92       * <li>Failure communicating with the VM.  The DebugException's
93       * status code contains the underlying exception responsible for
94       * the failure.</li>
95       * <li>This stack frame is no longer valid. That is, the thread
96       *   containing this stack frame has since been resumed.</li>
97       * </ul>
98       */
99      public boolean isStaticInitializer() throws DebugException;
100     /**
101      * Returns whether the method associated with this stack frame
102      * has been declared as synchronized.
103      *
104      * @return whether this stack frame has been declared as synchronized
105      * @exception DebugException if this method fails.  Reasons include:
106      * <ul>
107      * <li>Failure communicating with the VM.  The DebugException's
108      * status code contains the underlying exception responsible for
109      * the failure.</li>
110      * <li>This stack frame is no longer valid. That is, the thread
111      *   containing this stack frame has since been resumed.</li>
112      * </ul>
113      */
114     public boolean isSynchronized() throws DebugException;
115     /**
116      * Returns whether the method associated with this stack frame
117      * is running code in the VM that is out of synch with the code
118      * in the workspace.
119      * 
120      * @return whether this stack frame is out of synch with the workspace.
121      * @exception DebugException if this method fails.  Reasons include:
122      * <ul>
123      * <li>Failure communicating with the VM.  The DebugException's
124      * status code contains the underlying exception responsible for
125      * the failure.</li>
126      * <li>This stack frame is no longer valid. That is, the thread
127      *   containing this stack frame has since been resumed.</li>
128      * </ul>
129      * @since 2.0
130      */
131     public boolean isOutOfSynch() throws DebugException;
132     /**
133      * Returns whether the method associated with this stack frame is
134      * obsolete, that is, it is running old byte codes that have been
135      * replaced in the VM. This can occur when a hot code replace
136      * succeeds but the VM is unable to pop a call to an affected
137      * method from the call stack.
138      * @return whether this stack frame's method is obsolete
139      * @exception DebugException if this method fails.  Reasons include:
140      * <ul>
141      * <li>Failure communicating with the VM.  The DebugException's
142      * status code contains the underlying exception responsible for
143      * the failure.</li>
144      * <li>This stack frame is no longer valid. That is, the thread
145      *   containing this stack frame has since been resumed.</li>
146      * </ul>
147      * @since 2.0
148      */
149     public boolean isObsolete() throws DebugException;
150     /**
151      * Returns the fully qualified name of the type that declares the method
152      * associated with this stack frame.
153      *
154      * @return declaring type name
155      * @exception DebugException if this method fails.  Reasons include:
156      * <ul>
157      * <li>Failure communicating with the VM.  The DebugException's
158      * status code contains the underlying exception responsible for
159      * the failure.</li>
160      * <li>This stack frame is no longer valid. That is, the thread
161      *   containing this stack frame has since been resumed.</li>
162      * </ul>
163      */
164     public String   getDeclaringTypeName() throws DebugException;
165     /**
166      * Returns the fully qualified name of the type that is the receiving object
167      * associated with this stack frame
168      *
169      * @return receiving type name
170      * @exception DebugException if this method fails.  Reasons include:
171      * <ul>
172      * <li>Failure communicating with the VM.  The DebugException's
173      * status code contains the underlying exception responsible for
174      * the failure.</li>
175      * <li>This stack frame is no longer valid. That is, the thread
176      *   containing this stack frame has since been resumed.</li>
177      * </ul>
178      */
179     public String   getReceivingTypeName() throws DebugException;
180     
181     /**
182      * Returns the JNI signature for the method this stack frame is associated with.
183      *
184      * @return signature
185      * @exception DebugException if this method fails.  Reasons include:
186      * <ul>
187      * <li>Failure communicating with the VM.  The DebugException's
188      * status code contains the underlying exception responsible for
189      * the failure.</li>
190      * <li>This stack frame is no longer valid. That is, the thread
191      *   containing this stack frame has since been resumed.</li>
192      * </ul>
193      */
194     public String   getSignature() throws DebugException;
195     
196     /**
197      * Returns a list of fully qualified type names of the arguments for the method
198      * associated with this stack frame.
199      *
200      * @return argument type names, or an empty list if this method has no arguments
201      * @exception DebugException if this method fails.  Reasons include:
202      * <ul>
203      * <li>Failure communicating with the VM.  The DebugException's
204      * status code contains the underlying exception responsible for
205      * the failure.</li>
206      * <li>This stack frame is no longer valid. That is, the thread
207      *   containing this stack frame has since been resumed.</li>
208      * </ul>
209      */
210     public List   getArgumentTypeNames() throws DebugException;
211     
212     /**
213      * Returns the name of the method associated with this stack frame
214      *
215      * @return method name
216      * @exception DebugException if this method fails.  Reasons include:
217      * <ul>
218      * <li>Failure communicating with the VM.  The DebugException's
219      * status code contains the underlying exception responsible for
220      * the failure.</li>
221      * <li>This stack frame is no longer valid. That is, the thread
222      *   containing this stack frame has since been resumed.</li>
223      * </ul>
224      */
225     public String   getMethodName() throws DebugException;
226     
227     /**
228      * Returns the local, static, or "this" variable with the given
229      * name, or <code>null</code> if unable to resolve a variable with the name.
230      *
231      * @param variableName the name of the variable to search for
232      * @return a variable, or <code>null</code> if none
233      * @exception DebugException if this method fails.  Reasons include:
234      * <ul>
235      * <li>Failure communicating with the VM.  The DebugException's
236      * status code contains the underlying exception responsible for
237      * the failure.</li>
238      * <li>This stack frame is no longer valid. That is, the thread
239      *   containing this stack frame has since been resumed.</li>
240      * </ul>
241      */
242     public IJavaVariable findVariable(String   variableName) throws DebugException;
243     
244     /**
245      * Returns the line number of the instruction pointer in 
246      * this stack frame that corresponds to the line in the associated source
247      * element in the specified stratum, or <code>-1</code> if line number
248      * information is unavailable.
249      *
250      * @param stratum the stratum to use.
251      * @return line number of instruction pointer in this stack frame, or 
252      * <code>-1</code> if line number information is unavailable
253      * @exception DebugException if this method fails.  Reasons include:
254      * <ul><li>Failure communicating with the debug target.  The DebugException's
255      * status code contains the underlying exception responsible for
256      * the failure.</li>
257      * </ul>
258      * 
259      * @since 3.0
260      */
261     public int getLineNumber(String   stratum) throws DebugException;
262     
263     /**
264      * Returns the source name debug attribute associated with the declaring
265      * type of this stack frame, or <code>null</code> if the source name debug
266      * attribute not present.
267      * 
268      * @return source name debug attribute, or <code>null</code>
269      * @exception DebugException if this method fails.  Reasons include:
270      * <ul>
271      * <li>Failure communicating with the VM.  The DebugException's
272      * status code contains the underlying exception responsible for
273      * the failure.</li>
274      * <li>This stack frame is no longer valid. That is, the thread
275      *   containing this stack frame has since been resumed.</li>
276      * </ul>
277      */
278     public String   getSourceName() throws DebugException;
279     
280     /**
281      * Returns the source name debug attribute associated with the declaring
282      * type of this stack frame in the specified stratum, or <code>null</code>
283      * if the source name debug attribute not present.
284      * 
285      * @param stratum the stratum to use.
286      * @return source name debug attribute, or <code>null</code>
287      * @exception DebugException if this method fails.  Reasons include:
288      * <ul>
289      * <li>Failure communicating with the VM.  The DebugException's
290      * status code contains the underlying exception responsible for
291      * the failure.</li>
292      * <li>This stack frame is no longer valid. That is, the thread
293      *   containing this stack frame has since been resumed.</li>
294      * </ul>
295      * 
296      * @since 3.0
297      */
298     public String   getSourceName(String   stratum) throws DebugException;
299     
300     /**
301      * Returns the source path debug attribute associated with
302      * this stack frame in the specified stratum, or 
303      * <code>null</code> if the source path is not known.
304      * 
305      * @param stratum the stratum to use.
306      * @return source path debug attribute, or <code>null</code>
307      * @exception DebugException if this method fails.  Reasons include:
308      * <ul>
309      * <li>Failure communicating with the VM.  The DebugException's
310      * status code contains the underlying exception responsible for
311      * the failure.</li>
312      * <li>This stack frame is no longer valid. That is, the thread
313      *   containing this stack frame has since been resumed.</li>
314      * </ul>
315      * @since 3.0
316      */
317     public String   getSourcePath(String   stratum) throws DebugException;
318     
319     /**
320      * Returns the source path debug attribute associated with
321      * this stack frame, or <code>null</code> if the source path
322      * is not known.
323      * 
324      * @return source path debug attribute, or <code>null</code>
325      * @exception DebugException if this method fails.  Reasons include:
326      * <ul>
327      * <li>Failure communicating with the VM.  The DebugException's
328      * status code contains the underlying exception responsible for
329      * the failure.</li>
330      * <li>This stack frame is no longer valid. That is, the thread
331      *   containing this stack frame has since been resumed.</li>
332      * </ul>
333      * @since 3.0
334      */
335     public String   getSourcePath() throws DebugException;    
336     
337     /**
338      * Returns a collection of local variables that are visible
339      * at the current point of execution in this stack frame. The
340      * list includes arguments.
341      * 
342      * @return collection of locals and arguments
343      * @exception DebugException if this method fails.  Reasons include:
344      * <ul>
345      * <li>Failure communicating with the VM.  The DebugException's
346      * status code contains the underlying exception responsible for
347      * the failure.</li>
348      * <li>This stack frame is no longer valid. That is, the thread
349      *   containing this stack frame has since been resumed.</li>
350      * </ul>
351      * @since 2.0
352      */
353     public IJavaVariable[] getLocalVariables() throws DebugException;
354     
355     /**
356      * Returns a reference to the receiver of the method associated
357      * with this stack frame, or <code>null</code> if this stack frame
358      * represents a static method.
359      * 
360      * @return 'this' object, or <code>null</code>
361      * @exception DebugException if this method fails.  Reasons include:
362      * <ul>
363      * <li>Failure communicating with the VM.  The DebugException's
364      * status code contains the underlying exception responsible for
365      * the failure.</li>
366      * <li>This stack frame is no longer valid. That is, the thread
367      *   containing this stack frame has since been resumed.</li>
368      * </ul>
369      */
370     public IJavaObject getThis() throws DebugException;
371     
372     /**
373      * Returns the class in which this stack frame's method is
374      * declared.
375      * 
376      * @return the class in which this stack frame's method is
377      *   declared
378      * @exception DebugException if this method fails.  Reasons include:
379      * <ul>
380      * <li>Failure communicating with the VM.  The DebugException's
381      * status code contains the underlying exception responsible for
382      * the failure.</li>
383      * <li>This stack frame is no longer valid. That is, the thread
384      *   containing this stack frame has since been resumed.</li>
385      * </ul>
386      * @since 2.0
387      * @deprecated Use <code>getReferenceType()</code> instead, as a method is not
388      *  restricted to occur in a class. An interface may contain a synthetic
389      *  class initializer methods. Since 3.1, this method throws a 
390      *  <code>DebugException</code> when a stack frame's method is contained
391      *  in an interface.
392      */
393     public IJavaClassType getDeclaringType() throws DebugException; 
394     
395     /**
396      * Returns the type in which this stack frame's method is
397      * declared.
398      * 
399      * @return the type in which this stack frame's method is
400      *   declared
401      * @exception DebugException if this method fails.  Reasons include:
402      * <ul>
403      * <li>Failure communicating with the VM.  The DebugException's
404      * status code contains the underlying exception responsible for
405      * the failure.</li>
406      * <li>This stack frame is no longer valid. That is, the thread
407      *   containing this stack frame has since been resumed.</li>
408      * </ul>
409      * @since 3.1
410      */
411     public IJavaReferenceType getReferenceType() throws DebugException;     
412     
413     /**
414      * Returns whether local variable information was available
415      * when local variables were retrieved from the target for this
416      * frame. Returns <code>true</code> if locals have never been
417      * retrieved. This data is available after the fact, since variable
418      * retrieval is expensive.
419      * 
420      * @return whether local variable information was available
421      * when variables were retrieved from the target. Returns
422      * <code>true</code> if locals have never been retrieved
423      * 
424      * @since 2.0
425      */
426     public boolean wereLocalsAvailable();
427     
428     /**
429      * Returns whether the method associated with this stack frame accepts
430      * a variable number of arguments.
431      * 
432      * @return <code>true</code> if the method associated with this stack
433      * frame accepts a variable number of arguments, <code>false</code> otherwise.
434      * @exception DebugException if this method fails.  Reasons include:
435      * <ul>
436      * <li>Failure communicating with the VM.  The DebugException's
437      * status code contains the underlying exception responsible for
438      * the failure.</li>
439      * <li>This stack frame is no longer valid. That is, the thread
440      *   containing this stack frame has since been resumed.</li>
441      * </ul>
442      * @since 3.1
443      */
444     public boolean isVarArgs() throws DebugException;
445     
446     /**
447      * Returns whether this frame currently supports a force return operation. That is,
448      * can this method force a return before it reaches a return statement. Not all VMs
449      * support this feature.
450      * <p>
451      * Force return is only available when a thread is suspended.
452      * </p>
453      * @return whether force return can be performed currently
454      * @since 3.3
455      */
456     public boolean canForceReturn();
457     
458     /**
459      * Steps out of this frame's method returning the given value. No further instructions
460      * in the method are executed but locks acquired by entering synchronized blocks are released.
461      * The following conditions must be satisfied:
462      * <ul>
463      * <li>This frame must be suspended in a non-native method.</li>
464      * <li>The return value must be assignment compatible with this frame's method's
465      * return type. Use a void value when a method return type is void
466      * (see <code>IJavaDebugTarget.voidValue()</code>).</li>
467      * </ul>
468      * 
469      * @param value return value that must be assignment compatible with this frame's
470      *  method's return value
471      * @throws DebugException if the operation fails
472      * @since 3.3
473      */
474     public void forceReturn(IJavaValue value) throws DebugException;    
475 }
476 
477 
478
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags